Reference

Examples

End-to-end CLI workflows including executing a route

Common workflows for the Superbridge CLI. All examples assume SUPERBRIDGE_API_KEY is set in your environment.

Run without installing

Every example below uses the globally-installed superbridge binary. If you'd rather not install anything, prefix the command with your package manager's runner:

npx @superbridge/cli chains --mainnets

The same prefix works for any subcommand:

npx @superbridge/cli tokens --chain-key eth --search USDC

For repeated use — and especially for execute, which runs a long-lived poll loop — install the CLI globally instead. Each npx / dlx invocation re-resolves the package and is meaningfully slower to start.

Bridge ETH from Ethereum to Base

execute is interactive — it fetches quotes, lets you pick a provider, confirms the action, then runs the bridge end-to-end.

export EVM_PRIVATE_KEY=0xabc...

superbridge execute \
  --from-chain-key eth --to-chain-key base \
  --from-token 0x0000000000000000000000000000000000000000 \
  --to-token   0x0000000000000000000000000000000000000000 \
  --amount 0.01

execute handles approvals (if any), submits the initiating transaction, then polls activity and dispatches any follow-up step transactions until the bridge is done. Sender and recipient are derived from your wallet; pass --recipient to send to a different address.

Inspect quotes before executing

routes shows the same set of quotes that execute will pick from. Use it to scout fees, expected duration, and which providers cover the pair before committing.

superbridge routes \
  --from-chain-key eth --to-chain-key base \
  --from-token 0x0000000000000000000000000000000000000000 \
  --to-token   0x0000000000000000000000000000000000000000 \
  --amount 0.01

# When ready, run execute with the provider you want
superbridge execute \
  --from-chain-key eth --to-chain-key base \
  --from-token 0x0000000000000000000000000000000000000000 \
  --to-token   0x0000000000000000000000000000000000000000 \
  --amount 0.01 \
  --provider Across

Submit and exit without waiting

Bridges can take minutes to hours depending on the provider and chain. To submit the initiating transaction and return immediately, pass --no-wait:

superbridge execute \
  --from-chain-key eth --to-chain-key base \
  --from-token 0x0000000000000000000000000000000000000000 \
  --to-token   0x0000000000000000000000000000000000000000 \
  --amount 0.01 \
  --provider Across --yes --no-wait

You can later poll status with activity:

superbridge activity --tx-hash <returned-tx-hash>

Bridge from Solana

Provide an SVM key. The CLI will dispatch the SVM-shaped initiating transaction automatically.

export SVM_PRIVATE_KEY=...

superbridge execute \
  --from-chain-key sol --to-chain-key eth \
  --from-token <svm-token-mint> \
  --to-token   <evm-token-address> \
  --amount 1 \
  --recipient 0xYourEvmAddress

For cross-VM bridges, you must pass --recipient (or set both EVM_PRIVATE_KEY and SVM_PRIVATE_KEY so the CLI can derive the destination address from your wallet).

Run from a CI script

execute requires --provider and --yes in non-interactive contexts (no TTY) so a missed prompt can't block the script:

#!/usr/bin/env bash
set -euo pipefail

superbridge execute \
  --from-chain-key eth --to-chain-key base \
  --from-token 0x0000000000000000000000000000000000000000 \
  --to-token   0x0000000000000000000000000000000000000000 \
  --amount "$1" \
  --provider Across \
  --yes

Filter token lists with `jq`

Pass --output json to get raw JSON output that's pipe-friendly:

# Top 10 USDC variants across all chains
superbridge tokens --search USDC --limit 10 --output json \
  | jq '.tokens[] | {symbol, name, chain: .chain.name, address}'

# Just the chain IDs of every supported mainnet
superbridge chains --mainnets --output json | jq -r '.[].chainId' | sort -n

Build a route request from a JSON file

Hand-craft or template a request to keep flags out of your shell history:

{
  "fromChainKey": "eth",
  "toChainKey": "base",
  "fromTokenAddress": "0x0000000000000000000000000000000000000000",
  "toTokenAddress":   "0x0000000000000000000000000000000000000000",
  "amount": "10000000000000000",
  "sender":    "0xYourAddress",
  "recipient": "0xYourAddress",
  "slippage":  0.005
}

The JSON body matches the API request shape — amount is in wei / smallest denomination (this is 0.01 ETH).

superbridge routes --body @request.json

Flags can still override individual fields — handy for templating an amount. Unlike the JSON body, --amount is in human units and the CLI scales it by the from-token's decimals:

superbridge routes --body @request.json --amount 0.05