用途：为 AI 智能体提供接入 ORO GRAIL 黄金基础设施的快速参考，适用于需要查询金价、估算买卖成本、执行黄金买卖、创建用户与查询余额的集成场景。
主要能力：通过 Pyth 预言机获取当前金价；估算买入黄金所需 USDC 或卖出黄金可得 USDC；为用户或合作伙伴金库买入黄金；卖出用户或合作伙伴的黄金储备；创建已 KYC 的用户并查询用户详情与余额；查询合作伙伴信息。
使用方式：基础地址为 https://oro-tradebook-devnet.up.railway.app/api。认证分三步：先 POST /auth/challenge 提交 walletAddress、keyType、partnerId 获取挑战；再用 Ed25519（nacl.sign.detached）对消息签名；最后 POST /auth/api-key 提交 challengeId、signature、keyName 换取 API 密钥。后续请求在请求头携带 x-api-key: your-key。核心端点包括 GET /trading/gold-price、POST /trading/estimate/buy、POST /trading/estimate/sell、POST /trading/purchases/user、POST /trading/purchases/partner、POST /trading/sales/user、POST /trading/sales/partner、POST /users、GET /users/{id}、GET /distribution/partner/me。references/ 目录提供价格查询、余额查询、买入、卖出、定投（DCA）等脚本模式。
关键概念：托管模式下由集成方持有用户黄金，用户不接触区块链；自托管模式下用户在自己的钱包持有 GRAIL 代币；合作伙伴为集成账户，需白名单审批；PDA 为链上存储黄金的程序派生地址。
适用场景：价格监控与告警智能体、按计划自动买入的定投智能体、跟踪智能体或用户黄金持仓的余额智能体、通过金库实现的智能体间黄金打赏。
限制：合作伙伴账户需白名单审批；认证依赖钱包签名；资料未提供具体费率、限额、支持网络及错误码等细节。