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.

x402-cli is the single user-facing entrypoint. It includes payment commands, public catalog discovery, and provider gateway operations under one command tree. The gateway runtime is packaged underneath the CLI, so most users only install and remember x402-cli.

Community copy-paste examples live in examples/README.md.

1. Install

pip install bankofai-x402-cli==0.6.1
x402-cli --version

2. Set up a wallet (one-time)

x402-cli delegates all signing to bankofai-agent-wallet. Configure any supported wallet backend before paying.

agent-wallet list
agent-wallet resolve-address payer

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

Setup paths (encrypted local store, mnemonic, raw secret, Privy-managed): see agent-wallet — Getting Started. Keep wallet secrets outside this repository.

3. What each command does

Catalog search can read the hosted catalog, a local dist/catalog.json, or a gateway-exported catalog URL. This is the discovery step for agents and local tooling: the user asks for a capability, the catalog search finds matching paid APIs, then the normal x402 payment client can call the selected gateway URL.

export X402_CATALOG=https://x402-catelog.bankofai.io/api/catalog.json
x402-cli catalog update
x402-cli catalog search "token launch"
x402-cli catalog show sunpump-token-launch
x402-cli catalog endpoints sunpump-token-launch
x402-cli catalog pay-json sunpump-token-launch

For local gateway development:

x402-cli gateway scaffold sunpump-token-launch-tron \
  --output-dir providers/sunpump-token-launch-tron \
  --forward-url https://api.example.com

x402-cli gateway check providers/sunpump-token-launch-tron/provider.yml
x402-cli gateway start --providers-dir providers --host 0.0.0.0 --port 4020

Expected flow with the gateway:

Natural-language intent
  -> x402-cli catalog search
  -> x402-cli catalog show/endpoints/pay-json
  -> provider endpoint from the catalog
  -> x402-cli pay <gateway endpoint>
  -> x402 SDK handles the 402 challenge and payment retry
  -> upstream API result

Provider onboarding flow:

x402-cli gateway check providers/sunpump-token-launch-tron/provider.yml
x402-cli gateway start --providers-dir providers --host 0.0.0.0 --port 4020

x402-cli catalog export-gateway https://x402-gateway.bankofai.io \
  --provider sunpump-token-launch-tron \
  --output-dir providers/sunpump-token-launch-tron

The command writes public PR files only:

providers/sunpump-token-launch/catalog.json
providers/sunpump-token-launch/pay.md

Do not submit provider.yml, .env, upstream API keys, bearer tokens, or passwords.

Provider catalog build commands are also under x402-cli:

x402-cli gateway catalog generate providers/sunpump-token-launch-tron/provider.yml
x402-cli gateway catalog pay-assets providers/sunpump-token-launch-tron/provider.yml
x402-cli gateway catalog check providers
x402-cli gateway catalog build providers --dist-dir dist
x402-cli gateway catalog search providers sunpump

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.

Templates for other networks

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

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

6. Common errors

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.