> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Trader Context > Returns a single structured context object for one trader: the full trader profile (same shape as GET /api/v1/trader/{address}) plus a position_summary (sync coverage and realized/unrealized P&L rollups, with an as_of open-position freshness clock), the data_as_of freshness timestamp (the open-position data's latest /positions snapshot, else last completed sync; the snapshot advances only open positions, so resolved/closed aggregates still date to the last full sync), and a freshness_note describing the point-in-time snapshot semantics. The path accepts an Ethereum wallet address (0x...), a known trader username, or a trd_-prefixed trader ID emitted by this API. position_summary is omitted when the trader is not in the local database; unknown lookups return 200 with sync_status 'unknown' on the nested trader (no 404). Append .md to the path for the Markdown rendering. Returns one structured, AI-ready trader briefing: the full trader profile, position and sync coverage, realized and unrealized P\&L rollups, and point-in-time freshness metadata. The path accepts a wallet address, known username, or `trd_...` trader ID. An unknown trader returns `200` with `sync_status: "unknown"`; `position_summary` is omitted when no local row exists. ```bash theme={null} curl -H "Authorization: Bearer $OXINSIDER_API_KEY" \ "https://api.0xinsider.com/api/v1/trader/swisstony/context" ``` The JSON route returns an `ETag`. Send it with `If-None-Match` for a conditional read. Use the [Markdown variant](/api-reference/endpoint/get-trader-context-markdown) when you need a directly readable briefing instead. ## OpenAPI ````yaml GET /api/v1/trader/{address}/context openapi: 3.1.0 info: title: 0xinsider API description: >- Find your edge on Polymarket and Kalshi. Every wallet graded, every trade scored, every outlier flagged. API exposes trader grades, whale trades, smart money signals, and insider detection for AI agents, trading bots, and research tools. Normal API requests use a 30-second server timeout that returns HTTP 408 Request Timeout with an empty body when exceeded. Public REST /api/v1/* endpoints, excluding /api/v1/mcp, use Bearer-token based non-credentialed browser CORS: any Origin may call with Authorization, Content-Type, If-None-Match, Idempotency-Key, and Mcp-Session-Id request headers. Remote MCP at /api/v1/mcp is non-credentialed, but still validates Origin against the 0xinsider/localhost allowlist per MCP Streamable HTTP DNS-rebinding guidance. Successful browser CORS preflight responses advertise Access-Control-Max-Age: 86400. Browser JavaScript may read X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, ETag, X-Request-Id, X-Request-Cost, X-Batch-RateLimit-Limit, X-Batch-RateLimit-Remaining, X-Batch-RateLimit-Reset, Mcp-Session-Id, and X-Mcp-Error-Code response headers. Credentialed first-party routes such as /api/keys, /api/billing, and auth endpoints remain restricted to configured 0xinsider origins. version: 1.0.0 contact: name: 0xinsider email: support@0xinsider.com url: https://0xinsider.com servers: - url: https://api.0xinsider.com description: >- Production (live data). Authenticate with a live key (oxi_sk_live_...); requires an active Insider subscription. security: - bearerAuth: [] tags: - name: Traders description: Trader intelligence, batch lookups, timelines, and export readiness. - name: Positions description: Current prediction-market position snapshots from backend-owned mirrors. - name: Large Positions description: Largest current open positions from graded traders (Polymarket-only). - name: Whale Trades description: Recent and historical large trade intelligence. - name: Leaderboard description: Ranked trader discovery and category/strategy leaderboards. - name: Pick of the Day description: >- One sourced sharp-money call a day: the side proven smart money is backing, with pre-game odds, the proven holders, and the track record. - name: Markets description: Market search, discovery, snapshots, and smart-score flow. - name: Insider Radar description: Suspicious trading pattern detection. - name: Events description: Durable public event replay streams. - name: Streaming description: Resumable real-time Server-Sent Events stream of live feed envelopes. - name: Webhooks description: Signed builder webhook destinations and delivery controls. - name: Usage description: Developer API budget and usage introspection. - name: System description: Health and operational status checks. - name: MCP description: Remote Model Context Protocol transport. - name: Reports description: Daily, weekly, monthly, and trader export report snapshots. paths: /api/v1/trader/{address}/context: get: tags: - Traders summary: Get trader context (JSON) description: >- Returns a single structured context object for one trader: the full trader profile (same shape as GET /api/v1/trader/{address}) plus a position_summary (sync coverage and realized/unrealized P&L rollups, with an as_of open-position freshness clock), the data_as_of freshness timestamp (the open-position data's latest /positions snapshot, else last completed sync; the snapshot advances only open positions, so resolved/closed aggregates still date to the last full sync), and a freshness_note describing the point-in-time snapshot semantics. The path accepts an Ethereum wallet address (0x...), a known trader username, or a trd_-prefixed trader ID emitted by this API. position_summary is omitted when the trader is not in the local database; unknown lookups return 200 with sync_status 'unknown' on the nested trader (no 404). Append .md to the path for the Markdown rendering. operationId: getTraderContext parameters: - name: address in: path required: true description: >- Ethereum wallet address (0x...), known trader username, or trd_-prefixed trader ID emitted by this API. schema: type: string - name: If-None-Match in: header required: false description: >- Conditional GET validator from a previous ETag. Matching values return 304 Not Modified with an empty body. schema: type: string responses: '200': description: Trader context content: application/json: schema: type: object required: - object - data - meta properties: object: type: string const: trader_context data: $ref: '#/components/schemas/TraderContext' meta: $ref: '#/components/schemas/ResponseMeta' examples: success: summary: Successful response value: object: trader_context data: {} meta: request_id: req_example cached: false cost: 1 headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' ETag: $ref: '#/components/headers/ETag' '304': description: >- Not Modified. Returned when If-None-Match matches the current payload. headers: ETag: $ref: '#/components/headers/ETag' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/SubscriptionRequired' '403': $ref: '#/components/responses/Forbidden' '408': $ref: '#/components/responses/RequestTimeout' '423': $ref: '#/components/responses/Locked' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/RateLimitUnavailable' x-codeSamples: - lang: curl label: cURL source: |- curl -sS \ -H 'Authorization: Bearer $OXI_SK' \ 'https://api.0xinsider.com/api/v1/trader/{address}/context' components: schemas: TraderContext: type: object required: - trader - data_as_of - freshness_note properties: trader: $ref: '#/components/schemas/Trader' position_summary: type: object description: >- Aggregate position and P&L coverage for the trader. Omitted entirely (key absent, never null) when the trader is not in the local database. required: - markets_total - markets_synced - markets_resolved - markets_open - sync_coverage - synced_realized_pnl - total_realized_pnl - unrealized_mtm - cost_basis_locked - resolved_win_rate - as_of properties: markets_total: type: integer nullable: true description: >- Provider markets_traded count when known; null when the provider total is unavailable. markets_synced: type: integer description: Markets with locally synced position rows. markets_resolved: type: integer description: Synced markets that have resolved. markets_open: type: integer description: >- Synced markets still open with residual value (open positions with current value > 0). sync_coverage: type: number description: >- markets_synced divided by markets_total when the provider total is known (capped at 1.0); 0.0-1.0. When markets_total is unknown or not positive (null, 0, or negative), this is 1.0 if any markets are synced (else 0.0), so cross-check markets_total before treating 1.0 as full coverage. synced_realized_pnl: type: number description: Realized P&L (USD) across synced markets only. total_realized_pnl: type: number description: >- Realized P&L (USD) across synced markets: closed-leg realized plus realized gains booked on still-open positions; not provider all-time realized when sync_coverage < 1.0 -- cross-check sync_coverage. unrealized_mtm: type: number description: Mark-to-market unrealized P&L (USD) on open positions. cost_basis_locked: type: number description: Cost basis (USD) currently tied up in open positions. resolved_win_rate: type: number nullable: true description: >- Win rate as a percentage (0-100) over resolved markets; null when there is no resolved sample. as_of: type: string format: date-time nullable: true description: >- RFC3339 freshness of the served OPEN-position data: the trader's latest /positions snapshot, else the last completed sync. The snapshot advances ONLY open positions, so read this as the open-position freshness clock -- the resolved/closed aggregates on this same summary (markets_resolved, synced_realized_pnl, resolved_win_rate) advance only on a full sync. The value is the /positions snapshot instant when one exists, so it is typically at or just before the trader-level last sync on a normal sync, and can be AFTER it while the active-view loop refreshes open positions between full syncs. Always present on the wire (serialized as JSON null when the trader has neither a snapshot nor a sync); never omitted. data_as_of: type: string format: date-time nullable: true description: >- RFC3339 freshness of the OPEN-position-level data: when a position_summary is present this mirrors its as_of byte-for-byte (latest /positions snapshot, else last completed sync) -- the open-position freshness clock, since the snapshot advances only open positions; otherwise the trader's last completed sync. null only when the trader has neither a snapshot nor a sync. freshness_note: type: string description: >- Human-readable statement of the point-in-time snapshot semantics (data_as_of is the open-position clock -- the latest /positions snapshot, else the last completed sync; the snapshot advances only open positions, so resolved/closed aggregates date to the last full sync -- not a live feed; re-fetch for fresher data). ResponseMeta: type: object required: - request_id - cached - cost properties: request_id: type: string description: Unique request ID (req_ prefix). cached: type: boolean cache_age_s: type: integer nullable: true description: Cache age in seconds, null if not cached. cost: type: integer description: >- Advisory request weight (relative compute cost). 1 for simple reads; higher for heavier endpoints. Not a credit/price. directional_source: type: string enum: - live - degraded description: >- Which path produced the team-directional read on this response. Only present on endpoints that compute one (today: GET /api/v1/sports-edge-signals). "live" means the read RAN. "degraded" means it FAILED, so nothing was measured and the ranking fell back to raw conviction. The flag describes the READ, not its consequence: a read that ran and found nothing groupable also leaves the directional fields null, and that is honestly "live" -- the per-signal nulls already say "nothing to enrich here", so this snapshot-level flag carries only what they cannot, namely whether the read ran at all. A degraded response is cached on the shorter degraded TTL so it self-heals. Reported SEPARATELY from ranking_source because the two degradations are independent -- a smart-money DB miss weakens the ranking DATA, a directional failure removes a ranking WEIGHT -- and a consumer down-weighting a degraded response needs to know which input it lost. Omitted on endpoints that compute no directional read. ranking_source: type: string enum: - live - db_only description: >- Which ranking-data path produced this response. Only present on endpoints that can degrade a ranking (today: GET /api/v1/sports-edge-signals). "live" is the normal path (the current holder pile from the provider batch); "db_only" is the degraded fallback (a truthful but weaker trader_markets ranking) served when the live sharp-money ranking batch is unavailable (a smart-money DB read failure, not a Polymarket outage) and cached on a shorter TTL, so a consumer can down-weight or skip it. Omitted on endpoints that never degrade. Trader: type: object required: - id - address - pnl - stats properties: id: type: string description: Prefixed ID (trd_...). address: type: string username: type: string nullable: true grade: type: string enum: - S - A - B - C - D - F nullable: true streak_tier: type: string enum: - hot - rising - neutral - cooling - cold nullable: true description: >- Hot-streak tier (trailing-7d cross-sectional percentile); a separate axis from the all-time grade. Null when no recent activity. score: type: number nullable: true rank: type: integer nullable: true pnl: type: object properties: total: type: number nullable: true realized: type: number nullable: true unrealized: type: number nullable: true last_7d: type: number nullable: true description: >- DEPRECATED, always null. The local pnl_7d rollup over-counted P&L (#5416 class) and is no longer emitted. Read the provider-native weekly window from GET /api/trader/{address}/profile-summary instead. last_30d: type: number nullable: true description: >- DEPRECATED, always null. The local pnl_30d rollup over-counted P&L (#5416 class) and is no longer emitted. Read the provider-native monthly window from GET /api/trader/{address}/profile-summary instead. stats: type: object properties: markets_traded: type: integer nullable: true win_rate: type: number nullable: true daily_win_rate: type: number nullable: true total_volume: type: number nullable: true strategy: type: object nullable: true properties: strategy_type: type: string description: type: string nullable: true confidence: type: number nullable: true category_strengths: type: object nullable: true additionalProperties: true description: >- Per-category performance breakdown (expand=categories or expand[]=categories). Omitted unless expanded. Object keyed by category name; each value is the precomputed trader_rankings.category_ranks payload (rank, total_in_category, total_pnl, scaled_total_pnl, n_markets, wins, losses, win_rate; scaled_total_pnl is a legacy alias that currently equals total_pnl). Pass-through DB JSON: keys and value shape are DB-owned, so the inner shape is intentionally unconstrained and may carry additional compatibility fields. quant_metrics: type: object nullable: true additionalProperties: false required: - smart_score - copy_score - sharpe_30d - sharpe_7d - profit_factor - edge_consistency - sharpe_percentile - pf_percentile - consistency_percentile description: >- Curated advanced risk/performance metrics (expand=quant_metrics or expand[]=quant_metrics). Omitted unless expanded and the trader has computed metrics; when present, all listed fields are present (each is a number or null). null means insufficient trade history and must not be treated as 0. This is a fixed, documented field set, refreshed periodically by the cross-sectional ranking job. properties: smart_score: type: number nullable: true description: >- Composite skill score, 0-100. smart_score = clamp(0, 100, 30*sharpe_percentile_fraction + 20*profit_factor_percentile_fraction + 20*edge_consistency_percentile_fraction + 10*min(1, return_on_capital/2) + 10*equity_smoothness + 10*(1 - min(1, asset_concentration))). Higher is better. null when insufficient history. copy_score: type: number nullable: true description: >- Copyability score, 0-100. Same base as smart_score minus penalties for traits that make a strategy hard to replicate: -20 if fewer than 50 markets traded, -15 if positions are highly concentrated, -15 if position sizing exceeds about 2x Kelly, -10 if the worst single-trade loss exceeds 30%, -10 if edge is inconsistent; result clamped to 0-100. Higher means easier to follow. null when insufficient history. sharpe_30d: type: number nullable: true description: >- Sharpe ratio over the trailing 30 days (risk-adjusted return; higher is better). Magnitude can be large for small samples. null when insufficient history. sharpe_7d: type: number nullable: true description: >- Sharpe ratio over the trailing 7 days (risk-adjusted return; higher is better). null when insufficient history. profit_factor: type: number nullable: true description: >- Gross profit divided by gross loss; greater than 1 is profitable. Capped at 1000 when there are effectively no losses. null when insufficient history. edge_consistency: type: number nullable: true description: >- Stability of the trader's edge over time, 0-1 (higher is more consistent). null when insufficient history. sharpe_percentile: type: number nullable: true description: >- Cross-sectional percentile rank of the trader's Sharpe ratio versus all traders, 0-100. null when insufficient history. pf_percentile: type: number nullable: true description: >- Cross-sectional percentile rank of profit factor versus all traders, 0-100. null when insufficient history. consistency_percentile: type: number nullable: true description: >- Cross-sectional percentile rank of edge consistency versus all traders, 0-100. null when insufficient history. last_active: type: string format: date-time nullable: true synced_at: type: string format: date-time nullable: true sync_status: type: string nullable: true description: synced, unknown, or pending. trust: $ref: '#/components/schemas/TraderTrust' description: >- Field-level trust metadata. Present only when expand=trust or expand[]=trust is requested. ApiError: type: object required: - object - error - meta properties: object: type: string const: error error: type: object required: - code - message properties: code: type: string enum: - bad_request - invalid_api_key - subscription_required - forbidden - not_found - account_locked - rate_limited - rate_limit_unavailable - internal_error message: type: string doc_url: type: string nullable: true param: type: string nullable: true retry_at: type: string format: date-time nullable: true description: >- The recommended next retry instant (RFC3339). Present on every retryable error (reason=pick_not_released, code=rate_limited, code=rate_limit_unavailable, reason=read_model_warming) and omitted otherwise. Always in the future. For pick_not_released it has two regimes: before the 11:00 UTC operating-window start, before a selected pick's stored release, or after a terminal skipped day, it is an exact floor and nothing can publish first. When a publish is overdue or the selector is still hunting inside the operating window, it is a bounded cadence (~60s), not a lower-bound promise; a pick may publish before it. Schedule one request and do not poll. Prefer Retry-After for the duration because it is immune to client clock skew. reason: type: string enum: - cursor_expired - unknown_endpoint - pick_not_released - trader_not_tracked - read_model_warming nullable: true description: >- ADDITIVE (#7209). The specific, actionable cause behind `code`, when there is one more specific than the code itself. `code` keeps its published values, so existing clients are unaffected; new clients branch on `reason`. Omitted when the code already says everything we know. pick_not_released: no Pick of the Day is published for the current product day; schedule one request against retry_at instead of polling. unknown_endpoint: the PATH is not a route on this API -- read GET /api/v1, do not retry. trader_not_tracked: the wallet is real and the URL is right, but the trader is outside the HOT/WARM sync tiers -- stop asking for this wallet. cursor_expired: pagination went stale mid-walk -- re-request the first page and continue. read_model_warming: the requested endpoint cannot serve its read model yet; exact causes are endpoint-specific and can include a cold or contended refresh or a dependency that prevented refresh. Consult that endpoint's contract, retry only this route after the interval, and do not infer dependency health from this reason. meta: $ref: '#/components/schemas/ResponseMeta' TraderTrust: type: object description: >- Field-level trust metadata returned only when GET /api/v1/trader/{address} includes expand=trust. required: - total_pnl - realized_pnl - unrealized_pnl - markets_traded - win_rate - daily_win_rate - total_volume - grade - score - rank - streak_tier - strategy - category_strengths - quant_metrics - last_active - synced_at - sync_status properties: total_pnl: $ref: '#/components/schemas/TrustMetadata' realized_pnl: $ref: '#/components/schemas/TrustMetadata' unrealized_pnl: $ref: '#/components/schemas/TrustMetadata' markets_traded: $ref: '#/components/schemas/TrustMetadata' win_rate: $ref: '#/components/schemas/TrustMetadata' daily_win_rate: $ref: '#/components/schemas/TrustMetadata' total_volume: $ref: '#/components/schemas/TrustMetadata' grade: $ref: '#/components/schemas/TrustMetadata' score: $ref: '#/components/schemas/TrustMetadata' rank: $ref: '#/components/schemas/TrustMetadata' streak_tier: $ref: '#/components/schemas/TrustMetadata' strategy: $ref: '#/components/schemas/TrustMetadata' category_strengths: $ref: '#/components/schemas/TrustMetadata' quant_metrics: $ref: '#/components/schemas/TrustMetadata' last_active: $ref: '#/components/schemas/TrustMetadata' synced_at: $ref: '#/components/schemas/TrustMetadata' sync_status: $ref: '#/components/schemas/TrustMetadata' TrustMetadata: type: object description: >- Shared source/freshness/reconciliation/completeness metadata for public API values that may be cached, stale, partial, computed, or provider-unavailable. Unavailable provider values must be represented with explicit metadata instead of fabricated zeros or empty arrays. required: - source - freshness - reconciliation - completeness properties: source: $ref: '#/components/schemas/TrustSource' freshness: $ref: '#/components/schemas/TrustFreshness' reconciliation: $ref: '#/components/schemas/TrustReconciliation' completeness: $ref: '#/components/schemas/TrustCompleteness' TrustSource: type: object description: >- Source metadata for a trust-critical value. Providers and DB/read models own business truth; clients should not infer missing provider facts from titles, slugs, zeros, or empty arrays. required: - kind - owner properties: kind: type: string enum: - provider - database - cache - computed - client_input - unavailable owner: type: string description: Provider, table/read-model, cache, or service that owns the value. field: type: string nullable: true description: Provider field, DB column, or computed field name when applicable. TrustFreshness: type: object description: >- Freshness metadata for a trust-critical value. This is separate from transport cache fields in ResponseMeta. required: - status properties: status: type: string enum: - fresh - refreshing - stale - not_live - unknown - unavailable as_of: type: string format: date-time nullable: true max_age_s: type: integer nullable: true minimum: 0 TrustReconciliation: type: object description: How provider-owned facts were reconciled with stored/read-model values. required: - status properties: status: type: string enum: - provider_backed - db_mirror - computed - partial - not_applicable - unavailable detail: type: string nullable: true TrustCompleteness: type: object description: >- Whether the described value or result set is complete for its stated contract. required: - status properties: status: type: string enum: - complete - partial - not_computed - not_applicable - unavailable detail: type: string nullable: true headers: X-RateLimit-Limit: description: Authenticated V1 per-user request limit for the current sliding window. schema: type: integer example: 100 X-RateLimit-Remaining: description: >- Authenticated V1 requests remaining in the current sliding window after this response. schema: type: integer example: 84 X-RateLimit-Reset: description: Unix timestamp when the authenticated V1 request window resets. schema: type: integer example: 1710772860 X-Request-Id: description: Server-generated request identifier for support and tracing. schema: type: string example: req_550e8400 ETag: description: >- Weak semantic validator for conditional GET. Request-specific response metadata is excluded; send as If-None-Match to receive 304 when the stable payload is unchanged. schema: type: string example: W/"8f14e45fceea167a5a36dedd4bea2543" responses: BadRequest: description: Invalid request parameter content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiError' SubscriptionRequired: description: Active Insider subscription required content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: Account access denied content: application/json: schema: $ref: '#/components/schemas/ApiError' RequestTimeout: description: >- Request exceeded the server's 30-second transport timeout. The timeout response has an empty body because it is generated before handler-level JSON error shaping. Locked: description: Account is locked content: application/json: schema: $ref: '#/components/schemas/ApiError' RateLimited: description: >- Rate limit exceeded. Two independent budgets. (1) 100 requests/minute per user (sliding window), on every authenticated route. (2) On the BATCH routes only: 2500 batch item units/minute per user, reserved before any item is executed. A batch with N requested items costs N item units, including duplicate and invalid items. 2500 = 100 requests x 25 items per batch, which is the most item work a key can buy through the request limiter at all: a caller may spend their entire 100-request minute on full 25-item batches without the item budget being what stops them. The REQUEST budget is the effective ceiling, and batching is never the more expensive choice. The item budget still denies at a sliding-window boundary (both counters carry the previous window forward with a floor, and the item counter runs 25x the request counter), so honor a 429 from either. Over-quota batches return 429 with Retry-After before any item work is done. headers: Retry-After: description: Seconds until rate limit resets. schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer X-Request-Id: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ApiError' InternalError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ApiError' RateLimitUnavailable: description: >- Redis-backed authenticated rate limiter unavailable; retry after the per-process outage cooldown headers: Retry-After: description: >- Seconds until the middleware will probe the Redis-backed rate limiter again. schema: type: integer X-Request-Id: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key authentication. Send your key in the Authorization header as `Bearer oxi_sk_live_...`. Live keys require an active Insider subscription and return live data. ````