x402-cli

The BankofAI command-line client for the x402 protocol — pay any x402-protected URL, run your own paywall, or test the full handshake locally. No code required.

1. Install

pip install --pre bankofai-x402-cli
x402-cli --version

2. Set up a wallet (one-time)

x402-cli delegates all signing to bankofai-agent-wallet. Fastest path — import a 32-byte hex private key:

agent-wallet start raw_secret \
  --wallet-id payer \
  --private-key 0x<your-32-byte-hex-private-key>

A single key derives both an EVM address and a TRON address. You don't need a separate wallet per chain.

Other setup paths (encrypted local store, mnemonic, Privy-managed): see agent-wallet — Getting Started.

3. What each command does

Command	Who you are	What it does
x402-cli pay <url>	The payer	Hits a URL, and if the server returns 402 Payment Required, the cli signs + submits the payment + retrieves the response.
x402-cli serve	The recipient	Starts a local 402 paywall endpoint that only returns content after a valid payment is settled.
x402-cli roundtrip	Self-test / one-shot transfer	Spins up a serve in the background, runs pay against it, and tears it down. The fastest way to make a payment from the command line — and the easiest way to verify your install end-to-end.

4. Copy-paste: a USDT transfer on TRON mainnet

Replace <recipient-TRON-address> with a real T... address and run:

x402-cli roundtrip \
  --pay-to <recipient-TRON-address> \
  --amount 1 \
  --token USDT \
  --network tron:mainnet

Successful output (excerpt):

{
  "ok": true,
  "result": {
    "scheme": "exact_permit",
    "amount": "1000000",
    "paid": true,
    "transaction": "<64-hex-tx-hash>"
  }
}

Verify on chain at https://tronscan.org/#/transaction/<tx-hash>.

What just happened? Your wallet signed a permit off-chain (free, no gas), and the facilitator submitted it on chain on your behalf. You pay no TRX per payment — the facilitator covers gas.

First-time only: if this is your wallet's first payment for this token, the cli will ask you to sign and broadcast a one-time approve transaction (~6 TRX on mainnet) so the PaymentPermit contract can move tokens on your behalf later. After that, every payment is gas-free from your side.

Don't have any TRX at all? Add --scheme exact_gasfree to skip even that one-time approve — it routes everything through a GasFree relayer that fronts gas in exchange for a per-settlement fee deducted from a derived custodial address. Setup: docs/manual-test-guide.md → Walkthrough A.

Templates for other networks

Network	Replace --network with	Notes
TRON mainnet (default permit)	tron:mainnet	Facilitator pays per-payment gas. One-time ~6 TRX approve when you first use a token from a fresh wallet. Add --scheme exact_gasfree to skip that too.
BSC mainnet (USDT permit)	eip155:56	Same model — facilitator pays per-payment gas; one-time approve fee in BNB on first use.
TRON Nile (testnet)	tron:nile	Faucet
BSC Testnet	eip155:97	Faucet

To force a specific settlement scheme (instead of the auto-pick), add --scheme exact_gasfree | exact_permit | exact.

5. Amount units

rawAmount = amount × 10^decimals

What you mean	Flag to use
"1.25 USDT" (human-readable decimal)	--amount 1.25
1250000 (smallest on-chain unit, USDT has 6 decimals)	--rawAmount 1250000

Spending caps on pay follow the same split: --max-amount / --max-rawAmount.

6. Common errors

Error	Resolution
Insufficient GasFree balance	The GasFree custodial address is underfunded. See top-up steps.
cannot import name 'TokenRegistry' …	You're on bankofai-x402-cli ≤ 0.1.0b10. Upgrade: pip install --pre --upgrade bankofai-x402-cli.
resolve_wallet could not find a wallet source	No wallet configured yet. Go back to step 2.
Stuck on Master Password: prompt	A local_secure wallet without a persisted runtime password. Re-run with --save-runtime-secrets.
too many pending transfers	GasFree relayer rate limit. Wait 30–60s and retry.

Full troubleshooting matrix: docs/manual-test-guide.md → Troubleshooting.

Learn more

• docs/manual-test-guide.md — full hands-on walkthroughs from install to on-chain tx, covering TRON GasFree, TRON permit, and BSC permit.
• FEATURES.md — full flag matrix and example output for each command.
• agent-wallet docs — wallet setup options (Privy, mnemonic, encrypted local store).
• bankofai-x402 SDK — the underlying protocol and its programmatic API, in case you want to integrate directly instead of through the cli.