Skip to main content
Choose the service for your integration, then prepare its credentials and runtime. You can explore the CLI or build directly against the API; you do not need to complete both paths.

​
Prerequisites

  • For the Routes CLI: Node.js 20 or later, as required by eco-routes-cli 1.0.5.
  • For the TypeScript API guide: the Node.js version and dependencies listed in Integrate the Routes API.
  • For an onchain transfer: a wallet with the source token and enough native currency for any transactions it submits.
  • Access to a source-chain RPC endpoint. The CLI includes defaults. For an EVM chain, set EVM_RPC_URL_<chainId> to use your own endpoint, such as EVM_RPC_URL_8453 for Base.

​
Choose a service

These services have different request and response formats. Use the reference for the service you call.

​
API keys and attribution

For Eco API v1, send your key in the x-api-key header. The /v1/circle-gateway/* endpoints allow requests without a key. Request an API key for the other v1 endpoints and confirm that it has access to the operations you need. Keep the key in your backend environment. Use dappId to identify your application in v1 quote requests. The Open quoting service uses the distinct field dAppID. See the quote request example for the complete v1 body. See Errors and retries for authentication failures and API conventions for amount formats, identifiers, and rate limits.

​
Prepare the CLI

Set EVM_PRIVATE_KEY in your environment or in a local .env file for an EVM source. For Solana, use SVM_PRIVATE_KEY. Exclude .env from version control. The first-transfer guide shows how to preview a transfer before broadcasting. CLI 1.0.5 uses the legacy quoting service by default. Its command-line flow is separate from the v1 HTTP integration described in the API guide.

​
Environments

Use supported chains and tokens and the discovery endpoints to check mainnet coverage. For Circle Gateway testing, follow the dedicated testnet guide, which uses a different host and path scheme. Contact Eco for access to other test environments before using production credentials or funds.

​
Troubleshooting

  • API key rejected: check the header name, service hostname, and key’s v1 access. Do not put the key in a query string.
  • Insufficient balance: check the source-token balance and the gas needed for approvals and funding.
  • RPC request fails: confirm the endpoint serves the selected chain and retry read requests before submitting transactions.

​
Next steps