用你手里的币付任意 x402 API
x402 接口会返回 402 Payment Required，要求用 USDC 付款。ROZO 付的是要求 Base 上 USDC 的接口。你的 agent 手里可能是别的币、别的链。先用手里的币给 ROZO 余额充值一次，之后每次 x402 调用都从余额里秒付。
三条命令
只要你的 agent 能跑 shell 命令，这就是全部接入。
Shell
# 1. 充值一次。打印一次性收款地址，从你自己的钱包付款。 npx @rozoai/checkout x402 topup 20 --with usdt-solana # 2. 调用付费接口。读取 402，ROZO 签名，带着付款凭证重发请求。 npx @rozoai/checkout x402 pay https://api.example.com/v1/search --method POST --body '{"q":"..."}' # 3. 查看剩余余额。 npx @rozoai/checkout x402 balance
x402 pay 做了什么
- 请求由你的机器直接发给接口。ROZO 看不到请求内容、你的请求头，也看不到你给该服务用的 API key。
- 收到 402 后，CLI 读取付款要求，只保留 Base 上的 USDC，超过
--max-usd（默认 1.00）一律拒绝。 - 用新生成的
idempotencyKey请 ROZO 签一笔付款。重试沿用同一个 key，超时也不会重复扣款。 - 带上
PAYMENT-SIGNATURE请求头重发原请求，并输出返回内容。
原始 HTTP：两个调用
没有 shell？直接调用同一套 API。agent key 放在 Authorization: Bearer ak_... 里。
HTTP
# 充值：返回所选币种的一次性收款地址。 curl -s -X POST https://apiserver.mpprouter.dev/v1/x402/topup \ -H 'authorization: Bearer ak_...' -H 'content-type: application/json' \ -d '{"amount":"20","token":"USDT","chain":"900"}' # 签名：传入你从 402 的 "accepts" 列表里选中的那一条。 # 返回 PAYMENT-SIGNATURE 请求头的值，带上它重发你的请求。 curl -s -X POST https://apiserver.mpprouter.dev/v1/x402/sign \ -H 'authorization: Bearer ak_...' -H 'content-type: application/json' \ -d '{"accepts":[{"scheme":"exact","network":"eip155:8453","amount":"10000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x...","maxTimeoutSeconds":60}],"budget":"0.05","idempotencyKey":"<uuid>"}'
POST /v1/x402/keys 创建 agent key（只显示一次）。GET /v1/x402/balance 查询余额。同一笔付款的每次重试都用同一个 idempotencyKey。
能用什么充值，最终付的是什么
两条腿分开列：你付给 ROZO 的，和卖家收到的。
充值腿（你付给 ROZO）
| 币种 | 链 |
|---|---|
| USDT | Solana, BNB Chain, Ethereum, Polygon |
| USDC | Solana, BNB Chain, Ethereum, Polygon, Base, Stellar |
付款腿（ROZO 付给 x402 卖家）
| 网络 | 资产 | x402 方案 |
|---|---|---|
Base eip155:8453 | USDC | exact |
| Solana | 稍后支持。只接受 Solana USDC 的接口会在扣款前被拒绝。 | |
充值接受 USDC 和 USDT。卖家收到的永远是 USDC，因为 x402
exact 付款是代币转账；用 USDT 充值的余额，由 ROZO 用 USDC 付给卖家。手里是原生币或聪（sats）？可以用 ROZO Checkout 给 OpenRouter 充值。限额与 key
- 单笔：默认最多 $5。每日：默认最多 $100。也可以把 key 限定为只付给指定的
payTo地址。 - 最低充值：$5。充值收取 1% 手续费；之后每笔 x402 付款只扣卖家要求的金额。
- Agent key：第一次充值会创建一个以
ak_开头的 key，只显示一次，CLI 会把它存进~/.rozo-checkout/x402-key，仅本人可读。ROZO 只保存它的哈希。 - key 就是余额的所有权。不要贴进提示词、日志或工单。丢了就新建一个，并联系我们迁移余额。
常见问题
为什么要先充值？
x402 的付款要求只有一到五分钟有效期，而跨链转账需要更久。只有从已经到位的余额里付，才能赶在这个时间窗口内完成。充值次数少、金额大；付款次数多、金额小。
我的钱在哪？
在你的 ROZO x402 余额里。资金放在 ROZO 的钱包中，由 Base 上的钱包替你的 key 签名付款，所有余额总额每小时与这些钱包对账一次。ROZO 从不持有你自己钱包的私钥。
怎么把余额提回来？
暂时还不能自助提现。把打码后的 key（例如 ak_...a1b2）和金额发邮件到 hi@rozo.ai，我们会在你指定的链上退回。
ROZO 能看到我的请求吗？
看不到。付费请求从你的机器直接发往接口。ROZO 只看到它被要求签名的那条付款要求：付给谁、多少钱、在哪个网络。
卖家能在哪些网络收款？
Base 上的 USDC（eip155:8453），x402 方案 exact。Solana 付款腿稍后支持。如果接口只接受 Solana，CLI 会以 X402_UNSUPPORTED 停止，不会扣任何钱。