跳转到主要内容

先报价,再用 max_price_trx 购买

已连接的应用必须向 buy_energy 和 buy_bandwidth 传入 max_price_trx。缺少它时调用会以 MAX_PRICE_REQUIRED 失败——每日上限需要知道一次调用最多可能花多少。
  1. 使用数量和时长调用 quote_energy(或 quote_bandwidth)。
  2. 向用户展示报价中的 total_trx。
  3. 使用相同的数量和时长调用 buy_energy,并令 max_price_trx = 报价的 total_trx。
如果价格超过 max_price_trx,购买会以 PRICE_CHANGED 被拒绝,不会扣款。请重新报价并询问用户。 对于 API 密钥,max_price_trx 是可选的,但出于同样的原因我们建议传入。

幂等键

创建类工具接受 idempotency_key——即其路由的 Idempotency-Key 请求头。为每个新操作生成新的 UUID,并在超时或响应丢失后重试同一操作时复用它:服务器会返回第一次的结果,而不会再次扣款。密钥有效期 24 小时,最长 64 个字符。 同一个密钥用于不同的请求会以 IDEMPOTENCY_KEY_REUSED 被拒绝;如果该密钥的第一个请求仍在执行,会返回 IDEMPOTENT_REQUEST_IN_PROGRESS——请稍候,并用同一个密钥重试。

每日消费上限

每个连接在任意 24 小时内可以花费一个设定的金额——100 TRX,除非用户在授权页面或 已连接的应用 中选择了其他金额。只有账户所有者可以取消上限。
  • 在会产生支出的调用之前,服务器会预留它最多可能花费的金额:购买时为 max_price_trx 加上新地址的激活费用;Smart Mode、套餐、激活和 Node API 套餐为其价格;质押为质押金额。
  • 调用结束后,预留变为实际金额;如果没有扣款则释放。如果结果未知(超时),预留保留 24 小时——上限宁可拒绝也不冒险。
  • 自动执行的支出(recurring)不计入上限。
  • 控制台中的 已连接的应用 显示每个应用最近 24 小时的支出。
超出上限的调用会以 AGENT_SPEND_CAP 失败:
重试响应丢失的购买会再次预留其金额。接近上限时,重试前请先检查 list_orders:第一次调用可能已经成功。

订单来源

已连接的应用下的订单带有 "source": "agent"——在 get_order、list_orders 和 order.updated webhook 中。使用 API 密钥下的订单带有 "source": "api"。

错误代码

通过 MCP,错误以 isError: true 的工具结果返回:
通过 REST,同样的代码以标准错误格式返回。 其他所有代码与 REST API 相同——见错误处理。 过期或已撤销的令牌在 /mcp 请求本身上会得到 HTTP 401 和 WWW-Authenticate: Bearer ... error="invalid_token";MCP 客户端随后会刷新令牌或请用户重新登录。