Skip to main content
Circle Gateway deposits let you fund a Gateway balance through a source-chain USDC deposit. Your application requests a quoted address, the user funds it, and Eco publishes the intent for solver fulfillment. The funding transaction, intent publication, and Gateway credit are separate stages.

Prerequisites

  • A supported source-chain wallet with USDC
  • A recipient address for the Gateway balance on Polygon
  • Source-chain gas for a direct transfer, or a wallet that supports the gasless funding methods
  • A delivery check through Circle Gateway, or an Eco v1 API key for intent tracking
The documented source chains are Base, OP Mainnet, and Arbitrum One, with Gateway on Polygon as the destination. Check chain support and confirm availability for your deposit request before funding. A Routes-supported chain is not necessarily enabled for this deposit flow.

API conventions

Base URL: https://api.eco.com. Circle Gateway endpoints use /v1/circle-gateway/ and do not require an API key. Create and deposit lookup responses have a { data: ... } envelope; gasless submit and job status responses use the v1 job format. No requests-per-second quota is published. Handle 429 with backoff and honor Retry-After when present. The endpoint reference includes request schemas and success and error examples.

Step 1: Create a quoted deposit address

Use POST /v1/circle-gateway/deposit-addresses. Set the amount in USDC base units and provide the depositor and Gateway recipient. Optional refundRecipient defaults to the depositor. The following server-side TypeScript example creates an address and reads its current record. It does not transfer tokens.
A successful create request returns 201 with data.vaultAddress, data.amount, and data.deadline (Unix seconds). Repeating the same pending, unexpired request returns the existing address. Always retain and use the latest returned address, amount, and deadline together.

Step 2: Fund the address

Choose a funding method: The address must receive at least the quoted amount before its deadline. Prefer the quoted amount exactly; do not assume an overpayment increases the destination credit. Gasless funding means the user does not submit a gas-paying funding transaction. Check the quote separately for fees.

Step 3: Poll for completion

Read GET /v1/circle-gateway/deposit-addresses/{vaultAddress} with the original sourceChainId. The response includes the deposit state and intentHash. For gasless funding, also read GET /v1/circle-gateway/deposit-addresses/status with the bare UUID from job.id, without the gasless: prefix. Inspect subStatuses[] and transaction hashes if the job fails or completes only partially. Confirm delivery through the recipient’s Circle Gateway balance, or track the returned delivery intent using GET /v1/intents/status, which requires a v1 API key. If the deposit response includes stitched.destinationIntentHash, use that destination intent for delivery tracking.

Troubleshooting

  • Invalid request (400): check address formats, source chain, amount, and required fields. Deposit-address errors use validationErrors or a details envelope; they are not all v1 problem responses.
  • Unknown deposit (404): use the address and source chain from the same create response.
  • Funding below the quote: the balance must reach the quoted amount before the deadline. Do not top up an expired quote without checking its recovery state.
  • Failed gasless job: inspect the source transaction hashes and deposit record before signing again. A failed job does not prove that funds never left the wallet.
  • Published but not credited: check the delivery intent and Gateway balance. Do not count intent publication as payment completion.
Refund and recovery paths depend on the recorded state and onchain conditions. Expiry or a failed status does not itself confirm returned funds.

Next steps