@rail402.dev/cli (rail402)

A command-line x402 wallet and agent tool for Stellar. Fund a testnet account, discover paid APIs in the Bazaar, pay them under a spend cap, and look up the settlement on the explorer, from your terminal or from inside an AI agent.

It is the Stellar-native counterpart to the EVM and Solana x402 CLIs (there wasn't one before). Under the hood it wraps @rail402.dev/agent-helpers (x402 v2, spend-cap enforced) and the Rail402 explorer read API.

npm install -g @rail402.dev/cli     # or run ad-hoc with: npx @rail402.dev/cli <command>

60-second tour (testnet, free)

rail402 fund --usdc                            # generate + fund a testnet account, USDC included
export RAIL402_SECRET=S...                      # the secret it printed
rail402 search "summarize a web page"          # find paid APIs in the Bazaar
rail402 buy "summarize a web page" --max 0.10   # discover the cheapest match AND pay it
rail402 tx <hash>                               # look the settlement up on the explorer

Amounts are decimals in the asset's units (--max 0.10 = 0.10 USDC). Every payment requires an explicit --max cap, so the CLI never spends an unbounded amount.

Commands

| Command | What it does | |---|---| | rail402 fund [--usdc] | Friendbot-fund a testnet account (generates one if you have no --secret); --usdc also adds the USDC trustline and drips starter USDC from the playground dispenser | | rail402 trust [CODE:ISSUER] | Add a trustline (defaults to the playground's testnet USDC) | | rail402 whoami | Show your address and balances | | rail402 search "<query>" | Search the Bazaar (--max, --type http\|mcp, --limit) | | rail402 buy "<query>" --max <amt> | Discover the cheapest match and pay it | | rail402 pay <url> --max <amt> | Pay a known resource URL (--query k=v, --method) | | rail402 tx <hash> | Look up a settlement on the explorer | | rail402 feed | Recent x402 payments (--limit, --seller, --scheme) | | rail402 supported | What the facilitator advertises | | rail402 config [show\|set\|path] | Show or change saved config | | rail402 help / version | |

For AI agents

Pass --json to any command for structured output, and store the key in an env var (agents can't type an interactive password):

export RAIL402_SECRET=S...
rail402 buy "convert usdc to stroops" --max 0.10 --json
# { "ok": true, "data": { "paid": { "amount": "500000", "transaction": "6c6b..." }, ... } }

Every failure is a machine-readable code with a non-null reason and a retryable flag, for example { "ok": false, "error": { "code": "mcp_budget_exceeded", "reason": "...", "retryable": false } }, so an agent reasons about the failure instead of parsing prose. A Claude skill that teaches an agent to drive this CLI ships in skill/.

Configuration

Every endpoint defaults to Rail402's hosted testnet infrastructure and every one is overridable, so the same binary drives your own self-hosted facilitator or explorer. Precedence: flag, then env, then ~/.rail402/config.json, then the default.

| Setting | Flag | Env | Default | |---|---|---|---| | Facilitator | --facilitator | RAIL402_FACILITATOR_URL | https://facilitator.rail402.dev | | Explorer API | --explorer | RAIL402_EXPLORER_URL | https://explorer-api.rail402.dev | | Explorer web (tx links) | --explorer-web | RAIL402_EXPLORER_WEB_URL | https://explorer.rail402.dev | | Network | --network | RAIL402_NETWORK | stellar:testnet | | Secret | --secret | RAIL402_SECRET | (none) |

# Point at your own deployment:
rail402 supported --facilitator https://my-facilitator.example
rail402 config set explorerUrl https://my-explorer.example    # persists to ~/.rail402/config.json

Testnet only. rail402 fund --usdc covers the whole bootstrap (XLM via friendbot, the USDC trustline, and a starter USDC drip from the playground dispenser). Larger USDC amounts come from the Circle faucet.

Part of Rail402. Apache-2.0.