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

# 开发应用或交易 Agent

ohtrade 提供公开账户读取和钱包授权操作。你可以建设自己的界面，Agent 也可以按所有者授权准备并签署操作。签名密钥保留在钱包或获授权的签名设备中。

从 **/llms.txt** 查看文档目录，**/docs/manifest.json** 查看版本和页面链接，**/docs/openapi.json** 查看 HTTP 参考。每一页 Docs 都有 Markdown 版本，公开阅读资源的可访问性与交易功能分别处理。

## 先固定部署身份

读取 `/api/funding/config`、`/api/trading/config` 和 `/api/protocol/config`，将程序、集群、genesis 及结算代币标识与用户已批准的部署核对。账户操作是否开启见 `funding/config.execution.enabled`，拍卖见 `protocol/config.enabled`。交易配置没有统一的 enabled 字段；intent 服务不可用时返回 503。请求签名前先检查相应操作状态。

使用匹配的 SDK 和 IDL。公开 GET 不需要钱包签名或 API key；这些接口返回的钱包地址和账户活动属于公开信息。

## 快速交易路径

intent 接口接收由账户所有者或有效交易密钥签署的 **175 字节小端序消息**：

```text
POST /api/trading/intent
Content-Type: application/json

{
  "intent": "EXACT_175_SIGNED_BYTES_AS_BASE64",
  "signature": "ED25519_SIGNATURE_64_BYTES_AS_BASE64",
  "signer": "SIGNING_SOLANA_PUBLIC_KEY"
}
```

使用匹配 SDK 的 `encodeIntent`。签名字段包括域、程序 ID、owner、抵押池、动作、市场 ID、方向、保证金、杠杆、仓位、价格界限、nonce、签名槽位、过期槽位和最低盈利计算金额（`minExposure`）。

| 字段 | 编码与含义 |
|---|---|
| Domain | 固定 16 字节 `ohtrade:intent:2` 域字段 |
| Pool | USDC 为 0，OH 为 1 |
| Kind | 开仓为 0，平仓为 1 |
| Side | 多为 0，空为 1 |
| Margin | u64 微单位；平仓为零 |
| Leverage | 签名消息中为 u32；平仓为零 |
| Position | 开仓使用默认公钥，平仓指定真实持仓 |
| Price bound | u64，8 位小数；零明确表示无界限 |
| Nonce | 当前账户重放窗口中的 u64 |
| Signed / expiry slot | u64；默认有效 75 槽位，最多 150 |
| Minimum winning exposure | u64 micro-units at byte offset 167; zero for close; signed `minExposure` for open |

程序 ID 在签名消息中。Genesis 通过部署与可信 RPC 配置核对，不是这份消息中的独立字段。有效期按槽位计算，不要写死为固定秒数。

接收成功返回 `{id, accepted: true}`，intent ID 格式为 **owner:pool:nonce**。此时只是接单，尚未成交。

## 跟踪执行结果

订阅 `/api/trading/events?owner=PUBLIC_KEY`，并刷新 `/api/trading/snapshot?owner=PUBLIC_KEY`。SSE 包含 request、fill、rejected、cancelled 和 snapshot 事件；成交会推进 processed、confirmed、finalized 阶段。重新连接后，先与新快照核对。

不要把 intent ID 传给 `/api/trading/status`，它查询的是 prepare 交易。Intent 应保留原消息、签名、nonce、ID，通过对应执行事件和账户状态确认结果。拒绝也可能消耗 nonce，因此不能仅凭 nonce 已使用就判断成交。

## 账户、传统订单与拍卖

这些操作使用 prepare → 签名 → submit：

| 操作类别 | 准备 | 提交 | 查询 |
|---|---|---|---|
| 账户、充提、质押、租金、授权 | `/api/funding/account/prepare` | `/api/funding/account/submit` | `/api/funding/account/status?id=…` |
| 传统开平仓、Request 撤销 | `/api/trading/prepare` | `/api/trading/submit` | `/api/trading/status?id=…` |
| 回购挂单、改价、撤单 | `/api/protocol/prepare` | `/api/protocol/submit` | `/api/protocol/operation?id=…` |

签名前检查返回消息中的动作、金额、目标地址、部署、费用付款人、租金和有效期。代付交易通常需要 owner 或允许的 session 签名，加服务器付款人签名；主动选择的自付后备路径使用不同签名组合，不要假设所有接口都固定两位签名者。

交易和拍卖的准备结果可能返回 `quoteToken`。把这份报价凭证与操作记录一起保存，提交时原样回传；将其作为不透明字符串处理。它用于恢复被有限缓存淘汰的未签名预览，钱包签名和原准备结果的有效期仍然适用。

批量撤单要把主交易和所有 `followUps` 一起签好，再提交同一组原始字节。当前一次批准最多覆盖八片；持续检查 `afterBatch`、`awaitingSignature`、`presignedRemaining`，需要新的批准时准备 `continue_cancel`。

## 精确金额与恢复

USDC 和 OH 为 **6 位小数**，价格为 **8 位**，JSON 使用十进制整数字符串。100 OH、每 OH 0.25 USDC 为：

```json
{"amount":"100000000","price":"25000000"}
```

使用整数或 bigint。**提交前**持久化操作 ID、已批准条款和完整签名字节。响应不明时先查询原操作并核对状态。准备后的交易可以重发原字节，但换 blockhash 构造新交易属于新的授权决定。

`historyUnavailable` 表示结果尚未确定。未提交的准备可以到期；签名字节可能已经广播后，需要继续核对原签名。交易 prepare 路径中的 `neverLanded`，只有在 finalized 过期且有链上状态证明后才返回。界面报价过期本身不能判断广播结果；已确认失败和 RPC 超时要分开处理。

## 费用与服务额度

服务器承担受支持代付交易的网络费，用户承担可退存储租金。Intent 开仓需要共享预存 SOL 中的 Position 租金，传统 Request 路径还要临时请求租金和未来持仓预留。

HTTP 429 提供重试信息。遵守 `Retry-After` 和结构化 `code`，不要解析自然语言提示。转发额度及赞助预算属于服务控制，可与链上账户上限不同；选择自付后备路径应得到 owner 明确批准。

funding、trading 和 protocol 入口使用 HTTPS 和 CORS，不需要私密服务 API key。内部 Keeper 凭据不属于这套公开接口。可以先从只读请求开始，再为每项写操作取得所有者授权。

## V11 本地实现说明

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

签名前须核对部署程序、SDK/IDL、经济版本 11 和最终波动率校准哈希。仅有 175 字节的 Intent 不能证明账户兼容。保留确切的签署条款，以执行事件及账户状态核对拒单或成交；开仓被拒不能视为已有仓位，Request 路径的保证金与租金清理以实际结果为准。旧账户、未偿债权和交易历史不会自动转换。
