先报价,再用 max_price_trx 购买
已连接的应用必须向 buy_energy 和 buy_bandwidth 传入 max_price_trx。缺少它时调用会以 MAX_PRICE_REQUIRED 失败——每日上限需要知道一次调用最多可能花多少。
- 使用数量和时长调用
quote_energy(或quote_bandwidth)。 - 向用户展示报价中的
total_trx。 - 使用相同的数量和时长调用
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 API 相同——见错误处理。
过期或已撤销的令牌在
/mcp 请求本身上会得到 HTTP 401 和 WWW-Authenticate: Bearer ... error="invalid_token";MCP 客户端随后会刷新令牌或请用户重新登录。