Skip to content

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 later

The 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 link

Two ways to swap

The CLI talks to two APIs, and each has its own swap command:

sbc swapsbc agent swap
APISwap API (swap.stablecoin.xyz)Agent Payments (agents.stablecoin.xyz)
WalletYour own keys, signed locallyThe agent's managed wallet
LoginNone; set signing keysAgent key (sk_live_…)
RoutesEvery live Swap API route: same-chain on Base and Solana, redeems to USDC, and cross-chain Base↔Solana, Base↔Radius, Solana↔RadiusAgent Payments pairs; Base↔Solana cross-chain
Alsosbc swap quote, status, routes, info, balance, access, health, and sbc gasCounts 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 whoami

2. 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 whoami

Agent 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 list

Supported 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 fees

Add --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 --yes on mainnet the CLI refuses to sign unless SBC_SWAP_ALLOW_MAINNET=1. A person who answers the confirm prompt needs no opt-in. Testnet, quotes, read commands and --dry-run are never blocked by it.
  • Caps. With --yes on 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. none turns 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 only

Exit codes and error codes

ExitMeaning
0Done, or a dry run the policy would allow
1Error: network, Swap API, bad input, key or password problem, a failed or cancelled swap, or an order that is unknown or needs attention
2Refused 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":"…"}:

codeExitWhen
mainnet-not-allowed2--yes on mainnet without SBC_SWAP_ALLOW_MAINNET=1
over-per-swap-cap2Over SBC_SWAP_MAX_PER_SWAP. Also carries amountUsd and cap
over-daily-cap2Would go over SBC_SWAP_MAX_DAILY. Also carries amountUsd, cap, spent24h and left
ledger-unreadable2A daily cap applies and the ledger cannot be read
needs-confirmation2No --yes and no terminal to ask in
refused:<reason>2The intent check refused the built transaction, e.g. refused:recipient-not-self
key-locked1A keystore with no password file and no terminal to ask in
Swap API codes1Passed 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:

  1. Route. The pair or corridor must be in the Swap API's live route list. The CLI hardcodes no pairs, corridors or decimals.
  2. Build. The Swap API builds the transaction.
  3. 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.
  4. 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.
  5. Confirm. The CLI shows what you send and the least you receive, read from the checked transaction, and asks before signing. --yes skips the prompt; --dry-run stops here and reports what the policy would decide.
  6. 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.jsonl before 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 evm makes one from a private key.
  • Solana: SBC_SOLANA_KEYSTORE. Solana has no standard encrypted key file, so sbc key import --chain solana --keypair <file> encrypts a solana-keygen keypair in the same format, marked as Solana.
  • The password is asked for only when a key is about to sign. Read commands and --dry-run never ask, because the address is stored in the keystore. For scripts, point SBC_EVM_KEYSTORE_PASSWORD_FILE or SBC_SOLANA_KEYSTORE_PASSWORD_FILE at a file holding the password. There is no password environment variable.
  • Plaintext keys still work: SBC_EVM_KEY_FILE or SBC_EVM_PRIVATE_KEY, and SBC_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:

VariableDescription
SBC_API_URLAgent Payments base URL (default: https://agents.stablecoin.xyz)
SBC_AGENT_KEYAgent API key — overrides config file
SBC_AGENT_IDDefault agent UUID — overrides config file
SBC_USER_KEYUser API key — overrides config file
SBC_SWAP_API_URLSwap API base URL (default: https://swap.stablecoin.xyz); --testnet always uses the testnet worker
SBC_SWAP_API_KEYSwap API partner key, sent as x-api-key (see Authentication)
SBC_EVM_KEYSTOREEncrypted EVM keystore for Base and Radius (from sbc key import, Foundry, geth or MetaMask). Recommended
SBC_EVM_KEYSTORE_PASSWORD_FILEFile holding the EVM keystore password, for scripts
SBC_EVM_KEY_FILE / SBC_EVM_PRIVATE_KEYPlaintext EVM key, in a file or in the environment
SBC_SOLANA_KEYSTOREEncrypted Solana keystore from sbc key import. Recommended
SBC_SOLANA_KEYSTORE_PASSWORD_FILEFile holding the Solana keystore password, for scripts
SBC_SOLANA_KEYPAIRPlaintext Solana keypair file (solana-keygen JSON)
SBC_BASE_RPC_URL / SBC_RADIUS_RPC_URL / SBC_SOLANA_RPC_URLRPC overrides (defaults are the public endpoints)
SBC_SWAP_LEDGERWhere signed swaps are recorded (default: ~/.sbc/swap-ledger.jsonl). The daily cap is counted from it
SBC_SWAP_NETtestnet makes testnet the default for every Swap API command; --testnet always wins
SBC_SWAP_ALLOW_MAINNET1 lets --yes sign on mainnet (see For AI agents)
SBC_SWAP_MAX_PER_SWAPUSD cap per swap or gas buy. Default 100 for --yes on mainnet; none turns it off
SBC_SWAP_MAX_DAILYUSD 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. Run npm install -g @stablecoin.xyz/cli@latest, or from a source checkout run node dist/index.js (or npm link once).
  • sbc swap status says not found. Use the same network as the swap: add --testnet for 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. --yes on mainnet needs SBC_SWAP_ALLOW_MAINNET=1. Set it for scripts and agents that may sign on mainnet, or run without --yes and confirm yourself. Nothing was signed.
  • refusing: … over SBC_SWAP_MAX_PER_SWAP or SBC_SWAP_MAX_DAILY. The swap is over a spending cap. With --yes on mainnet the defaults are 100 USD per swap and 500 USD per 24 hours; raise them, or set none. Nothing was signed.
  • broadcast failed on base on 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_KEY instead of the config file.
  • Signing keys for sbc swap and sbc gas are 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-run or --testnet first.
  • Report vulnerabilities privately to security@stablecoin.xyz.

Related