Overview

papertrade-x402 is an unofficial, pay-per-call intelligence API over Papertrade, the on-chain 1000x synthetic perpetuals exchange on Hyperliquid HyperEVM. It answers four questions an agent or a trader keeps asking, and it charges per request in USDC with the x402 protocol. There are no API keys and no accounts. Solana is the first payment rail, Base is the second.

Unofficial integration. Not affiliated with, endorsed by or operated by Papertrade. High leverage can lose your entire margin. Nothing here is financial advice.

What you can ask#

Endpoint	Question it answers	Default price
`GET /api/v1/wallet/{address}/risk`	How close is each open position of this wallet to liquidation?	$0.02
`GET /api/v1/liquidations/nearby`	Where are the liquidations stacked around the live mark?	$0.05
`POST /api/v1/estimate`	What would this hypothetical position settle for?	$0.005
`GET /api/v1/traders/top`	Who is winning, and how do they trade?	$0.03

Prices are operator settings, so the live values in /.well-known/x402 are the source of truth.

Three ways in#

Free preview tier. Every paid endpoint has a rate limited free preview under /api/v1/preview/* that runs the same live computation and withholds the detail that makes the paid answer worth paying for. See API reference.
MCP server. Connect Claude, Codex, ChatGPT, Gemini, Cursor and others to https://papertrade-x402.pages.dev/mcp. Free tools return data directly. Paid tools return the exact x402 payment requirements and never pay. See MCP and Connect your AI.
Pay and call. An agent that holds its own wallet calls a paid route, receives HTTP 402 with a PAYMENT-REQUIRED header, signs one option and retries. See Paying as an agent.

Current deployment status#

The operator has to set a payout address before paid routes can accept money. Until then paid routes answer an explanatory 503 not_configured that links to the free tier, and accepts in the discovery document is empty. Nothing is invented: the service never fabricates a payTo. Check status in /.well-known/x402 (accepting_payments or payments_not_configured) or call the get_service_status MCP tool.

Where the data comes from#

Every answer is computed live from the Papertrade protocol through the papertrade-sdk read layer and the public exchange API at https://exchange.papertrade.xyz. Formulas (bust price, close settlement) come from the SDK, not from a reimplementation. Responses are never cached long enough to be stale and never filled with sample data.

Next#

Quickstart, then Concepts for the Papertrade rules that shape every number.