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
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
UsePOST /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.
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
ReadGET /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 usevalidationErrorsor adetailsenvelope; 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.
