Routes CLI

Send assets across chains with a single command.

Routes CLI is a terminal tool for publishing cross-chain intents built on the Eco Routes Protocol. You lock a reward on your source chain; competitive solvers race to deliver the result on your destination chain. Supports EVM (Ethereum, Base, Optimism, and more), and Solana.

---

See It In Action

$ eco-routes-cli publish --private-key 0xYOUR_PRIVATE_KEY

? Select source chain:        Base
? Select destination chain:   Optimism

? Route token:   USDC
? Route amount:  100

? Reward token:  USDC
? Reward amount: 101

┌─────────────────────────────────────────────┐
│            Intent Summary                   │
├──────────────────┬──────────────────────────┤
│ Source chain     │ Base (8453)              │
│ Destination      │ Optimism (10)            │
│ Route            │ 100 USDC → Optimism      │
│ Reward           │ 101 USDC on Base         │
│ Route deadline   │ 2026-02-26 14:00 UTC     │
│ Reward deadline  │ 2026-02-26 15:00 UTC     │
└──────────────────┴──────────────────────────┘

? Confirm and publish intent? Yes

⠋ Publishing intent...
✔ Intent published — tx: 0xabc123...def456

---

Quick Start

1. Install globally

npm i -g eco-routes-cli

2. Publish your first EVM intent

eco-routes-cli publish --private-key 0xYOUR_PRIVATE_KEY

Follow the prompts to select source chain (e.g. Base), destination chain (e.g. Optimism), token, and amounts. Done.

Tip: pass --source and --destination to skip chain selection prompts.

Prefer not to pass keys inline? Copy .env.example to .env and set EVM_PRIVATE_KEY (or SVM_PRIVATE_KEY for Solana) — the CLI will pick it up automatically.

---

What Is an Intent?

An intent describes what you want to happen on the destination chain and what reward you're offering to whoever makes it happen. Solvers — independent actors monitoring the protocol — race to fulfill your intent and claim the reward. The faster the solver, the better the deal for everyone.

This is powered by the Eco Routes Protocol. For the full picture of how intents are encoded, published, and proven, see ARCHITECTURE.md.

---

Command Reference

Command	Description
eco-routes-cli publish	Interactive intent publishing wizard
eco-routes-cli publish --source <chain> --destination <chain>	Skip chain selection prompts
eco-routes-cli chains	List all supported chains
eco-routes-cli tokens	List all configured tokens

publish flags:

Flag	Alias	Description
--source	-s	Source chain name or ID
--destination	-d	Destination chain name or ID
--route-token <symbol|address>		Token delivered on the destination chain
--reward-token <symbol|address>		Token paid on the source chain
--route-token-decimals <n>		Token decimals; required when --route-token is a raw address
--reward-token-decimals <n>		Token decimals; required when --reward-token is a raw address
--amount <value>		Reward amount in human units (e.g. 5); requires --reward-token
--route-amount <value>		Route amount in human units, only needed as a manual fallback when the quote service is down; requires --route-token
--private-key	-k	EVM private key (overrides EVM_PRIVATE_KEY env)
--private-key-tvm		TVM (Tron) private key (overrides TVM_PRIVATE_KEY env)
--private-key-svm		SVM private key (overrides SVM_PRIVATE_KEY env)
--recipient		Recipient address on the destination chain
--portal-address		Portal contract address on the source chain
--prover-address		Prover contract address on the source chain
--prover-type <name>		Prover type to use (e.g. LayerZero, Hyperlane)
--dry-run		Validate and preview without broadcasting
--yes	-y	Skip the confirmation prompt (required for a non-interactive publish)
--json		Machine-readable output: one JSON object on stdout, human logs on stderr
--watch	-w	Watch for fulfillment after publishing

Publish non-interactively:

eco-routes-cli publish -s base -d optimism \
  --reward-token USDC --route-token USDC --amount 5 \
  --recipient 0xYourRecipient -y --json

Private key formats:

Chain	Format	Example
EVM	0x + 64 hex chars	0xac09...ff80
Tron	64 hex chars, no 0x	ac09...ff80
Solana	Base58	5Jd7F...
Solana	JSON byte array	[1,2,3,...]
Solana	Comma-separated bytes	1,2,3,...

---

Configuration Reference

Copy .env.example to .env. On-chain operations require a wallet key and an operator-managed RPC endpoint. Missing RPC configuration fails before a client is created; no public primary or secondary endpoint is selected automatically. Known public catalog endpoints are rejected even when explicitly supplied. Chain listing, API quotes and offline dry-runs do not require an RPC endpoint.

Variable	Required	Description
EVM_PRIVATE_KEY	For EVM chains	EVM wallet private key (0x…)
SVM_PRIVATE_KEY	For Solana	Solana wallet key (base58, array, or bytes)
EVM_RPC_URL_<CHAIN_ID>	For EVM operations	Dedicated per-chain RPC; e.g. EVM_RPC_URL_2020 for Ronin. Takes precedence over EVM_RPC_URL
EVM_RPC_URL	If no per-chain URL	Explicit EVM RPC endpoint; ensure it serves the chain being used
TVM_RPC_URL	For Tron operations	Dedicated Tron RPC endpoint
SVM_RPC_URL	For Solana operations	Dedicated Solana RPC endpoint
EVM_RPC_URL_2 / TVM_RPC_URL_2 / SVM_RPC_URL_2	No	Explicit secondary endpoint; never defaults to a public RPC
ECO_ENV	No	Eco API gateway environment for quotes and status: production (default, api.eco.com) or staging (api.stag.eco.com). --env on publish/status overrides it per command
ECO_API_URL	No	Override the Eco API gateway base URL
ECO_API_KEY_PRODUCTION / ECO_API_KEY_STAGING	No	Per-environment API key sent as x-api-key to that gateway host only (staging requires one; production answers keyless but rejects unknown keys). Never commit them
ECO_API_KEY	No	Fallback key used for any environment without a per-environment key
SOLVER_URL	No	Bypass the gateway: quote directly from a solver-v2 host
QUOTES_API_URL	No	Bypass the gateway: use this exact quote-service v3 URL
QUOTES_PREPROD	No	Bypass the gateway: use the preprod quote service (set to true)
PORTAL_ADDRESS_ETH	No	Override Ethereum portal contract
PORTAL_ADDRESS_BASE	No	Override Base portal contract
PORTAL_ADDRESS_OPTIMISM	No	Override Optimism portal contract
PORTAL_ADDRESS_SOLANA	No	Override Solana portal contract

See .env.example for the complete list of portal address overrides.

---

Troubleshooting

Issue	Fix
Private key error	Check the format matches the chain type — see Private key formats above
Chain not found	Run eco-routes-cli chains to verify the exact chain name or ID
Insufficient balance	Ensure your wallet has the reward token plus gas on the source chain
Quote unavailable	Not all chain pairs have live routes yet — try a different pair
No RPC configured / Public RPC endpoints are not permitted	Set a dedicated per-chain EVM_RPC_URL_<CHAIN_ID>, TVM_RPC_URL or SVM_RPC_URL. Never commit provider credentials
RPC timeout	Check the configured provider's health and rate limits; do not switch to a public RPC

Enable verbose output for more detail:

DEBUG=* eco-routes-cli publish

---

Going Deeper

• ARCHITECTURE.md — How intents work, the Universal Address system, publisher internals
• CONTRIBUTING.md — Dev setup, adding chains and tokens, PR process
• GitHub Issues — Bug reports and feature requests

---

License

MIT © Eco Protocol

Built with viem, and @solana/web3.js. Powered by the Eco Routes Protocol.