{"openapi":"3.1.0","info":{"title":"papertrade-x402","version":"0.1.0","description":"Unofficial pay-per-call Papertrade intelligence API (x402). Networks: none configured. Not affiliated with Papertrade.","license":{"name":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}},"servers":[{"url":"https://papertrade-x402.pages.dev"}],"paths":{"/api/v1/health":{"get":{"summary":"Service health","tags":["free"],"responses":{"200":{"description":"Status of the API, the Papertrade upstream and x402 configuration"}}}},"/api/v1/markets":{"get":{"summary":"Live instruments and mark prices","tags":["free"],"responses":{"200":{"description":"Instruments with mark price, limits and open interest"}}}},"/api/v1/preview/wallet/{address}/risk":{"get":{"operationId":"preview_wallet_risk","summary":"Wallet liquidation risk (free preview)","description":"Free, rate limited. Same live computation as the paid endpoint, without: per-position bust prices, scores and settlement estimates. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; 429 includes Retry-After.","tags":["free","preview"],"responses":{"200":{"description":"Preview result"},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"},"502":{"description":"Papertrade upstream unavailable"}},"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"HyperEVM wallet address of the Papertrade trader"},"description":"HyperEVM wallet address of the Papertrade trader"}]}},"/api/v1/wallet/{address}/risk":{"get":{"operationId":"wallet_risk","summary":"Wallet liquidation risk","description":"Open Papertrade positions of a wallet with bust price, distance to liquidation, a 0-100 liquidation-risk score, effective leverage, unrealized PnL and the net settlement if closed at the live mark.","tags":["paid"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string"},"asOf":{"type":"string"},"balanceUsd":{"type":"number"},"summary":{"type":"object","properties":{"openPositions":{"type":"number"},"totalNotionalUsd":{"type":"number"},"unrealizedPnlUsd":{"type":"number"},"accountEffectiveLeverage":{"type":"number"},"maxRiskScore":{"type":"number"},"nearestBustDistancePct":{"type":"number"}}},"positions":{"type":"array","items":{"type":"object","properties":{"positionId":{"type":"string"},"market":{"type":"string"},"side":{"type":"string"},"leverage":{"type":"number"},"entryPrice":{"type":"number"},"markPrice":{"type":"number"},"bustPrice":{"type":"number"},"bustDistancePct":{"type":"number"},"riskScore":{"type":"number"},"riskBand":{"type":"string"},"effectiveLeverage":{"type":"number"},"unrealizedPnlUsd":{"type":"number"},"estimatedCloseNetUsd":{"type":"number"}}}}}}}}},"400":{"description":"Invalid input (not charged)"},"402":{"description":"Payment required. The PAYMENT-REQUIRED header carries the base64 x402 v2 requirements."},"502":{"description":"Papertrade upstream unavailable (not charged)"},"503":{"description":"Payment addresses are not configured on this deployment"}},"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"HyperEVM wallet address of the Papertrade trader"},"description":"HyperEVM wallet address of the Papertrade trader"}]}},"/api/v1/preview/liquidations/nearby":{"get":{"operationId":"preview_liquidations_nearby","summary":"Nearby liquidations map (free preview)","description":"Free, rate limited. Same live computation as the paid endpoint, without: price buckets; nearest positions; scan of more than 5 accounts. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; 429 includes Retry-After.","tags":["free","preview"],"responses":{"200":{"description":"Preview result"},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"},"502":{"description":"Papertrade upstream unavailable"}},"parameters":[{"name":"market","in":"query","required":false,"schema":{"type":"string","enum":["BTC","ETH"],"default":"BTC"}},{"name":"pct","in":"query","required":false,"schema":{"type":"number","exclusiveMinimum":0,"maximum":25,"default":0.5,"description":"Window around mark, in percent"},"description":"Window around mark, in percent"},{"name":"accounts","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":20,"description":"Leaderboard accounts to scan"},"description":"Leaderboard accounts to scan"}]}},"/api/v1/liquidations/nearby":{"get":{"operationId":"liquidations_nearby","summary":"Nearby liquidations map","description":"Open positions of the top leaderboard accounts whose bust price is within pct percent of the live mark, aggregated into 20 price buckets (a liquidation map), plus protocol-wide totals for the same window.","tags":["paid"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"market":{"type":"string"},"markPrice":{"type":"number"},"window":{"type":"object","properties":{"pct":{"type":"number"},"low":{"type":"number"},"high":{"type":"number"}}},"totals":{"type":"object"},"buckets":{"type":"array","items":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"longNotionalUsd":{"type":"number"},"shortNotionalUsd":{"type":"number"},"longCount":{"type":"number"},"shortCount":{"type":"number"}}}},"nearest":{"type":"array","items":{"type":"object"}},"protocolWide":{"type":"object"}}}}}},"400":{"description":"Invalid input (not charged)"},"402":{"description":"Payment required. The PAYMENT-REQUIRED header carries the base64 x402 v2 requirements."},"502":{"description":"Papertrade upstream unavailable (not charged)"},"503":{"description":"Payment addresses are not configured on this deployment"}},"parameters":[{"name":"market","in":"query","required":false,"schema":{"type":"string","enum":["BTC","ETH"],"default":"BTC"}},{"name":"pct","in":"query","required":false,"schema":{"type":"number","exclusiveMinimum":0,"maximum":25,"default":0.5,"description":"Window around mark, in percent"},"description":"Window around mark, in percent"},{"name":"accounts","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":20,"description":"Leaderboard accounts to scan"},"description":"Leaderboard accounts to scan"}]}},"/api/v1/preview/estimate":{"post":{"operationId":"preview_estimate","summary":"Settlement estimate for a hypothetical trade (free preview)","description":"Free, rate limited. Same live computation as the paid endpoint, without: close at a chosen exit; PAPER mint estimate; price-move scenario ladder. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; 429 includes Retry-After.","tags":["free","preview"],"responses":{"200":{"description":"Preview result"},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"},"502":{"description":"Papertrade upstream unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"market":{"type":"string","enum":["BTC","ETH"]},"side":{"type":"string","enum":["long","short"]},"marginUsd":{"type":"number","exclusiveMinimum":0},"leverage":{"type":"integer","minimum":1,"maximum":1000},"entryPrice":{"type":"number","description":"Defaults to the live mark"},"exitPrice":{"type":"number","description":"Absolute exit price (or use exitMovePct)"},"exitMovePct":{"type":"number","description":"Signed percent move from entry (or use exitPrice)"}},"required":["market","side","marginUsd","leverage"]},"example":{"market":"BTC","side":"long","marginUsd":100,"leverage":100,"exitMovePct":-0.5}}}}}},"/api/v1/estimate":{"post":{"operationId":"estimate","summary":"Settlement estimate for a hypothetical trade","description":"Estimate what a hypothetical Papertrade position settles for: bust price, limit checks, the close at a chosen exit (deadband, impact, 2% win fee), PAPER minted on a loss, and a ladder of price-move scenarios.","tags":["paid"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"market":{"type":"string"},"notionalUsd":{"type":"number"},"entryPrice":{"type":"number"},"bustPrice":{"type":"number"},"wouldBeAccepted":{"type":"boolean"},"openIssues":{"type":"array","items":{"type":"string"}},"close":{"type":"object","properties":{"exitPrice":{"type":"number"},"outcome":{"type":"string"},"netPnlUsd":{"type":"number"},"winFeeUsd":{"type":"number"},"paperMinted":{"type":"number"}}},"scenarios":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid input (not charged)"},"402":{"description":"Payment required. The PAYMENT-REQUIRED header carries the base64 x402 v2 requirements."},"502":{"description":"Papertrade upstream unavailable (not charged)"},"503":{"description":"Payment addresses are not configured on this deployment"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"market":{"type":"string","enum":["BTC","ETH"]},"side":{"type":"string","enum":["long","short"]},"marginUsd":{"type":"number","exclusiveMinimum":0},"leverage":{"type":"integer","minimum":1,"maximum":1000},"entryPrice":{"type":"number","description":"Defaults to the live mark"},"exitPrice":{"type":"number","description":"Absolute exit price (or use exitMovePct)"},"exitMovePct":{"type":"number","description":"Signed percent move from entry (or use exitPrice)"}},"required":["market","side","marginUsd","leverage"]},"example":{"market":"BTC","side":"long","marginUsd":100,"leverage":100,"exitMovePct":-0.5}}}}}},"/api/v1/preview/traders/top":{"get":{"operationId":"preview_traders_top","summary":"Top traders with derived stats (free preview)","description":"Free, rate limited. Same live computation as the paid endpoint, without: ranks beyond 3; derived win rate, leverage and hold-time stats; open exposure. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; 429 includes Retry-After.","tags":["free","preview"],"responses":{"200":{"description":"Preview result"},"400":{"description":"Invalid input"},"429":{"description":"Rate limited"},"502":{"description":"Papertrade upstream unavailable"}},"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d","all"],"default":"7d"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}]}},"/api/v1/traders/top":{"get":{"operationId":"traders_top","summary":"Top traders with derived stats","description":"Top Papertrade traders by windowed PnL with open exposure and stats derived from their recent closed trades: win rate, average and margin-weighted leverage, liquidations and average hold time.","tags":["paid"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"string"},"traders":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"number"},"wallet":{"type":"string"},"windowedPnlUsd":{"type":"number"},"volumeUsd":{"type":"number"},"open":{"type":"object"},"stats":{"type":"object","properties":{"winRatePct":{"type":"number"},"avgLeverage":{"type":"number"},"marginWeightedLeverage":{"type":"number"},"liquidations":{"type":"number"},"closedTrades":{"type":"number"}}}}}}}}}}},"400":{"description":"Invalid input (not charged)"},"402":{"description":"Payment required. The PAYMENT-REQUIRED header carries the base64 x402 v2 requirements."},"502":{"description":"Papertrade upstream unavailable (not charged)"},"503":{"description":"Payment addresses are not configured on this deployment"}},"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d","all"],"default":"7d"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}]}},"/mcp":{"post":{"operationId":"mcp","summary":"MCP server (Streamable HTTP, stateless JSON-RPC 2.0)","description":"Model Context Protocol endpoint. Methods: initialize, ping, tools/list, tools/call. Free tools return live data; paid tools return x402 payment requirements and never pay. See /docs/mcp/.","tags":["free","mcp"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number"]},"method":{"type":"string"},"params":{"type":"object"}}},"example":{"jsonrpc":"2.0","id":1,"method":"tools/list"}}}},"responses":{"200":{"description":"JSON-RPC response (application/json, or one SSE message event when only text/event-stream is accepted)"},"202":{"description":"Notification accepted"},"400":{"description":"Parse error or invalid request"},"429":{"description":"Rate limited"}}}}}}