@parallel-protocol/cli

Command-line interface for the Parallel Protocol — query live on-chain data, build and sign transactions, and interact with the x402 payment layer directly from your terminal.

Installation

# Install globally
npm install -g @parallel-protocol/cli

# Or run without installing
npx @parallel-protocol/cli <command>

Requirements: Node.js ≥ 18

Quick start

# 1. Configure (interactive wizard — runs once)
parallel config init

# 2. Explore
parallel protocol overview
parallel protocol tvl --chain base
parallel protocol savings-rate

# 3. Build a transaction (dry-run — no wallet needed)
parallel swap quote --op mint --collateral USDC --amount 1000 --chain avalanche
parallel swap mint  --collateral USDC --amount 1000 --chain avalanche --dry-run

Development (from the parallel-mcp repo):

npm run build:cli                              # build once
alias parallel="node packages/cli/dist/index.js"
parallel protocol overview

Configuration

parallel config init

Interactive wizard that creates ~/.parallel/config.toml:

[network]
default_chain = "base"

[wallet]
keystore_path = "~/.parallel/keystore.json"

[display]
default_format = "table"   # table | json

parallel config get / set

parallel config get network.default_chain   # → base
parallel config set network.default_chain ethereum

Creating a keystore

Always use a dedicated wallet for testing — never your main wallet.

The CLI uses the Ethereum V3 keystore format (AES-128-CTR encrypted, password required at each use). Three ways to create one:

Option A — Foundry cast (recommended for developers)

cast wallet new ~/.parallel/keystore.json
# → generates a fresh address and encrypts it with a password you choose

Option B — Geth

geth account new --keystore ~/.parallel/

Option C — From MetaMask (non-dev users)

# 1. MetaMask → Account details → Export Private Key
# 2. Convert to keystore:
cast wallet import ~/.parallel/keystore.json --interactive
# → paste the private key, set a password

Then point the CLI to it:

parallel config set wallet.keystore_path ~/.parallel/keystore.json
# or pass it directly: --wallet ~/.parallel/keystore.json

Environment variables

All optional — they override the config file when set.

| Variable | Description | |---|---| | PARALLEL_PRIVATE_KEY | Raw private key (hex, 0x prefix) — alternative to keystore, useful for scripts and CI | | PARALLEL_DEFAULT_CHAIN | Default chain — overrides network.default_chain in config | | PARALLEL_JSON | Set to true to force JSON output on all commands | | PARALLEL_API_URL | Parallel API base URL for --history commands (default: https://api.parallel.best) |

Global flags

These flags are available across most commands. Command-specific flags (e.g. --collateral, --amount, --op) are documented in each command's section.

| Flag | Alias | Description | |---|---|---| | --chain <chain> | -c | Target chain (e.g. base, ethereum, avalanche) | | --json | -j | Force JSON output | | --dry-run | | Build transaction without broadcasting (write commands only) | | --wallet [path\|env] | -w | Sign with a wallet — see below | | --help | -h | Contextual help |

--wallet resolution:

| Usage | Behavior | |---|---| | --wallet (alone) | Auto-resolves: reads wallet.keystore_path from config first, then falls back to $PARALLEL_PRIVATE_KEY | | --wallet env | Explicitly uses $PARALLEL_PRIVATE_KEY | | --wallet /path/to/keystore.json | Uses that specific keystore file (password prompted) |

Commands

parallel protocol

Read-only. No wallet required.

parallel protocol overview                                             # TVL · supply · APY · backing ratio
parallel protocol tvl            [--chain <chain>]                     # Total Value Locked per chain
parallel protocol supply         <usdp|susdp|prl|sprl1|sprl2> [--chain <chain>]  # Token supply breakdown
parallel protocol backing        [--chain <chain>]                     # Collateral composition + backing ratio
parallel protocol chains                                               # Supported chains + feature matrix
parallel protocol collaterals    --chain <chain>                       # Accepted collaterals · caps · fees
parallel protocol mint-capacity  --collateral <symbol> --chain <chain> [--amount <n>]
parallel protocol fees           [--collateral <symbol>] [--chain <chain>]
parallel protocol savings-rate   [--chain <chain>]                     # Global APY + per-chain breakdown
parallel protocol exchange-rate  [--chain <chain>]                     # sUSDp / USDp rate
parallel protocol solvency       [--chain <chain>]                     # Backing ratio per chain
parallel protocol surplus        [--chain <chain>]                     # Pending surplus (USDp)
parallel protocol flashloan      [--chain <chain>]                     # Flash loan capacity + fee rate

# Historical data (daily series) — flags: [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--chain <chain>]
parallel protocol backing      --history       # reserves over time, per chain (source: Parallel API)
parallel protocol tvl          --history       # TVL over time (source: DeFiLlama)
parallel protocol savings-rate --history       # sUSDp APY over time (source: DeFiLlama)
parallel protocol supply       --history usdp  # USDp circulating supply over time (source: DeFiLlama)

parallel swap

Build Parallelizer transactions (mint / burn / redeem).

# Get a quote first
parallel swap quote --op mint   --collateral <symbol> --amount <n> --chain <chain>
parallel swap quote --op burn   --collateral <symbol> --amount <n> --chain <chain>
parallel swap quote --op redeem --amount <n> --chain <chain>

# Dry-run (shows raw unsigned tx — no wallet needed)
parallel swap mint   --collateral <symbol> --amount <n> --chain <chain> --dry-run
parallel swap burn   --collateral <symbol> --amount <n> --chain <chain> --dry-run
parallel swap redeem --amount <n> --chain <chain> --dry-run

# Sign and broadcast
parallel swap mint   --collateral <symbol> --amount <n> --chain <chain> --wallet
parallel swap burn   --collateral <symbol> --amount <n> --chain <chain> --wallet
parallel swap redeem --amount <n> --chain <chain> --wallet   # proportional redeem

Options:

| Flag | Default | Description | |---|---|---| | --op <mint\|burn\|redeem> | | Operation (quote only) | | --collateral <symbol> | | Collateral symbol (e.g. USDC, USDS, sUSDS) | | --amount <n> | | Amount in USDp (or collateral units for mint) | | --address <0x...> | | Receiver address for dry-run (no key needed) |

parallel savings

sUSDp savings operations.

parallel savings rate     [--chain <chain>]                         # APY + exchange rate + TVL
parallel savings estimate --amount <n> --duration <days>            # Projected yield

parallel savings balance  <address> [--chain <chain>]               # sUSDp balance + USDp equivalent

# Dry-run
parallel savings deposit  --amount <n> --chain <chain> --dry-run
parallel savings withdraw --amount <n> --chain <chain> --dry-run    # amount in sUSDp shares

# Sign and broadcast
parallel savings deposit  --amount <n> --chain <chain> --wallet
parallel savings withdraw --amount <n> --chain <chain> --wallet

Note: savings deposit uses EIP-3009 transferWithAuthorization when available — single signature, gasless on L2/sidechains.

parallel bridge

LayerZero cross-chain bridge (USDp / sUSDp).

parallel bridge quote  --token <usdp|susdp> --from <chain> --to <chain> --amount <n>
parallel bridge fees   --from <chain> --token <usdp|susdp>   # fees to all destinations
parallel bridge limits [--chain <chain>]                      # daily + global limits

# Dry-run
parallel bridge send --token <usdp|susdp> --from <chain> --to <chain> --amount <n> --dry-run

# Sign and broadcast
parallel bridge send --token <usdp|susdp> --from <chain> --to <chain> --amount <n> --wallet [--recipient <address>]

parallel bridge status <txHash> --from <chain>

Note: Mantle does not support bridging (no BridgeableToken deployed). All other chains support bridge.

parallel staking

PRL staking — sPRL1 (single-sided) and sPRL2 (BPT, Balancer).

parallel staking overview                    # global stats: supply, voting power, rewards
parallel staking info     <address>          # per-address: staked, voting power, pending rewards
parallel staking cooldown <address>          # cooldown status + expiry date

# sPRL1 — stake PRL on Ethereum
parallel staking stake   --type sprl1 --amount <n> --dry-run
parallel staking unstake --type sprl1 --amount <n> --dry-run
parallel staking stake   --type sprl1 --amount <n> --wallet
parallel staking unstake --type sprl1 --amount <n> --wallet

# sPRL2 — Ethereum only (Balancer BPT, multi-step: Balancer → Aura)
parallel staking stake   --type sprl2 --amount <n> --dry-run                                    # BPT path
parallel staking stake   --type sprl2 --amount <n> --weth-amount <n> --dry-run                  # PRL+WETH path
parallel staking unstake --type sprl2 --amount <n> --wallet                                     # initiate cooldown
parallel staking unstake --type sprl2 --wallet                                                  # execute ready withdrawals

# Claim rewards
parallel staking claim   --type sprl1 --dry-run
parallel staking claim   --type sprl2 --dry-run
parallel staking claim   --type all   --wallet

parallel gov

Snapshot governance — read-only.

parallel gov proposals [--status active|pending|passed|rejected] [--type PIP|PGP|PIR]
parallel gov proposal  <PIP-65|0xabc...>    # full details + vote results + description
parallel gov params                          # protocol parameters: fee rates, collateral caps

parallel pay

x402 payment layer.

# Explore what's available on a chain
parallel pay capabilities [--chain <chain>]

# Gas sponsoring quota for an address
parallel pay quota --chain <chain> [--address <address>]

# Verify a payment on-chain
parallel pay verify <txHash> --chain <chain>

parallel pay prepare

Builds a signed or unsigned x402 payment payload.

# Unsigned — shows route + payload (no wallet required)
parallel pay prepare \
  --amount <n> \
  --recipient <address> \
  --chain <chain>

# Signed — reads wallet balance, auto-selects best route, encodes the payload
parallel pay prepare \
  --amount <n> \
  --recipient <address> \
  --chain <chain> \
  --wallet

# Force which token the agent pays with
parallel pay prepare --amount <n> --recipient <address> --chain <chain> --pay-with <usdp|usdc|susdp>

--token controls what the merchant receives (default: usdp). Accepted values: usdp · usdc · susdp · any backing collateral symbol (susds, sfrxusd, …).

--pay-with overrides which token the agent pays with (default: auto-detected from wallet balance). Accepted values: usdp · usdc · susdp.

Auto-route selection (when --wallet is provided):

| --token (merchant receives) | Agent wallet | Route | Method | |---|---|---|---| | usdp | USDp ≥ amount | A | transferWithAuthorization | | usdp | sUSDp only | H | redeemWithAuthorization → USDp | | usdp | sUSDp + USDp (top-up) | L | partialRedeemWithAuthorization | | usdc | USDp | B | swapExactOutputWithAuthorization | | usdc | sUSDp | I | redeemWithAuthorization → USDC | | usdc | USDC | F | transferWithAuthorization | | susdp | USDp | C | depositWithAuthorization | | susdp | sUSDp | J | transferWithAuthorization | | collateral (e.g. susds) | USDp | D | swapExactOutputWithAuthorization | | collateral (e.g. susds) | sUSDp | K | redeemWithAuthorization → collateral |

Without --wallet, the payload is unsigned and tokenIn defaults to usdp.

parallel cashback

Cashback rewards — read-only, via facilitator API.

parallel cashback balance  <address>                              # current month spend + earnings + tier
parallel cashback tier     <address>                              # 4-tier breakdown + rates
parallel cashback history  <address> [--limit <n>]                # monthly history + distribution status
parallel cashback estimate <address> [--projected-spend <n>]      # projected earnings this month
parallel cashback quota    <address> [--chain <chain>]            # gas sponsoring quota

Utilities

parallel version                  # CLI version · MCP server version · Node version
parallel health [--chain <chain>]  # RPC latency check for all chains (or one)
parallel config init              # interactive setup wizard
parallel config get <key>         # e.g. network.default_chain
parallel config set <key> <value> # e.g. parallel config set network.default_chain ethereum

Output

All commands print a human-readable table by default.

# Force JSON
parallel protocol tvl --json
# {"success":true,"data":{...}}

# Pipe-friendly: JSON is automatic when stdout is not a TTY
parallel protocol tvl | jq '.data.totalTVL'

JSON envelope:

{ "success": true, "data": { ... } }
{ "success": false, "error": { "code": "CHAIN_SUNSET", "message": "..." } }

Supported chains

ethereum · base · arbitrum · optimism · polygon · avalanche · bsc · scroll · gnosis · sei · berachain · hyperevm · unichain · ink · tac · mantle · linea · xlayer · fraxtal · worldchain · hemi · plume · plasma · katana

sonic is sunset (PIP-64) — read operations work, write operations return CHAIN_SUNSET.

Not all chains support every feature. Use parallel protocol chains to see the full feature matrix (Parallelizer, sUSDp, bridge).

Error codes

| Code | Trigger | |---|---| | CHAIN_SUNSET | Operation not available on a sunset chain | | CHAIN_PAUSED | Chain temporarily paused (auto-pause by Hypernative or governance) | | PARALLELIZER_NOT_DEPLOYED | Feature requires Parallelizer, not deployed on this chain | | UNKNOWN_CHAIN | Chain identifier not recognised | | INSUFFICIENT_BALANCE | Wallet balance too low for the requested amount | | EXCEEDS_CAP | Amount would exceed a collateral exposure cap | | EXCEEDS_BRIDGE_LIMIT | Amount exceeds daily or global bridge limit | | SLIPPAGE_EXCEEDED | Actual slippage exceeds the configured tolerance | | COOLDOWN_ACTIVE | Unstake impossible — cooldown period not yet expired | | COLLATERAL_NOT_SUPPORTED | Collateral not accepted on this chain | | WALLET_REQUIRED | Write command called without --wallet or --dry-run | | INVALID_KEYSTORE | Keystore file not found or invalid format | | WRONG_PASSWORD | Incorrect keystore decryption password | | INVALID_AMOUNT | Negative, zero, or unparseable amount | | MISSING_OPTION | Required flag not provided | | INVALID_ADDRESS | Argument is not a valid EVM address | | PAYMENT_EXPIRED | x402 payment — validBefore exceeded, re-sign required | | INVALID_SIGNATURE | x402 payment — EIP-712 signature invalid | | INVALID_NONCE | x402 payment — nonce already used | | ROUTE_UNAVAILABLE | x402 payment — no route available for this merchant/chain combination | | RPC_ERROR | RPC call failed (network issue or node unreachable) |

Related

• parallel-mcp — MCP server + x402 facilitator
• Parallel Protocol