SBC CLI
Official terminal interface for SBC Agent Payments and the Swap API. Authenticate agents and users, check balances, pay x402 / MPP seller URLs, send SBC or cfUSD, manage seller endpoints, and swap stablecoins or buy gas with your own wallet, all from the command line.
Package: @stablecoin.xyz/cli · Binary: sbc · Node.js: 20+ · This page: 0.5.0
npm install -g @stablecoin.xyz/cli@latest
sbc --version # 0.5.0 or laterThe Swap API commands (sbc swap, sbc gas, sbc key) need 0.4.0 or later. To upgrade an older install, run the same npm install -g @stablecoin.xyz/cli@latest. The guardrails for unattended agents (see For AI agents) need 0.5.0 or later. Released versions are listed on npm.
Or from source:
git clone https://github.com/stablecoinxyz/sbc-cli.git
cd sbc-cli
npm install && npm run build && npm linkTwo ways to swap
The CLI talks to two APIs, and each has its own swap command:
sbc swap | sbc agent swap | |
|---|---|---|
| API | Swap API (swap.stablecoin.xyz) | Agent Payments (agents.stablecoin.xyz) |
| Wallet | Your own keys, signed locally | The agent's managed wallet |
| Login | None; set signing keys | Agent key (sk_live_…) |
| Routes | Every live Swap API route: same-chain on Base and Solana, redeems to USDC, and cross-chain Base↔Solana, Base↔Radius, Solana↔Radius | Agent Payments pairs; Base↔Solana cross-chain |
| Also | sbc swap quote, status, routes, info, balance, access, health, and sbc gas | Counts toward agent spending limits |
Quickstart: Agent Payments
1. Log in as a user
Generate a user key in the dashboard → Settings → CLI access → Generate key.
sbc auth user login --user-key sk_user_YOUR_KEY
sbc user whoami2. Log in as an agent
Create an agent and generate an API key on the agent detail page → API Keys → + New Key.
sbc agent login --agent-key sk_live_YOUR_KEY
sbc whoamiAgent login resolves the agent ID, chain, wallets and token from the API key via GET /api/agents/me.
3. Pay, send, manage
# Balances by chain: SBC, cfUSD, USDC, USDGLO; SOL on Solana
sbc balance
sbc balance --token USDC
# Pay a seller URL (x402 or MPP — amount and token set by the seller)
sbc pay --url "https://api.example.com/data"
# Send tokens: a 0x address on EVM chains, base58 on Solana
sbc send --to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0 --amount 1.5
sbc send --to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0 --amount 1.5 --token cfUSD
# Swap from the agent wallet
sbc agent swap --from USDC --to SBC --amount 10
sbc agent swap --from SBC --to cfUSD --amount 5 --from-chain base --to-chain solana
# Switch a Para dual-wallet agent's home between Base and Solana
sbc agent set-home --chain solana
# Platform manifest + account management
sbc manifest
sbc agent list
sbc endpoint listSupported tokens: SBC on all chains; cfUSD and USDC on Base and Solana; USDGLO on Base. Send is SBC or cfUSD. The token is chosen at send / endpoint-create time, not when creating an agent.
Quickstart: Swap API with your own wallet
sbc swap and sbc gas need no login. Set an encrypted signing key for each chain you use (see Signing keys):
sbc key import --chain evm # asks for the private key and a password
sbc key import --chain solana --keypair ~/.config/solana/id.json
export SBC_EVM_KEYSTORE=~/.sbc/keys/evm-….json # path printed by sbc key import
export SBC_SOLANA_KEYSTORE=~/.sbc/keys/solana-….json
sbc key show # which key each chain uses, and its address
sbc swap routes # live routes; priced ones marked "not 1:1"
sbc swap quote --from SBC --to cfUSD --amount 10 # rate, fee, expected output, can it fill now
sbc swap --from SBC --to cfUSD --amount 10 --dry-run # build and check, sign nothing
sbc swap --from SBC --to cfUSD --amount 10 # same-chain on Base (default)
sbc swap --from SBC --to cfUSD --amount 10 --chain solana # same-chain on Solana
sbc swap --from SBC --to SBC --amount 5 --from-chain base --to-chain solana # cross-chain
sbc swap status <orderId> --watch # follow it to claimed (add --testnet for a testnet order)
sbc gas --token SBC --amount 2 --chain base # buy ETH; the solver pays the feesAdd --testnet to any Swap API command for Base Sepolia, Solana devnet and Radius testnet.
Add --output json to any command for machine-readable output. See the full command reference.
For AI agents
An AI agent with a shell can run sbc swap and sbc gas unattended (0.5.0 or later). A person sets the limits in advance through the environment, so an agent that is mistaken or prompt-injected cannot spend more than intended or touch mainnet by accident. The intent check still applies: output only ever goes to the agent's own wallet.
Setup
sbc key import --chain evm --password-file ~/.sbc/evm.pw # encrypt the agent's key once
export SBC_EVM_KEYSTORE=~/.sbc/keys/evm-….json
export SBC_EVM_KEYSTORE_PASSWORD_FILE=~/.sbc/evm.pw # unlock without a prompt (chmod 600)
export SBC_SWAP_NET=testnet # optional: default to testnet; unset it to use mainnet
export SBC_SWAP_ALLOW_MAINNET=1 # only when the agent may sign on mainnet
export SBC_SWAP_MAX_PER_SWAP=25 # USD per swap or gas buy
export SBC_SWAP_MAX_DAILY=100 # USD per rolling 24 hours, per net- Mainnet needs an opt-in. With
--yeson mainnet the CLI refuses to sign unlessSBC_SWAP_ALLOW_MAINNET=1. A person who answers the confirm prompt needs no opt-in. Testnet, quotes, read commands and--dry-runare never blocked by it. - Caps. With
--yeson mainnet the caps default to 100 USD per swap and 500 USD per rolling 24 hours. Caps you set yourself apply to every run, with or without--yes, on either net.noneturns a cap off. A value that is not a positive number is refused. - How a swap is valued. The amount you send, read from the checked transaction (never from the API's response), at 1 USD per unit. Every input the CLI can spend is a dollar stable.
- The daily total is counted from the local swap ledger: every swap signed on the same net in the last 24 hours, counted once, including one whose send then failed. If a daily cap applies and the ledger cannot be read, the swap is refused.
- Cross-chain gas (
sbc gas --to-chain) spends the amount twice, once per step. Both steps are checked against the caps before step 1 signs.
Run loop
Always pass --output json and --yes. Do a dry run first: it builds and checks the real transaction, reports what the policy would decide, and needs no password.
sbc --output json swap quote --from SBC --to cfUSD --amount 10 # canFill, rate, minOut
sbc --output json swap --from SBC --to cfUSD --amount 10 --yes --dry-run # exit 2 if it would be refused
sbc --output json swap --from SBC --to cfUSD --amount 10 --yes # sign and send
sbc --output json swap status <orderId> --watch # cross-chain onlyExit codes and error codes
| Exit | Meaning |
|---|---|
0 | Done, or a dry run the policy would allow |
1 | Error: network, Swap API, bad input, key or password problem, a failed or cancelled swap, or an order that is unknown or needs attention |
2 | Refused before signing: intent check, mainnet opt-in, caps, unreadable ledger, or no way to confirm |
Errors go to stderr as one JSON line, {"ok":false,"error":"…","code":"…"}:
code | Exit | When |
|---|---|---|
mainnet-not-allowed | 2 | --yes on mainnet without SBC_SWAP_ALLOW_MAINNET=1 |
over-per-swap-cap | 2 | Over SBC_SWAP_MAX_PER_SWAP. Also carries amountUsd and cap |
over-daily-cap | 2 | Would go over SBC_SWAP_MAX_DAILY. Also carries amountUsd, cap, spent24h and left |
ledger-unreadable | 2 | A daily cap applies and the ledger cannot be read |
needs-confirmation | 2 | No --yes and no terminal to ask in |
refused:<reason> | 2 | The intent check refused the built transaction, e.g. refused:recipient-not-self |
key-locked | 1 | A keystore with no password file and no terminal to ask in |
| Swap API codes | 1 | Passed through from the Swap API, with its HTTP status |
{"ok":false,"error":"refusing: 80 USD would bring the last 24h to 520 USD, over SBC_SWAP_MAX_DAILY (500); 60 USD left","amountUsd":80,"cap":500,"spent24h":440,"left":60,"code":"over-daily-cap"}JSON output
sbc swap quote:
{"from":"SBC","to":"cfUSD","fromChain":"base","toChain":"base","net":"testnet","amount":1,"rate":"1:1","expectedOut":1,"minOut":1,"fee":"none","canFill":true,"reasons":[]}sbc swap --dry-run (request is the full built transaction). policy is {"ok":false,"reason":"over-per-swap-cap","message":"…","amountUsd":…,"cap":…} when it would be refused:
{"status":"dry-run",
"route":{"inSym":"SBC","outSym":"cfUSD","fromChain":"base","toChain":"base","crossChain":false,"uiAmount":1,"pair":{…},"priced":false},
"summary":{"send":{"amount":"1","token":"SBC","chain":"base"},"receive":{"atLeast":"1","token":"cfUSD","chain":"base"},"recipient":"0x…","rate":"1:1"},
"policy":{"ok":true,"amountUsd":1,"caps":{"perSwap":null,"daily":null}},
"request":{…}}sbc swap after sending. status is confirmed, pending or failed; orderId and rail appear for cross-chain swaps:
{"status":"confirmed","route":{…},"txId":"0x…","explorer":"https://…","confirmation":"confirmed","orderId":"0x…","rail":"evm-origin"}sbc gas returns {"status":"dry-run"|"confirmed"|"pending"|"failed","chain":"base","quote":{…},"txId":"0x…","explorer":"…","confirmation":"…"}; a dry run has summary, policy and request in place of txId. With --to-chain it returns {"status":"dry-run"|"done"|"waiting"|"step1-failed"|"cancelled","plan":[…],"step1":{…},"step2":{…}}, where a dry run's policy is the verdict for both steps.
sbc swap status:
{"orderId":"0x…","rail":"evm-origin","status":"pending"|"claimed"|"refunded"|"attention"|"unknown","delivered":…,"deliverRef":…,"claimRef":…,"recipient":…,"reason":…,"deliveredAt":…,"claimedAt":…}How it works
Payments (sbc pay)
sbc pay sends the seller URL to the SBC platform. The seller responds with HTTP 402 and the price; the platform signs and settles (x402 permit or MPP transfer). You never pass the amount on the CLI.
Gasless send (sbc send on Base)
On Base and Base Sepolia, sbc send uses ERC-4337 with the SBC AA proxy (api.aa.stablecoin.xyz) as bundler and paymaster. Gas is sponsored: the agent wallet needs zero ETH. Pass --token cfUSD to send cfUSD (default is SBC). On Radius and Tempo, direct transfer is used (SBC only). On Solana, SPL transfers need a little SOL for fees.
Agent swap (sbc agent swap)
sbc agent swap calls Agent Payments (POST /api/agents/:id/swap) and swaps from the agent's managed wallet. Pass --from-chain / --to-chain for the companion chain or Base↔Solana cross-chain. Swaps count toward agent spending limits.
Swap API (sbc swap, sbc gas)
Every signing command runs the same steps:
- Route. The pair or corridor must be in the Swap API's live route list. The CLI hardcodes no pairs, corridors or decimals.
- Build. The Swap API builds the transaction.
- Check. Before signing, the CLI decodes the built transaction and checks it against what you asked for: tokens, amount, your own wallet as the recipient, the known contracts and solver, deadlines, and the quoted minimum output. Any mismatch is refused with the reason, and nothing is signed. This is the same check the Swap MCP signer runs.
- Policy. The amount you send, read from the checked transaction, is checked against the spending caps and the mainnet opt-in (see For AI agents). A refusal unlocks no key, writes nothing to the ledger and sends nothing.
- Confirm. The CLI shows what you send and the least you receive, read from the checked transaction, and asks before signing.
--yesskips the prompt;--dry-runstops here and reports what the policy would decide. - Sign, record, send. If the key is an encrypted keystore, its password is asked for now, after the check and your confirm. Each signature or transaction hash is recorded in
~/.sbc/swap-ledger.jsonlbefore it is sent.
Same-chain. On Base you sign a permit and an order, and the solver submits them and pays the gas. On Solana the API returns a transaction the solver has already co-signed; you sign it and the CLI sends it. Redeems to USDC are priced by a DEX and marked "not 1:1". See Same-chain swaps.
Cross-chain. Your input is locked in an escrow on the source chain, and the solver delivers to your own wallet on the destination, so a swap between EVM and Solana needs both keys. The lock is sent from your wallet, so the source wallet needs a little native gas. If an order expires unfilled, the refund is automatic and permissionless after expiry; the CLI never settles or refunds. See Cross-chain swaps.
Gas. sbc gas buys ETH on Base or SOL on Solana with a stable, and the solver pays every fee. --to-chain buys gas on the other chain in two steps, each with its own signature: a cross-chain swap, then the gas buy once it is delivered.
Mainnet access. Mainnet can be invite-only; sbc swap access shows whether your wallet may use it (or pass --address).
Signing keys
sbc swap and sbc gas sign with your own wallet keys, set through environment variables. Use an encrypted keystore for each chain you sign on:
- EVM (Base, Radius):
SBC_EVM_KEYSTORE. It is the standard Ethereum keystore (Web3 Secret Storage v3), so a file from Foundry (cast wallet import, in~/.foundry/keystores/), geth or a MetaMask export works as is.sbc key import --chain evmmakes one from a private key. - Solana:
SBC_SOLANA_KEYSTORE. Solana has no standard encrypted key file, sosbc key import --chain solana --keypair <file>encrypts asolana-keygenkeypair in the same format, marked as Solana. - The password is asked for only when a key is about to sign. Read commands and
--dry-runnever ask, because the address is stored in the keystore. For scripts, pointSBC_EVM_KEYSTORE_PASSWORD_FILEorSBC_SOLANA_KEYSTORE_PASSWORD_FILEat a file holding the password. There is no password environment variable. - Plaintext keys still work:
SBC_EVM_KEY_FILEorSBC_EVM_PRIVATE_KEY, andSBC_SOLANA_KEYPAIR. Set one source per chain; two are refused.
Config
Agent Payments credentials are stored in ~/.sbc/config.json with 0600 permissions. Prefer environment variables in CI:
| Variable | Description |
|---|---|
SBC_API_URL | Agent Payments base URL (default: https://agents.stablecoin.xyz) |
SBC_AGENT_KEY | Agent API key — overrides config file |
SBC_AGENT_ID | Default agent UUID — overrides config file |
SBC_USER_KEY | User API key — overrides config file |
SBC_SWAP_API_URL | Swap API base URL (default: https://swap.stablecoin.xyz); --testnet always uses the testnet worker |
SBC_SWAP_API_KEY | Swap API partner key, sent as x-api-key (see Authentication) |
SBC_EVM_KEYSTORE | Encrypted EVM keystore for Base and Radius (from sbc key import, Foundry, geth or MetaMask). Recommended |
SBC_EVM_KEYSTORE_PASSWORD_FILE | File holding the EVM keystore password, for scripts |
SBC_EVM_KEY_FILE / SBC_EVM_PRIVATE_KEY | Plaintext EVM key, in a file or in the environment |
SBC_SOLANA_KEYSTORE | Encrypted Solana keystore from sbc key import. Recommended |
SBC_SOLANA_KEYSTORE_PASSWORD_FILE | File holding the Solana keystore password, for scripts |
SBC_SOLANA_KEYPAIR | Plaintext Solana keypair file (solana-keygen JSON) |
SBC_BASE_RPC_URL / SBC_RADIUS_RPC_URL / SBC_SOLANA_RPC_URL | RPC overrides (defaults are the public endpoints) |
SBC_SWAP_LEDGER | Where signed swaps are recorded (default: ~/.sbc/swap-ledger.jsonl). The daily cap is counted from it |
SBC_SWAP_NET | testnet makes testnet the default for every Swap API command; --testnet always wins |
SBC_SWAP_ALLOW_MAINNET | 1 lets --yes sign on mainnet (see For AI agents) |
SBC_SWAP_MAX_PER_SWAP | USD cap per swap or gas buy. Default 100 for --yes on mainnet; none turns it off |
SBC_SWAP_MAX_DAILY | USD cap per rolling 24 hours, per net. Default 500 for --yes on mainnet; none turns it off |
export SBC_API_URL=http://localhost:3000
sbc agent login --agent-key sk_live_...Troubleshooting
sbc: command not found. The CLI is not installed globally. Runnpm install -g @stablecoin.xyz/cli@latest, or from a source checkout runnode dist/index.js(ornpm linkonce).sbc swap statussays not found. Use the same network as the swap: add--testnetfor a testnet order. Without it the CLI looks on mainnet.the Swap API could not read the chain: the RPC at … failed. The Swap API could not reach that chain's RPC. A 403 means the RPC refused the request, which some RPCs do for certain regions; try again later or from another network. Nothing was signed.refusing to sign on mainnet without a person.--yeson mainnet needsSBC_SWAP_ALLOW_MAINNET=1. Set it for scripts and agents that may sign on mainnet, or run without--yesand confirm yourself. Nothing was signed.refusing: … over SBC_SWAP_MAX_PER_SWAPorSBC_SWAP_MAX_DAILY. The swap is over a spending cap. With--yeson mainnet the defaults are 100 USD per swap and 500 USD per 24 hours; raise them, or setnone. Nothing was signed.broadcast failed on baseon a cross-chain swap. The lock is sent from your wallet, so it needs a little ETH on the source chain for gas. Nothing moved; add gas and run the swap again.
Security
- Never commit
~/.sbc/or plaintext keys. Add~/.sbc/to your global.gitignore. - In automated environments, use
SBC_AGENT_KEY/SBC_USER_KEYinstead of the config file. - Signing keys for
sbc swapandsbc gasare read only from environment variables, keystores and key files. Prefer an encrypted keystore (sbc key import). Key, keystore and password files must be owned by you and readable only by you (chmod 600); the CLI refuses any other file. Signing keys are never written to~/.sbc/config.json, never sent anywhere, and never shown in output. - Use a wallet that holds only what you intend to swap, and try new routes with
--dry-runor--testnetfirst. - Report vulnerabilities privately to security@stablecoin.xyz.