Skip to content

Command reference

Binary: sbc · Package: @stablecoin.xyz/cli

Global flags: --output json | --output text (default).

Authentication

Login/logout are user-scoped by default. Agent auth lives under an explicit agent path. The Swap API commands (sbc swap, sbc gas) need no login.

User (sk_user_…)

CommandDescription
sbc loginLog in as a user (save user key)
sbc logoutLog out the user. Add --all to also remove the agent key
sbc auth login / sbc auth logoutSame as above
sbc user login / sbc user logoutSame as above
sbc auth user login / sbc auth user logoutSame as above

Agent (sk_live_…)

CommandDescription
sbc agent login / sbc agent logoutLog in / out as an agent
sbc agent auth login / sbc agent auth logoutSame as above
sbc auth agent login / sbc auth agent logoutSame as above

Whoami

CommandDescription
sbc whoamiShow all active keys and user info (summary)
sbc auth whoamiSame summary
sbc user whoami / sbc auth user whoamiAuthenticated user info via API
sbc agent whoami / sbc auth agent whoamiActive agent key and agent ID, with EVM and Solana addresses

Manage agents

Requires a user key (sk_user_…).

CommandDescription
sbc agent listList your agents
sbc agent show <id>Agent details, EVM and Solana wallets, limits, recent transactions
sbc agent createCreate an agent (--chain, --wallet-provider para|self)
sbc agent set-home --chain <slug>Switch a Para dual-wallet agent's home between Base and Solana
sbc agent archive <id>Archive an agent
sbc agent sendAlias for sbc send
sbc agent payAlias for sbc pay
sbc agent swapSwap from the agent wallet via Agent Payments (see below)

Example:

sbc agent create --name "Dual Bot" --chain base --wallet-provider para
sbc agent show <id>
sbc agent set-home --chain solana

Manage seller endpoints

Requires a user key (sk_user_…).

CommandDescription
sbc endpoint listList seller endpoints
sbc endpoint show <id>Endpoint details
sbc endpoint createCreate an endpoint with a managed wallet
sbc endpoint create … --tokens SBC,cfUSDRestrict accepted tokens (cfUSD only on Base)
sbc endpoint archive <id>Archive an endpoint
sbc endpoint balance <id>Endpoint wallet balance
sbc endpoint payments <id>List payments received
sbc endpoint keys list <id>List API keys
sbc endpoint keys generate <id>Generate a seller API key
sbc endpoint keys revoke <endpointId> --key-id <id>Revoke a seller API key

Example:

sbc endpoint create --name "My API" --url https://api.mine.com --price 0.5 --chain base-sepolia
sbc endpoint keys generate <id> --label "production"
# → copy sk_seller_... into your server env as X-Seller-Key

Day-to-day agent usage

CommandDescription
sbc balanceAgent balances by chain: SBC, cfUSD, USDC, USDGLO; SOL on Solana
sbc balance --token USDCSingle token balance
sbc pay --url <url>Pay a seller URL (x402 or MPP)
sbc send --to <addr> --amount <n>Send SBC to a 0x address or a Solana base58 address (gasless on Base)
sbc send --to <addr> --amount <n> --token cfUSDSend cfUSD (Base / Solana)
sbc transactionsTransaction history (requires user key)

sbc agent swap

Swap from the agent's managed wallet via Agent Payments. Requires an agent key. Before 0.4.0 this was sbc swap.

FlagDescription
--from <token>Input token: USDC, SBC, cfUSD, or USDGLO (Base same-chain)
--to <token>Output token: SBC or cfUSD
--amount <n>Amount of --from to swap
--from-chain <slug>Pay network (default: agent home)
--to-chain <slug>Receive network (default: agent home); Base↔Solana cross-chain when different from --from-chain
--agent <id>Agent UUID (defaults to the saved agent ID)
sbc agent swap --from USDC --to SBC --amount 10
sbc agent swap --from SBC --to cfUSD --amount 5 --from-chain base --to-chain solana

Swap API (your own wallet)

These commands use the Swap API and need no login. Signing commands (sbc swap, sbc gas) need a key for the chain they sign on: an encrypted keystore (SBC_EVM_KEYSTORE for Base and Radius, SBC_SOLANA_KEYSTORE for Solana), or a plaintext key (SBC_EVM_KEY_FILE, SBC_EVM_PRIVATE_KEY, SBC_SOLANA_KEYPAIR). See Signing keys. Key, keystore and password files must be readable only by you. Every Swap API command takes --testnet.

sbc key

Set up signing keys. Neither command calls the Swap API.

CommandDescription
sbc key import --chain evm|solanaEncrypt a key into a password-protected keystore in ~/.sbc/keys/. EVM: --key-file <path>, or you are asked for the key. Solana: --keypair <path> (a solana-keygen JSON file). --out <path> chooses the file; --password-file <path> reads the new password from a file
sbc key showWhich signing key each chain uses (keystore, key file or environment) and its address, without unlocking anything
sbc key import --chain evm --key-file ~/keys/base.key
sbc key import --chain solana --keypair ~/.config/solana/id.json
sbc key show

The plaintext file you imported from is left in place; delete it once you have a backup.

sbc swap

Swap with your own wallet. The CLI checks the built transaction against what you asked for before signing, and refuses any mismatch.

FlagDescription
--from <token>Token to pay with (see sbc swap routes)
--to <token>Token to receive
--amount <n>Amount of --from to swap
--chain <chain>Chain for a same-chain swap: base or solana (default base)
--from-chain <chain>Chain you pay on (same as --chain for a same-chain swap)
--to-chain <chain>Chain you receive on; a different chain makes it cross-chain
--testnetUse the testnet Swap API (Base Sepolia, Solana devnet); SBC_SWAP_NET=testnet makes it the default
--yesSign without the confirm prompt (for scripts and agents). On mainnet it needs SBC_SWAP_ALLOW_MAINNET=1 and is capped; see For AI agents
--dry-runBuild and check the transaction, show what would be signed and whether the caps allow it, and stop
sbc swap --from SBC --to cfUSD --amount 10
sbc swap --from SBC --to USDC --amount 10 --chain solana          # DEX-priced redeem, "not 1:1"
sbc swap --from SBC --to SBC --amount 5 --from-chain base --to-chain radius

A cross-chain swap prints its order id; follow it with sbc swap status.

sbc swap quote

Rate, fee, expected and minimum output, and whether the route can fill right now. Takes --from, --to, --amount, --chain, --from-chain, --to-chain and --testnet, as for sbc swap. See Quotes.

sbc swap status <orderId>

Follow a cross-chain order: pending, claimed, refunded, or needs attention.

FlagDescription
--rail <rail>Corridor the order is on: sol-origin, evm-origin, base->radius, radius->base, radius->solana or solana->radius. Without it, the CLI uses your local ledger, or tries each corridor, so you rarely need it. Quote the value in a shell (--rail 'radius->base'), since > is a redirect
--watchKeep polling until the order is claimed or refunded
--testnetUse the testnet Swap API

Use the same network as the swap: sbc swap status <orderId> --testnet for a testnet order; without --testnet the CLI looks on mainnet. After a cross-chain swap the CLI prints the exact command to run.

If a corridor cannot be read, the CLI says so instead of reporting the order as not found. If an order expires unfilled, the refund is automatic and permissionless after expiry. The CLI never settles or refunds.

Read commands

CommandDescription
sbc swap routesLive routes, same-chain and cross-chain; priced routes are marked "not 1:1"
sbc swap info --chain base|solanaToken addresses, decimals, solver inventory and caps for a chain
sbc swap balance [--address <addr>] [--chain base|radius|solana]Balances for your wallets (the ones in SBC_EVM_* / SBC_SOLANA_*), or for any address: Base and Radius for a 0x address, Solana for a base58 one
sbc swap access [--address <addr>]Whether your wallets, or any address, may use mainnet
sbc swap healthCheck the Swap API is up

sbc gas

Buy ETH or SOL with a stable. The solver pays every fee, so an empty wallet works.

FlagDescription
--token <token>Stable to pay with (accepted ones come from the API's gas quote)
--amount <n>Amount of --token to spend
--chain <chain>Chain to pay on, and to buy gas on unless --to-chain is set: base or solana (default base)
--to-chain <chain>Buy gas on the other chain: a cross-chain swap first, then a gas buy there (two signatures)
--testnetUse the testnet Swap API (Base Sepolia, Solana devnet); SBC_SWAP_NET=testnet makes it the default
--yesSign without the confirm prompt (for scripts and agents). On mainnet it needs SBC_SWAP_ALLOW_MAINNET=1 and is capped; see For AI agents
--dry-runBuild and check, show what would be signed and whether the caps allow it, and stop
sbc gas --token SBC --amount 2 --chain base                       # ETH on Base
sbc gas --token USDC --amount 2 --chain solana                    # SOL on Solana
sbc gas --token SBC --amount 2 --chain base --to-chain solana     # SOL from Base, two steps

Other

CommandDescription
sbc manifestFetch platform /.well-known/agent.json

Common workflow

# First-time setup (Agent Payments)
sbc login --user-key sk_user_...
sbc agent login --agent-key sk_live_...
sbc whoami
 
# Day-to-day (agent)
sbc balance
sbc pay --url https://api.mine.com
sbc send --to 0x... --amount 5
sbc agent swap --from USDC --to SBC --amount 10
 
# Swap API with your own wallet
sbc key import --chain evm                 # once per chain
export SBC_EVM_KEYSTORE=~/.sbc/keys/evm-….json SBC_SOLANA_KEYSTORE=~/.sbc/keys/solana-….json
sbc swap quote --from SBC --to cfUSD --amount 10
sbc swap --from SBC --to cfUSD --amount 10
sbc swap --from SBC --to SBC --amount 5 --from-chain solana --to-chain base
sbc swap status <orderId> --watch          # add --testnet for a testnet order
sbc gas --token SBC --amount 2
 
# Seller setup
sbc endpoint create --name "My API" --url https://api.mine.com --price 0.5 --chain base-sepolia
sbc endpoint keys generate <id> --label "production"
sbc endpoint balance <id>
sbc endpoint payments <id>
 
# Switch accounts
sbc logout                              # user key only
sbc logout --all                        # agent + user keys
sbc agent logout                        # agent key only

Next