{ "openapi": "3.0.3", "info": { "title": "Unhosted Intelligence API", "version": "1.0.0", "description": "The Unhosted Intelligence API serves derived intelligence computed by our own engine over live on-chain data: bands, scores, gates, verdicts and one-sentence rationales. No raw provider data (holder lists, exact liquidity, price feeds, raw PnL rows) is redistributed.\n\nAuthentication: send your key as `Authorization: Bearer ` or `x-api-key: `. Keys are self-serve at https://www.unhosted.ai/partners (sandbox keys `key_test_…`, live keys `key_live_…`).\n\nMetering: every successful call is billed in weighted units (the operation's `x-cost-units`; also returned as `X-Usage-Units`). Rate limits are per key and per plan — sandbox 60/min, free 30/min, pro 300/min, enterprise 2000/min — reported as `X-RateLimit-Limit` / `X-RateLimit-Remaining`; exceeding them returns 429 `rate_limited`. A global daily data budget returns 503 `capacity` with `Retry-After` when exhausted. `GET /usage` is never rate limited.\n\nErrors are JSON: `{ \"error\": \"\", \"detail\": \"\" }` (404s add `hint` and `docs`). Codes: invalid_api_key, wallet_auth_required, wallet_auth_expired, invalid_address, invalid_chain, unknown_param, venue_not_entitled, not_found, not_a_token, rate_limited, capacity, gateway_unconfigured, execution_unavailable, analysis_failed, dossier_failed, method_not_allowed, internal.\n\nThe verdict vocabulary is fixed across the API: `mirror-worthy`, `watch`, `avoid`, `unrated` — and `unrated` means unknown, never bad.\n\nDeveloper portal: https://www.unhosted.ai/developers · catalog: https://www.unhosted.ai/api/v1 · llms.txt: https://www.unhosted.ai/llms.txt", "termsOfService": "https://www.unhosted.ai/terms-of-use", "contact": { "name": "Unhosted AI developer support", "url": "https://www.unhosted.ai/developers", "email": "hi@unhosted.ai" }, "x-logo": { "url": "https://www.unhosted.ai/icon-512.png", "altText": "Unhosted AI" } }, "externalDocs": { "description": "Developer portal", "url": "https://www.unhosted.ai/developers" }, "servers": [ { "url": "https://api.unhosted.ai/v1", "description": "Canonical API host" }, { "url": "https://www.unhosted.ai/api/v1", "description": "Legacy path on the web host (same deployment)" } ], "tags": [ { "name": "infra", "description": "Alerts and usage metering." }, { "name": "token", "description": "Token intelligence — risk, signal, holders, narrative, price structure, smart-money flow and the one-call dossier." }, { "name": "market", "description": "Market surfaces — regime, movers, smart-money radar, conviction board, Hyperliquid vault consensus." }, { "name": "copytrading", "description": "Copy-trading intelligence and execution — copy decisions, simulations, graded leaders per venue, track records, and the wallet-signed relay to the agent API." }, { "name": "trader", "description": "Trader grading — score, style, edge, positions and leaderboards." }, { "name": "wallet", "description": "Wallet intelligence — health, PnL quality, archetype, netflow, trades, portfolio risk and the one-call overview." }, { "name": "signals", "description": "Durable signal history and whether the signals preceded moves." } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "paths": { "/": { "get": { "operationId": "getCatalog", "summary": "Endpoint catalog", "description": "Machine-readable catalog of every endpoint: path, method, unit cost, inputs (shorthand), what it returns and its group. Public — no key. The same catalog this OpenAPI document is generated from.", "tags": [ "infra" ], "security": [], "responses": { "200": { "description": "The catalog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "auth": { "type": "string" }, "metering": { "type": "string" }, "note": { "type": "string" }, "openapi": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" }, "count": { "type": "integer" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "cost": { "type": "integer" }, "input": { "type": "object", "additionalProperties": { "type": "string" } }, "returns": { "type": "string" }, "group": { "type": "string" } } } } } } } } } } } }, "/token-intel": { "post": { "operationId": "tokenIntel", "summary": "Complete derived profile for one token", "description": "Returns: verdict, risk, momentum, entry, activity. Costs 1 unit per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" }, "sizeUsd": { "type": "number" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — verdict, risk, momentum, entry, activity", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "verdict, risk, momentum, entry, activity", "properties": { "verdict": {}, "risk": {}, "momentum": {}, "entry": {}, "activity": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-signal": { "post": { "operationId": "tokenSignal", "summary": "Single alpha call for a token", "description": "Returns: signal(BUY/ACCUMULATE/HOLD/AVOID), conviction, rationale(LLM). Costs 2 units per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — signal(BUY/ACCUMULATE/HOLD/AVOID), conviction, rationale(LLM)", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "signal(BUY/ACCUMULATE/HOLD/AVOID), conviction, rationale(LLM)", "properties": { "signal": { "type": "string", "enum": [ "BUY", "ACCUMULATE", "HOLD", "AVOID" ] }, "conviction": {}, "rationale": { "type": "string", "description": "Written by the LLM rationale layer over signals the engine computed; never a number." } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-risk": { "post": { "operationId": "tokenRisk", "summary": "Rug / honeypot / concentration verdict", "description": "Returns: risk, score, signals, flags. Costs 1 unit per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — risk, score, signals, flags", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "risk, score, signals, flags", "properties": { "risk": {}, "score": {}, "signals": {}, "flags": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-holders-insight": { "post": { "operationId": "tokenHoldersInsight", "summary": "Holder base: accumulating or bleeding, organic or not", "description": "Returns: verdict, trend, organic, whaleShape. Costs 1 unit per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — verdict, trend, organic, whaleShape", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "verdict, trend, organic, whaleShape", "properties": { "verdict": {}, "trend": {}, "organic": {}, "whaleShape": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-narrative": { "post": { "operationId": "tokenNarrative", "summary": "Stance and one-paragraph thesis", "description": "Returns: stance, thesis(LLM). Costs 2 units per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — stance, thesis(LLM)", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "stance, thesis(LLM)", "properties": { "stance": {}, "thesis": { "type": "string", "description": "Written by the LLM rationale layer over signals the engine computed; never a number." } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-compare": { "post": { "operationId": "tokenCompare", "summary": "Rank a set of tokens and pick one", "description": "Returns: pick, ranked[]. Costs 2 units per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/Address" }, "minItems": 1 } }, "required": [ "tokens" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — pick, ranked[]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "pick, ranked[]", "properties": { "pick": {}, "ranked": { "type": "array", "items": {} } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-inflection": { "post": { "operationId": "tokenInflection", "summary": "Is the token coiling or breaking out", "description": "Returns: state(coiling/breaking-out), earlyScore. Costs 1 unit per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — state(coiling/breaking-out), earlyScore", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "state(coiling/breaking-out), earlyScore", "properties": { "state": { "type": "string", "enum": [ "coiling", "breaking-out" ] }, "earlyScore": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-valuation": { "post": { "operationId": "tokenValuation", "summary": "Valuation stance", "description": "Returns: stance, signals. Costs 1 unit per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — stance, signals", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "stance, signals", "properties": { "stance": {}, "signals": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/exit-risk": { "post": { "operationId": "exitRisk", "summary": "Exit risk for a position in this token", "description": "Returns: exitRisk, direction, signals. Costs 1 unit per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — exitRisk, direction, signals", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "exitRisk, direction, signals", "properties": { "exitRisk": {}, "direction": {}, "signals": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-changes": { "post": { "operationId": "tokenChanges", "summary": "What changed since the last scan", "description": "Returns: changes[{metric,from,to,severity}], current, headline(LLM) — signal deltas vs prior snapshot (incl. price breaks). Costs 2 units per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — changes[{metric,from,to,severity}], current, headline(LLM)", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "changes[{metric,from,to,severity}], current, headline(LLM) — signal deltas vs prior snapshot (incl. price breaks)", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "metric": {}, "from": {}, "to": {}, "severity": {} }, "additionalProperties": true } }, "current": {}, "headline": { "type": "string", "description": "Written by the LLM rationale layer over signals the engine computed; never a number." } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-price-action": { "post": { "operationId": "tokenPriceAction", "summary": "Price structure read (derived, no raw candles)", "description": "Returns: trend, structure, breakout, volatility, distanceFromHigh, priceMomentum, summary(LLM) — derived from Codex OHLCV. Costs 2 units per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" }, "hours": { "type": "number" }, "resolution": { "type": "string" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — trend, structure, breakout, volatility, distanceFromHigh, priceMomentum, summary(LLM)", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "trend, structure, breakout, volatility, distanceFromHigh, priceMomentum, summary(LLM) — derived from Codex OHLCV", "properties": { "trend": {}, "structure": {}, "breakout": {}, "volatility": {}, "distanceFromHigh": {}, "priceMomentum": {}, "summary": { "type": "string", "description": "Written by the LLM rationale layer over signals the engine computed; never a number." } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-spark": { "post": { "operationId": "tokenSpark", "summary": "Normalized sparkline shape", "description": "Returns: chain, token, available, hours, points, changePct, series[] — a normalized price shape for sparklines: closes only, rebased to percent-from-first-bar, capped at 72 hourly points, no timestamps/volumes/OHLC. Costs 1 unit per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" }, "hours": { "type": "number", "minimum": 6, "maximum": 72, "default": 48 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — chain, token, available, hours, points, changePct, series[]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "chain, token, available, hours, points, changePct, series[] — a normalized price shape for sparklines: closes only, rebased to percent-from-first-bar, capped at 72 hourly points, no timestamps/volumes/OHLC", "properties": { "chain": {}, "token": {}, "available": {}, "hours": {}, "points": {}, "changePct": {}, "series": { "type": "array", "items": {} } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/smart-money-flow": { "post": { "operationId": "smartMoneyFlow", "summary": "Are graded wallets buying this token", "description": "Returns: smartMoneyBuying, mirrorWorthyBuyers, verdict. Costs 6 units per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 6, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" }, "sample": { "type": "number" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — smartMoneyBuying, mirrorWorthyBuyers, verdict", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "smartMoneyBuying, mirrorWorthyBuyers, verdict", "properties": { "smartMoneyBuying": {}, "mirrorWorthyBuyers": {}, "verdict": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/token-overview": { "post": { "operationId": "tokenOverview", "summary": "The whole token page in one call", "description": "Returns: token, chain, bundle, tokenIntel, tokenSignal, smartMoneyFlow, exitRisk, tokenInflection, tokenHoldersInsight, tokenValuation, tokenNarrative, tokenChanges, tokenPriceAction, failed[] — the whole token dossier in one call; each slot is the verbatim response of the single endpoint it is named after, a failed component becomes an error object in its slot (502 only when every component failed). Costs 19 units per successful call (X-Usage-Units). Group: token.", "tags": [ "token" ], "x-cost-units": 19, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" }, "sample": { "type": "number" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — token, chain, bundle, tokenIntel, tokenSignal, smartMoneyFlow, exitRisk, tokenInflection, tokenHoldersInsight, tokenValuation, tokenNarrative, tokenChanges, tokenPriceAction, failed[]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "token, chain, bundle, tokenIntel, tokenSignal, smartMoneyFlow, exitRisk, tokenInflection, tokenHoldersInsight, tokenValuation, tokenNarrative, tokenChanges, tokenPriceAction, failed[] — the whole token dossier in one call; each slot is the verbatim response of the single endpoint it is named after, a failed component becomes an error object in its slot (502 only when every component failed)", "properties": { "token": {}, "chain": {}, "bundle": {}, "tokenIntel": {}, "tokenSignal": {}, "smartMoneyFlow": {}, "exitRisk": {}, "tokenInflection": {}, "tokenHoldersInsight": {}, "tokenValuation": {}, "tokenNarrative": {}, "tokenChanges": {}, "tokenPriceAction": {}, "failed": { "type": "array", "items": {} } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/smart-money-radar": { "get": { "operationId": "smartMoneyRadar", "summary": "What smart money is accumulating", "description": "Returns: headline(LLM), accumulating[{symbol, smartBuyers, conviction, sizeBand}], setSize. Costs 8 units per successful call (X-Usage-Units). Group: market.", "tags": [ "market" ], "x-cost-units": 8, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] } }, { "name": "window", "in": "query", "required": false, "description": "in hours", "schema": { "type": "integer" } }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK — headline(LLM), accumulating[{symbol, smartBuyers, conviction, sizeBand}], setSize", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "headline(LLM), accumulating[{symbol, smartBuyers, conviction, sizeBand}], setSize", "properties": { "headline": { "type": "string", "description": "Written by the LLM rationale layer over signals the engine computed; never a number." }, "accumulating": { "type": "array", "items": { "type": "object", "properties": { "symbol": {}, "smartBuyers": {}, "conviction": {}, "sizeBand": {} }, "additionalProperties": true } }, "setSize": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/conviction-board": { "get": { "operationId": "convictionBoard", "summary": "Compound high-conviction plays", "description": "Returns: headline(LLM), board[{symbol, conviction, pillarsLit, pillars{smartMoney,coiling,lowExit,organic,momentum,structure}}] — compound high-conviction plays. Costs 6 units per successful call (X-Usage-Units). Group: market.", "tags": [ "market" ], "x-cost-units": 6, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "refresh", "in": "query", "required": false, "description": "bypass 120s cache", "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK — headline(LLM), board[{symbol, conviction, pillarsLit, pillars{smartMoney,coiling,lowExit,organic,momentum,structure}}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "headline(LLM), board[{symbol, conviction, pillarsLit, pillars{smartMoney,coiling,lowExit,organic,momentum,structure}}] — compound high-conviction plays", "properties": { "headline": { "type": "string", "description": "Written by the LLM rationale layer over signals the engine computed; never a number." }, "board": { "type": "array", "items": { "type": "object", "properties": { "symbol": {}, "conviction": {}, "pillarsLit": {}, "pillars": { "type": "object", "properties": { "smartMoney": {}, "coiling": {}, "lowExit": {}, "organic": {}, "momentum": {}, "structure": {} }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/market-movers": { "get": { "operationId": "marketMovers", "summary": "Risk-filtered discovery feed", "description": "Returns: movers[]. Costs 1 unit per successful call (X-Usage-Units). Group: market.", "tags": [ "market" ], "x-cost-units": 1, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK — movers[]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "movers[]", "properties": { "movers": { "type": "array", "items": {} } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/robinhood-movers": { "get": { "operationId": "robinhoodMovers", "summary": "Robinhood Chain movers", "description": "Returns: movers[{symbol, momentum, risk, signals{flow,activity,liquidity,holderBase}, verdict}] — Robinhood Chain (Codex, Moralis-free). Costs 1 unit per successful call (X-Usage-Units). Group: market.", "tags": [ "market" ], "x-cost-units": 1, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK — movers[{symbol, momentum, risk, signals{flow,activity,liquidity,holderBase}, verdict}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "movers[{symbol, momentum, risk, signals{flow,activity,liquidity,holderBase}, verdict}] — Robinhood Chain (Codex, Moralis-free)", "properties": { "movers": { "type": "array", "items": { "type": "object", "properties": { "symbol": {}, "momentum": {}, "risk": {}, "signals": { "type": "object", "properties": { "flow": {}, "activity": {}, "liquidity": {}, "holderBase": {} }, "additionalProperties": true }, "verdict": {} }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/market-regime": { "get": { "operationId": "marketRegime", "summary": "Market regime for a chain", "description": "Returns: regime, confidence, breadth. Costs 1 unit per successful call (X-Usage-Units). Group: market.", "tags": [ "market" ], "x-cost-units": 1, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] } } ], "responses": { "200": { "description": "OK — regime, confidence, breadth", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "regime, confidence, breadth", "properties": { "regime": {}, "confidence": {}, "breadth": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/hl-alpha": { "get": { "operationId": "hlAlpha", "summary": "Hyperliquid vault-consensus board (public)", "description": "Returns: success — the Hyperliquid vault-consensus board: the tracked vault universe, fired consensus signals and the paper-trade blotter that scores them; everything derived and public-safe (no key required). No API key required; not metered. Group: market.", "tags": [ "market" ], "x-cost-units": 0, "parameters": [ { "name": "signals", "in": "query", "required": false, "schema": { "default": 40, "type": "integer", "maximum": 100 } }, { "name": "trades", "in": "query", "required": false, "schema": { "default": 60, "type": "integer", "maximum": 200 } } ], "responses": { "200": { "description": "OK — success", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "description": "success — the Hyperliquid vault-consensus board: the tracked vault universe, fired consensus signals and the paper-trade blotter that scores them; everything derived and public-safe (no key required)", "properties": { "success": {} }, "additionalProperties": true } } } }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [] } }, "/copy-decision": { "post": { "operationId": "copyDecision", "summary": "Mirror this trade? At what size?", "description": "Returns: copy, sizeFactor, risk, reasons. Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "token": { "$ref": "#/components/schemas/Address" }, "sizeUsd": { "type": "number" } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — copy, sizeFactor, risk, reasons", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "copy, sizeFactor, risk, reasons", "properties": { "copy": {}, "sizeFactor": {}, "risk": {}, "reasons": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy-plan": { "post": { "operationId": "copyPlan", "summary": "Should a follower copy this lead, and how", "description": "Returns: copy, plan, warnings. Costs 3 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 3, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "leadWallet" ], "additionalProperties": false, "properties": { "chain": { "$ref": "#/components/schemas/ChainSlug" }, "leadWallet": { "$ref": "#/components/schemas/Address" }, "follower": { "type": "object", "description": "The follower's own profile (capital, risk appetite, existing positions) used to shape the plan; free-form.", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "OK — copy, plan, warnings", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "copy, plan, warnings", "properties": { "copy": {}, "plan": {}, "warnings": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy-simulate": { "post": { "operationId": "copySimulate", "summary": "Simulate copying this wallet", "description": "Returns: winRate, medianReturnPct, form. Costs 2 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — winRate, medianReturnPct, form", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "winRate, medianReturnPct, form", "properties": { "winRate": {}, "medianReturnPct": {}, "form": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy-overlap": { "post": { "operationId": "copyOverlap", "summary": "Overlap between a candidate lead and existing leads", "description": "Returns: overlapPct, recommendation. Costs 3 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 3, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "candidate": { "$ref": "#/components/schemas/Address" }, "existing": { "type": "array", "items": { "$ref": "#/components/schemas/Address" }, "minItems": 1 } }, "required": [ "candidate", "existing" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — overlapPct, recommendation", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "overlapPct, recommendation", "properties": { "overlapPct": {}, "recommendation": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/perp-copy-decision": { "post": { "operationId": "perpCopyDecision", "summary": "Perp gate: leverage / liquidation distance", "description": "Returns: copy, maxLeverage, liqDistancePct. Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "side", "leverage", "markPrice" ], "additionalProperties": true, "properties": { "side": { "type": "string", "enum": [ "long", "short" ] }, "leverage": { "type": "number", "minimum": 0 }, "markPrice": { "type": "number", "minimum": 0 }, "liqPrice": { "type": "number", "minimum": 0, "nullable": true } } } } } }, "responses": { "200": { "description": "OK — copy, maxLeverage, liqDistancePct", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "copy, maxLeverage, liqDistancePct", "properties": { "copy": {}, "maxLeverage": {}, "liqDistancePct": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/perp-wallet": { "post": { "operationId": "perpWallet", "summary": "Hyperliquid perp profile of a wallet", "description": "Returns: accountBand, openPositions[{coin,side,leverage,sizeBand,pnl,roePct}], bias, winRate, sampleWindow, closedTrades — Hyperliquid perp profile. USD banded; returns are exact percentages.. Costs 2 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — accountBand, openPositions[{coin,side,leverage,sizeBand,pnl,roePct}], bias, winRate, sampleWindow, closedTrades", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "accountBand, openPositions[{coin,side,leverage,sizeBand,pnl,roePct}], bias, winRate, sampleWindow, closedTrades — Hyperliquid perp profile. USD banded; returns are exact percentages.", "properties": { "accountBand": {}, "openPositions": { "type": "array", "items": { "type": "object", "properties": { "coin": {}, "side": {}, "leverage": {}, "sizeBand": {}, "pnl": {}, "roePct": {} }, "additionalProperties": true } }, "bias": {}, "winRate": {}, "sampleWindow": {}, "closedTrades": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/prediction-wallet": { "post": { "operationId": "predictionWallet", "summary": "Grade any Polymarket wallet for copyability", "description": "Returns: wallet, venue, available, active, windowDays, mirrorable, score, grade, verdict, reasons, signals, evidence — grade ANY Polymarket wallet for copyability with the exact assessor the prediction-leaders board uses; a wallet with no venue history returns active:false with zeros stated, never a grade. Costs 3 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 3, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — wallet, venue, available, active, windowDays, mirrorable, score, grade, verdict, reasons, signals, evidence", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "wallet, venue, available, active, windowDays, mirrorable, score, grade, verdict, reasons, signals, evidence — grade ANY Polymarket wallet for copyability with the exact assessor the prediction-leaders board uses; a wallet with no venue history returns active:false with zeros stated, never a grade", "properties": { "wallet": {}, "venue": {}, "available": {}, "active": {}, "windowDays": {}, "mirrorable": {}, "score": {}, "grade": {}, "verdict": {}, "reasons": {}, "signals": {}, "evidence": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/leader-dossier": { "post": { "operationId": "leaderDossier", "summary": "The whole leader card in one request", "description": "Returns: source(warm/live) — the whole leader card in one request: the spot or perps dossier served from Postgres when the warming cron reached this wallet (warm), assembled live otherwise. Costs 3 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 3, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Address" }, "kind": { "type": "string", "enum": [ "spot", "perps" ], "default": "spot" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — source(warm/live)", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "source(warm/live) — the whole leader card in one request: the spot or perps dossier served from Postgres when the warming cron reached this wallet (warm), assembled live otherwise", "properties": { "source": { "type": "string", "enum": [ "warm", "live" ] } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy/top-traders": { "get": { "operationId": "copyTopTraders", "summary": "Copy-trading leaderboard, graded", "description": "Returns: traders[{address, pnl, roi, intel{grade,verdict,score}}] — copy-trading leaderboard graded by our engine. Costs 3 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 3, "parameters": [ { "name": "chainId", "in": "query", "required": false, "schema": { "default": 8453, "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK — traders[{address, pnl, roi, intel{grade,verdict,score}}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "traders[{address, pnl, roi, intel{grade,verdict,score}}] — copy-trading leaderboard graded by our engine", "properties": { "traders": { "type": "array", "items": { "type": "object", "properties": { "address": {}, "pnl": {}, "roi": {}, "intel": { "type": "object", "properties": { "grade": {}, "verdict": {}, "score": {} }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy/spot-leaders": { "get": { "operationId": "copySpotLeaders", "summary": "Spot leaders that survive the delay gate", "description": "Returns: leaders[{address, chain, pumpsEarlyIn, medianDelayed7dReturnPct, assessment{mirrorable,grade,verdict,reasons,signals}, disclosure}], byChain[{chain,screened,mirrorable,count}], delayModel, screened — repeat-early pump wallets promoted through the delay-adjusted copyability gate. chain=all merges every discovered chain, ranked mirror-worthy first. Costs 2 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 2, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "eth", "all" ], "default": "base" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "mirrorableOnly", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK — leaders[{address, chain, pumpsEarlyIn, medianDelayed7dReturnPct, assessment{mirrorable,grade,verdict,reasons,signals}, disclosure}], byChain[{chain,screened,mirrorable,count}], delayModel, screened", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "leaders[{address, chain, pumpsEarlyIn, medianDelayed7dReturnPct, assessment{mirrorable,grade,verdict,reasons,signals}, disclosure}], byChain[{chain,screened,mirrorable,count}], delayModel, screened — repeat-early pump wallets promoted through the delay-adjusted copyability gate. chain=all merges every discovered chain, ranked mirror-worthy first", "properties": { "leaders": { "type": "array", "items": { "type": "object", "properties": { "address": {}, "chain": {}, "pumpsEarlyIn": {}, "medianDelayed7dReturnPct": {}, "assessment": { "type": "object", "properties": { "mirrorable": {}, "grade": {}, "verdict": {}, "reasons": {}, "signals": {} }, "additionalProperties": true }, "disclosure": {} }, "additionalProperties": true } }, "byChain": { "type": "array", "items": { "type": "object", "properties": { "chain": {}, "screened": {}, "mirrorable": {}, "count": {} }, "additionalProperties": true } }, "delayModel": {}, "screened": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy/perp-leaders": { "get": { "operationId": "copyPerpLeaders", "summary": "Hyperliquid leaders screened for copyability", "description": "Returns: leaders[{venue, address, equity, openValue, screenedAt, assessment{mirrorable,score,grade,verdict,reasons,blockedBy,blockedLabel,executability,metrics,flags}, excursions{trips,maeMedianPct,maeWinnerMedianPct,mfeMedianPct}, streak{trips,currentWinStreak,currentLossStreak,lastLossAt}}] — discovered Hyperliquid leaders screened for copyability. include=rejected adds a rejected[] of wallets the gates refused, each with blockedLabel — the evidence the grade means something. include=unscreened adds unscreened[]: the screening backlog, copyable:false and carrying NO assessment key, because nobody has judged them. Both arrive in their own keys, never mixed into leaders[]. Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "include", "in": "query", "required": false, "description": "query? — comma list: rejected, unscreened", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK — leaders[{venue, address, equity, openValue, screenedAt, assessment{mirrorable,score,grade,verdict,reasons,blockedBy,blockedLabel,executability,metrics,flags}, excursions{trips,maeMedianPct,maeWinnerMedianPct,mfeMedianPct}, streak{trips,currentWinStreak,currentLossStreak,lastLossAt}}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "leaders[{venue, address, equity, openValue, screenedAt, assessment{mirrorable,score,grade,verdict,reasons,blockedBy,blockedLabel,executability,metrics,flags}, excursions{trips,maeMedianPct,maeWinnerMedianPct,mfeMedianPct}, streak{trips,currentWinStreak,currentLossStreak,lastLossAt}}] — discovered Hyperliquid leaders screened for copyability. include=rejected adds a rejected[] of wallets the gates refused, each with blockedLabel — the evidence the grade means something. include=unscreened adds unscreened[]: the screening backlog, copyable:false and carrying NO assessment key, because nobody has judged them. Both arrive in their own keys, never mixed into leaders[]", "properties": { "leaders": { "type": "array", "items": { "type": "object", "properties": { "venue": {}, "address": {}, "equity": {}, "openValue": {}, "screenedAt": {}, "assessment": { "type": "object", "properties": { "mirrorable": {}, "score": {}, "grade": {}, "verdict": {}, "reasons": {}, "blockedBy": {}, "blockedLabel": {}, "executability": {}, "metrics": {}, "flags": {} }, "additionalProperties": true }, "excursions": { "type": "object", "properties": { "trips": {}, "maeMedianPct": {}, "maeWinnerMedianPct": {}, "mfeMedianPct": {} }, "additionalProperties": true }, "streak": { "type": "object", "properties": { "trips": {}, "currentWinStreak": {}, "currentLossStreak": {}, "lastLossAt": {} }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy/prediction-leaders": { "get": { "operationId": "copyPredictionLeaders", "summary": "Polymarket leaders screened for copyability", "description": "Returns: leaders[{address, assessment{mirrorable,grade,verdict,reasons,signals}}], screened — discovered Polymarket leaders screened for copyability. Costs 5 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 5, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "mirrorableOnly", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK — leaders[{address, assessment{mirrorable,grade,verdict,reasons,signals}}], screened", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "leaders[{address, assessment{mirrorable,grade,verdict,reasons,signals}}], screened — discovered Polymarket leaders screened for copyability", "properties": { "leaders": { "type": "array", "items": { "type": "object", "properties": { "address": {}, "assessment": { "type": "object", "properties": { "mirrorable": {}, "grade": {}, "verdict": {}, "reasons": {}, "signals": {} }, "additionalProperties": true } }, "additionalProperties": true } }, "screened": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy/grade-leaders": { "post": { "operationId": "copyGradeLeaders", "summary": "Grade a set of perp leaders you supply", "description": "Returns: graded, mirrorable, leaders[{address, window, mirrorable, grade, score, verdict, signals, reasons, windowsRanked, evidence, medianHoldMs}] — caller-supplied Hyperliquid perp leaders graded for copyability; cache-only derivation, never a paid provider on the request path. Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "leaders" ], "additionalProperties": false, "properties": { "leaders": { "type": "array", "maxItems": 200, "items": { "type": "object", "required": [ "address" ], "additionalProperties": true, "properties": { "address": { "$ref": "#/components/schemas/Address" }, "window": { "type": "string", "description": "Leaderboard window the figures come from (e.g. day, week, month, allTime)." }, "rank": { "type": "number" }, "roi": { "type": "number" }, "pnl": { "type": "number" }, "vlm": { "type": "number" }, "accountValue": { "type": "number" }, "maxDrawdownPct": { "type": "number" }, "copyScore": { "type": "number" } } } } } } } } }, "responses": { "200": { "description": "OK — graded, mirrorable, leaders[{address, window, mirrorable, grade, score, verdict, signals, reasons, windowsRanked, evidence, medianHoldMs}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "graded, mirrorable, leaders[{address, window, mirrorable, grade, score, verdict, signals, reasons, windowsRanked, evidence, medianHoldMs}] — caller-supplied Hyperliquid perp leaders graded for copyability; cache-only derivation, never a paid provider on the request path", "properties": { "graded": {}, "mirrorable": {}, "leaders": { "type": "array", "items": { "type": "object", "properties": { "address": {}, "window": {}, "mirrorable": {}, "grade": {}, "score": {}, "verdict": {}, "signals": {}, "reasons": {}, "windowsRanked": {}, "evidence": {}, "medianHoldMs": {} }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/repeat-early": { "get": { "operationId": "repeatEarly", "summary": "Wallets repeatedly early into pumps", "description": "Returns: wallets[{wallet, pumps, bestRank, pumpsEarlyIn[], delayAdjusted?}], cohortPairs — wallets repeatedly early into pumped tokens (signal surface, receipts included). Costs 2 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 2, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "eth" ] } }, { "name": "minPumps", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "delayAdjusted", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK — wallets[{wallet, pumps, bestRank, pumpsEarlyIn[], delayAdjusted?}], cohortPairs", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "wallets[{wallet, pumps, bestRank, pumpsEarlyIn[], delayAdjusted?}], cohortPairs — wallets repeatedly early into pumped tokens (signal surface, receipts included)", "properties": { "wallets": { "type": "array", "items": { "type": "object", "properties": { "wallet": {}, "pumps": {}, "bestRank": {}, "pumpsEarlyIn": { "type": "array", "items": {} }, "delayAdjusted": {} }, "additionalProperties": true } }, "cohortPairs": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/cohort-watch": { "get": { "operationId": "cohortWatch", "summary": "Fresh entries by repeat-early wallets", "description": "Returns: chain, hours, events[], disclosure — fresh token entries by repeat-early wallets: the first time the watch saw each (wallet, token) pair, newest first, with the wallet's early-entry record as context; served from persisted watch events (no provider credits). Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base", "eth" ], "default": "base" } }, { "name": "hours", "in": "query", "required": false, "description": "in hours", "schema": { "type": "integer", "minimum": 1, "maximum": 336, "default": 72 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "maximum": 200 } } ], "responses": { "200": { "description": "OK — chain, hours, events[], disclosure", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "chain, hours, events[], disclosure — fresh token entries by repeat-early wallets: the first time the watch saw each (wallet, token) pair, newest first, with the wallet's early-entry record as context; served from persisted watch events (no provider credits)", "properties": { "chain": {}, "hours": {}, "events": { "type": "array", "items": {} }, "disclosure": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/traders/track-record": { "get": { "operationId": "tradersTrackRecord", "summary": "Did the trader grades carry signal?", "description": "Returns: grades[], verdicts[], separation — did mirror-worthy actually beat avoid over the forward window?. Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d" ] } }, { "name": "sinceDays", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "source", "in": "query", "required": false, "description": "spot-leader-gate for the spot gate’s own record", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK — grades[], verdicts[], separation", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "grades[], verdicts[], separation — did mirror-worthy actually beat avoid over the forward window?", "properties": { "grades": { "type": "array", "items": {} }, "verdicts": { "type": "array", "items": {} }, "separation": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/perp-track-record": { "get": { "operationId": "perpTrackRecord", "summary": "Did the perp grades carry signal?", "description": "Returns: horizon, grades[], verdicts[], separation — did the Hyperliquid leaders graded A out-earn those graded D over the forward window? Outcomes are the leaders' own realized PnL from venue fills; separation is avg(A∪B) − avg(D∪F); misses included. Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d" ] } }, { "name": "sinceDays", "in": "query", "required": false, "schema": { "minimum": 7, "maximum": 365, "type": "integer", "default": 90 } } ], "responses": { "200": { "description": "OK — horizon, grades[], verdicts[], separation", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "horizon, grades[], verdicts[], separation — did the Hyperliquid leaders graded A out-earn those graded D over the forward window? Outcomes are the leaders' own realized PnL from venue fills; separation is avg(A∪B) − avg(D∪F); misses included", "properties": { "horizon": {}, "grades": { "type": "array", "items": {} }, "verdicts": { "type": "array", "items": {} }, "separation": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/prediction-track-record": { "get": { "operationId": "predictionTrackRecord", "summary": "Did the prediction grades carry signal?", "description": "Returns: available, horizon, grades[], verdicts[], separation — did the Polymarket leaders graded A out-earn those graded D over the forward window? Outcomes are the leaders' own realized PnL from closed positions; misses included. Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d" ] } }, { "name": "sinceDays", "in": "query", "required": false, "schema": { "minimum": 7, "maximum": 365, "type": "integer", "default": 90 } } ], "responses": { "200": { "description": "OK — available, horizon, grades[], verdicts[], separation", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "available, horizon, grades[], verdicts[], separation — did the Polymarket leaders graded A out-earn those graded D over the forward window? Outcomes are the leaders' own realized PnL from closed positions; misses included", "properties": { "available": {}, "horizon": {}, "grades": { "type": "array", "items": {} }, "verdicts": { "type": "array", "items": {} }, "separation": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy/strategies": { "get": { "operationId": "copyStrategies", "summary": "Copy strategies with graded leaders", "description": "Returns: strategies[{id, name, leaderWalletAddress, intel{grade,verdict}}] — copy strategies (spot+perps), leaders graded. Costs 3 units per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 3, "parameters": [ { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK — strategies[{id, name, leaderWalletAddress, intel{grade,verdict}}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "strategies[{id, name, leaderWalletAddress, intel{grade,verdict}}] — copy strategies (spot+perps), leaders graded", "properties": { "strategies": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "name": {}, "leaderWalletAddress": {}, "intel": { "type": "object", "properties": { "grade": {}, "verdict": {} }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy/proxy": { "post": { "operationId": "copyProxy", "summary": "Relay a wallet-signed call to the agent API", "description": "Returns: relays wallet-signed transactional calls to the copy-trading agent API (activate/approve). Costs 1 unit per successful call (X-Usage-Units). Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "method", "auth" ], "additionalProperties": false, "properties": { "path": { "type": "string", "description": "Agent-API path under /v1/agent/* (allowlisted).", "example": "/v1/agent/agents" }, "method": { "type": "string", "enum": [ "GET", "POST", "PATCH", "DELETE" ] }, "body": { "type": "object", "additionalProperties": true, "nullable": true }, "auth": { "type": "object", "required": [ "signature", "address", "timestamp" ], "properties": { "signature": { "type": "string", "description": "EIP-191 personal_sign of the canonical agent-API message." }, "address": { "$ref": "#/components/schemas/Address" }, "timestamp": { "type": "integer", "description": "Unix seconds; the agent API allows 300 s of skew." } } } } } } } }, "responses": { "200": { "description": "OK — relays wallet-signed transactional calls to the copy-trading agent API (activate/approve)", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "relays wallet-signed transactional calls to the copy-trading agent API (activate/approve)", "properties": {}, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/copy/agent/{path}": { "post": { "operationId": "copyAgentRelay", "summary": "Execution relay to the copy-trading agent API", "description": "Returns: the agent API's own response and status, relayed — create/activate/cancel/list agents and executions, list venues; the gateway verifies the partner key, requires the end user's wallet signature headers and asserts the partner tenant downstream. Costs 2 units per successful call (X-Usage-Units). Execution route: requires the partner API key AND the end user's wallet authorization headers; the partner tenant is asserted downstream so agents are scoped per partner. Group: copytrading.", "tags": [ "copytrading" ], "x-cost-units": 2, "parameters": [ { "name": "path", "in": "path", "required": true, "description": "Agent-API route under /v1/agent/ (segments may contain slashes, e.g. agents/{id}/activate). The HTTP method is relayed as sent.", "schema": { "type": "string" } }, { "name": "X-Wallet-Address", "in": "header", "required": true, "description": "The end user's wallet (EIP-55 checksummed EVM address) whose funds the call moves.", "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } }, { "name": "X-Wallet-Signature", "in": "header", "required": true, "description": "EIP-191 personal_sign by that wallet over the canonical agent-API message naming the method and path (see createWalletAuthHeaders in the copytrading SDK).", "schema": { "type": "string" } }, { "name": "X-Auth-Timestamp", "in": "header", "required": true, "description": "Unix seconds when the signature was made; rejected when more than 300 s from server time.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Forwarded verbatim to the agent API. Example (start a Hyperliquid perps copy): { \"chainId\": 0, \"smartAccountAddress\": \"0x…\", \"strategyId\": \"perps-copytrade-hyperliquid\", \"leaderWalletAddress\": \"0x…\", \"riskConfig\": { \"maxUsd\": \"1000\", \"copyPercent\": 100 } }" } } } }, "responses": { "200": { "description": "OK — the agent API's own response and status, relayed", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "the agent API's own response and status, relayed — create/activate/cancel/list agents and executions, list venues; the gateway verifies the partner key, requires the end user's wallet signature headers and asserts the partner tenant downstream", "properties": { "relayed": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/trader-score": { "post": { "operationId": "traderScore", "summary": "Is this lead worth mirroring", "description": "Returns: score, grade, verdict, subscores. Costs 2 units per successful call (X-Usage-Units). Group: trader.", "tags": [ "trader" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — score, grade, verdict, subscores", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "score, grade, verdict, subscores", "properties": { "score": {}, "grade": {}, "verdict": {}, "subscores": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/trader-style": { "post": { "operationId": "traderStyle", "summary": "Behavioural fingerprint", "description": "Returns: style, tempo, riskAppetite. Costs 1 unit per successful call (X-Usage-Units). Group: trader.", "tags": [ "trader" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — style, tempo, riskAppetite", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "style, tempo, riskAppetite", "properties": { "style": {}, "tempo": {}, "riskAppetite": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/trader-positions": { "post": { "operationId": "traderPositions", "summary": "Quality of the current book", "description": "Returns: mirrorReadiness, bookQuality, positions. Costs 1 unit per successful call (X-Usage-Units). Group: trader.", "tags": [ "trader" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — mirrorReadiness, bookQuality, positions", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "mirrorReadiness, bookQuality, positions", "properties": { "mirrorReadiness": {}, "bookQuality": {}, "positions": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/trader-edge": { "post": { "operationId": "traderEdge", "summary": "Where the trader's edge is", "description": "Returns: edge, holdStyle, bestAt. Costs 2 units per successful call (X-Usage-Units). Group: trader.", "tags": [ "trader" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — edge, holdStyle, bestAt", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "edge, holdStyle, bestAt", "properties": { "edge": {}, "holdStyle": {}, "bestAt": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/trader-leaderboard": { "post": { "operationId": "traderLeaderboard", "summary": "Rank a set of wallets", "description": "Returns: leaderboard[], mirrorWorthy. Costs 5 units per successful call (X-Usage-Units). Group: trader.", "tags": [ "trader" ], "x-cost-units": 5, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/Address" }, "minItems": 1 } }, "required": [ "wallets" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — leaderboard[], mirrorWorthy", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "leaderboard[], mirrorWorthy", "properties": { "leaderboard": { "type": "array", "items": {} }, "mirrorWorthy": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/trader-board": { "get": { "operationId": "traderBoard", "summary": "Leaderboard of discovered wallets", "description": "Returns: traders[{wallet, grade, verdict, score}] — leaderboard of proven wallets the smart-money engine discovered (no input list needed). Costs 1 unit per successful call (X-Usage-Units). Group: trader.", "tags": [ "trader" ], "x-cost-units": 1, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK — traders[{wallet, grade, verdict, score}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "traders[{wallet, grade, verdict, score}] — leaderboard of proven wallets the smart-money engine discovered (no input list needed)", "properties": { "traders": { "type": "array", "items": { "type": "object", "properties": { "wallet": {}, "grade": {}, "verdict": {}, "score": {} }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/wallet-health": { "post": { "operationId": "walletHealth", "summary": "Drain / monitoring exposure", "description": "Returns: health, healthScore, recommendedActions. Costs 1 unit per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — health, healthScore, recommendedActions", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "health, healthScore, recommendedActions", "properties": { "health": {}, "healthScore": {}, "recommendedActions": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/wallet-analyze": { "post": { "operationId": "walletAnalyze", "summary": "Narrative over the computed signals", "description": "Returns: grade, topRisks, topStrengths, summary(LLM). Costs 2 units per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — grade, topRisks, topStrengths, summary(LLM)", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "grade, topRisks, topStrengths, summary(LLM)", "properties": { "grade": {}, "topRisks": {}, "topStrengths": {}, "summary": { "type": "string", "description": "Written by the LLM rationale layer over signals the engine computed; never a number." } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/wallet-pnl-quality": { "post": { "operationId": "walletPnlQuality", "summary": "Is the PnL real", "description": "Returns: verdict, real, washFlag, luckIndex. Costs 2 units per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — verdict, real, washFlag, luckIndex", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "verdict, real, washFlag, luckIndex", "properties": { "verdict": {}, "real": {}, "washFlag": {}, "luckIndex": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/wallet-archetype": { "post": { "operationId": "walletArchetype", "summary": "Wallet archetype", "description": "Returns: archetype, traits. Costs 2 units per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — archetype, traits", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "archetype, traits", "properties": { "archetype": {}, "traits": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/wallet-netflow": { "post": { "operationId": "walletNetflow", "summary": "Recent posture", "description": "Returns: posture, buyShare. Costs 1 unit per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — posture, buyShare", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "posture, buyShare", "properties": { "posture": {}, "buyShare": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/wallet-trades": { "post": { "operationId": "walletTrades", "summary": "Recent trades, banded", "description": "Returns: trades[{action, symbol, sizeBand, minsAgo}], summary{tilt, buyRatio, topTokens} — recent activity (banded). Costs 1 unit per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" }, "limit": { "type": "number" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — trades[{action, symbol, sizeBand, minsAgo}], summary{tilt, buyRatio, topTokens}", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "trades[{action, symbol, sizeBand, minsAgo}], summary{tilt, buyRatio, topTokens} — recent activity (banded)", "properties": { "trades": { "type": "array", "items": { "type": "object", "properties": { "action": {}, "symbol": {}, "sizeBand": {}, "minsAgo": {} }, "additionalProperties": true } }, "summary": { "type": "object", "properties": { "tilt": {}, "buyRatio": {}, "topTokens": {} }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/portfolio-risk": { "post": { "operationId": "portfolioRisk", "summary": "Aggregate holdings risk", "description": "Returns: grade, weightedRisk, riskyPositions. Costs 3 units per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 3, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" }, "depth": { "type": "number" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — grade, weightedRisk, riskyPositions", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "grade, weightedRisk, riskyPositions", "properties": { "grade": {}, "weightedRisk": {}, "riskyPositions": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/wallet-overview": { "post": { "operationId": "walletOverview", "summary": "The whole wallet page in one call", "description": "Returns: wallet, chain, bundle, traderScore, copySimulate, traderEdge, walletPnlQuality, walletArchetype, traderStyle, walletHealth, walletNetflow, walletTrades, failed[] — the whole trader/wallet page in one call; each slot is the verbatim response of the single endpoint it is named after (502 only when every component failed). Costs 14 units per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 14, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" }, "tradesLimit": { "type": "number" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — wallet, chain, bundle, traderScore, copySimulate, traderEdge, walletPnlQuality, walletArchetype, traderStyle, walletHealth, walletNetflow, walletTrades, failed[]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "wallet, chain, bundle, traderScore, copySimulate, traderEdge, walletPnlQuality, walletArchetype, traderStyle, walletHealth, walletNetflow, walletTrades, failed[] — the whole trader/wallet page in one call; each slot is the verbatim response of the single endpoint it is named after (502 only when every component failed)", "properties": { "wallet": {}, "chain": {}, "bundle": {}, "traderScore": {}, "copySimulate": {}, "traderEdge": {}, "walletPnlQuality": {}, "walletArchetype": {}, "traderStyle": {}, "walletHealth": {}, "walletNetflow": {}, "walletTrades": {}, "failed": { "type": "array", "items": {} } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/portfolio-overview": { "post": { "operationId": "portfolioOverview", "summary": "The portfolio screen in one call", "description": "Returns: wallet, chain, bundle, portfolioRisk, walletHealth, walletNetflow, failed[] — the holdings screen in one call: aggregate risk, drain exposure and recent posture, each slot the verbatim single-endpoint response. Costs 5 units per successful call (X-Usage-Units). Group: wallet.", "tags": [ "wallet" ], "x-cost-units": 5, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] }, "wallet": { "$ref": "#/components/schemas/Address" }, "depth": { "type": "number", "default": 5, "maximum": 10, "description": "top-N holdings for the risk read" } }, "required": [ "wallet" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK — wallet, chain, bundle, portfolioRisk, walletHealth, walletNetflow, failed[]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "wallet, chain, bundle, portfolioRisk, walletHealth, walletNetflow, failed[] — the holdings screen in one call: aggregate risk, drain exposure and recent posture, each slot the verbatim single-endpoint response", "properties": { "wallet": {}, "chain": {}, "bundle": {}, "portfolioRisk": {}, "walletHealth": {}, "walletNetflow": {}, "failed": { "type": "array", "items": {} } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/alert-check": { "post": { "operationId": "alertCheck", "summary": "Evaluate alert conditions against a target", "description": "Returns: fired, current, results. Costs 1 unit per successful call (X-Usage-Units). Group: infra.", "tags": [ "infra" ], "x-cost-units": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target", "conditions" ], "additionalProperties": false, "properties": { "target": { "type": "object", "required": [ "address" ], "properties": { "chain": { "$ref": "#/components/schemas/ChainSlug" }, "address": { "$ref": "#/components/schemas/Address" }, "kind": { "type": "string", "description": "token or wallet" } }, "additionalProperties": true }, "conditions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "A condition over a derived metric (metric, operator, value)." } } } } } } }, "responses": { "200": { "description": "OK — fired, current, results", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "fired, current, results", "properties": { "fired": {}, "current": {}, "results": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/signals/history": { "get": { "operationId": "signalsHistory", "summary": "Signal time-series for a token", "description": "Returns: history[{capturedAt, signal, ...derived, outcome24h, outcome7d}] — durable signal time-series. Costs 1 unit per successful call (X-Usage-Units). Group: signals.", "tags": [ "signals" ], "x-cost-units": 1, "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ChainSlug" } ] } }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "in hours", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK — history[{capturedAt, signal, ...derived, outcome24h, outcome7d}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "history[{capturedAt, signal, ...derived, outcome24h, outcome7d}] — durable signal time-series", "properties": { "history": { "type": "array", "items": { "type": "object", "properties": { "capturedAt": {}, "signal": {}, "outcome24h": {}, "outcome7d": {} }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/signals/track-record": { "get": { "operationId": "signalsTrackRecord", "summary": "Do the signals precede moves?", "description": "Returns: predictors[{predictor, hitRate, avgForwardReturnPct, samples}] — do the signals precede moves?. Costs 1 unit per successful call (X-Usage-Units). Group: signals.", "tags": [ "signals" ], "x-cost-units": 1, "parameters": [ { "name": "horizon", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d" ] } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK — predictors[{predictor, hitRate, avgForwardReturnPct, samples}]", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "predictors[{predictor, hitRate, avgForwardReturnPct, samples}] — do the signals precede moves?", "properties": { "predictors": { "type": "array", "items": { "type": "object", "properties": { "predictor": {}, "hitRate": {}, "avgForwardReturnPct": {}, "samples": {} }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/usage": { "get": { "operationId": "usage", "summary": "Your usage and the service data budget", "description": "Returns: unitsBilledToday, service budget. Costs 0 units per successful call (X-Usage-Units). Group: infra.", "tags": [ "infra" ], "x-cost-units": 0, "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 30, "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "OK — unitsBilledToday, service budget", "headers": { "X-Usage-Units": { "$ref": "#/components/headers/X-Usage-Units" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "description": "unitsBilledToday, service budget", "properties": { "unitsBilledToday": {} }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (key_live_… or key_test_…)", "description": "Partner API key as a Bearer token." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Partner API key in the x-api-key header." } }, "schemas": { "Address": { "type": "string", "description": "An EVM address (0x + 40 hex) or a Solana address (base58, 32–44 chars).", "pattern": "^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$", "example": "0x6982508145454ce325ddbe47a25d4ec3d2311933" }, "ChainSlug": { "type": "string", "description": "Chain slug: eth, base, polygon, bsc, arbitrum, optimism, avalanche, fantom, linea, pulse, ronin, solana, robinhood … (hex chain ids such as 0x1 are accepted too). Defaults to eth where optional.", "example": "eth" }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable code. Known codes: invalid_api_key, wallet_auth_required, wallet_auth_expired, invalid_address, invalid_chain, unknown_param, venue_not_entitled, not_found, not_a_token, rate_limited, capacity, gateway_unconfigured, execution_unavailable, analysis_failed, dossier_failed, method_not_allowed, internal.", "example": "invalid_api_key" }, "detail": { "type": "string", "description": "Human-readable explanation with the resolution where there is one." }, "hint": { "type": "string", "description": "Where to look next (404s)." }, "docs": { "type": "string", "format": "uri", "description": "Documentation URL (404s)." } }, "additionalProperties": true } }, "headers": { "X-Usage-Units": { "description": "Units billed for this call.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Requests per minute allowed for the key's plan.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (503 capacity).", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Invalid input — `invalid_address`, `invalid_chain`, `unknown_param`, or a missing required field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing/invalid API key (`invalid_api_key`), or missing/expired wallet authorization on execution routes (`wallet_auth_required`, `wallet_auth_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key is not entitled to the requested venue (`venue_not_entitled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Nothing to analyse at that address (`not_a_token`), or no such route (`not_found`, with `hint` and `docs`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Plan rate limit exceeded (`rate_limited`); see X-RateLimit-Limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Unexpected failure (`internal`, `analysis_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServiceUnavailable": { "description": "Daily data budget reached (`capacity`, with Retry-After), no keys provisioned (`gateway_unconfigured`), or execution not configured (`execution_unavailable`).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }