Skip to main content
By the end of this page you will have funded a testnet account, discovered a paid API, paid it under a cap, and verified the settlement, all from the terminal, and you will know how to drive the same flow from an agent. This uses @rail402.dev/cli (bin rail402). It turns the whole payment loop, fund then discover then pay then verify, into a handful of commands. It defaults to Rail402’s hosted testnet facilitator, which is free and needs no API key, and the buyer needs no XLM because the facilitator sponsors fees.

​
Install

Every payment requires an explicit --max cap. The CLI never spends an unbounded amount, and it is testnet-only by construction.

​
The full flow

1

Fund a testnet account

Generates a testnet account and funds it with friendbot. Save the S... secret it prints and export it:
Friendbot funds XLM. For testnet USDC, fund the printed address at the Circle faucet (select Stellar testnet). Check the account any time with rail402 whoami.
2

Search the Bazaar

Ranks the catalog in natural language and prints the matches with their price and parameters. Pays nothing.
3

Discover and pay, capped

Discovers the best-ranked match within your cap and pays it. The command prints the settlement hash and the resource’s response. To pay a URL you already have, use rail402 pay <url> --max 0.10, with --query k=v for query parameters and --method for the HTTP method.
4

Verify the settlement

Looks the settlement up on the explorer and prints an openable link. rail402 feed shows recent settlements.
CLI amounts are decimals in the asset’s units, so --max 0.10 is 0.10 USDC. This is deliberately different from the SDK, which uses atomic-unit strings ("1000000" is 0.10 USDC). A person types decimals; the SDK stays on atomic strings so amount math is never a float. Keep them straight.

​
The rest of the commands

Global flags: --json, --facilitator, --explorer, --network, and --secret (the secret can also come from RAIL402_SECRET). Command flags: search and buy take --max, --type <http|mcp>, and --limit <n>; pay takes --max, --method, and --query k=v; feed takes --limit, --seller, and --scheme. The CLI defaults to https://facilitator.rail402.dev; point it elsewhere with --facilitator.

​
--json for agents

Add --json to any command and it prints a single machine-readable envelope instead of formatted text: { ok, data } on success, { ok, error } on failure, where error is the same { code, reason, retryable } used everywhere in Rail402. Branch on ok, read data or error, and never parse the human output.
A refusal keeps the same shape:

​
The bundled Claude skill

The CLI ships a Claude skill at skill/SKILL.md. Point an agent at it and the agent can drive the fund, search, buy, and verify flow through the --json interface, staying inside whatever --max cap you give it. This is the fastest way to let an AI agent pay for Stellar services from the command line.

​
Next steps

Pay for a resource

The same flow from the SDK.

Spend controls

Decimals here, atomic strings in the SDK, and the ceiling above both.

Pay over MCP

Give an agent runtime the same search and pay tools.

Discover services

What a Bazaar listing tells you before you pay.

​
When it fails

With --json, every failure is { ok: false, error: { code, reason, retryable } }. The full registry is in Rejection reasons.