API & MCP
Public read-only HTTP, SSE and WebSocket endpoints, signed write intents, and a read-only MCP server for AI agents.
The shadowpaper API exposes the protocol's public on-chain state. Read endpoints are public and require no API key; per-IP rate limits apply, and a rate-limited response returns HTTP 429 with a Retry-After header. The production base URL is published with the mainnet launch.
Conventions#
| Item | Convention |
|---|---|
| Amounts (USDT, SPAPER, margin, notional) | Decimal integer strings with 18 decimals |
| Prices | priceRaw = index × 10⁸, decimal integer string |
| Timestamps | Unix milliseconds |
| Errors | JSON code, with optional reason and message; HTTP 400, 403, 404, 409, 422 or 429 |
Markets and protocol#
| Endpoint | Returns |
|---|---|
GET /state/trading | Markets, leverage limits, open-interest caps and latest prices |
GET /query/markets/{id}/price-history | Index price history |
GET /query/markets/{id}/liquidation-map | Distribution of open positions' liquidation prices |
GET /query/prices/signed | Public log of signed prices (instrument, from, to, limit) |
GET /query/protocol/summary | LP, payout queue, SPAPER supply and mint curve state |
GET /query/protocol/trades/recent | Recent trades across the exchange |
GET /state/leaderboard/accounts · GET /state/leaderboard/positions | Leaderboards |
GET /query/notices | Announcements, including pending Timelock actions |
Accounts#
Account endpoints return the public on-chain view of any wallet.
| Endpoint | Returns |
|---|---|
GET /state/user/live?wallet= | Server-sent event stream of balances, positions and orders |
GET /query/accounts/{w}/trades | Trade history |
GET /query/accounts/{w}/cashflows | Deposits, withdrawals and claims |
GET /query/accounts/{w}/staking | Staking history |
GET /query/accounts/{w}/queue | Payout queue entries |
GET /query/accounts/{w}/orders | Resting limit orders and TP/SL |
GET /query/accounts/{w}/deposit-address | The wallet's CREATE2 deposit address |
Real-time#
WebSocket endpoint /connection/websocket. Each message is plain JSON of the form channel plus data; on connection the client receives the current frame of every channel.
| Channel | Content |
|---|---|
trading:current | Full market state, as in GET /state/trading |
public:trades | Recent public trades |
pressure:current | Relayer intake load and recent block gas usage |
Writing#
Trades and orders are EIP-712 typed-data intents posted to POST /intents. The API is non-custodial: every intent is signed by the trader's wallet or session key, and the contract re-verifies the signature and every price condition at settlement. The Exchange signing domain is shadowpaperExchange, version 2.
Example: Alice's session key signs an open-position intent for a 100× BTC long with 100 USDT margin. The relayer includes it in the next batch together with the signed price, and the position appears on /state/user/live once the batch settles.
MCP for AI agents#
A public, read-only Model Context Protocol (MCP) server is served at the /mcp path of the API host. Tools: markets, price, signed_prices, leaderboard, account and deposit_address. The read-only server holds no keys and cannot place trades. Agents follow exactly the same rules as other traders.