开发者
API 与 MCP
公开只读的 HTTP、SSE 与 WebSocket 接口、签名写入意图，以及面向 AI agent 的只读 MCP 服务。
shadowpaper API 提供协议的公开链上状态。读接口公开、无需 API key；按 IP 限流，触发限流时返回 HTTP 429 并附 Retry-After 头。生产环境 Base URL 将随主网上线公布。
约定#
| 项目 | 约定 |
|---|---|
| 金额（USDT、SPAPER、保证金、名义） | 18 位精度的十进制整数字符串 |
| 价格 | priceRaw = 指数价 × 10⁸，十进制整数字符串 |
| 时间戳 | Unix 毫秒 |
| 错误 | JSON 字段 code，可附 reason 与 message；HTTP 400、403、404、409、422 或 429 |
市场与协议#
| 接口 | 返回内容 |
|---|---|
GET /state/trading | 市场、杠杆限制、持仓上限与最新价格 |
GET /query/markets/{id}/price-history | 指数价历史 |
GET /query/markets/{id}/liquidation-map | 未平仓仓位的爆仓价分布 |
GET /query/prices/signed | 公开签名价日志（参数 instrument、from、to、limit） |
GET /query/protocol/summary | LP、赔付队列、SPAPER 供应量与铸造曲线状态 |
GET /query/protocol/trades/recent | 全站最近成交 |
GET /state/leaderboard/accounts · GET /state/leaderboard/positions | 排行榜 |
GET /query/notices | 公告，包括待执行的时间锁操作 |
账户#
账户接口返回任意钱包的公开链上视图。
| 接口 | 返回内容 |
|---|---|
GET /state/user/live?wallet= | 余额、仓位与委托的 SSE 推送流 |
GET /query/accounts/{w}/trades | 成交历史 |
GET /query/accounts/{w}/cashflows | 充值、提现与领取记录 |
GET /query/accounts/{w}/staking | 质押记录 |
GET /query/accounts/{w}/queue | 赔付队列条目 |
GET /query/accounts/{w}/orders | 当前限价单与止盈止损 |
GET /query/accounts/{w}/deposit-address | 该钱包的 CREATE2 充值地址 |
实时推送#
WebSocket 接口 /connection/websocket。每条消息为包含 channel 与 data 的纯 JSON；建立连接后，客户端即收到各频道的当前帧。
| 频道 | 内容 |
|---|---|
trading:current | 完整市场状态，与 GET /state/trading 相同 |
public:trades | 最近公开成交 |
pressure:current | relayer 待处理负载与最近区块 gas 使用情况 |
写入#
交易与委托是 EIP-712 结构化签名意图，提交至 POST /intents。API 不托管任何资产：每条意图均由交易者的钱包或会话密钥签名，合约在结算时重新验证签名及全部价格条件。Exchange 签名域为 shadowpaperExchange，版本 2。
示例：Alice 的会话密钥签署一条开仓意图（BTC 多单，100× 杠杆，保证金 100 USDT）。relayer 将其与签名价一同放入下一批次；批次结算后，该仓位出现在 /state/user/live 中。
面向 AI agent 的 MCP#
API 主机的 /mcp 路径提供公开只读的 Model Context Protocol（MCP）服务，工具包括 markets、price、signed_prices、leaderboard、account 与 deposit_address。只读服务不持有任何密钥，不能下单。agent 与其他交易者遵守完全相同的规则。