> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a Circle Gateway deposit address

> Creates a quoted Circle Gateway deposit address and returns it with the quoted amount and deadline.

Creates a quoted Circle Gateway deposit address and returns it as `vaultAddress`, with the quoted `amount` and the quote `deadline` (Unix seconds). The address must receive at least `amount` before `deadline`, gaslessly or by plain transfer. Repeating the same request while the quote is pending returns the same address. Responses keep the `{ data: … }` envelope and the deposit-address validation error format.

No API key is required: Circle Gateway operations are open so that any wallet or relay can create and fund a deposit address. A supplied key that is unknown, revoked, or not enabled for v1 is still rejected with `401 invalid-api-key`, so send no key rather than a wrong one. No requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.

Examples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.


## OpenAPI

````yaml api-v1.openapi.json POST /v1/circle-gateway/deposit-addresses
openapi: 3.1.0
info:
  title: Eco API
  version: v1
  description: >-
    Reference for the Eco API at https://api.eco.com/v1: quotes, chain and token
    discovery, gasless funding, intent status, and Circle Gateway fast deposits.
    Every operation requires an API key except the Circle Gateway operations,
    which are open.
servers:
  - url: https://api.eco.com
    description: Eco API
security: []
tags:
  - name: quotes
  - name: intents
  - name: status
  - name: discovery
  - name: circle-gateway
paths:
  /v1/circle-gateway/deposit-addresses:
    post:
      tags:
        - circle-gateway
      summary: Get a Circle Gateway deposit address
      description: >-
        Creates a quoted Circle Gateway deposit address and returns it as
        `vaultAddress`, with the quoted `amount` and the quote `deadline` (Unix
        seconds). The address must receive at least `amount` before `deadline`,
        gaslessly or by plain transfer. Repeating the same request while the
        quote is pending returns the same address. Responses keep the `{ data: …
        }` envelope and the deposit-address validation error format.


        No API key is required: Circle Gateway operations are open so that any
        wallet or relay can create and fund a deposit address. A supplied key
        that is unknown, revoked, or not enabled for v1 is still rejected with
        `401 invalid-api-key`, so send no key rather than a wrong one.


        No requests-per-second quota is published. Handle `429` and honor
        `Retry-After` when present.


        Examples use real mainnet token and contract addresses with placeholder
        wallets, hashes, signatures, and IDs.
      operationId: gateway-create
      parameters:
        - name: x-api-key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Optional. A key that is unknown, revoked, or not enabled for v1 is
            rejected with 401.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CircleGatewayDepositAddressDTO'
            examples:
              base-usdc:
                summary: Deposit 1 USDC from Base into the recipient's Gateway balance
                value:
                  sourceChainId: 8453
                  amount: '1000000'
                  recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
                  depositor: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
              with-refund-recipient:
                summary: Same, with an explicit refund recipient
                value:
                  sourceChainId: 8453
                  amount: '1000000'
                  recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
                  depositor: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
                  refundRecipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
      responses:
        '201':
          description: Quoted vault created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: >-
                      #/components/schemas/CircleGatewayDepositAddressResponseDTO
              examples:
                vault:
                  summary: Quoted deposit address (placeholder)
                  value:
                    data:
                      vaultAddress: '0x379BAB257e7Eb159538F01165B766A1BEaf2D954'
                      amount: '1000000'
                      deadline: 1789526504
        '400':
          description: Validation failure in the deposit-address service's format.
          content:
            application/json:
              examples:
                empty-body:
                  summary: 'Live: empty body'
                  value:
                    statusCode: 400
                    createdBy: ValidationFilter
                    validationErrors:
                      sourceChainId: >-
                        sourceChainId must not be less than 1, sourceChainId
                        should not be empty, sourceChainId must be an integer
                        number, sourceChainId must be a number conforming to the
                        specified constraints
                      amount: >-
                        amount must be a positive integer string <=
                        115792089237316195423570985008687907853269984665640564039457584007913129639935,
                        amount must be a positive integer string, amount should
                        not be empty, amount must be a string
                      recipient: >-
                        recipient must be an Ethereum address, recipient should
                        not be empty, recipient must be a string
                      depositor: >-
                        depositor must be an Ethereum address, depositor should
                        not be empty, depositor must be a string
                zero-refund-recipient:
                  summary: refundRecipient set to the zero address
                  value:
                    statusCode: 400
                    createdBy: ValidationFilter
                    validationErrors:
                      refundRecipient: refundRecipient must not be the zero address
        '401':
          description: >-
            The supplied x-api-key is unknown, revoked, or not enabled for the
            v1 API. Returned for every v1 endpoint by the gateway, with
            Content-Type application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://api.eco.com/v1/errors/invalid-api-key
                title: API key is missing, unknown, or revoked
                status: 401
                code: invalid-api-key
                requestId: 98e4c42f-9c70-4539-843e-8d31803001e6
        '403':
          description: Access denied.
        '429':
          description: Rate limit; honor Retry-After when supplied.
        '500':
          description: Service failure; preserve identifiers before retrying.
      security: []
components:
  schemas:
    CircleGatewayDepositAddressDTO:
      type: object
      required:
        - sourceChainId
        - amount
        - recipient
        - depositor
      properties:
        sourceChainId:
          type: integer
          minimum: 1
          example: 8453
          description: Source chain of the deposit.
        amount:
          type: string
          description: >-
            Required positive integer source-chain USDC amount in base units.
            Must fit uint256.
          example: '1000000'
        recipient:
          $ref: '#/components/schemas/EvmAddress'
          description: Gateway depositFor target on the destination chain.
        depositor:
          $ref: '#/components/schemas/EvmAddress'
          description: Address that will fund the vault.
        refundRecipient:
          $ref: '#/components/schemas/EvmAddress'
          description: Address that receives expiry refunds. Defaults to depositor.
    CircleGatewayDepositAddressResponseDTO:
      type: object
      required:
        - vaultAddress
        - amount
        - deadline
      properties:
        vaultAddress:
          $ref: '#/components/schemas/EvmAddress'
          description: Vault address on the source chain.
        amount:
          type: string
          description: Requested source-chain USDC amount in base units.
          example: '1000000'
        deadline:
          type: number
          description: Unix seconds quote deadline.
          example: 1798915200
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
          minLength: 1
        status:
          type: integer
          minimum: 400
          maximum: 599
        code:
          type: string
          description: >-
            Stable, machine-readable error code from the catalog. Branch on this
            and `status`, not on `title` or `detail`.
        detail:
          type: string
        instance:
          type: string
        legacyCode:
          type: string
          description: >-
            The pre-v1 numeric error code this problem maps to, for integrations
            migrating from the older services.
        solverErrors:
          type: array
          items:
            type: object
            properties:
              solver:
                type: string
                description: >-
                  Address on the relevant chain: `0x…` hex for EVM chains,
                  base58 for Solana, `T…` base58 for Tron.
              solverName:
                type: string
                minLength: 1
              code:
                type: string
                minLength: 1
              message:
                type: string
            required:
              - solver
              - message
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                minLength: 1
              detail:
                type: string
                minLength: 1
            required:
              - field
              - detail
          description: Field-level validation failures.
        requestId:
          type: string
          description: >-
            Correlation ID for support. Present on router-served errors;
            deposit-address-served errors carry a short numeric value.
      required:
        - type
        - title
        - status
        - code
    EvmAddress:
      type: string
      description: EIP-55 / lowercase hex 20-byte address
      example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'

````