{ "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." }, { "url": "https://api.0xinsider.com", "description": "Sandbox / test mode (deterministic fixture data, no live rows). Authenticate with a test key (oxi_sk_test_...) on a free account. Same base URL and paths as production: the key class selects live vs sandbox. Test keys are billing-exempt, served from a fixed fixture dataset, and never read live data or persist writes; webhooks, usage, and MCP responses show the response shape only." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1": { "get": { "operationId": "getApiDiscovery", "summary": "API discovery", "description": "Unauthenticated API-origin discovery document pointing agents to the canonical API base URL, full docs, web-origin OpenAPI spec, health check, and representative authenticated data routes.", "tags": [ "System" ], "security": [], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.0xinsider.com/api/v1'" } ], "responses": { "200": { "description": "API discovery document", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "api_discovery" }, "data": { "$ref": "#/components/schemas/ApiDiscovery" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "object": "api_discovery", "data": { "api_base_url": "https://api.0xinsider.com", "docs_url": "https://0xinsider.com/llms-full.txt", "openapi_url": "https://0xinsider.com/api/v1/openapi.json", "health_url": "https://api.0xinsider.com/api/v1/health", "authentication": "Bearer API key required for data endpoints; discovery (/api/v1), health, and /api/v1/platforms are public.", "authenticated_routes": [ "GET /api/v1/markets/search" ] }, "meta": { "request_id": "req_550e8400-e29b-41d4-a716-446655440000", "cached": false, "cache_age_s": null } } } } }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/openapi.json": { "get": { "operationId": "redirectApiOpenapiSpec", "summary": "Redirect to the canonical OpenAPI spec", "description": "Unauthenticated API-origin compatibility redirect to the canonical web-origin OpenAPI JSON document at https://0xinsider.com/api/v1/openapi.json.", "tags": [ "System" ], "security": [], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -I 'https://api.0xinsider.com/api/v1/openapi.json'" } ], "responses": { "307": { "description": "Temporary redirect to the canonical web-origin OpenAPI spec.", "headers": { "Location": { "description": "Canonical OpenAPI spec URL.", "schema": { "type": "string", "format": "uri", "const": "https://0xinsider.com/api/v1/openapi.json" }, "example": "https://0xinsider.com/api/v1/openapi.json" } } }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/trader/{address}": { "get": { "operationId": "getTrader", "summary": "Get trader intelligence", "description": "Returns a trader's cohort-relative skill grade (S through F; calibration, risk-adjusted returns, and consistency, not profit size), P&L, win rate, and optional strategy/category data. The path accepts either an Ethereum wallet address, a known trader username, or a trd_-prefixed trader ID emitted by this API. Unknown lookups return sync_status \"unknown\" instead of 404.", "tags": [ "Traders" ], "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": "expand[]", "in": "query", "required": false, "description": "Backward-compatible alias for expand. Repeatable: strategy, categories, quant_metrics, trust.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "strategy", "categories", "quant_metrics", "trust" ] } }, "style": "form", "explode": true }, { "name": "expand", "in": "query", "required": false, "description": "Include heavy fields and trust metadata. Repeatable: strategy, categories, quant_metrics, trust.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "strategy", "categories", "quant_metrics", "trust" ] } }, "style": "form", "explode": true }, { "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 profile", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "trader" }, "data": { "$ref": "#/components/schemas/Trader" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "traders", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/trader/{address}'" } ], "x-examples": { "success": { "object": "traders", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/traders/batch": { "post": { "operationId": "batchGetTraders", "summary": "Batch trader intelligence", "description": "Returns trader intelligence for 1-25 wallet addresses or known usernames. Results preserve request order, duplicate inputs return duplicate rows, and each item is charged one batch item unit before execution. Unknown trader lookups return data with sync_status \"unknown\" matching the single trader endpoint.", "tags": [ "Traders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "traders" ], "properties": { "traders": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string" } }, "expand": { "type": "array", "items": { "type": "string", "enum": [ "strategy", "categories", "quant_metrics", "trust" ] }, "description": "Shared expand flags applied to every trader item." } } }, "example": { "traders": [ "swisstony", "0x0000000000000000000000000000000000000000" ], "expand": [ "strategy" ] } } } }, "responses": { "200": { "description": "Ordered batch trader results", "headers": { "X-Request-Cost": { "schema": { "type": "integer" }, "description": "Number of batch item units charged for this request." }, "X-Batch-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Batch item units allowed per minute." }, "X-Batch-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Batch item units remaining in the current sliding window." }, "X-Batch-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the batch item window resets." }, "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" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "trader_batch" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchTraderItem" } }, "meta": { "$ref": "#/components/schemas/BatchResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "traders", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "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 \\\n -X POST \\\n -H 'Authorization: Bearer $OXI_SK' \\\n -H 'Content-Type: application/json' \\\n -d '{\"traders\":[\"swisstony\",\"0x0000000000000000000000000000000000000000\"],\"expand\":[\"strategy\"]}' \\\n 'https://api.0xinsider.com/api/v1/traders/batch'" } ], "x-examples": { "success": { "object": "traders", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/trader/{address}/position-timeline": { "get": { "operationId": "getPositionTimeline", "summary": "Get a trader's position timeline for one market", "description": "Returns every Polymarket fill for one trader in one market, newest first, with server-computed running_amount and running_avg_price. Only HOT and WARM tier traders are tracked; other traders return 404. running_avg_price is a buy-weighted entry basis (sells do not change the running average) matching Polymarket /positions avgPrice semantics. Cursor-paginated. An id-keyed alias exists at GET /api/v1/traders/{id}/position-timeline.", "tags": [ "Traders" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Trader wallet address (0x...) or trd_-prefixed trader ID emitted by this API. Case-insensitive wallet addresses are lowercased server-side.", "schema": { "type": "string" } }, { "name": "condition_id", "in": "query", "required": true, "description": "Market condition_id. One timeline per (trader, market).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response's next_cursor.", "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": "Position timeline page", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PositionTimelineEvent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "404": { "$ref": "#/components/responses/NotFound" }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/trader/{address}/position-timeline'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/trader/{address}/pnl": { "get": { "operationId": "getTraderPnl", "summary": "Get trader P&L time series", "description": "Returns a trader's daily P&L time series and pre-derived stats from the precomputed daily_pnl read model: entries (daily cumulative P&L), period stats (all/90d/30d/7d), monthly aggregation, per-year totals, and the drawdown series. Reads the refreshed read model, not a per-request equity replay. A resolved trader with no daily P&L returns an empty structured object (HTTP 200); an unknown address returns 404. Spans both providers wherever the read model has the trader's series.", "tags": [ "Traders" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Wallet address (0x...), username, or trd_-prefixed trader id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trader P&L object", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "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" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "trader_pnl" }, "data": { "$ref": "#/components/schemas/TraderPnl" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "example": { "object": "trader_pnl", "data": { "id": "trd_0xabc123", "entries": [ { "date": "2026-05-12", "markets_traded": 3, "total_volume": 10000.0, "cumulative_profit": 50000.0, "total_pnl": 50000.0, "daily_change": 250.0 } ], "stats": { "all": { "current": 50000.0, "change": 50000.0, "change_pct": 0.0, "best_day": 5000.0, "worst_day": -2000.0, "win_days": 30, "loss_days": 10, "avg_day": 250.0, "rebase_anchor": 0.0 }, "d90": { "current": 12000.0, "change": 12000.0, "change_pct": 31.5, "best_day": 5000.0, "worst_day": -2000.0, "win_days": 18, "loss_days": 6, "avg_day": 500.0, "rebase_anchor": 38000.0 }, "d30": { "current": 4000.0, "change": 4000.0, "change_pct": 8.7, "best_day": 2500.0, "worst_day": -800.0, "win_days": 9, "loss_days": 3, "avg_day": 333.0, "rebase_anchor": 46000.0 }, "d7": { "current": 900.0, "change": 900.0, "change_pct": 1.8, "best_day": 600.0, "worst_day": -150.0, "win_days": 4, "loss_days": 1, "avg_day": 180.0, "rebase_anchor": 49100.0 } }, "monthly": [ { "year": 2026, "month": 5, "pnl": 12000.0, "markets_traded": 18 } ], "year_totals": [ { "year": 2026, "pnl": 50000.0 } ], "drawdown": [ { "date": "2026-05-12", "cumulative_profit": 50000.0, "drawdown": -1500.0 } ] }, "meta": { "request_id": "req_example", "cached": false } } } } }, "304": { "description": "Not Modified. Returned when If-None-Match matches the current payload.", "headers": { "ETag": { "description": "Validator for the unchanged payload.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/trader/0xabc123/pnl'" } ] } }, "/api/v1/traders/{trader}/position-timeline": { "get": { "operationId": "getPositionTimelineById", "summary": "Get a trader's position timeline (unified identity resolver)", "description": "Unified trader-timeline route (#4975). {trader} accepts all four identity shapes - 0x... wallet, username, trd_-prefixed trader id, and bare integer id - resolved by the single shared trader-identity resolver. Returns every Polymarket fill for one trader in one market, newest first, with server-computed running_amount and running_avg_price. Only HOT and WARM tier traders are tracked; other traders return 404. Response body is byte-identical to the singular GET /api/v1/trader/{address}/position-timeline route for the same (trader, market). The prior integer-id-only variant is preserved: the same path now accepts every identity shape.", "tags": [ "Traders" ], "parameters": [ { "name": "trader", "in": "path", "required": true, "description": "Trader identity: 0x... wallet address, username, trd_-prefixed trader id, or bare integer traders.id. Resolved with precedence wallet -> trd_ -> integer -> username. Unknown identities return 404.", "schema": { "type": "string" } }, { "name": "condition_id", "in": "query", "required": true, "description": "Market condition_id. One timeline per (trader, market).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response's next_cursor.", "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": "Position timeline page", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PositionTimelineEvent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "404": { "$ref": "#/components/responses/NotFound" }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/traders/{id}/position-timeline'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/positions": { "get": { "operationId": "listPositions", "summary": "List current positions (positions-board feed)", "description": "Returns the current positions-board feed backed by the wallet_positions mirror. Ordered by current_value_usd DESC with deterministic (wallet, condition_id, outcome_index) tiebreakers. Pre-reconcile rows (current_value_usd IS NULL) are excluded. Cursor-paginated. Every filter pushes into SQL.", "tags": [ "Positions" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response's next_cursor.", "schema": { "type": "string" } }, { "name": "min_size", "in": "query", "description": "Minimum current position value in USD.", "schema": { "type": "number", "default": 100 } }, { "name": "category", "in": "query", "description": "Exact match against provider-backed market_canonical.category.", "schema": { "type": "string" } }, { "name": "min_grade", "in": "query", "description": "Minimum trader grade allowlist. `A` matches S and A; `B` matches S, A, B; etc.", "schema": { "type": "string", "enum": [ "S", "A", "B", "C", "D", "F" ] } }, { "name": "side", "in": "query", "description": "Filter by the binary outcome side. `yes` maps to outcome_index=0, `no` to outcome_index=1.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "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": "Page of positions", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/positions'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/large-positions": { "get": { "operationId": "listLargePositions", "summary": "List large positions", "description": "Returns the largest current open positions from graded traders, value-descending, with opaque cursor pagination. Polymarket-only by design: the large-positions scanner filters platform = 'polymarket' (backend/src/large_positions/scanner.rs:238,245), so no Kalshi rows are ever scanned and a Kalshi or unknown condition_id filter returns an empty list (never fabricated rows). The teaser cap that the internal product UI applies to anonymous viewers does not apply here: the API key already proves an active insider/annual subscription, so authed API callers get full access.", "tags": [ "Large Positions" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string" } }, { "name": "min_size", "in": "query", "description": "Minimum position value in USD.", "schema": { "type": "number", "minimum": 0 } }, { "name": "category", "in": "query", "description": "Filter by provider-backed market category.", "schema": { "type": "string" } }, { "name": "min_grade", "in": "query", "description": "Minimum trader grade.", "schema": { "type": "string", "enum": [ "S", "A", "B", "C", "D", "F" ] } }, { "name": "condition_id", "in": "query", "description": "Scope to one market. Accepts the raw provider condition_id or the mkt_-prefixed market id (round-trips a value from a list response). Polymarket-only; a Kalshi or unknown id returns [].", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Large positions list", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "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" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LargePosition" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page; absent on the last page." }, "total": { "type": "integer", "nullable": true, "description": "Total ranked rows when the read model exposes a count; may be absent." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "304": { "description": "Not Modified. Returned when If-None-Match matches the current payload.", "headers": { "ETag": { "description": "Validator for the unchanged payload.", "schema": { "type": "string" } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/large-positions?min_grade=A&limit=10'" } ] } }, "/api/v1/whale-trades": { "get": { "operationId": "listWhaleTrades", "summary": "List whale trades", "description": "Returns recent large trades with signal scoring. Filter by size, category, or trader grade. Filters are applied before pagination, and every request uses SQL-backed limit + 1 pagination so has_more and next_cursor reflect the filtered result set. Cursor-paginated, newest first. Market categories come from provider-backed market_canonical identity.", "tags": [ "Whale Trades" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response's next_cursor.", "schema": { "type": "string" } }, { "name": "min_size", "in": "query", "description": "Minimum trade size in USD.", "schema": { "type": "number", "default": 5000 } }, { "name": "category", "in": "query", "description": "Filter by market category (case-insensitive). A canonical bucket name (e.g. Basketball) matches every provider member that folds into it (NBA, WNBA, NCAAB); a raw provider value also resolves to its bucket.", "schema": { "type": "string" } }, { "name": "min_grade", "in": "query", "description": "Minimum trader grade.", "schema": { "type": "string", "enum": [ "S", "A", "B", "C", "D", "F" ] } }, { "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": "List of whale trades", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhaleTrade" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/whale-trades'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/whale-trades/history": { "get": { "operationId": "listWhaleTradeHistory", "summary": "Replay historical whale trades", "description": "Returns historical whale trades from local whale_alerts rows, not request-time provider fetches. Filter by condition_id, trader, category, minimum grade, platform, and RFC3339 from/to windows. All filters are pushed into SQL before LIMIT, every request uses SQL-backed limit + 1 pagination, and results are ordered newest first by traded_at desc, id desc. Metadata exposes local_replay source and best_effort completeness.", "tags": [ "Whale Trades" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response's next_cursor. Prefix: wth_. URL-encode when replaying as a query parameter.", "schema": { "type": "string" } }, { "name": "min_size", "in": "query", "description": "Minimum trade size in USD.", "schema": { "type": "number", "default": 5000 } }, { "name": "condition_id", "in": "query", "description": "Exact raw provider condition_id. Unknown markets return an empty list.", "schema": { "type": "string" } }, { "name": "trader", "in": "query", "description": "Trader wallet address, timestamp-suffixed wallet alias, or username resolved against the traders table. Unknown traders return an empty list.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by market category (case-insensitive). A canonical bucket name (e.g. Basketball) matches every provider member that folds into it (NBA, WNBA, NCAAB); a raw provider value also resolves to its bucket.", "schema": { "type": "string" } }, { "name": "min_grade", "in": "query", "description": "Minimum trader grade.", "schema": { "type": "string", "enum": [ "S", "A", "B", "C", "D", "F" ] } }, { "name": "platform", "in": "query", "description": "Filter by whale_alerts.platform. all is equivalent to omitted.", "schema": { "type": "string", "enum": [ "polymarket", "kalshi", "all" ] } }, { "name": "from", "in": "query", "description": "Inclusive RFC3339 lower bound on whale_alerts.traded_at.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "Exclusive RFC3339 upper bound on whale_alerts.traded_at. Must be after from when both are present.", "schema": { "type": "string", "format": "date-time" } }, { "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": "Historical whale trade replay", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhaleTrade" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "$ref": "#/components/schemas/WhaleTradeHistoryMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/whale-trades/history'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/whale-trades/{id}": { "get": { "operationId": "getWhaleTrade", "summary": "Get whale trade by ID", "description": "Returns one whale trade by raw whale_alerts.id or the wt_-prefixed id emitted by list and history responses.", "tags": [ "Whale Trades" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Raw whale_alerts.id or wt_-prefixed whale trade id.", "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": "Whale trade", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "whale_trade" }, "data": { "$ref": "#/components/schemas/WhaleTrade" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "whale_trade", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/whale-trades/wt_123'" } ], "x-examples": { "success": { "object": "whale_trade", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/leaderboard": { "get": { "operationId": "listLeaderboard", "summary": "Get trader leaderboard", "description": "Returns ranked traders (grades S/A/B) sorted by score descending. Supports cursor pagination and optional category/strategy filters.", "tags": [ "Leaderboard" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor (score_address format).", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by category. Values are matched to canonical category buckets: political variants (Elections, Global Politics, U.S. Politics, ...) fold into Politics, Geopolitics stays distinct, Culture/Entertainment map to Pop Culture, Science maps to Science & Tech, and Finance/Business map to Stocks. Mapped buckets are case-insensitive; passthrough categories (Crypto, NBA, and the sports leagues) match case-sensitively against the provider-native bucket key, so use exact casing (e.g. Crypto, NBA).", "schema": { "type": "string" } }, { "name": "strategy", "in": "query", "description": "Filter by ML-detected strategy type. Values come from backend/src/trader_analysis/classification/decision_tree.rs and are matched exactly against trader_classifications.primary_type. Unknown values currently match zero rows; the handler does not return HTTP 400.", "schema": { "type": "string", "enum": [ "accumulator", "algo_trader", "arbitrageur", "directional", "event_driven", "market_maker", "momentum", "scalper", "speculator", "swing_trader" ] } }, { "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": "Ranked trader list", "headers": { "ETag": { "description": "Stable validator for the current leaderboard payload. Re-send it via If-None-Match for conditional GETs.", "schema": { "type": "string" } }, "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" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaderboardEntry" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "304": { "description": "Not Modified. Returned when If-None-Match matches the current leaderboard payload.", "headers": { "ETag": { "description": "Validator for the unchanged leaderboard payload.", "schema": { "type": "string" } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/leaderboard'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/leaderboard/trending": { "get": { "operationId": "listTrendingWallets", "summary": "List trending wallets", "description": "Returns wallets ranked by trailing-window realized P&L (Polymarket-only discovery), with opaque page-cursor pagination. Each row carries window P&L, volume, distinct markets, grade, hot-streak tier, and a zero-filled daily P&L series. The underlying read model is warmed into Redis; a cold read returns 503 (warming, retry-after), never a 500 or a fabricated ranking. Polymarket-only: the read model filters platform = 'polymarket'.", "tags": [ "Leaderboard" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor from a previous response.", "schema": { "type": "string" } }, { "name": "window", "in": "query", "description": "Trailing window.", "schema": { "type": "string", "enum": [ "7d", "30d" ], "default": "7d" } } ], "responses": { "200": { "description": "Trending wallets list", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "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" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrendingWallet" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page; absent on the last page." }, "total": { "type": "integer", "nullable": true, "description": "Total ranked rows when the read model exposes a count; may be absent." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "304": { "description": "Not Modified. Returned when If-None-Match matches the current payload.", "headers": { "ETag": { "description": "Validator for the unchanged payload.", "schema": { "type": "string" } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/leaderboard/trending?window=7d&limit=10'" } ] } }, "/api/v1/markets/search": { "get": { "operationId": "searchMarkets", "summary": "Search markets", "description": "Search prediction markets by keyword. Returns representative market matches with status, category, and platform metadata. Cursor pagination advances over grouped market results rather than raw sub-market rows.", "tags": [ "Markets" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query. Must be 1-512 characters before whitespace trimming and non-empty after trimming.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response's next_cursor.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by market status.", "schema": { "type": "string", "enum": [ "active", "closed", "all" ], "default": "all" } }, { "name": "category", "in": "query", "description": "Filter by category.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketSearchResult" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/markets/search'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/markets/explore": { "get": { "operationId": "exploreMarkets", "summary": "Explore markets", "description": "Browse whale-active titled markets with category, platform, status, and keyword filters. Paginates visible discovery entries rather than raw market rows, returns live category/platform facets alongside grouped event clusters or standalone markets, and includes total on the first page only. Categories come straight from provider metadata (Polymarket Gamma, Kalshi) and facets are flat value/label/count rows.", "tags": [ "Markets" ], "parameters": [ { "name": "category", "in": "query", "description": "Filter by market category (case-insensitive). A canonical bucket name (e.g. Basketball) matches every provider member that folds into it (NBA, WNBA, NCAAB); a raw provider value also resolves to its bucket. Facet values are returned as the canonical bucket.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by market status.", "schema": { "type": "string", "enum": [ "active", "closed", "all" ], "default": "all" } }, { "name": "platform", "in": "query", "description": "Filter by source platform.", "schema": { "type": "string", "enum": [ "polymarket", "kalshi", "all" ], "default": "all" } }, { "name": "sort", "in": "query", "description": "Sort order for the discovery feed.", "schema": { "type": "string", "enum": [ "trending", "hot", "expiring", "whales", "volume", "newest" ], "default": "trending" } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor from the previous response.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 48, "default": 24 } }, { "name": "q", "in": "query", "description": "Keyword search against market titles.", "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": "Grouped market discovery results", "headers": { "ETag": { "description": "Stable validator for the current explore payload. Re-send it via If-None-Match for conditional GETs.", "schema": { "type": "string" } }, "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" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "facets", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExploreEntry" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "total": { "type": "integer", "nullable": true, "description": "Total matching visible entries after grouping. Present on the first page and omitted on cursor pages." }, "facets": { "$ref": "#/components/schemas/ExploreFacets" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "304": { "description": "Not Modified. Returned when If-None-Match matches the current explore payload.", "headers": { "ETag": { "description": "Validator for the unchanged explore payload.", "schema": { "type": "string" } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/markets/explore'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/markets/smart-money-flows": { "get": { "operationId": "listSmartMoneyFlows", "summary": "List ranked smart-money flows", "description": "Ranks markets by absolute net S/A/B-grade whale flow over a requested timeframe. Use this discovery endpoint to answer where smart money is flowing before drilling into a specific market with /api/v1/market/{condition_id}/intel. Pagination is anchored by an opaque cursor carrying the first page as_of timestamp so new whale trades do not reorder page 2.", "tags": [ "Markets" ], "parameters": [ { "name": "timeframe", "in": "query", "description": "Lookback window for grade-filtered whale flow aggregation.", "schema": { "type": "string", "enum": [ "1h", "4h", "24h", "7d" ], "default": "24h" } }, { "name": "limit", "in": "query", "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from previous response's next_cursor. Encodes the first-page as_of timestamp plus the last row's absolute net flow and condition_id.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by market category (case-insensitive). A canonical bucket name (e.g. Basketball) matches every provider member that folds into it (NBA, WNBA, NCAAB); a raw provider value also resolves to its bucket.", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "description": "Filter by source platform. all is a request-side no-op.", "schema": { "type": "string", "enum": [ "polymarket", "kalshi", "all" ], "default": "all" } }, { "name": "min_grade", "in": "query", "description": "Minimum latest trader grade included in the flow. Default B means S/A/B only; unranked traders are excluded.", "schema": { "type": "string", "enum": [ "S", "A", "B", "C", "D", "F" ], "default": "B" } }, { "name": "direction", "in": "query", "description": "Optional post-aggregate flow direction filter.", "schema": { "type": "string", "enum": [ "YES", "NO" ] } }, { "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": "Ranked market smart-money flows", "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" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmartMoneyFlowMarket" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "total": { "type": "integer", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [ { "market": { "id": "mkt_0x123", "condition_id": "0x123", "title": "Will BTC close above $100k this week?", "slug": "btc-close-above-100k-this-week", "category": "Crypto", "platform": "polymarket" }, "smart_money": { "net_flow_usd": 12345.67, "direction": "YES", "whale_trade_count": 7, "buy_volume_usd": 20000, "sell_volume_usd": 7654.33 }, "timeframe": "24h" } ], "has_more": false, "next_cursor": null, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/markets/smart-money-flows?timeframe=7d&min_grade=B&limit=10'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/platforms": { "get": { "operationId": "getPlatforms", "summary": "Get platform capability matrix", "description": "Unauthenticated discovery endpoint that declares which V1 intelligence surfaces are supported, partial, or unsupported per provider platform.", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "Platform capability matrix", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "platforms" }, "data": { "$ref": "#/components/schemas/Platforms" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "platforms", "data": { "platforms": { "polymarket": { "grade": "supported", "pnl": "supported", "strategy": "supported", "timeline": "supported", "whale_signal": "supported", "insider_radar": "supported", "market_snapshot": "supported" }, "kalshi": { "grade": "unsupported", "pnl": "partial", "strategy": "unsupported", "timeline": "partial", "whale_signal": "unsupported", "insider_radar": "unsupported", "market_snapshot": "partial" } } }, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS 'https://api.0xinsider.com/api/v1/platforms'" } ], "x-examples": { "success": { "object": "platforms", "data": { "platforms": { "polymarket": { "grade": "supported", "pnl": "supported", "strategy": "supported", "timeline": "supported", "whale_signal": "supported", "insider_radar": "supported", "market_snapshot": "supported" }, "kalshi": { "grade": "unsupported", "pnl": "partial", "strategy": "unsupported", "timeline": "partial", "whale_signal": "unsupported", "insider_radar": "unsupported", "market_snapshot": "partial" } } }, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/market/{condition_id}/intel": { "get": { "operationId": "getMarketIntel", "summary": "Get market intelligence", "description": "Smart money flow analysis for a specific market — net flow direction, whale trade count, buy/sell volumes, and top graded trader positions.", "tags": [ "Markets" ], "parameters": [ { "name": "condition_id", "in": "path", "required": true, "description": "Market condition ID. Accepts the raw provider-backed condition_id returned by /api/v1/markets/search or the mkt_-prefixed market.id emitted by V1 responses.", "schema": { "type": "string" } }, { "name": "timeframe", "in": "query", "description": "Lookback window for whale flow aggregation.", "schema": { "type": "string", "enum": [ "1h", "4h", "24h", "7d" ], "default": "24h" } }, { "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": "Market intelligence", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "market_intel" }, "data": { "$ref": "#/components/schemas/MarketIntel" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "markets", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/market/{condition_id}/intel'" } ], "x-examples": { "success": { "object": "markets", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/markets/intel/batch": { "post": { "operationId": "batchGetMarketIntel", "summary": "Batch market intelligence", "description": "Returns smart-money market intelligence for 1-25 raw provider condition_id values. Results preserve request order, duplicate inputs return duplicate rows, and each item is charged one batch item unit before execution. Do not pass prefixed mkt_ IDs; use market.condition_id from search or explore.", "tags": [ "Markets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "condition_ids" ], "properties": { "condition_ids": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string" } }, "timeframe": { "type": "string", "enum": [ "1h", "4h", "24h", "7d" ], "default": "24h" } } }, "example": { "condition_ids": [ "0x1234567890abcdef" ], "timeframe": "24h" } } } }, "responses": { "200": { "description": "Ordered batch market intelligence results", "headers": { "X-Request-Cost": { "schema": { "type": "integer" }, "description": "Number of batch item units charged for this request." }, "X-Batch-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Batch item units allowed per minute." }, "X-Batch-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Batch item units remaining in the current sliding window." }, "X-Batch-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the batch item window resets." }, "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" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "market_intel_batch" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchMarketIntelItem" } }, "meta": { "$ref": "#/components/schemas/BatchResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "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 \\\n -X POST \\\n -H 'Authorization: Bearer $OXI_SK' \\\n -H 'Content-Type: application/json' \\\n -d '{\"condition_ids\":[\"0x1234567890abcdef\"],\"timeframe\":\"24h\"}' \\\n 'https://api.0xinsider.com/api/v1/markets/intel/batch'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/market/{condition_id}/snapshot": { "get": { "operationId": "getMarketSnapshot", "summary": "Get market live snapshot", "description": "Provider-first market card snapshot with canonical identity, outcome labels, cached top-of-book when available, liquidity, live sports context, and explicit freshness/unavailable states.", "tags": [ "Markets" ], "parameters": [ { "name": "condition_id", "in": "path", "required": true, "description": "Market condition ID. Accepts the raw provider-backed condition_id returned by /api/v1/markets/search or /api/v1/markets/explore, or the mkt_-prefixed market.id emitted by V1 responses.", "schema": { "type": "string" } }, { "name": "expand[]", "in": "query", "required": false, "description": "Backward-compatible alias for expand. Repeatable: trust.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "trust" ] } }, "style": "form", "explode": true }, { "name": "expand", "in": "query", "required": false, "description": "Include trust metadata for current_price and spread_bps. Repeatable: trust.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "trust" ] } }, "style": "form", "explode": true }, { "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": "Provider-first market snapshot", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "market_snapshot" }, "data": { "$ref": "#/components/schemas/MarketSnapshot" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "markets", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/market/{condition_id}/snapshot'" } ], "x-examples": { "success": { "object": "markets", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/insider-radar": { "get": { "operationId": "listInsiderRadar", "summary": "Get insider radar flags", "description": "Suspicious trading patterns — pre-resolution accumulation, coordinated wallets, unusual timing. Cursor-paginated by suspicion score.", "tags": [ "Insider Radar" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response.", "schema": { "type": "string" } }, { "name": "min_suspicion", "in": "query", "description": "Minimum suspicion score (0-100).", "schema": { "type": "number", "default": 0 } }, { "name": "severity", "in": "query", "description": "Filter by severity level.", "schema": { "type": "string", "enum": [ "flag", "watch" ] } }, { "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": "Radar flags list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RadarFlag" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "insider_radar", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/insider-radar'" } ], "x-examples": { "success": { "object": "insider_radar", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/insider-radar/{id}": { "get": { "operationId": "getInsiderRadarFlag", "summary": "Get insider radar flag by ID", "description": "Returns one suspicious-trading radar flag by raw radar_flags.id or the rf_-prefixed id emitted by list responses.", "tags": [ "Insider Radar" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Raw radar_flags.id or rf_-prefixed radar flag id.", "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": "Radar flag", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "radar_flag" }, "data": { "$ref": "#/components/schemas/RadarFlag" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "radar_flag", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/insider-radar/rf_123'" } ], "x-examples": { "success": { "object": "radar_flag", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/stream": { "get": { "operationId": "getStream", "summary": "Resumable real-time event stream (SSE)", "description": "Server-Sent Events stream of the live feed envelopes the platform already broadcasts (whale-trade pulses and other public/insider feed events). Forwards the same backend-owned envelope shape as the internal feed; no provider data is recomputed. Authenticated via the oxi_sk Bearer key like every other /api/v1 endpoint, and limited to a small number of concurrent connections per API key and a cluster-wide ceiling across all keys (HTTP 429 with Retry-After when either cap is exceeded; HTTP 503 with Retry-After if the admission backend is briefly unavailable). Each delivered frame carries an SSE id equal to the envelope sequence; reconnect with the Last-Event-ID header (or the last_event_id / seq query fallback) to replay the missed window before resuming live. When the requested resume point predates the retained window the stream emits one resync marker event (event: resync) instead of silently skipping frames. Idle connections receive periodic ': keep-alive' comment lines. This is a long-lived response: keep the connection open and read frames as they arrive.", "tags": [ "Streaming" ], "parameters": [ { "name": "Last-Event-ID", "in": "header", "required": false, "description": "Sequence id of the last frame the client successfully processed. The stream replays the strictly-newer window before resuming live. Browser EventSource clients send this automatically on reconnect. Omit to attach live from now.", "schema": { "type": "string" } }, { "name": "last_event_id", "in": "query", "required": false, "description": "Query-string fallback for the Last-Event-ID resume cursor when the client cannot set the request header. Numeric sequence id; non-numeric or absent attaches live with no replay.", "schema": { "type": "string" } }, { "name": "seq", "in": "query", "required": false, "description": "Alias for last_event_id. Numeric sequence id to resume after; non-numeric or absent attaches live with no replay.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Open Server-Sent Events stream. The body is an unbounded text/event-stream of frames; each data frame is a JSON feed envelope (with seq, published_at, type, and event-specific fields) and carries an SSE id equal to seq. resync marker frames use event: resync.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Newline-delimited SSE frames: 'id: \\ndata: \\n\\n' for events, 'event: resync\\nid: \\ndata: \\n\\n' for resync markers, and ': keep-alive' comment lines while idle." }, "examples": { "whaleEvent": { "summary": "One live whale-trade event frame", "value": "id: 142\ndata: {\"seq\":142,\"published_at\":\"2026-06-04T12:00:00Z\",\"type\":\"WhaleTradesInserted\",\"count\":3}\n\n" }, "resyncMarker": { "summary": "Resync marker after a too-old resume point", "value": "event: resync\nid: 9001\ndata: {\"type\":\"resync\",\"completeness\":{\"status\":\"truncated\",\"reason\":\"The requested Last-Event-ID predates the retained replay window; treat this as a full resync and refetch current state.\"},\"from_sequence\":12,\"to_sequence\":9001}\n\n" } } } }, "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" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -N -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/stream'" }, { "lang": "curl", "label": "cURL (resume)", "source": "curl -N -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n -H 'Last-Event-ID: 100' \\\n 'https://api.0xinsider.com/api/v1/stream'" } ] } }, "/api/v1/events/feed/since": { "get": { "operationId": "getEventReplaySince", "summary": "Replay public whale-trade intelligence events", "description": "Returns durable public whale-trade intelligence events strictly after an opaque cursor backed by whale_alerts.id. This is a separate API-key contract from the browser/session /api/events/feed stream: browser-only and private alert, following, radar, and position patch events are excluded until they have a durable public outbox.", "tags": [ "Events" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque event replay cursor returned as next_cursor by a prior response. The cursor maps to whale_alerts.id and is valid across backend replicas. Omit to fetch the latest durable public suffix.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum durable public whale-trade events to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Public event replay window", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "meta" ], "properties": { "object": { "type": "string", "const": "event_replay" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventReplayEvent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "meta": { "$ref": "#/components/schemas/EventReplayMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "events", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "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" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/events/feed/since'" } ], "x-examples": { "success": { "object": "events", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List builder webhook destinations", "description": "Returns webhook destinations owned by the authenticated API key user. Disabled endpoints are omitted.", "tags": [ "Webhooks" ], "responses": { "200": { "$ref": "#/components/responses/WebhookList" }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/webhooks'" } ], "x-examples": { "success": { "object": "list", "data": [ { "id": 1, "object": "webhook", "name": "Production webhook", "url": "https://example.com/0xinsider/webhook", "event_types": [ "whale_trades_inserted" ], "status": "pending_verification" } ], "has_more": false, "next_cursor": null, "meta": { "request_id": "req_example", "cached": false } } } }, "post": { "operationId": "createWebhook", "summary": "Create a builder webhook destination", "description": "Creates a pending HTTPS webhook destination. The response includes one-time signing_secret and verification.token values. Deliveries are not sent until the endpoint is verified.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" }, "example": { "name": "Production webhook", "url": "https://example.com/0xinsider/webhook", "event_types": [ "whale_trades_inserted" ] } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookObject" }, "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" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/IdempotencyConflict" }, "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 \\\n -X POST \\\n -H 'Authorization: Bearer $OXI_SK' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"Production webhook\",\"url\":\"https://example.com/0xinsider/webhook\",\"event_types\":[\"whale_trades_inserted\"]}' \\\n 'https://api.0xinsider.com/api/v1/webhooks'" } ], "x-examples": { "success": { "object": "webhook", "data": { "id": 1, "object": "webhook", "name": "Production webhook", "url": "https://example.com/0xinsider/webhook", "event_types": [ "whale_trades_inserted" ], "status": "pending_verification" }, "meta": { "request_id": "req_example", "cached": false } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Get one builder webhook destination", "description": "Returns one webhook destination owned by the authenticated API key user.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "$ref": "#/components/responses/WebhookObject" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/webhooks/{id}'" } ], "x-examples": { "success": { "object": "webhook", "data": { "id": 1, "object": "webhook", "name": "Production webhook", "url": "https://example.com/0xinsider/webhook", "event_types": [ "whale_trades_inserted" ], "status": "pending_verification" }, "meta": { "request_id": "req_example", "cached": false } } } }, "patch": { "operationId": "updateWebhook", "summary": "Update a builder webhook destination", "description": "Updates name, HTTPS URL, event types, or enabled state. URL changes force pending_verification and return a new verification token.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" }, "example": { "name": "Updated webhook", "enabled": true } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookObject" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/IdempotencyConflict" }, "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 \\\n -X PATCH \\\n -H 'Authorization: Bearer $OXI_SK' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"Updated webhook\",\"enabled\":true}' \\\n 'https://api.0xinsider.com/api/v1/webhooks/{id}'" } ], "x-examples": { "success": { "object": "webhook", "data": { "id": 1, "object": "webhook", "name": "Production webhook", "url": "https://example.com/0xinsider/webhook", "event_types": [ "whale_trades_inserted" ], "status": "pending_verification" }, "meta": { "request_id": "req_example", "cached": false } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Disable a builder webhook destination", "description": "Soft-deletes a webhook destination owned by the authenticated API key user. Existing delivery audit rows remain retained.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/WebhookObject" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/IdempotencyConflict" }, "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 \\\n -X DELETE \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/webhooks/{id}'" } ], "x-examples": { "success": { "object": "webhook", "data": { "id": 1, "object": "webhook", "name": "Production webhook", "url": "https://example.com/0xinsider/webhook", "event_types": [ "whale_trades_inserted" ], "status": "pending_verification" }, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/webhooks/{id}/verify": { "post": { "operationId": "verifyWebhook", "summary": "Verify a builder webhook destination", "description": "Activates a pending webhook destination when the one-time verification token matches and has not expired.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyWebhookRequest" }, "example": { "verification_token": "whv_example" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookObject" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "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 \\\n -X POST \\\n -H 'Authorization: Bearer $OXI_SK' \\\n -H 'Content-Type: application/json' \\\n -d '{\"verification_token\":\"whv_example\"}' \\\n 'https://api.0xinsider.com/api/v1/webhooks/{id}/verify'" } ], "x-examples": { "success": { "object": "webhooks", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate a builder webhook signing secret", "description": "Rotates the endpoint signing secret and returns the new signing_secret once in the response.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/WebhookObject" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/IdempotencyConflict" }, "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 \\\n -X POST \\\n -H 'Authorization: Bearer $OXI_SK' \\\n -H 'Content-Type: application/json' \\\n -d '{}' \\\n 'https://api.0xinsider.com/api/v1/webhooks/{id}/rotate-secret'" } ], "x-examples": { "success": { "object": "webhook", "data": { "id": 1, "object": "webhook", "name": "Production webhook", "url": "https://example.com/0xinsider/webhook", "event_types": [ "whale_trades_inserted" ], "status": "pending_verification" }, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/health": { "get": { "operationId": "getHealth", "summary": "Health check", "description": "Returns API health status. No authentication required. Limited to 60 requests per minute per IP.", "tags": [ "System" ], "security": [], "parameters": [ { "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": "Health status", "headers": { "ETag": { "description": "Stable validator for the current health payload. Re-send it via If-None-Match for conditional GETs.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "health" }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "down", "maintenance" ] }, "db": { "type": "boolean" }, "cache": { "type": "boolean" }, "subsystems": { "type": "object", "required": [ "background_jobs" ], "properties": { "background_jobs": { "type": "object", "required": [ "status", "checked", "total", "healthy", "stale", "missing", "invalid", "unconfigured" ], "description": "Public-safe aggregate status for expected background job successful-completion heartbeats. Does not expose Redis keys, job names, raw errors, provider payloads, wallet addresses, or condition IDs.", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "down", "not_checked" ] }, "checked": { "type": "boolean" }, "total": { "type": "integer", "minimum": 0 }, "healthy": { "type": "integer", "minimum": 0 }, "stale": { "type": "integer", "minimum": 0 }, "missing": { "type": "integer", "minimum": 0 }, "invalid": { "type": "integer", "minimum": 0 }, "unconfigured": { "type": "integer", "minimum": 0 } } } } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "health", "data": { "status": "ok" }, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "304": { "description": "Not Modified. Returned when If-None-Match matches the current health payload.", "headers": { "ETag": { "description": "Validator for the unchanged health payload.", "schema": { "type": "string" } } } }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/health'" } ], "x-examples": { "success": { "object": "health", "data": { "status": "ok" }, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/mcp": { "post": { "operationId": "createMcpJsonRpcResponse", "summary": "Remote MCP endpoint (JSON-RPC)", "description": "Model Context Protocol (MCP) Streamable HTTP transport. Accepts a JSON-RPC 2.0 request and returns a JSON-RPC response. Supported methods: initialize, notifications/initialized, ping, tools/list, tools/call. Remote MCP exposes 29 read-only tools for public V1 read operations: get_leaderboard, get_trader, batch_get_traders, get_whale_trades, get_whale_trade, get_whale_trades_history, get_market_intel, batch_get_market_intel, get_smart_money_flows, get_market_snapshot, get_insider_radar, get_insider_radar_flag, get_positions, get_position_timeline, get_position_timeline_by_id, search_markets, explore_markets, get_event_replay_since, list_webhooks, get_webhook, get_daily_report_snapshot, get_weekly_report_snapshot, get_monthly_report_snapshot, get_report, get_trader_export_snapshot, get_platforms, get_large_positions, get_trending_wallets, get_trader_pnl. Webhook create/update/delete/verify/rotate operations are intentionally not exposed as remote MCP tools. The remote endpoint advertises tools only; it does not implement resources/list, resources/read, prompts/list, or prompts/get. Each tool dispatches to the matching /api/v1/* handler in-process so auth, rate limits, and payload shape match. Auth should use Authorization: Bearer . ?token= remains a legacy compatibility path for URL-only MCP clients, but URL secrets can land in shell history, browser history, and logs, so prefer headers or the stdio package. Mcp-Session-Id is minted on initialize and echoed on every response. Origin header, when present, is validated against the 0xinsider + localhost allowlist.", "tags": [ "MCP" ], "parameters": [ { "name": "token", "in": "query", "required": false, "description": "Deprecated compatibility API-key query parameter for remote MCP clients that cannot send Authorization headers. Prefer Authorization: Bearer or the stdio package because URL secrets are easier to leak through logs and history.", "schema": { "type": "string" } }, { "name": "Mcp-Session-Id", "in": "header", "required": false, "description": "Session ID minted by the server on initialize; echoed on every subsequent request.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "initialize", "notifications/initialized", "ping", "tools/list", "tools/call" ] }, "params": { "type": "object" } } }, "example": {} } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "id" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "result": { "type": "object" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "mcp", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "202": { "description": "Notification acknowledged (no body)", "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" } } }, "400": { "description": "JSON-RPC parse or invalid-request error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "Origin rejected or tier forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -X POST \\\n -H 'Authorization: Bearer $OXI_SK' \\\n -H 'Content-Type: application/json' \\\n -d '{}' \\\n 'https://api.0xinsider.com/api/v1/mcp'" } ], "x-examples": { "success": { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-11-25" } } } }, "get": { "operationId": "openMcpEventStream", "summary": "Open MCP server-to-client stream", "description": "Opens a text/event-stream connection for server-initiated notifications as described in the MCP Streamable HTTP transport. The endpoint currently sends no notifications — clients that only care about request/response use POST.", "tags": [ "MCP" ], "parameters": [ { "name": "token", "in": "query", "required": false, "description": "API key as query parameter (same contract as POST).", "schema": { "type": "string" } }, { "name": "Mcp-Session-Id", "in": "header", "required": false, "description": "Session ID minted by the server on initialize.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "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" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Origin rejected" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/mcp'" } ], "x-examples": { "success": { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-11-25" } } } } }, "/api/v1/reports": { "get": { "operationId": "getReports", "summary": "Unified report snapshot (granularity selector)", "description": "Unified convenience route (#4975) that consolidates the three singular report routes. Dispatches to the exact per-granularity cap (daily 50, weekly 100, monthly 200) and date window the legacy /api/v1/reports/{daily,weekly,monthly} routes use, so the response body is byte-identical to the matching legacy route for the same period. The three legacy routes stay live. Also reachable via the MCP get_report selector.", "tags": [ "Reports" ], "parameters": [ { "name": "granularity", "in": "query", "required": true, "description": "Report granularity selector.", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] } }, { "name": "period", "in": "query", "required": true, "description": "Period token for the granularity. daily: UTC date YYYY-MM-DD. weekly: ISO week YYYY-WW, or a from,to YYYY-MM-DD pair. monthly: UTC month YYYY-MM.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Daily report snapshot", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "report_snapshot" }, "data": { "$ref": "#/components/schemas/ReportSnapshot" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/reports?granularity=daily&period=2026-02-17'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } }, "x-mcp-tool": "get_report" } }, "/api/v1/reports/daily": { "get": { "operationId": "getDailyReportSnapshot", "summary": "Daily report snapshot", "description": "Returns a dated daily whale-activity report snapshot with source_range, snapshot.status, completeness, and reconciliation metadata. Report whale volume is local whale-alert activity volume, not provider lifetime trader volume.", "tags": [ "Reports" ], "parameters": [ { "name": "date", "in": "query", "required": true, "description": "UTC report date in YYYY-MM-DD format.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Daily report snapshot", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "report_snapshot" }, "data": { "$ref": "#/components/schemas/ReportSnapshot" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/reports/daily'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/reports/weekly": { "get": { "operationId": "getWeeklyReportSnapshot", "summary": "Weekly report snapshot", "description": "Returns a weekly whale-activity report snapshot. Pass either from/to UTC dates or an ISO YYYY-WW week token. The response identifies closed ranges as final and current ranges as rolling.", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "UTC source-range start in YYYY-MM-DD format; required with to.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "UTC source-range end in YYYY-MM-DD format; required with from.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "week", "in": "query", "required": false, "description": "ISO week selector in YYYY-WW format; alternative to from/to.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } } ], "responses": { "200": { "description": "Weekly report snapshot", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "report_snapshot" }, "data": { "$ref": "#/components/schemas/ReportSnapshot" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/reports/weekly'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/reports/monthly": { "get": { "operationId": "getMonthlyReportSnapshot", "summary": "Monthly report snapshot", "description": "Returns a UTC monthly whale-activity report snapshot with source_range, completeness, and reconciliation metadata.", "tags": [ "Reports" ], "parameters": [ { "name": "month", "in": "query", "required": true, "description": "UTC report month in YYYY-MM format.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } } ], "responses": { "200": { "description": "Monthly report snapshot", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "report_snapshot" }, "data": { "$ref": "#/components/schemas/ReportSnapshot" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/reports/monthly'" } ], "x-examples": { "success": { "object": "list", "data": [], "has_more": false, "next_cursor": null, "total": 0, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/trader/{address}/export": { "get": { "operationId": "getTraderExportSnapshot", "summary": "Trader export snapshot metadata", "description": "Returns export source-range, completeness, volume reconciliation, row-count estimate, and large-export policy for one trader. V1 is metadata-only; full raw dataset export remains on the internal streaming or async export route.", "tags": [ "Traders" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Trader wallet address (0x...), known trader username-style lookup, or trd_-prefixed trader ID emitted by this API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trader export snapshot metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "trader_export_snapshot" }, "data": { "$ref": "#/components/schemas/TraderExportSnapshot" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "examples": { "success": { "summary": "Successful response", "value": { "object": "traders", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "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 \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/trader/{address}/export'" } ], "x-examples": { "success": { "object": "traders", "data": {}, "meta": { "request_id": "req_example", "cached": false } } } } }, "/api/v1/usage": { "get": { "tags": [ "Usage" ], "operationId": "getUsage", "summary": "Inspect current API usage without spending primary request quota", "description": "Returns the authenticated caller sliding-window request budget and UTC-day usage. This endpoint is authenticated and does not increment the primary Redis rate-limit counter or log itself into the API usage table; it is separately throttled at 100 reads/minute per user to protect the usage-count query.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Usage budget and counters for the authenticated API key owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "examples": { "success": { "summary": "Successful response", "value": { "object": "usage", "data": { "rate_limit": { "used": 7, "limit": 100, "remaining": 93, "reset_at": 1710772860, "window_seconds": 60 }, "daily_usage": { "used": 42, "limit": null, "remaining": null, "reset_at": 1710806400, "window_seconds": 86400 } }, "meta": { "request_id": "req_example", "cached": false } } } } } }, "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" } } }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -sS \\\n -H 'Authorization: Bearer $OXI_SK' \\\n 'https://api.0xinsider.com/api/v1/usage'" } ], "x-examples": { "success": { "object": "usage", "data": { "rate_limit": { "used": 7, "limit": 100, "remaining": 93, "reset_at": 1710772860, "window_seconds": 60 }, "daily_usage": { "used": 42, "limit": null, "remaining": null, "reset_at": 1710806400, "window_seconds": 86400 } }, "meta": { "request_id": "req_example", "cached": false } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key: Authorization: Bearer oxi_sk_live_... for live data (requires an active Insider subscription), or oxi_sk_test_... for sandbox/test mode (free account, deterministic fixture data, no live rows). Both key classes use the same paths; the prefix selects live vs sandbox." } }, "parameters": { "WebhookId": { "name": "id", "in": "path", "required": true, "description": "Webhook endpoint id owned by the authenticated API key user.", "schema": { "type": "integer", "format": "int64" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional safe-retry key. Reuse the same value only when retrying the exact same mutation request body; a different body returns 422 and an in-flight matching request returns 409.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "wh_idem_01HX7Y9ZQ4K7Z0Q2E4N6A8C1BF" } }, "schemas": { "WebhookEventType": { "type": "string", "enum": [ "whale_trades_inserted", "live_sports_updated", "whale_trader_synced", "large_positions_updated" ] }, "WebhookStatus": { "type": "string", "enum": [ "pending_verification", "active", "disabled" ] }, "WebhookRetryPolicy": { "type": "object", "required": [ "max_attempts", "terminal_status" ], "properties": { "max_attempts": { "type": "integer", "const": 8 }, "terminal_status": { "type": "string", "const": "dead_letter" } } }, "WebhookVerification": { "type": "object", "required": [ "token", "expires_at" ], "properties": { "token": { "type": "string", "description": "One-time verification token returned only on create or URL change." }, "expires_at": { "type": "string", "format": "date-time" } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "object", "name", "url", "event_types", "status", "verification_token_expires_at", "failure_count", "created_at", "updated_at", "retry_policy" ], "properties": { "id": { "type": "integer", "format": "int64" }, "object": { "type": "string", "const": "webhook" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "status": { "$ref": "#/components/schemas/WebhookStatus" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "verification_token_expires_at": { "type": "string", "format": "date-time" }, "failure_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "retry_policy": { "$ref": "#/components/schemas/WebhookRetryPolicy" }, "signing_secret": { "type": "string", "description": "Returned only on create or rotate-secret." }, "verification": { "$ref": "#/components/schemas/WebhookVerification" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "name", "url", "event_types" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "url": { "type": "string", "format": "uri", "description": "Public HTTPS callback URL. Local/private/internal targets are rejected." }, "event_types": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventType" } } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "enabled": { "type": "boolean" } } }, "VerifyWebhookRequest": { "type": "object", "required": [ "verification_token" ], "properties": { "verification_token": { "type": "string" } } }, "ResponseMeta": { "type": "object", "required": [ "request_id", "cached" ], "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." } } }, "ApiDiscovery": { "type": "object", "required": [ "api_base_url", "docs_url", "openapi_url", "health_url", "authentication", "authenticated_routes" ], "properties": { "api_base_url": { "type": "string", "format": "uri", "description": "Canonical API origin for public V1 requests." }, "docs_url": { "type": "string", "format": "uri", "description": "Full agent-readable API reference." }, "openapi_url": { "type": "string", "format": "uri", "description": "Canonical web-origin OpenAPI JSON document." }, "health_url": { "type": "string", "format": "uri", "description": "Unauthenticated API health endpoint." }, "authentication": { "type": "string", "const": "Bearer API key required for data endpoints; discovery (/api/v1), health, and /api/v1/platforms are public." }, "authenticated_routes": { "type": "array", "description": "Representative authenticated data routes. Full route coverage lives in OpenAPI and llms-full.txt.", "items": { "type": "string" } } } }, "WhaleTradeHistoryMeta": { "type": "object", "required": [ "request_id", "cached", "source", "completeness" ], "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." }, "source": { "type": "object", "required": [ "kind", "table", "provider_fetch_at_request_time" ], "properties": { "kind": { "type": "string", "const": "local_replay" }, "table": { "type": "string", "const": "whale_alerts" }, "provider_fetch_at_request_time": { "type": "boolean", "const": false } } }, "completeness": { "type": "object", "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "const": "best_effort" }, "reason": { "type": "string", "description": "Explains that local replay completeness can vary by market and time window." } } } } }, "EventReplayEvent": { "type": "object", "required": [ "id", "type", "cursor", "sequence", "published_at", "payload", "source", "freshness" ], "properties": { "id": { "type": "string", "description": "Opaque event ID; currently identical to cursor for the whale_alerts.id sequence." }, "type": { "type": "string", "enum": [ "whale_trades_inserted" ] }, "cursor": { "type": "string", "description": "Cursor positioned at this event." }, "sequence": { "type": "integer", "minimum": 1, "description": "Global whale_alerts.id sequence." }, "published_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "additionalProperties": true }, "source": { "$ref": "#/components/schemas/EventReplaySource" }, "freshness": { "$ref": "#/components/schemas/EventReplayFreshness" } } }, "EventReplaySource": { "type": "object", "required": [ "kind", "producer_family", "owner", "provider_fetch_at_request_time" ], "properties": { "kind": { "type": "string", "const": "local_durable_replay" }, "producer_family": { "type": "string", "enum": [ "whale_trades" ] }, "owner": { "type": "string", "const": "whale_alerts" }, "provider_fetch_at_request_time": { "type": "boolean", "const": false } } }, "EventReplayFreshness": { "type": "object", "required": [ "status", "observed_at" ], "properties": { "status": { "type": "string", "const": "observed" }, "observed_at": { "type": "string", "format": "date-time" } } }, "EventReplayMeta": { "type": "object", "required": [ "request_id", "cached", "replay", "retention", "completeness" ], "properties": { "request_id": { "type": "string", "description": "Unique request ID (req_ prefix)." }, "cached": { "type": "boolean" }, "cache_age_s": { "type": "integer", "nullable": true }, "replay": { "type": "object", "required": [ "from_cursor", "to_cursor", "from_sequence", "to_sequence", "ordering" ], "properties": { "from_cursor": { "type": "string" }, "to_cursor": { "type": "string" }, "from_sequence": { "type": "integer", "minimum": 0 }, "to_sequence": { "type": "integer", "minimum": 0 }, "ordering": { "type": "string", "const": "whale_alerts_id_asc" } } }, "retention": { "type": "object", "required": [ "status", "retained_events", "cursor_expired" ], "properties": { "status": { "type": "string", "enum": [ "durable_database" ] }, "retained_events": { "type": "integer", "minimum": 0 }, "cursor_expired": { "type": "boolean", "const": false } } }, "completeness": { "type": "object", "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "enum": [ "complete", "caught_up" ] }, "reason": { "type": "string" } } } } }, "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 } } }, "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" } } }, "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" } } }, "PlatformCapabilityStatus": { "type": "string", "enum": [ "supported", "partial", "unsupported" ] }, "PlatformCapabilities": { "type": "object", "required": [ "grade", "pnl", "strategy", "timeline", "whale_signal", "insider_radar", "market_snapshot" ], "properties": { "grade": { "$ref": "#/components/schemas/PlatformCapabilityStatus" }, "pnl": { "$ref": "#/components/schemas/PlatformCapabilityStatus" }, "strategy": { "$ref": "#/components/schemas/PlatformCapabilityStatus" }, "timeline": { "$ref": "#/components/schemas/PlatformCapabilityStatus" }, "whale_signal": { "$ref": "#/components/schemas/PlatformCapabilityStatus" }, "insider_radar": { "$ref": "#/components/schemas/PlatformCapabilityStatus" }, "market_snapshot": { "$ref": "#/components/schemas/PlatformCapabilityStatus" } } }, "Platforms": { "type": "object", "required": [ "platforms" ], "properties": { "platforms": { "type": "object", "required": [ "kalshi", "polymarket" ], "properties": { "kalshi": { "$ref": "#/components/schemas/PlatformCapabilities" }, "polymarket": { "$ref": "#/components/schemas/PlatformCapabilities" } } } } }, "PositionTimelineEvent": { "type": "object", "required": [ "id", "event_timestamp", "action", "outcome_side", "amount_delta", "price", "usdc_notional", "tx_hash", "running_amount", "running_avg_price" ], "properties": { "id": { "type": "string", "description": "Prefixed ID (pe_...)." }, "event_timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of the on-chain fill." }, "action": { "type": "string", "enum": [ "buy", "sell" ], "description": "From the taker's perspective." }, "outcome_side": { "type": "string", "enum": [ "yes", "no" ] }, "amount_delta": { "type": "number", "description": "Signed share delta (+ on buy, − on sell)." }, "price": { "type": "number", "description": "Fill price in USDC per share, in [0,1]." }, "usdc_notional": { "type": "number", "description": "Positive USDC notional of the fill." }, "tx_hash": { "type": "string", "description": "Polygon transaction hash of the fill." }, "running_amount": { "type": "number", "description": "Cumulative signed share balance after this fill." }, "running_avg_price": { "type": "number", "description": "Buy-weighted entry basis (matches Polymarket /positions avgPrice semantics). Sells do not change this value. 0 when no buys have occurred yet." } } }, "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 }, "last_30d": { "type": "number", "nullable": true } } }, "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). Null 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." } } }, "Position": { "type": "object", "required": [ "id", "platform", "wallet", "side", "shares", "current_value_usd", "freshness", "trader", "market" ], "properties": { "id": { "type": "string", "description": "Composite prefixed ID `pos_::`." }, "platform": { "type": "string", "enum": [ "polymarket", "kalshi" ], "description": "Provider discriminator. Slice 5 ships Polymarket only; the field stays in the response shape so Kalshi positions can land without a breaking change." }, "wallet": { "type": "string", "description": "Lowercased proxy wallet address." }, "side": { "type": "string", "enum": [ "YES", "NO" ], "description": "Binary outcome side. Non-binary positions are not surfaced on V1." }, "shares": { "type": "number", "description": "Live share count from the wallet_positions mirror." }, "avg_price": { "type": "number", "nullable": true, "description": "Volume-weighted entry price for this leg." }, "current_value_usd": { "type": "number", "description": "Current mark-to-market value in USD (always non-null on V1 — pre-reconcile rows are excluded)." }, "initial_value_usd": { "type": "number", "nullable": true }, "cash_pnl": { "type": "number", "nullable": true, "description": "Unrealized P&L for the open position (Polymarket `cashPnl`)." }, "realized_pnl": { "type": "number", "nullable": true, "description": "Closed-leg P&L rolled up (Polymarket `realizedPnl`)." }, "last_reconciled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Max updated_at across mirror legs for this pair." }, "freshness": { "type": "string", "enum": [ "fresh", "refreshing", "stale", "unknown" ], "description": "Backend-computed staleness bucket derived from last_reconciled_at." }, "trader": { "type": "object", "required": [ "id", "address", "is_new_wallet" ], "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 }, "win_rate": { "type": "number", "nullable": true, "description": "Percentage 0-100." }, "pnl": { "type": "number", "nullable": true }, "markets": { "type": "integer", "nullable": true }, "wallet_age_days": { "type": "number", "nullable": true }, "is_new_wallet": { "type": "boolean", "description": "Wallet is younger than the new-wallet threshold (30 days)." } } }, "market": { "type": "object", "required": [ "id", "condition_id", "title" ], "properties": { "id": { "type": "string", "description": "Prefixed ID (`mkt_...`)." }, "condition_id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "event_slug": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true, "description": "Provider-backed market_canonical category." }, "outcome_label": { "type": "string", "nullable": true, "description": "Provider-reported outcome label (e.g. team name for sports). Separate from `side` because provider labels can diverge from the binary Yes/No axis." }, "end_date": { "type": "string", "format": "date-time", "nullable": true } } } } }, "WhaleTrade": { "type": "object", "required": [ "id", "traded_at", "size_usd", "side", "price", "signal_score", "trader", "market" ], "properties": { "id": { "type": "string", "description": "Prefixed ID (wt_...)." }, "traded_at": { "type": "string", "format": "date-time" }, "size_usd": { "type": "number" }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "price": { "type": "number" }, "signal_score": { "type": "number", "description": "0.0–1.0 normalized signal score." }, "trader": { "type": "object", "required": [ "id", "address" ], "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "username": { "type": "string", "nullable": true }, "grade": { "type": "string", "nullable": true } } }, "market": { "type": "object", "required": [ "id", "condition_id", "title" ], "properties": { "id": { "type": "string" }, "condition_id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true, "description": "Provider-backed market_canonical category." } } } } }, "LeaderboardEntry": { "type": "object", "required": [ "id", "address", "platform" ], "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "username": { "type": "string", "nullable": true }, "grade": { "type": "string", "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 }, "pnl": { "type": "number", "nullable": true }, "volume": { "type": "number", "nullable": true }, "markets_traded": { "type": "integer", "nullable": true }, "win_rate": { "type": "number", "nullable": true }, "strategy_type": { "type": "string", "nullable": true }, "platform": { "type": "string" }, "last_active": { "type": "string", "format": "date-time", "nullable": true } } }, "MarketSearchResult": { "type": "object", "required": [ "id", "condition_id", "title", "status" ], "properties": { "id": { "type": "string" }, "condition_id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "closed" ] } } }, "ExploreMarket": { "type": "object", "required": [ "id", "condition_id", "title", "status" ], "properties": { "id": { "type": "string" }, "condition_id": { "type": "string" }, "title": { "type": "string", "minLength": 1, "description": "Non-empty market title." }, "slug": { "type": "string", "nullable": true, "description": "Provider-native market slug." }, "url_slug": { "type": "string", "nullable": true, "description": "First-party market page slug used for internal links." }, "image": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "volume": { "type": "number", "nullable": true }, "liquidity": { "type": "number", "nullable": true }, "whale_trade_count": { "type": "integer", "nullable": true }, "whale_distinct_wallets": { "type": "integer", "nullable": true }, "whale_total_usd": { "type": "number", "nullable": true }, "whale_last_trade_at": { "type": "string", "format": "date-time", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "outcome_yes": { "type": "string", "nullable": true }, "outcome_no": { "type": "string", "nullable": true }, "event_slug": { "type": "string", "nullable": true }, "kalshi_series_slug": { "type": "string", "nullable": true }, "smart_score": { "type": "number", "nullable": true }, "smart_count": { "type": "integer", "nullable": true }, "smart_label": { "type": "string", "nullable": true }, "outcome_yes_label": { "type": "string", "nullable": true, "description": "Display label for the YES/outcome_index=0 side, enriched from provider outcome metadata when available." }, "outcome_no_label": { "type": "string", "nullable": true, "description": "Display label for the NO/outcome_index=1 side, enriched from provider outcome metadata when available." }, "outcome_yes_provider_id": { "type": "integer", "nullable": true, "description": "Provider-owned YES/outcome_index=0 identifier when available for trade-ticket wiring." }, "outcome_no_provider_id": { "type": "integer", "nullable": true, "description": "Provider-owned NO/outcome_index=1 identifier when available for trade-ticket wiring." }, "open_interest": { "type": "number", "nullable": true }, "oi_change_pct": { "type": "number", "nullable": true }, "price_points": { "type": "array", "nullable": true, "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" } } }, "no_price_points": { "type": "array", "nullable": true, "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" } } }, "last_price": { "type": "number", "nullable": true }, "no_last_price": { "type": "number", "nullable": true }, "change_pct_24h": { "type": "number", "nullable": true }, "no_change_pct_24h": { "type": "number", "nullable": true }, "discover_score": { "type": "number", "nullable": true, "description": "Backend-owned deterministic market discovery score used by the hot sort." }, "score_components": { "type": "object", "required": [ "missing_price_penalty" ], "properties": { "volume_signal": { "type": "number", "nullable": true }, "whale_signal": { "type": "number", "nullable": true }, "liquidity_signal": { "type": "number", "nullable": true }, "recency_signal": { "type": "number", "nullable": true }, "smart_money_signal": { "type": "number", "nullable": true }, "price_move_signal": { "type": "number", "nullable": true }, "missing_price_penalty": { "type": "number" } } }, "freshness": { "type": "object", "required": [ "enrichment_status", "price_status" ], "properties": { "enrichment_status": { "type": "string", "enum": [ "available", "unavailable" ] }, "price_status": { "type": "string", "enum": [ "available", "unavailable" ] } } } } }, "ExploreGroup": { "type": "object", "required": [ "type", "event_slug", "parent_title", "markets" ], "properties": { "type": { "type": "string", "const": "group" }, "event_slug": { "type": "string" }, "parent_title": { "type": "string" }, "image": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "markets": { "type": "array", "items": { "$ref": "#/components/schemas/ExploreMarket" } }, "rep_volume": { "type": "number", "nullable": true }, "rep_whales": { "type": "integer", "nullable": true } } }, "ExploreStandalone": { "type": "object", "required": [ "type", "market" ], "properties": { "type": { "type": "string", "const": "standalone" }, "market": { "$ref": "#/components/schemas/ExploreMarket" } } }, "ExploreFacetValue": { "type": "object", "required": [ "value", "label", "count" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" } } }, "ExploreFacets": { "type": "object", "required": [ "categories", "platforms" ], "properties": { "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ExploreFacetValue" } }, "platforms": { "type": "array", "items": { "$ref": "#/components/schemas/ExploreFacetValue" } } } }, "ExploreEntry": { "oneOf": [ { "$ref": "#/components/schemas/ExploreGroup" }, { "$ref": "#/components/schemas/ExploreStandalone" } ], "discriminator": { "propertyName": "type", "mapping": { "group": "#/components/schemas/ExploreGroup", "standalone": "#/components/schemas/ExploreStandalone" } } }, "MarketIntel": { "type": "object", "required": [ "market", "smart_money", "timeframe" ], "properties": { "market": { "type": "object", "required": [ "id", "condition_id", "title" ], "properties": { "id": { "type": "string" }, "condition_id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true } } }, "smart_money": { "type": "object", "required": [ "net_flow_usd", "direction", "whale_trade_count", "buy_volume_usd", "sell_volume_usd", "top_positions" ], "properties": { "net_flow_usd": { "type": "number" }, "direction": { "type": "string", "enum": [ "YES", "NO" ] }, "whale_trade_count": { "type": "integer" }, "buy_volume_usd": { "type": "number" }, "sell_volume_usd": { "type": "number" }, "top_positions": { "type": "array", "items": { "type": "object", "required": [ "id", "address", "side", "size_usd" ], "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "username": { "type": "string", "nullable": true }, "grade": { "type": "string", "nullable": true }, "side": { "type": "string", "enum": [ "YES", "NO" ] }, "size_usd": { "type": "number" } } } } } }, "timeframe": { "type": "string" } } }, "SmartMoneyFlowMarket": { "type": "object", "required": [ "market", "smart_money", "timeframe" ], "properties": { "market": { "type": "object", "required": [ "id", "condition_id", "title", "slug", "category", "platform" ], "properties": { "id": { "type": "string" }, "condition_id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true } } }, "smart_money": { "type": "object", "required": [ "net_flow_usd", "direction", "whale_trade_count", "buy_volume_usd", "sell_volume_usd" ], "properties": { "net_flow_usd": { "type": "number" }, "direction": { "type": "string", "enum": [ "YES", "NO" ] }, "whale_trade_count": { "type": "integer" }, "buy_volume_usd": { "type": "number" }, "sell_volume_usd": { "type": "number" } } }, "timeframe": { "type": "string" } } }, "MarketSnapshotFreshness": { "type": "object", "required": [ "status", "source" ], "properties": { "status": { "type": "string", "enum": [ "fresh", "stale", "available", "not_live", "unavailable" ] }, "source": { "type": "string" }, "as_of": { "type": "string", "format": "date-time", "nullable": true }, "stale_after_s": { "type": "integer", "nullable": true }, "reason": { "type": "string", "nullable": true } } }, "MarketSnapshotTopOfBook": { "type": "object", "required": [ "status", "source" ], "properties": { "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "source": { "type": "string" }, "best_bid": { "type": "number", "nullable": true }, "best_ask": { "type": "number", "nullable": true }, "spread_bps": { "type": "integer", "nullable": true }, "bid_depth_usdc": { "type": "number", "nullable": true }, "ask_depth_usdc": { "type": "number", "nullable": true }, "reason": { "type": "string", "nullable": true } } }, "MarketSnapshotTrust": { "type": "object", "description": "Price and spread trust metadata returned only when GET /api/v1/market/{condition_id}/snapshot includes expand=trust.", "required": [ "current_price", "spread_bps" ], "properties": { "current_price": { "$ref": "#/components/schemas/TrustMetadata" }, "spread_bps": { "$ref": "#/components/schemas/TrustMetadata" } } }, "MarketSnapshot": { "type": "object", "required": [ "market", "outcomes", "liquidity", "sports", "freshness" ], "properties": { "market": { "type": "object", "required": [ "id", "condition_id", "provider", "status" ], "properties": { "id": { "type": "string" }, "condition_id": { "type": "string" }, "provider": { "type": "string" }, "title": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "page_slug": { "type": "string", "nullable": true }, "event_slug": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "description": { "type": "string", "nullable": true }, "image": { "type": "string", "nullable": true }, "series_slug": { "type": "string", "nullable": true }, "kalshi_series_slug": { "type": "string", "nullable": true }, "market_type": { "type": "string", "nullable": true }, "market_result": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "end_date": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true } } }, "outcomes": { "type": "array", "items": { "type": "object", "required": [ "side", "label", "top_of_book" ], "properties": { "side": { "type": "string", "enum": [ "yes", "no" ] }, "label": { "type": "string" }, "token_id": { "type": "string", "nullable": true }, "current_price": { "type": "number", "nullable": true }, "top_of_book": { "$ref": "#/components/schemas/MarketSnapshotTopOfBook" } } } }, "liquidity": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string" }, "volume_usd": { "type": "number", "nullable": true }, "liquidity_usd": { "type": "number", "nullable": true }, "volume_24h_usd": { "type": "number", "nullable": true }, "last_price": { "type": "number", "nullable": true } } }, "sports": { "type": "object", "required": [ "status", "source" ], "properties": { "status": { "type": "string", "enum": [ "fresh", "stale", "not_live", "unavailable" ] }, "source": { "type": "string" }, "live_match_key": { "type": "string", "nullable": true }, "live_league_key": { "type": "string", "nullable": true }, "live_score": { "type": "object", "nullable": true }, "reason": { "type": "string", "nullable": true } } }, "freshness": { "type": "object", "required": [ "market_data", "top_of_book", "live_sports" ], "properties": { "market_data": { "$ref": "#/components/schemas/MarketSnapshotFreshness" }, "top_of_book": { "$ref": "#/components/schemas/MarketSnapshotFreshness" }, "live_sports": { "$ref": "#/components/schemas/MarketSnapshotFreshness" } } }, "trust": { "$ref": "#/components/schemas/MarketSnapshotTrust", "description": "Price and spread trust metadata. Present only when expand=trust or expand[]=trust is requested." } } }, "RadarFlag": { "type": "object", "required": [ "id", "suspicion_score", "severity", "trader", "market", "scores", "evidence", "created_at" ], "properties": { "id": { "type": "string", "description": "Prefixed ID (rf_...)." }, "suspicion_score": { "type": "number" }, "severity": { "type": "string", "enum": [ "flag", "watch" ] }, "trader": { "type": "object", "required": [ "id", "address" ], "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "username": { "type": "string", "nullable": true } } }, "market": { "type": "object", "required": [ "id", "condition_id", "title" ], "properties": { "id": { "type": "string" }, "condition_id": { "type": "string" }, "title": { "type": "string" } } }, "scores": { "type": "object", "properties": { "timing": { "type": "number", "nullable": true }, "edge": { "type": "number", "nullable": true }, "size": { "type": "number", "nullable": true }, "fresh_wallet": { "type": "number", "nullable": true } } }, "evidence": { "description": "Structured evidence JSON." }, "created_at": { "type": "string", "format": "date-time" } } }, "ApiErrorBody": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "doc_url": { "type": "string", "nullable": true }, "param": { "type": "string", "nullable": true } } }, "BatchRateLimitMeta": { "type": "object", "required": [ "basis", "limit", "remaining", "reset" ], "properties": { "basis": { "type": "string", "const": "batch_items_per_minute" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "reset": { "type": "integer", "description": "Unix timestamp when the batch item window resets." } } }, "BatchResponseMeta": { "type": "object", "required": [ "request_id", "cached", "total_items", "successful_items", "failed_items", "request_cost", "rate_limit" ], "properties": { "request_id": { "type": "string" }, "cached": { "type": "boolean" }, "total_items": { "type": "integer" }, "successful_items": { "type": "integer" }, "failed_items": { "type": "integer" }, "request_cost": { "type": "integer", "description": "Number of batch item units reserved before execution." }, "rate_limit": { "$ref": "#/components/schemas/BatchRateLimitMeta" } } }, "BatchTraderItem": { "type": "object", "required": [ "index", "input", "status" ], "properties": { "index": { "type": "integer", "description": "Zero-based request index. Duplicate inputs keep separate result rows." }, "input": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "data": { "$ref": "#/components/schemas/Trader" }, "error": { "$ref": "#/components/schemas/ApiErrorBody" } } }, "BatchMarketIntelItem": { "type": "object", "required": [ "index", "input", "status" ], "properties": { "index": { "type": "integer", "description": "Zero-based request index. Duplicate inputs keep separate result rows." }, "input": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "data": { "$ref": "#/components/schemas/MarketIntel" }, "error": { "$ref": "#/components/schemas/ApiErrorBody" } } }, "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 } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ReportSnapshot": { "type": "object", "required": [ "kind", "generated_at", "source_range", "snapshot", "completeness", "reconciliation", "report" ], "properties": { "kind": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "generated_at": { "type": "string", "format": "date-time" }, "source_range": { "$ref": "#/components/schemas/ReportSourceRange" }, "snapshot": { "$ref": "#/components/schemas/SnapshotState" }, "completeness": { "$ref": "#/components/schemas/SnapshotCompleteness" }, "reconciliation": { "$ref": "#/components/schemas/ReportReconciliation" }, "report": { "$ref": "#/components/schemas/ReportPayload" } } }, "ReportSourceRange": { "type": "object", "required": [ "start_date", "end_date", "timezone" ], "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "timezone": { "type": "string", "const": "UTC" } } }, "SnapshotState": { "type": "object", "required": [ "status", "generated_at" ], "properties": { "status": { "type": "string", "enum": [ "final", "rolling" ] }, "generated_at": { "type": "string", "format": "date-time" }, "mutable_until": { "type": "string", "format": "date", "nullable": true } } }, "SnapshotCompleteness": { "type": "object", "required": [ "status", "reason", "expected_days", "covered_days_with_whale_activity" ], "properties": { "status": { "type": "string", "enum": [ "complete", "partial", "empty" ] }, "reason": { "type": "string" }, "expected_days": { "type": "integer" }, "covered_days_with_whale_activity": { "type": "integer" } } }, "ReportReconciliation": { "type": "object", "required": [ "volume_kind", "whale_volume_source", "notes" ], "properties": { "volume_kind": { "type": "string", "const": "local_whale_activity_volume" }, "whale_volume_source": { "type": "string", "const": "whale_alerts.usdc_notional_num" }, "notes": { "type": "string" } } }, "ReportPayload": { "type": "object", "properties": { "total_whale_trades": { "type": "integer", "nullable": true }, "total_whale_volume": { "type": "number", "nullable": true }, "biggest_trade_size": { "type": "number", "nullable": true }, "active_traders": { "type": "integer", "nullable": true }, "top_whale_trades": { "type": "array", "items": { "type": "object" }, "nullable": true }, "categories": { "type": "array", "items": { "type": "object" }, "nullable": true }, "grade_distribution": { "type": "array", "items": { "type": "object" }, "nullable": true } } }, "TraderExportSnapshot": { "type": "object", "required": [ "address", "generated_at", "source_range", "completeness", "reconciliation", "counts", "large_export_policy" ], "properties": { "address": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "source_range": { "$ref": "#/components/schemas/ExportSourceRange" }, "completeness": { "$ref": "#/components/schemas/ExportCompleteness" }, "reconciliation": { "$ref": "#/components/schemas/ExportVolumeReconciliation" }, "counts": { "$ref": "#/components/schemas/ExportCounts" }, "large_export_policy": { "$ref": "#/components/schemas/LargeExportPolicy" } } }, "ExportSourceRange": { "type": "object", "properties": { "first_pnl_date": { "type": "string", "format": "date", "nullable": true }, "last_pnl_date": { "type": "string", "format": "date", "nullable": true }, "latest_trade_at": { "type": "string", "format": "date-time", "nullable": true }, "latest_market_activity_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ExportCompleteness": { "type": "object", "required": [ "status", "reason", "sync_coverage" ], "properties": { "status": { "type": "string", "enum": [ "complete", "partial", "empty" ] }, "reason": { "type": "string" }, "sync_coverage": { "type": "number", "minimum": 0 } } }, "ExportVolumeReconciliation": { "type": "object", "required": [ "exported_activity_volume", "exported_market_cost_basis" ], "properties": { "provider_lifetime_volume": { "type": "number", "nullable": true }, "exported_activity_volume": { "type": "number" }, "exported_market_cost_basis": { "type": "number" }, "provider_activity_volume_gap": { "type": "number", "nullable": true }, "activity_volume_coverage": { "type": "number", "nullable": true } } }, "ExportCounts": { "type": "object", "required": [ "pnl_days", "exported_markets", "estimated_trade_rows", "estimated_size_mb" ], "properties": { "pnl_days": { "type": "integer" }, "exported_markets": { "type": "integer" }, "estimated_trade_rows": { "type": "integer" }, "estimated_size_mb": { "type": "number" } } }, "LargeExportPolicy": { "type": "object", "required": [ "mode", "current_internal_route", "direct_streaming", "async_job", "rate_limit" ], "properties": { "mode": { "type": "string", "const": "metadata_only_in_v1" }, "current_internal_route": { "type": "string" }, "direct_streaming": { "type": "object" }, "async_job": { "type": "object" }, "rate_limit": { "type": "object" } } }, "Usage": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "usage" }, "data": { "type": "object", "required": [ "rate_limit", "daily_usage" ], "properties": { "rate_limit": { "type": "object", "required": [ "used", "limit", "remaining", "reset_at", "window_seconds" ], "properties": { "used": { "type": "integer", "example": 7 }, "limit": { "type": "integer", "example": 100 }, "remaining": { "type": "integer", "example": 93 }, "reset_at": { "type": "integer", "example": 1710772860 }, "window_seconds": { "type": "integer", "example": 60 } } }, "daily_usage": { "type": "object", "required": [ "used", "limit", "remaining", "reset_at", "window_seconds" ], "properties": { "used": { "type": "integer", "example": 42 }, "limit": { "type": [ "integer", "null" ], "example": null }, "remaining": { "type": [ "integer", "null" ], "example": null }, "reset_at": { "type": "integer", "example": 1710806400 }, "window_seconds": { "type": "integer", "example": 86400 } }, "description": "UTC-day usage count. Current V1 has no daily hard cap, so limit and remaining are null rather than synthesized." } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "LargePosition": { "type": "object", "required": [ "id", "platform", "share_count", "event_leg_count", "first_seen_at", "last_updated_at", "trader", "market" ], "properties": { "id": { "type": "string", "description": "Composite prefixed ID `pos_::`." }, "platform": { "type": "string", "enum": [ "polymarket", "kalshi" ], "description": "Provider discriminator. Always polymarket today (scanner is Polymarket-only); kept in the shape so Kalshi can land without a breaking change." }, "total_size_usd": { "type": "number", "nullable": true, "description": "Aggregate provider currentValue for this position leg in USD." }, "position_unrealized_pnl": { "type": "number", "nullable": true, "description": "Provider per-position unrealized P&L (trader_markets.unrealized_pnl_num, from Polymarket cashPnl)." }, "share_count": { "type": "number", "description": "Live share count for this position." }, "avg_entry_price": { "type": "number", "nullable": true, "description": "Volume-weighted entry price." }, "current_price": { "type": "number", "nullable": true, "description": "Latest provider mark price for the position's token." }, "outcome_label": { "type": "string", "nullable": true, "description": "Backend-resolved outcome label (provider outcome, else Yes/No from the binary index)." }, "event_leg_count": { "type": "integer", "description": "Legs collapsed into this representative row for one (wallet, event, outcome side) group. 1 means standalone." }, "event_total_value_usd": { "type": "number", "nullable": true, "description": "Aggregate provider currentValue across collapsed sibling legs; equals total_size_usd when event_leg_count = 1." }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_updated_at": { "type": "string", "format": "date-time" }, "trader": { "type": "object", "required": [ "id", "address" ], "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 }, "win_rate": { "type": "number", "nullable": true }, "pnl": { "type": "number", "nullable": true, "description": "Trader lifetime realized P&L across all markets." }, "markets_traded": { "type": "integer", "nullable": true } } }, "market": { "type": "object", "required": [ "id", "condition_id" ], "properties": { "id": { "type": "string", "description": "Prefixed ID (`mkt_...`)." }, "condition_id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "event_slug": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true } } } } }, "TrendingWallet": { "type": "object", "required": [ "id", "address", "rank", "platform", "trending_pnl_usd", "window_volume_usd", "window_markets_traded", "window_trade_days", "daily_pnl_series" ], "properties": { "id": { "type": "string", "description": "Prefixed trader ID (`trd_...`)." }, "address": { "type": "string" }, "rank": { "type": "integer", "description": "1-based rank within the full ranked set (stable across pages)." }, "username": { "type": "string", "nullable": true }, "profile_image_url": { "type": "string", "nullable": true, "description": "Official Polymarket avatar URL (profileImage)." }, "platform": { "type": "string", "enum": [ "polymarket", "kalshi" ], "description": "Real provider platform; surfaced, never coerced. Polymarket-only today." }, "trending_pnl_usd": { "type": "number", "description": "Realized P&L over the trailing window in USD (ranking axis)." }, "window_volume_usd": { "type": "number" }, "window_markets_traded": { "type": "integer" }, "window_trade_days": { "type": "integer" }, "grade": { "type": "string", "enum": [ "S", "A", "B", "C", "D", "F" ], "description": "All-time cohort-relative skill grade (forecasting calibration, risk-adjusted returns, consistency); a separate axis from streak_tier. Not a profit ranking, and relative, so it drifts as the cohort moves. Omitted when the trader is Unranked (fewer than 5 markets, insufficient track record to cohort-rank)." }, "streak_tier": { "type": "string", "enum": [ "hot", "rising", "neutral", "cooling", "cold" ], "nullable": true, "description": "Hot-streak tier (trailing-7d cross-sectional percentile). Null when no recent activity." }, "all_time_pnl_usd": { "type": "number", "nullable": true }, "all_time_score": { "type": "number", "nullable": true }, "last_synced": { "type": "string", "format": "date-time", "nullable": true }, "daily_pnl_series": { "type": "array", "description": "Zero-filled daily P&L series across the window.", "items": { "type": "object", "required": [ "date", "pnl_usd" ], "properties": { "date": { "type": "string", "format": "date" }, "pnl_usd": { "type": "number" } } } } } }, "TraderPnl": { "type": "object", "required": [ "id", "entries", "stats", "monthly", "year_totals", "drawdown" ], "properties": { "id": { "type": "string", "description": "Prefixed trader ID (`trd_...`)." }, "entries": { "type": "array", "description": "Daily cumulative-P&L series (oldest-first).", "items": { "type": "object", "required": [ "date", "daily_change" ], "properties": { "date": { "type": "string", "format": "date" }, "markets_traded": { "type": "integer", "nullable": true }, "total_volume": { "type": "number", "nullable": true }, "cumulative_profit": { "type": "number", "nullable": true }, "total_pnl": { "type": "number", "nullable": true }, "daily_change": { "type": "number" } } } }, "stats": { "type": "object", "required": [ "all", "d90", "d30", "d7" ], "properties": { "all": { "type": "object", "required": [ "current", "change", "change_pct", "best_day", "worst_day", "win_days", "loss_days", "avg_day", "rebase_anchor" ], "properties": { "current": { "type": "number" }, "change": { "type": "number" }, "change_pct": { "type": "number" }, "best_day": { "type": "number" }, "best_day_date": { "type": "string", "format": "date", "nullable": true }, "worst_day": { "type": "number" }, "worst_day_date": { "type": "string", "format": "date", "nullable": true }, "win_days": { "type": "integer" }, "loss_days": { "type": "integer" }, "avg_day": { "type": "number" }, "rebase_anchor": { "type": "number" } } }, "d90": { "type": "object", "required": [ "current", "change", "change_pct", "best_day", "worst_day", "win_days", "loss_days", "avg_day", "rebase_anchor" ], "properties": { "current": { "type": "number" }, "change": { "type": "number" }, "change_pct": { "type": "number" }, "best_day": { "type": "number" }, "best_day_date": { "type": "string", "format": "date", "nullable": true }, "worst_day": { "type": "number" }, "worst_day_date": { "type": "string", "format": "date", "nullable": true }, "win_days": { "type": "integer" }, "loss_days": { "type": "integer" }, "avg_day": { "type": "number" }, "rebase_anchor": { "type": "number" } } }, "d30": { "type": "object", "required": [ "current", "change", "change_pct", "best_day", "worst_day", "win_days", "loss_days", "avg_day", "rebase_anchor" ], "properties": { "current": { "type": "number" }, "change": { "type": "number" }, "change_pct": { "type": "number" }, "best_day": { "type": "number" }, "best_day_date": { "type": "string", "format": "date", "nullable": true }, "worst_day": { "type": "number" }, "worst_day_date": { "type": "string", "format": "date", "nullable": true }, "win_days": { "type": "integer" }, "loss_days": { "type": "integer" }, "avg_day": { "type": "number" }, "rebase_anchor": { "type": "number" } } }, "d7": { "type": "object", "required": [ "current", "change", "change_pct", "best_day", "worst_day", "win_days", "loss_days", "avg_day", "rebase_anchor" ], "properties": { "current": { "type": "number" }, "change": { "type": "number" }, "change_pct": { "type": "number" }, "best_day": { "type": "number" }, "best_day_date": { "type": "string", "format": "date", "nullable": true }, "worst_day": { "type": "number" }, "worst_day_date": { "type": "string", "format": "date", "nullable": true }, "win_days": { "type": "integer" }, "loss_days": { "type": "integer" }, "avg_day": { "type": "number" }, "rebase_anchor": { "type": "number" } } } } }, "monthly": { "type": "array", "description": "Per-month P&L aggregation.", "items": { "type": "object", "required": [ "year", "month", "pnl", "markets_traded" ], "properties": { "year": { "type": "integer" }, "month": { "type": "integer" }, "pnl": { "type": "number" }, "markets_traded": { "type": "integer" } } } }, "year_totals": { "type": "array", "description": "Per-year P&L totals (ascending by year).", "items": { "type": "object", "required": [ "year", "pnl" ], "properties": { "year": { "type": "integer" }, "pnl": { "type": "number" } } } }, "drawdown": { "type": "array", "description": "Underwater (drawdown) series.", "items": { "type": "object", "required": [ "date", "cumulative_profit", "drawdown" ], "properties": { "date": { "type": "string", "format": "date" }, "cumulative_profit": { "type": "number" }, "drawdown": { "type": "number" } } } } } } }, "responses": { "WebhookObject": { "description": "Webhook destination", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "const": "webhook" }, "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "WebhookList": { "description": "Webhook destination list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "meta" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true }, "total": { "type": "integer", "nullable": true }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "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" } } } }, "Locked": { "description": "Account is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Resource not found", "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." }, "RateLimited": { "description": "Rate limit exceeded (100 req/min; batch endpoints also reserve 100 batch item units/min before execution)", "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" } } } }, "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" } } } }, "InternalError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "IdempotencyInProgress": { "description": "An Idempotency-Key request with the same body is still in progress. Retry shortly with the same key and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "in_progress": { "summary": "Idempotency request still in progress", "value": { "object": "error", "error": { "code": "bad_request", "message": "Idempotency-Key request is still in progress; retry shortly", "param": "Idempotency-Key" }, "meta": { "request_id": "req_example", "cached": false } } } } } } }, "IdempotencyConflict": { "description": "The Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "different_body": { "summary": "Idempotency key reused with a different body", "value": { "object": "error", "error": { "code": "bad_request", "message": "Idempotency-Key already used with a different request body", "param": "Idempotency-Key" }, "meta": { "request_id": "req_example", "cached": false } } } } } } } }, "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": "Strong validator for conditional GET. Send as If-None-Match to receive 304 when unchanged.", "schema": { "type": "string", "example": "\"8f14e45fceea167a5a36dedd4bea2543\"" } } } }, "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": "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." } ] }