开发应用或交易 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 字节小端序消息:
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 为:
{"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 路径的保证金与租金清理以实际结果为准。旧账户、未偿债权和交易历史不会自动转换。