Reference
Commands
Full reference for every superbridge subcommand
Every command accepts the global flags below in addition to its own arguments. Run superbridge <command> --help for the canonical, up-to-date list.
Global Flags
Every command pretty-prints to stdout by default. Pass --output json to get raw JSON instead — useful for piping into jq, saving to a file, or feeding into another command.
| Flag | Description |
|---|---|
--api-key | Override SUPERBRIDGE_API_KEY for this invocation. |
--output | pretty (default) or json. |
health
Check the API is reachable and your key works.
superbridge healthchains
List supported chains. Without filters, returns every chain Superbridge knows about.
| Flag | Description |
|---|---|
--key | Filter by shorthand chain key (e.g. eth). |
--id | Filter by native chain id (e.g. 1). |
--uid | Filter by Superbridge chain UID. |
--mainnets | Restrict to mainnet chains. |
--testnets | Restrict to testnet chains. |
superbridge chains --mainnets
superbridge chains --key eth --output json | jq '.[0]'tokens
List tokens, optionally filtered by chain or search term. Cursor-paginated.
| Flag | Description |
|---|---|
--address | Filter by token address. |
--chain-key, --chain-id, --chain-uid | Filter by chain. |
--search | Search by name, symbol, or address. |
--cursor | Cursor for fetching the next page of results. |
--limit | Page size (1–100). |
superbridge tokens --chain-key eth --search USDC --limit 5routes
Fetch available routes for a bridge or swap. Body-heavy — pass the request via --body, with individual flags overriding fields.
| Flag | Description |
|---|---|
--body | Request body as inline JSON, @path/to/file.json, or - for stdin. |
--from-chain-key, --from-chain-id, --from-chain-uid | Source chain. |
--to-chain-key, --to-chain-id, --to-chain-uid | Destination chain. |
--from-token, --to-token | Token addresses (0x000...0 for native). |
--sender, --recipient | Addresses involved in the route. If omitted, a default address is derived for the source/destination chain's VM. |
--amount | Amount in human units (e.g. 0.01 for 0.01 ETH or USDC). The CLI scales by the from-token's decimals. |
--slippage | Slippage as a decimal (e.g. 0.005 for 0.5%). |
--provider | Comma-separated list of providers to restrict the search to. |
superbridge routes \
--from-chain-key eth \
--to-chain-key base \
--from-token 0x0000000000000000000000000000000000000000 \
--to-token 0x0000000000000000000000000000000000000000 \
--amount 0.01Or pass an entire request as JSON:
superbridge routes --body @route-request.jsonSee the Routes API reference for the full request schema.
activity
Fetch bridge activity (history). All filters are optional; without any, you'll get the most recent items.
| Flag | Description |
|---|---|
--tx-hash | Filter by initiating transaction hash. |
--address | Filter by sender or recipient address. |
--status | pending or done (default: all). |
--type | mainnets or testnets (default: all). |
--page-size | Max 30. |
--from-chain-*, --to-chain-* | Chain filters (key / id / uid). |
superbridge activity --tx-hash 0xabc...
superbridge activity --address 0xYourAddress --status pendingstep
Find a ready step for an in-flight bridge, build its transaction, walk through signing/submission, and poll until the step status changes. Used during long-running flows where the user has to sign a follow-up transaction (for example, a Prove or Finalise step on an OP Stack rollup).
| Flag | Description |
|---|---|
--tx-hash | Initiating transaction hash. |
--action | RouteAction — e.g. Approve, Initiate, Prove, Finalise, Refund. |
--yes | Skip the confirmation prompt. |
superbridge step \
--tx-hash 0xabc... \
--action ProveIn most cases you should let execute handle follow-up steps for you — see below.
execute
Quote a bridge interactively, pick a provider, and run it end-to-end: any required revoke / approval / gas-token-approval transactions, the initiating transaction (or a gasless intent), then activity polling with automatic step dispatch until the bridge is complete.
This command needs a private key for the from-chain's VM. Sender and recipient are derived from your wallet — pass --recipient to send somewhere else.
| Flag | Description |
|---|---|
--from-chain-key / --from-chain-id / --from-chain-uid | Source chain. Required. |
--to-chain-key / --to-chain-id / --to-chain-uid | Destination chain. Required. |
--from-token / --to-token | Token addresses (0x000...0 for native). Required. |
--amount | Amount in human units (e.g. 0.01 for 0.01 ETH or USDC). The CLI scales by the from-token's decimals. Required. |
--slippage | Slippage as a decimal (e.g. 0.005). Default 0.005. |
--recipient | Override the recipient address (defaults to your wallet on the to-chain). |
--provider | Pre-select a provider by id or name, skipping the picker. |
--yes | Skip the confirmation prompt. |
--no-wait | Submit the initiating transaction and exit without polling. |
--evm-private-key / --evm-private-key-file | EVM signing key (or EVM_PRIVATE_KEY). |
--svm-private-key / --svm-private-key-file | SVM signing key (or SVM_PRIVATE_KEY). |
--stark-private-key / --stark-private-key-file | Starknet signing key (or STARK_PRIVATE_KEY). |
--stark-account-address | Starknet account contract address (or STARK_ACCOUNT_ADDRESS). |
export EVM_PRIVATE_KEY=0x...
superbridge execute \
--from-chain-key eth --to-chain-key base \
--from-token 0x0000000000000000000000000000000000000000 \
--to-token 0x0000000000000000000000000000000000000000 \
--amount 0.01The CLI fetches quotes, prompts you to choose a provider, confirms the action, then logs progress to stderr (› evm tx sent on Ethereum: 0x...) until the bridge is complete.
For non-interactive use (CI, scripts), pass --provider <id> and --yes.
index-transaction and submit-gasless are intentionally not exposed as subcommands — they're called automatically by execute and aren't useful in isolation.