wallet-cli x402 roundtrip¶

Start a local paywall, pay it once, and exit.

Synopsis¶

wallet-cli x402 roundtrip --pay-to <address> [--amount <n> | --raw-amount <n>] [--token <symbol> | --asset <address> [--decimals <n>]]
                          [--scheme <exact|exact_gasfree>] [--valid-for-seconds <n>] [--port <n>] [--facilitator-url <url>]
                          [--gasfree-relay <official|gasfree|url>] [--max-gasfree-fee <n> | --max-gasfree-fee-raw <n>]
                          [--password-stdin] [options]

Description¶

Runs x402 serve and x402 pay in one step: it starts the same local endpoint, pays it once from the active account (or --account), and shuts the server down. Use it to check the whole x402 flow — payment requirements, signature, facilitator settlement — end to end.

This is a real payment of the price to --pay-to, and pay only accepts the route the server was started with, so nothing else can be paid.

The server always binds to 127.0.0.1. The same validation as x402 serve applies to the price, token, scheme, port and facilitator options. Requires an account and the master password (via --password-stdin).

Options¶

Option	Description
`--pay-to <address>`	Required. Recipient address on the selected network
`--amount <n>`	Price in whole tokens, no more decimals than the token (default `0.0001`); excludes `--raw-amount`
`--raw-amount <n>`	Price in the token's smallest unit
`--token <symbol>`	Payment token the address book knows on the network (default `USDT`); excludes `--asset`
`--asset <address>`	Payment token by contract address instead of symbol; a contract the address book does not know also needs `--decimals`
`--decimals <n>`	Decimals of the `--asset` token, 0–18; requires `--asset`
`--scheme <exact\\|exact_gasfree>`	Payment scheme (default `exact`); `exact_gasfree` on TRON only
`--valid-for-seconds <n>`	How long a payment authorization stays valid, 1–86400 (default `300`)
`--port <n>`	Port, 1–65535 (default `4020`)
`--facilitator-url <url>`	HTTPS facilitator (default `https://facilitator.bankofai.io`)
`--gasfree-relay <official\\|gasfree\\|url>`	GasFree account data source for `exact_gasfree`; see `x402 pay`
`--max-gasfree-fee <n>` / `--max-gasfree-fee-raw <n>`	Cap on the GasFree fee; mutually exclusive
`--password-stdin`	Master password from stdin

Plus the global options.

Examples¶

Pay 0.0001 USDT on Nile to TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ through a local paywall. $PW is your master password (from an environment variable, password manager, etc.), fed on stdin via --password-stdin:

printf '%s' "$PW" | wallet-cli x402 roundtrip --pay-to TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ --network nile --password-stdin

✅ Payment settled
  Network      nile
  Scheme       exact
  Amount       0.0001 USDT
  From         TWer2Ygk5TEheHp3TPuYeqxmB6SsGZmaL6
  To           TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ
  Transaction  d6e0bb3015dce28ac9813f4d90be442d0f1ef61a6d4268cb023c5e8cfc09ef36
  Delivery     Delivered

printf '%s' "$PW" | wallet-cli x402 roundtrip --pay-to TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ --network nile --password-stdin -o json

{"schema":"wallet-cli.result.v1","success":true,"command":"x402.roundtrip","data":{"serve":{"payUrl":"http://127.0.0.1:4020/pay","network":"tron:3448148188","scheme":"exact","token":"USDT","asset":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","decimals":6,"validForSeconds":300,"resourceUrl":"http://127.0.0.1:4020/pay","rawAmount":"100","payTo":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ"},"pay":{"url":"http://127.0.0.1:4020/pay","status":200,"delivered":true,"settled":true,"payer":{"address":"TWer2Ygk5TEheHp3TPuYeqxmB6SsGZmaL6"},"paymentResponse":{"success":true,"transaction":"1ca932a4cda16fe9485689d6b7daa38ca34c601bbd970f609fb1c5a56b375438","network":"tron:0xcd8690dc","payer":"0xe2e1a54926527fbb4e4420de4c6bab82beaee24d"},"response":{"success":true,"network":"tron:3448148188","scheme":"exact","transaction":"1ca932a4cda16fe9485689d6b7daa38ca34c601bbd970f609fb1c5a56b375438"}}},"meta":{"durationMs":7594,"warnings":[]},"chain":{"family":"tron","network":"tron:3448148188","chainId":"3448148188"}}

Payment settled with Delivery Delivered means the payment went through on chain and the paywall returned its response. From is the paying account and Transaction the payment's transaction ID. In JSON, serve is what the paywall charged (rawAmount in the token's smallest unit), and pay is the payment result: paymentResponse is the facilitator's receipt, whose payer is your address in hex form, and response is what the paywall returned after payment.

Output¶

Field	Type	Meaning
`serve`	object	What the server offered — the same fields as `x402 serve`
`pay`	object	The payment result — the same fields as `x402 pay`

Exit status¶

0 paid · 1 execution failure (the payment errors of x402 pay; auth_required — no --password-stdin; missing_wallet_address; port_in_use) · 2 usage error (the usage errors of x402 serve; invalid_option — two exclusive options (--amount / --raw-amount, --token / --asset, both GasFree fee caps), --decimals without --asset, or --wait / --wait-timeout, which this command does not take; gasfree_credentials_missing).