gateway-cli

CLI for BOB Gateway — swap between BTC and EVM tokens from the terminal.

Install

npm install -g @gobob/gateway-cli
gateway-cli --help

From source

pnpm install && pnpm build
npm link                      # makes gateway-cli available globally
gateway-cli --help

For development without linking:

pnpm cli:dev --help

Quick start

# Set your keys
export BITCOIN_PRIVATE_KEY="<wif-or-hex>"
export EVM_PRIVATE_KEY="<hex>"

# Get a quote
gateway-cli quote --src BTC --dst USDC:base --amount 0.05BTC --recipient 0xYourAddress

# Execute a swap
gateway-cli swap --src BTC --dst USDC:base --amount 0.05BTC --recipient 0xYourAddress

# Send everything
gateway-cli swap --src BTC --dst USDC:base --amount ALL --recipient 0xYourAddress

# Swap without --recipient (uses derived address from EVM_PRIVATE_KEY)
gateway-cli swap --src BTC --dst USDC:base --amount 0.05BTC

# Check your balances (derives addresses from keys)
gateway-cli balance

Commands

swap

Execute a cross-chain swap.

gateway-cli swap --src BTC --dst USDC:base --amount 0.05BTC --recipient 0x...

Required: --src, --dst, --amount

quote

Preview a swap without executing.

gateway-cli quote --src BTC --dst USDC:base --amount 100USD --recipient 0x...

balance

Show token balances across chains.

gateway-cli balance                           # derive addresses from env keys
gateway-cli balance bc1q... 0x123...          # explicit addresses
gateway-cli balance 0x123... --chain base     # specific chain
gateway-cli balance --chain base,bob          # multiple chains (comma-separated)
gateway-cli balance --chain base --chain bob  # multiple chains (repeated)
gateway-cli balance --non-zero                # only non-zero balances and tokens

routes

List supported routes, chains, or tokens.

gateway-cli routes                            # all routes
gateway-cli routes --chains                   # supported chains
gateway-cli routes --tokens base              # tokens on Base
gateway-cli routes --src-chain bitcoin        # routes from BTC

status, orders, register

gateway-cli status <order-id>                 # check order status
gateway-cli orders <address>                  # list orders for address
gateway-cli register <order-id> <txid>        # manually register a tx (recovery)

Amount format

The --amount flag accepts multiple formats:

| Format | Example | Meaning | |--------|---------|---------| | Token suffix | 0.05BTC | 0.05 BTC in human-readable units | | USD | 100USD | $100 worth (via price oracle) | | Atomic | 5000000 | 5,000,000 satoshis / wei / etc. | | All | ALL | Max spendable balance |

Bare numbers are always atomic units — you can't accidentally send 100 BTC by typing 100.

Configuration

All config via environment variables. No config files.

| Variable | Description | |----------|------------| | BITCOIN_PRIVATE_KEY | BTC private key (WIF or hex) | | EVM_PRIVATE_KEY | EVM private key (hex) | | GATEWAY_API_URL | Gateway API base URL (default: production) | | BTC_FEE_RATE | Bitcoin fee rate in sat/vbyte (default: mempool fastest) | | EVM_RPC_URL_<CHAIN> | Custom RPC URL per chain (e.g. EVM_RPC_URL_ETHEREUM) |

All flags

Shared (quote + swap)

--src <asset[:chain]>    Source asset (e.g. BTC, USDC:ethereum)
--dst <asset[:chain]>    Destination asset
--amount <value>         Amount (see format table above)
--recipient <address>    Recipient address (optional if destination wallet key is set)
--sender <address>       Sender address (optional)
--slippage <bps>         Slippage tolerance in basis points (default: 300)
--gas-refill-usd <usd>   ETH gas refill on destination
--btc-fee-rate <sat>     Bitcoin fee rate override
--fee-token <address>    ERC20 token for gas payment (paymaster)
--fee-reserve <amount>   Amount of fee token to reserve for gas
--json                   Output as JSON

Note: When --recipient is omitted, the CLI derives the recipient from the destination chain's private key (BITCOIN_PRIVATE_KEY for BTC destinations, EVM_PRIVATE_KEY for EVM destinations). BTC recipients use P2WPKH addresses (bc1q...). Other BTC address types are not yet supported. An explicit --recipient always overrides the derived address.

Swap only

--private-key <key>      Signing key (or use env vars)
--unsigned               Output unsigned PSBT/tx without signing
--no-wait                Exit after submitting without polling
--no-retry               Fail immediately on transient errors
--timeout <seconds>      Polling timeout (default: 1800)

Output modes

By default, output is human-readable. Add --json for machine-readable JSON output.

# Human-readable
gateway-cli quote --src BTC --dst USDC:base --amount 0.05BTC --recipient 0x...

# JSON
gateway-cli quote --src BTC --dst USDC:base --amount 0.05BTC --recipient 0x... --json

Publishing to npm

Tag a release to trigger the GitHub Actions publish workflow:

git tag cli-v0.2.0
git push origin cli-v0.2.0

Release candidates use the rc npm tag:

git tag cli-v0.3.0-rc0
git push origin cli-v0.3.0-rc0

Error handling

• Transient errors (rate limits, timeouts): automatically retried on quote and registration steps. Use --no-retry to disable.
• Registration failure: if a signed tx fails to register, the error includes the order ID and a recovery command: gateway-cli register <order-id> <txid>.
• Balance errors: per-chain failures show "N/A" instead of failing the entire command.