ohtrade文档
进入交易 ↗

开发应用或交易 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 域字段
PoolUSDC 为 0,OH 为 1
Kind开仓为 0,平仓为 1
Side多为 0,空为 1
Marginu64 微单位;平仓为零
Leverage签名消息中为 u32;平仓为零
Position开仓使用默认公钥,平仓指定真实持仓
Price boundu64,8 位小数;零明确表示无界限
Nonce当前账户重放窗口中的 u64
Signed / expiry slotu64;默认有效 75 槽位,最多 150
Minimum winning exposureu64 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 路径的保证金与租金清理以实际结果为准。旧账户、未偿债权和交易历史不会自动转换。

← 上一篇
协议权限与清退
下一篇 →
公开 HTTP 接口