充值与 Agent 账户

充值方式

使用 USDC · Base 或 USDG · Robinhood Chain 充值，以当前账户实际开放的选项为准。RH 只支持 USDG。使用当前账户令牌请求 GET /v1/payments/options，获取可用方式；可用性取决于当前网络配置。普通钱包支付与兼容支付窗口是两个独立选项。

连接钱包或确认付款前，请核对醒目显示的 “当前正在给 [用户] 充值” 与账户编号。充值到账的 Xenodia 账户在创建订单时固定；切换钱包或登录另一个用户不会改变已有订单的到账账户。主账户和 Agent 各自拥有余额，创建付款前务必确认正在为谁充值。

普通钱包支付

使用当前登录账户已验证绑定的钱包。Xenodia 支持该钱包直接执行 ERC-20 transfer，包括委托签名钱包；不支持交易所提币、任意合约钱包或网络费代付。付款钱包必须在同一网络持有足量稳定币和用于网络费的 ETH。连接或验证钱包不代表授权代币支出。

钱包充值在交易成功上链并通过核验后入账，不再等待以太坊最终确认。未上链或失败的交易不会入账。通常几秒内到账，具体取决于网络和核验服务状态。

1. 使用 POST /v1/payments/orders 创建订单，提交 asset_id（base_usdc 或 rh_usdg）、以十进制整数字符串表示的 amount_micro 和唯一 idempotency_key。只有恢复完全相同的请求时才复用此键。
2. 核对响应中的到账账户、网络、代币、credit_micro、amount_micro、rate_ppm 和收款地址。GET /v1/payments/options 的 wallet_pricing.stablecoin_per_credit_rate 是新订单当前倍率；每张订单会保留创建时的原报价，后台之后调价不会改变它。要求钱包付款前，先以 {} 调用 POST /v1/payments/orders/{id}/attempts，保留返回的 attempt_id。只有成功取得此次付款资格的页面可以使用订单指定的钱包按原金额转账；若提示冲突，说明已有付款正在处理，不要再次转账。不要直接沿用历史订单中的收款地址。
3. 向 POST /v1/payments/orders/{id}/transactions 提交 tx_hash。交易哈希不是到账证明；Xenodia 会核验实际转账及其账户归属。
4. 通过 GET /v1/payments/orders/{id} 查询，或通过 GET /v1/payments/orders 找回订单。只有 completed 表示 Credits 已到账。“已提交”和“确认中”仍需等待，不要因为关掉页面或确认缓慢而重复付款。

订单保留原账户、钱包和金额，达到所需确认后只入账一次。归属不明、金额不符或迟到付款可能需要核对；订单过期不能撤回已经发送的交易。充值记录可通过 GET /v1/payments/history 查询。历史银行卡付款使用通用的银行卡充值标识，内部实现标识不属于公开协议。

付款资格在不同页面、标签页和设备之间共享。只有钱包明确拒绝且没有发送交易时，才能以 {} 调用 POST /v1/payments/orders/{id}/attempts/{attemptId}/reject 记录取消并释放资格。超时、钱包断连或结果未知时，不得释放资格或再次付款；请使用原交易哈希恢复核验或联系支持。

未付款订单过期后，先确认确实没有发送交易，再以空请求体或 {} 调用 POST /v1/payments/orders/{id}/resume。该操作将同一订单延长 30 分钟并记录此次延期，不会转账，也不会改变到账用户、钱包、金额、网络、代币或收款地址。如果已经付款，应提交交易哈希并查询原订单。已记录交易、已有付款尝试、已完成或待核对的订单不能续期。原订单尚未解决时，同一钱包和资产的新订单可能被阻止；请联系支持核对，不要再次付款。

兼容支付窗口与 x402 客户端

已有 x402 协议在启用时继续支持兼容客户端。浏览器先通过 POST /v1/payments/context 获取绑定当前账户的付款上下文，再打开支付窗口。展示响应中的到账用户，并使用服务端返回的付款链接保留签名上下文；不要自行在链接中拼接到账账户编号。上下文固定充值账户和金额。

保留 x402 响应中的 payment_id，使用到账账户令牌访问 GET /v1/payments/x402/{id}。accepted 表示提交已接受，credited 才表示 Credits 已入账。确认延迟时先查询原付款，不要直接再签一笔转账。Agent 原有的自主充值协议请求与浏览器给当前用户充值是不同场景。

Infini 和 AXON 已永久停用。 旧报价、下单、付款、核对、兑换和回调接口返回 HTTP 410，错误码为 payment_method_retired。请勿向历史收款地址转账或调用旧兑换入口。历史资金记录保留，可在鉴权后的充值记录和账本中查询。

绑定 Agent

打开 设置 → 我的 Agents → 添加 Agent。使用浏览器钱包时，点击 连接并添加 Agent，连接 Agent 使用的钱包并确认消息签名，即可自动完成绑定。

如果钱包由外部 Agent 保管，选择 其他设备上的 Agent，填写地址并点击 获取指令。将完整指令发送给 Agent，粘贴它返回的签名，再点击 添加 Agent。名称可不填。新 Agent 默认先用自己的 Credits，不足时使用 Owner Credits，不设额度上限。无需提供私钥。

主账户通过 POST /v1/me/agents/challenge 提交 wallet_address，获得 challenge_id、message、wallet_address 和以 Unix 秒表示的 expires_at。随后向 POST /v1/me/agents 提交 wallet_address、alias、challenge_id 和 EIP-191 signature。签名消息绑定申请的主账户和 Agent 地址，五分钟内有效，限用一次。

成功绑定即建立信任关系，双方余额仍各自保留。新绑定默认使用 self_then_owner，开启主账户代付，所有额度为 0（无限制）。已登录的 Owner 可直接修改已绑定 Agent 的名称、付款方式和额度，无需再次签名。历史 legacy_pending 绑定同样支持直接修改设置。已有设置会保留，直到 Owner 主动修改。

控制代付与额度

在 我的 Agents → 编辑 选择付款方式，按需展开可选额度设置：

• self_only：使用 Agent 自己的 Credits。
• self_then_owner：优先使用 Agent 余额，允许代付时再使用主账户余额。
• owner_only：只使用主账户余额，代付暂停后拒绝新请求。

成功绑定后即可管理代付，使用 Owner 当前登录会话直接保存，无需再次签名。接口为 GET / PUT /v1/me/agents/{address}/billing-policy，响应数据位于 data。

字段包括 billing_mode、owner_funding_enabled、per_request_limit_micro、daily_limit_micro、monthly_limit_micro 和 max_concurrent。1 Credit = 1,000,000 microcredits。各项额度独立生效，留空或填 0 表示该项无限制；设置并发上限时可填 1–1000。页面会将空值保存为 0。API 更新时省略字段会保留原值，取消已有上限应显式传 0。无限制仍以账户可用 Credits 为限。

正在执行的请求也占用适用额度。暂停或解绑会限制新的主账户代付，已有任务仍可能结算。超时本身不能证明已受理任务没有执行或没有产生成本；如有待核实冻结，请保留请求编号联系支持。

媒体任务返回 billing.status: review 或 error.review_required: true 时，表示结果未知、待核查，预留 Credits 仍占用。这不代表已退款；请保留任务编号，勿重新提交同一任务。

待结算费用与付款审核

在 Credits → 待结算费用与付款审核 中，Owner 可以查看已经完成、但实际费用超过原授权的请求。核对显示的总费用后，明确授权这一笔请求。已冻结额度计入总额；确认不会提高 Agent 今后的预算，也不会重新执行原请求。已授权的费用仍可能因可用余额不足或付款审核而等待结算，可刷新查看当前状态。

GET /v1/credits/settlements 接受 Owner 或 Agent access token。Owner 可查看有权处理的付款关系；Agent 只能只读查看自己的请求，不会获得其他付款方的可用余额或授权权限。列表包括已核实的待结算费用，以及 billing_state: usage_unknown 的结果不确定冻结。金额尚未核实不等于费用为零：应保留请求编号并联系支持核查，不能确认此类费用或仅因超时自动释放。

POST /v1/credits/settlements/authorize 仍需要 Owner 浏览器会话、原始 request_id、已核实的 actual_amount_micro 与 confirm: true。没有绑定 Owner 的独立自付 Agent 如遇需要明确授权的历史费用，应联系支持；绑定 Owner 本身不会批准历史扣费。调整 Agent 后续预算不代表追认历史费用。

退款和争议通知独立保存，重复投递不会重复冲销。已确认冲销只追回可用的钱包余额，保留其他请求已冻结的额度；不足部分单独记录，并可能限制新使用。后续充值优先抵偿尚待追回的额度。未结束的争议、矛盾或缺失证据继续审核；历史上无法关联原充值单的邀请奖励需人工核对。GET /v1/payments/reversals 只返回当前账户的审核状态。这些操作不会主动发起外部退款或转账。

断线后取回已完成的聊天

保留原 Idempotency-Key，用完全相同的请求内容重试。如果已保存经过验证的完整 JSON 或流式结果，系统直接返回原结果，不会再次调用模型或重复扣费。按持久化 JSON 编码后的大小限制为最多 4 MiB、保留七天。未完成、结果不确定或超限未缓存时返回 409；保存内容过期时返回 410，此时不要自动换新 Key 重做。有效结果可在账务待结算时先交付，通过 X-Billing-Status 和 Idempotent-Replayed 查看状态。首次 SSE 响应的账务状态通过声明的 HTTP trailer 发送，部分客户端和代理不会展示它。价格按请求受理时确定的报价结算。

原付款账户与历史费用

GET /v1/credits/settlements?limit=50 会先筛选真正待结算的费用，再分页。响应包含 next_cursor 时，用其作为 before_id 查询较早记录。解绑 Agent 后，原主账户仍可查看、确认自己承担的历史费用；该费用只使用 Agent 原有冻结及原主账户的资金，不会追加扣除 Agent 解绑后的新余额，也不会改向新主账户扣费。

每笔费用返回 funding_accounts 和 shortfall_micro。有缺口时，应向 supplemental_allowed: true 的原付款账户补充额度。页面显示的合计余额可能包含不能用于这笔费用的其他账户。self_then_owner 请求若最初完全由 Agent 预留，确认实际金额后也不会静默新增主账户代付；应补充该 Agent 原付款账户的余额。

Agent 查询 GET /v1/credits/ledger 只能看到自身额度变动，以及与该 Agent 原请求对应的付款方冻结、扣费、释放和退款。主账户无关的充值及其他 Agent 的交易明细不对其开放。

账本使用 page（从 1 开始）和 per_page（1–100，默认 20）分页，不使用 limit 或 before_id。例如 /v1/credits/ledger?page=1&per_page=100。根据返回的 entries、total、page、per_page 继续读取剩余页，不能将首屏当作完整账本。未知查询参数会被忽略。

所有账户的账本条目统一提供通用描述，并省略内部 metadata 和 idempotency_key。其他付款账户承担的请求条目还会省略 balance_after，仅保留该请求的金额、付款方等必要记录，不暴露付款账户的整体余额。公开充值记录以 card 表示历史银行卡付款，以 wallet 表示普通钱包及兼容协议付款。

payment_review_required=true 表示原付款账户存在付款审核限制：余额足够或确认金额均不能单独完成结算，需要先完成付款审核。