Canonical: https://ohtrade.xyz/docs/zh-CN/api.html
Language: zh-CN
Updated: 2026-11-08

# 公开 HTTP 接口

下列路径相对于所选 ohtrade 部署。先读取部署配置；预览模式可能开放公共读取，同时关闭资金执行。

机器可读说明位于 **/docs/openapi.json**，常用请求结构与 intent 布局随文档索引一起发布。本页描述当前接口类别，不是一套额外的登录服务。

## 读取接口

| 方法与路径 | 用途 |
|---|---|
| `GET /api/markets/quotes` | 参考价格与图表历史 (`quotes`) |
| `GET /api/markets/history?schema=3&symbol=BTC` | 参考价格与图表历史 (`history`) |
| `GET /api/funding/config` | 网络、程序、genesis、结算币、功能状态和代付策略 |
| `GET /api/trading/config` | 网络标识、最低名义开仓额及费用策略 |
| `GET /api/protocol/config` | 拍卖配置与功能状态 |
| `GET /api/trading/snapshot?owner=…` | 市场、持仓、待处理状态、余额、nonce 和租金容量 |
| `GET /api/protocol/snapshot?owner=…` | 资金池、质押、回购及协议状态 |
| `GET /api/funding/account?owner=…` | 用户协议账户与资金余额 |
| `GET /api/funding/wallet?owner=…` | 钱包 SOL 与受支持 USDC 余额 |
| `GET /api/funding/rent/configuration?owner=…` | 租金预算与可新增容量 |
| `GET /api/funding/rent?owner=…` | 租金项目和可退款状态 |
| `GET /api/funding/refund?owner=…&mode=staking` | 账户退出计划与阻塞原因 |
| `GET /api/funding/account/fees` | 当前网络费选项 |
| `GET /api/trading/session?owner=…&authority=…` | 交易授权状态 |
| `GET /api/funding/referrals?owner=…&offset=…` | 每页 50 位受邀账户 |
| `GET /api/funding/history?owner=…&before=…&limit=…` | 按签名分页的已确认账户历史 |
| `GET /api/protocol/auction/rounds?before=…&limit=…` | 回购轮次历史 |
| `GET /api/trading/events?owner=…` | 执行事件 SSE |

交易与协议快照省略 owner 时返回公开部分。个人账户读取需要有效公钥，但读取请求不证明调用者拥有该钱包，公开活动也可由其他客户端查询。

## 参考价格与图表历史

行情服务只提供读取。`/api/markets/quotes` 返回 `now`、`historyEpoch`、`historyStartedAt` 和 `markets`。各市场包含 `id`、`symbol`、`session`、`sessionOpen`、`price`、`bid`、`ask`、`updatedAt`、`sources`、`status`，以及已有的 `chartTick` 和 `referencePoints`。价格以 **8 位小数的 USDC 整数字符串**表示；时间为 UTC Unix 毫秒。不可用的价格、买卖价或更新时间为 `null`。

各市场标有 `executionEnabled:false` 和 `referenceOnly:true`。`sessionOpen` 仅表示参考交易时段，不能据此提交金融操作。`status` 为 `live`、`degraded` 或 `unavailable`。短暂中断时，降级报价可能保留原始观测时间，使用前应检查时间；旧 `chartTick` 属于历史记录。

历史请求使用 `schema=3` 和市场列表中大小写完全一致的大写 `symbol`。响应含 `epoch`、`startedAt`、`currency:USDC`、`source:ohtrade-canonical-quotes`，以及三个独立的数据流：`ticks`、15 秒 `candles`、900 秒 `coarseCandles`。每页每个流最多 1,000 项；最多保留最近 7,200 个 tick、24 小时基础 K 线和 30 天粗粒度 K 线。中断或新市场的数据可能更少。

| 参数 | 用途 |
|---|---|
| `epoch` | 轮询时原样带回 epoch。省略或不匹配时，服务器仅将 `after` 重置为零。 |
| `after` | 非负安全整数序号，默认 `0`；读取更新的 tick 和变化的 K 线。两种周期的最后两根 K 线可能重复返回，以更新覆盖状态。 |
| `beforeTick` | 旧 tick 的 UTC 毫秒时间上界，不含该时刻；使用 `olderTicksBefore`。 |
| `beforeCandle` | 旧基础 K 线的时间上界，不含该时刻；使用 `olderCandlesBefore`。 |
| `beforeCoarse` | 旧粗粒度 K 线的时间上界，不含该时刻；使用 `olderCoarseBefore`。 |

旧页游标为 `null` 表示该流已读完。如果其他流还需翻页，将已读完的流对应 `before` 设为 `1`，避免再次读取最新页。tick 按 `sequence` 合并；K 线按桶起始 `time` 合并，保留更大的 `lastSequence`，同序号也接受覆盖状态更新。向前翻旧页之前，保存首个最新页的 `sequence`；旧页全部成功后才把实时 `after` 推进到这个保存值。后续页可能报告更高的实时序号，却没有包含那些新 tick。epoch 变化时清空旧数据和全部游标，重新读取。

tick 的 `time` 是采样时间，`observedAt` 是底层报价证据时间，`sourceAgeMs` 是采样时测得的证据年龄，`gapBefore` 标记中断。K 线包含真实采样的 `open`、`high`、`low`、`close`、`samples`、`firstAt`、`lastAt`、`lastSequence`、`partial`。`partial` 表示覆盖不完整。缺失观测保持缺失，不用虚构价格补齐，也不导入交易所成交 K 线。

```sh
curl https://ohtrade.xyz/api/markets/quotes
curl 'https://ohtrade.xyz/api/markets/history?schema=3&symbol=BTC'
```

这两个接口**仅接受 GET**，返回 `Cache-Control: no-store`，遵循网站地区访问规则，不提供金融 API 的 CORS/OPTIONS 接口。无效历史参数返回 `400`；其他方法被拒绝。请使用网站域名下的公开路径。

## 报价与 intent

`POST /api/trading/quote` 接收开仓预览：`asset`、`marketId`、`side`、`amount`、`leverage` 和可选 `owner`。返回的是参考报价，还没有创建成交仓位。

`POST /api/trading/intent` 接收 `{intent, signature, signer}`，消息和 64 字节签名使用 base64。返回 `{id, accepted:true}` 表示已接收，需要通过 SSE 与账户状态确认成交。[Agent 指南](https://ohtrade.xyz/docs/zh-CN/agents.md)说明签名字段和恢复流程。

## 准备与提交

| 类别 | Prepare 内容 | Submit 内容 |
|---|---|---|
| 交易 | `owner`, `kind`, `asset`, 保证金／杠杆或 position／Request；`orderType` 为 `market` 或 `limit` | `id`、`transaction`，以及返回的可选 `quoteToken` |
| 账户 | `owner`、`action`，以及金额、接收人、邀请或租金配置 | `id`、`transaction` |
| 拍卖 | `owner`、`kind`，以及金额／价格或订单地址／修订号／选择范围 | `id`、`transaction`，有后续片时加签好的 `followUps`，以及返回的可选 `quoteToken` |

准备的 `transaction` 为 base64 Solana 序列化交易。添加钱包签名时保留完整原消息，批准前核对部署标识、预期费用付款人和存储成本。返回的 `quoteToken` 应与操作记录一起保存，提交时原样回传。

持久限价传 `orderType: "limit"` 与正整数字符串 `orderPrice`（价格 8 位小数）。平仓还需 `triggerAbove: 1`（价格 ≥ 目标）或 `0`（≤）。准备接口不传 `priceBound`，旧价格保护输入会被拒绝；市价无界限。限价使用 Request，不使用短期 intent。快照提供 `orderMode`（0 市价／旧版，1 限价开仓，2 平仓 ≥，3 平仓 ≤）、`orderPrice` 和仓位地址。条件委托创建、日常撤销使用普通代付预算；实际市价平仓及退出操作保留原退出预算规则。可用性取决于部署的合约及金融服务是否启用。

交易 kind 包括 `open`、`close`、`cancel_request`。拍卖 kind 包括 `sell`、`amend_sell`、`cancel_sell`、`cancel_sells`、`cancel_all`、`continue_cancel`，改价需要订单地址及预期修订号。

账户动作覆盖开户、充提、内部 OH 划转、质押解押、领取、交易授权、SOL 租金存取和符合条件的账户退款。返回报价列出这次账户变化和阻塞条件。

## 状态与撤单进度

- 准备交易：`GET /api/trading/status?id=…&owner=…`。
- 账户操作：`GET /api/funding/account/status?id=…`。
- 拍卖操作：`GET /api/protocol/operation?id=…&owner=…`。
- 撤单批次：`GET /api/protocol/cancellation?operationId=…&owner=…`。

状态区分确认、失败、过期及历史不可用；撤单进度还区分已处理选择项、待签名工作和待清理租金。

## 响应处理

POST 请求使用 `Content-Type: application/json`。funding、trading 和 protocol API 前缀支持带 CORS 的 GET、POST 和 OPTIONS。普通读取及签名提交无需公共 API 密钥或 Cookie。

资金数量保持十进制整数字符串。将 400 系列校验／权限错误、429 限频和 503 忙碌／不可用分开处理；稳定的接入字段是错误 `code`，自然语言提示可以本地化。

```sh
curl https://ohtrade.xyz/api/trading/config
curl 'https://ohtrade.xyz/api/protocol/snapshot'
```

构造授权操作时使用钱包签名流程，不向 HTTP 服务发送私钥。生成的 OpenAPI 只列公开接口。

## V11 本地实现说明

本 V11 构建仅支持全新部署。账户判别符与布局已变化，须使用同一发布版本的 `sdk/idl/perp.json` 和 SDK 解码；本构建不支持把旧账户重新解释或原地升级。Intent 消息版本与账户 ABI 是两回事。

经济版本 11：开仓预览返回 `exposure`，即压力调整后的盈利计算敞口 C，不是预留赔付预算。`minExposure` 是用户签署的接受下限，以抵押币原子单位表示，不得超过名义金额；网站默认 `minExposure = 0`；API 调用者仍可明确签署非零下限，作为自己的接受条件。执行时低于签署下限会拒绝开仓；机器人签 0 只关闭这一项下限检查，不关闭保证金、报价、整数容量或权限检查。Intent v2 仍为 175 字节，`minExposure` 位于偏移 167，平仓须为 0。开仓从 UTC 表选取 D 并以 ppb 保存。计算与取整见 [盈亏](https://ohtrade.xyz/docs/zh-CN/pnl.md)。本地 V11 实现不代表线上部署已经切换版本。
