Project TIA API Documentation

The Trade Ideas API is a JSON REST surface with five read endpoints:

• GET /v1/trade-ideas/active — every trade idea with status LIVE and a non-null published_at (stop orders waiting for entry never appear until auto-published), newest published_at first.
• GET /v1/trade-ideas/closed — recently terminal ideas (TP_HIT, TP1_HIT, TP2_HIT, SL_HIT, EXPIRED, WITHDRAWN) within the lookback window.
• GET /v1/trade-ideas/history — full published archive (LIVE plus terminal rows), paginated.
• GET /v1/trade-ideas/reports — aggregate performance metrics (win rate, ROI, hit counts) for a day / week / month / year or custom IST date window.
• GET /v1/trade-ideas/{id} — one idea by id; a successful response is the trade idea JSON object at the root, not an envelope with data.

LIVE rows may still track without an entry stamp: use entry_hit_at, status, and hit timestamps in the JSON—not informal labels—to decide how you surface them in your own systems (Status values).

All live evaluation uses last traded price (LTP) from Bybit linear perpetual lastPrice (WebSocket plus REST reconcile) — not Mudrex, index, or mark. Entry, TP, and SL hits are stamped from those market prices on the tracker.

All responses are JSON; timestamps are ISO 8601 UTC instants on the wire (trailing Z). Numeric prices and percentages are strings so clients preserve precision without float parsing.

Access is layered: a per-partner bearer token (provided when your integration is onboarded), optional per-client IP allowlists, and always-on rate limits. Bearer tokens are required in production.

Bearer token (required)

Send your assigned token on every request:

Authorization: Bearer tia_live_…

Store the token as a secret environment variable (for example TIA_API_TOKEN on Railway) and attach it to your HTTP client — no URL or response-format changes are required.

export TIA_API_TOKEN="tia_live_…"
curl -sS -H "Authorization: Bearer $TIA_API_TOKEN" "https://project-tia.app/v1/trade-ideas/active"

Per-client IP allowlists

When IP allowlisting is required for your integration, requests that include your bearer token must originate from an IP or CIDR registered for your account. Multiple partners may share the same egress IP (for example Railway) and remain distinguishable because each has a unique token.

Deprecated (do not use)

• Global IP-only allowlists — superseded by per-client IP lists used together with bearer tokens.
• TIA_PUBLIC_API_BEARER_TOKEN environment variable — ignored; use the per-partner token provided at onboarding instead.
• /v1/picks/* paths — redirect to /v1/trade-ideas/* with HTTP 308; migrate callers to the new paths.
• API keys, scopes, and self-service token registration — not supported on this API.

Default quota: 240 requests per minute with a burst of 120. When you send a valid bearer token, limits apply per integration (not only per IP).

Prefer long polling on /v1/trade-ideas/active (see below)—one hanging request per update cycle uses fewer hits than spraying sub-second polls. Short interval polling remains fine under the quota.

When you exceed the limit you will receive an HTTP 429 with a Retry-After header (in seconds):

{
  "error": "rate_limited"
}

Every visible trade idea has exactly one wire status:

For some ideas classified at publish time, take-profit / stop-loss / milestones are tracked by the tracker only after entry_hit_at becomes non-null. Until then,LIVE persists and later hit timestamps stay null even though price moves in the broader market.

expiry_at is the published validity cut-off. Operators may move it earlier or later on a LIVE idea (dashboard Amend expiry, up to 30 days from now); integrators should accept an extra trade_idea.updated whose expiry_at can be smaller or larger while the idea remains LIVE. If TP2 or SL triggers before then, status becomes terminal; otherwise EXPIRED. On leftover dual-TP ideas a touch of tp1_price records tp1_hit_at without changing status — the idea can remain LIVE. New single-TP ideas have one target: a full-target touch is TP_HIT and emits trade_idea.closed (the idea leaves GET /active).

For in-app widgets and partner overlays, map potential profit to est_potential_pct (leverage-adjusted move to the full take-profit at publish time — canonical tp_price). Two additive fields support deeplink and coin imagery:

• mudrex_deeplink — opens Mudrex futures with published entry, SL, and TP1. Null without a Mudrex asset id.
• logo_url — verified images.mudrex.com URL or a manual override. Null until probed OK or overridden.

Optional fields for in-app deeplinks and coin imagery. Both may be null until catalogue data is available — safe to ignore if your integration does not use them.

New publishes have one take-profit. REST and webhooks use the same payload for every partner. Production and staging both use the grace payload (compat tp1_* / tp2_* still present).

Risk: a client that requires a numeric tp2_price or only treats TP2_HIT as a win will mis-handle new ideas even in grace.

Rollout: production and staging both publish single-TP with the grace payload (toggle off). Prefer tp_* / TP_HIT now; enforcement (drop tp1_* / tp2_*) comes later after partners confirm.

Grace-period example (new LIVE idea). Field order on the wire follows serialize; compat keys are present while the toggle is off:

{
  "id": "a1b2c3d4-1111-2222-3333-444444444444",
  "symbol": "BTCUSDT",
  "direction": "LONG",
  "margin_type": "ISOLATED",
  "leverage": 10,
  "entry_price": "62500.00000000",
  "stop_loss": "62000.00000000",
  "est_potential_pct": "16.0",
  "est_loss_pct": "-8.0",
  "risk_reward_ratio": "1:2",
  "confidence": "HIGH",
  "status": "LIVE",
  "published_at": "2026-09-03T06:00:00.000Z",
  "expiry_at": "2026-09-04T06:00:00.000Z",
  "entry_hit_at": null,
  "tp_price": "63500.00000000",
  "tp_hit_at": null,
  "sl_hit_at": null,
  "expired_at": null,
  "withdrawn_at": null,
  "resolved_at": null,
  "resolution": null,
  "mudrex_deeplink": "mudrex://futures-buy-sell/abc123/long/BTCUSDT/10/62500.00000000/62000.00000000/63500.00000000",
  "logo_url": "https://images.mudrex.com/BTC.png",
  "tp1_price": "63500.00000000",
  "tp2_price": null,
  "tp1_hit_at": null,
  "tp2_hit_at": null
}

Every trade idea object exposes the fields below with this key order on the wire. Numeric prices and percentages are strings so callers can parse with decimal libraries without floats.

{
  "id": "8c2a9b7e-4f12-4d8a-9e3b-7a6e5b1c2d3f",
  "symbol": "BTCUSDT",
  "direction": "LONG",
  "margin_type": "ISOLATED",
  "leverage": 10,
  "entry_price": "62500.00000000",
  "stop_loss": "62000.00000000",
  "est_potential_pct": "32.0",
  "est_loss_pct": "-8.0",
  "risk_reward_ratio": "1:4",
  "confidence": "HIGH",
  "status": "LIVE",
  "published_at": "2026-05-12T13:42:01.000Z",
  "expiry_at": "2026-05-13T13:42:01.000Z",
  "entry_hit_at": null,
  "tp_price": "64500.00000000",
  "tp_hit_at": null,
  "sl_hit_at": null,
  "expired_at": null,
  "withdrawn_at": null,
  "resolved_at": null,
  "resolution": null,
  "mudrex_deeplink": "mudrex://futures-buy-sell/abc123/long/BTCUSDT/10/62500.00000000/62000.00000000/63500.00000000",
  "logo_url": "https://images.mudrex.com/BTC.png",
  "tp1_price": "63500.00000000",
  "tp2_price": "64500.00000000",
  "tp1_hit_at": null,
  "tp2_hit_at": null
}

Leftover dual-TP full-target close (TP2_HIT) — tp_price is TP2; tp1_price stays stored TP1:

{
  "id": "8c2a9b7e-4f12-4d8a-9e3b-7a6e5b1c2d3f",
  "symbol": "BTCUSDT",
  "direction": "LONG",
  "margin_type": "ISOLATED",
  "leverage": 10,
  "entry_price": "62500.00000000",
  "stop_loss": "62000.00000000",
  "est_potential_pct": "32.0",
  "est_loss_pct": "-8.0",
  "risk_reward_ratio": "1:4",
  "confidence": "HIGH",
  "status": "TP2_HIT",
  "published_at": "2026-05-12T13:42:01.000Z",
  "expiry_at": "2026-05-13T13:42:01.000Z",
  "entry_hit_at": "2026-05-12T13:58:02.000Z",
  "tp_price": "64500.00000000",
  "tp_hit_at": "2026-05-12T14:11:09.000Z",
  "sl_hit_at": null,
  "expired_at": null,
  "withdrawn_at": null,
  "resolved_at": "2026-05-12T14:11:09.000Z",
  "resolution": "TP2_HIT",
  "mudrex_deeplink": "mudrex://futures-buy-sell/abc123/long/BTCUSDT/10/62500.00000000/62000.00000000/63500.00000000",
  "logo_url": "https://images.mudrex.com/BTC.png",
  "tp1_price": "63500.00000000",
  "tp2_price": "64500.00000000",
  "tp1_hit_at": "2026-05-12T14:02:11.000Z",
  "tp2_hit_at": "2026-05-12T14:11:09.000Z"
}

Withdrawn trades use the same field order; terminal example WITHDRAWN:

{
  "id": "9d3bacc1-aaaa-bbbb-cccc-dddddddddddd",
  "symbol": "ETHUSDT",
  "direction": "SHORT",
  "margin_type": "ISOLATED",
  "leverage": 5,
  "entry_price": "3000.00000000",
  "stop_loss": "3050.00000000",
  "est_potential_pct": "25.0",
  "est_loss_pct": "-8.3",
  "risk_reward_ratio": "1:3",
  "confidence": "HIGH",
  "status": "WITHDRAWN",
  "published_at": "2026-05-14T09:00:00.000Z",
  "expiry_at": "2026-05-15T09:00:00.000Z",
  "entry_hit_at": null,
  "tp_price": "2850.00000000",
  "tp_hit_at": null,
  "sl_hit_at": null,
  "expired_at": null,
  "withdrawn_at": "2026-05-14T09:42:03.000Z",
  "resolved_at": "2026-05-14T09:42:03.000Z",
  "resolution": "WITHDRAWN",
  "mudrex_deeplink": "mudrex://futures-buy-sell/def456/short/ETHUSDT/5/3000.00000000/3050.00000000/2900.00000000",
  "logo_url": "https://images.mudrex.com/ETH.png",
  "tp1_price": "2900.00000000",
  "tp2_price": "2850.00000000",
  "tp1_hit_at": null,
  "tp2_hit_at": null
}

Integrations may receive signed HTTPS POST payloads on URLs provisioned for your environment—an alternative to polling /v1/trade-ideas/active. Delivery starts when a trade idea is published (LIVE), continues on materially relevant live updates (entry / TP1 progress, terminals), and uses the same snake_case trade_idea object as REST. Limit orders waiting for a fill show LIVE with entry_hit_at: null exactly like REST.

• Headers include Content-Type: application/json, X-TIA-Timestamp (Unix milliseconds), and X-TIA-Signature: sha256=<hex digest> where digest is HMAC-SHA256 over {timestamp}.{rawBody} (ASCII dot between the two). Optional X-TIA-Webhook-Event-Group-Id matches envelope event_id; X-TIA-Webhook-Event-Type mirrors envelope event_type.
• Lifecycle events: trade_idea.published (first publish), trade_idea.updated (entry or TP1 progress, or validity moved earlier or later while LIVE), trade_idea.closed (TP_HIT, legacy TP2/TP1, SL, expiry, or withdrawal). Connectivity checks may send integration.ping.

{
  "schema_version": 1,
  "event_id": "8c2a9b7e-4f12-4d8a-9e3b-7a6e5b1c2d3f",
  "event_type": "trade_idea.published",
  "occurred_at": "2026-05-12T13:42:01.000Z",
  "trade_idea":   {
    "id": "8c2a9b7e-4f12-4d8a-9e3b-7a6e5b1c2d3f",
    "symbol": "BTCUSDT",
    "direction": "LONG",
    "margin_type": "ISOLATED",
    "leverage": 10,
    "entry_price": "62500.00000000",
    "stop_loss": "62000.00000000",
    "est_potential_pct": "32.0",
    "est_loss_pct": "-8.0",
    "risk_reward_ratio": "1:4",
    "confidence": "HIGH",
    "status": "LIVE",
    "published_at": "2026-05-12T13:42:01.000Z",
    "expiry_at": "2026-05-13T13:42:01.000Z",
    "entry_hit_at": null,
    "tp_price": "64500.00000000",
    "tp_hit_at": null,
    "sl_hit_at": null,
    "expired_at": null,
    "withdrawn_at": null,
    "resolved_at": null,
    "resolution": null,
    "mudrex_deeplink": "mudrex://futures-buy-sell/abc123/long/BTCUSDT/10/62500.00000000/62000.00000000/63500.00000000",
    "logo_url": "https://images.mudrex.com/BTC.png",
    "tp1_price": "63500.00000000",
    "tp2_price": "64500.00000000",
    "tp1_hit_at": null,
    "tp2_hit_at": null
  }
}

Verify timestamps within a reasonable clock skew window; tolerate at-least-once deliveries by deduplicating on event_id.

{
  "schema_version": 1,
  "event_id": "9f2c…",
  "event_type": "integration.ping",
  "occurred_at": "2026-05-12T13:43:01.000Z",
  "message": "Handshake test from Project TIA."
}

Errors return JSON with at least an error code. Validation responses from route handlers usually include message with a plain-language hint; clients should not depend on the exact copy of message.

Breaking changes are called out explicitly. Integration requirements are in Access.