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

# Estimate fees and expiration block heights for a transfer

> Calculates the required fees and expiration block heights for a transfer without requiring signatures or executing the transaction.



## OpenAPI

````yaml openapi/gateway.yaml post /v1/estimate
openapi: 3.0.3
info:
  title: Circle Gateway
  version: 1.0.0
  description: >
    Circle Gateway allows you to create a chain-abstracted USDC balance and
    transfer it instantly to any supported destination chain.
servers:
  - url: https://gateway-api-testnet.circle.com
  - url: https://gateway-api.circle.com
security: []
tags:
  - name: Gateway
    description: >-
      Endpoints for getting a unified USDC balance and creating attestations for
      transfer
  - name: Gateway Batch
    description: Endpoints for batch processing of EIP-3009 authorizations
  - name: Gateway x402
    description: Endpoints for x402 payment protocol integration
  - name: Webhook Subscriptions
    description: Manage webhook subscriptions for Gateway event notifications.
paths:
  /v1/estimate:
    post:
      tags:
        - Gateway
      summary: Estimate fees and expiration block heights for a transfer
      description: >-
        Calculates the required fees and expiration block heights for a transfer
        without requiring signatures or executing the transaction.
      operationId: EstimateTransfer
      parameters:
        - in: query
          name: maxAttestationSize
          required: false
          schema:
            type: integer
            minimum: 1
          description: Maximum allowed size (in bytes) for the encoded attestation.
        - in: query
          name: enableForwarder
          required: false
          schema:
            type: boolean
            default: false
          description: Whether to enable the forwarding service for estimating the fees.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateRequest'
      responses:
        '200':
          description: >-
            Successfully calculated the estimated fees and expiration block
            heights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateResponse'
        '400':
          description: >-
            Invalid request parameters or invalid partial burn intents or burn
            intent sets.
        '500':
          description: Internal server error
components:
  schemas:
    EstimateRequest:
      type: array
      description: >-
        Batch of partial burn intents or partial burn intent sets (without
        signatures). Burn intent sets are only supported for EVM source domains.
      minItems: 1
      items:
        oneOf:
          - $ref: '#/components/schemas/PartialBurnIntent'
          - $ref: '#/components/schemas/PartialBurnIntentSet'
    EstimateResponse:
      type: object
      description: >-
        Response containing estimated burn intents with calculated fees and
        expiration block heights.
      properties:
        body:
          type: array
          description: >-
            Array of burn intents or burn intent sets with calculated fees and
            expiration block heights.
          items:
            oneOf:
              - type: object
                properties:
                  burnIntent:
                    $ref: '#/components/schemas/EstimateBurnIntent'
                required:
                  - burnIntent
              - type: object
                properties:
                  burnIntentSet:
                    $ref: '#/components/schemas/EstimateBurnIntentSet'
                required:
                  - burnIntentSet
        fees:
          $ref: '#/components/schemas/FeeSummary'
          description: Information on the estimated fees to be charged.
      required:
        - body
        - fees
    PartialBurnIntent:
      type: object
      description: >-
        A burn intent for estimation purposes without signatures. Optional
        maxBlockHeight and maxFee for cost estimation.
      properties:
        maxBlockHeight:
          $ref: '#/components/schemas/Uint256'
          description: >-
            The maximum block height at which this burn is valid (optional for
            estimation).
        maxFee:
          $ref: '#/components/schemas/Uint256'
          description: >-
            The maximum fee the user is willing to pay (optional for
            estimation).
        spec:
          $ref: '#/components/schemas/TransferSpec'
        recipientSetupOptions:
          $ref: '#/components/schemas/RecipientSetupOptions'
      required:
        - spec
    PartialBurnIntentSet:
      type: object
      description: A set of partial burn intents for estimation purposes.
      properties:
        intents:
          type: array
          minItems: 1
          description: >-
            Array of partial burn intents to estimate fees and expiration block
            heights for.
          items:
            $ref: '#/components/schemas/PartialBurnIntent'
      required:
        - intents
    EstimateBurnIntent:
      type: object
      description: >-
        A burn intent returned from the estimate endpoint with addresses in
        canonical format.
      properties:
        maxBlockHeight:
          $ref: '#/components/schemas/Uint256'
          description: The maximum block height at which this burn is valid.
        maxFee:
          $ref: '#/components/schemas/Uint256'
          description: The maximum fee the user is willing to pay.
        spec:
          $ref: '#/components/schemas/EstimateTransferSpec'
        recipientSetupOptions:
          $ref: '#/components/schemas/EstimateRecipientSetupOptions'
      required:
        - maxBlockHeight
        - maxFee
        - spec
    EstimateBurnIntentSet:
      type: object
      description: >-
        A set of burn intents returned from the estimate endpoint with addresses
        in canonical format.
      properties:
        intents:
          type: array
          minItems: 1
          description: >-
            Array of burn intents with calculated fees and expiration block
            heights.
          items:
            $ref: '#/components/schemas/EstimateBurnIntent'
      required:
        - intents
    FeeSummary:
      type: object
      description: Aggregated fee information for a transfer request.
      properties:
        total:
          type: string
          description: Total fees from all burn intents across chains.
          example: '1.178'
        token:
          $ref: '#/components/schemas/Token'
          description: Token symbol.
          example: USDC
        perIntent:
          type: array
          items:
            $ref: '#/components/schemas/IntentFee'
          description: List of fee breakdowns for each burn intent.
        forwardingFee:
          type: string
          description: Forwarding fee charged for the transfer.
          example: '0.210000'
      required:
        - total
        - token
        - perIntent
    Uint256:
      type: string
      description: A large integer value, represented as a string.
      example: '1000000000000000000'
    TransferSpec:
      type: object
      properties:
        version:
          type: integer
          minimum: 0
          maximum: 4294967295
          description: Version of the transfer spec (uint32).
          example: 1
        sourceDomain:
          type: integer
          minimum: 0
          maximum: 4294967295
          description: The domain of the wallet contract this transfer came from (uint32).
          example: 0
        destinationDomain:
          type: integer
          minimum: 0
          maximum: 4294967295
          description: >-
            The domain of the minter contract this transfer is valid for
            (uint32).
          example: 4
        sourceContract:
          $ref: '#/components/schemas/Bytes32'
          description: >-
            The address of the wallet contract on the source domain (32-byte
            padded).
        destinationContract:
          $ref: '#/components/schemas/Bytes32'
          description: >-
            The address of the minter contract on the destination domain
            (32-byte padded).
        sourceToken:
          $ref: '#/components/schemas/Bytes32'
          description: The token address on the source domain (32-byte padded).
        destinationToken:
          $ref: '#/components/schemas/Bytes32'
          description: The token address on the destination domain (32-byte padded).
        sourceDepositor:
          $ref: '#/components/schemas/Bytes32'
          description: >-
            The address to debit within the wallet contract on the source domain
            (32-byte padded).
        destinationRecipient:
          $ref: '#/components/schemas/Bytes32'
          description: >-
            The address that should receive the funds on the destination domain
            (32-byte padded).
        sourceSigner:
          $ref: '#/components/schemas/Bytes32'
          description: The signer who signed for the transfer (32-byte padded).
        destinationCaller:
          $ref: '#/components/schemas/Bytes32'
          description: >-
            The address of the caller who may use the attestation, 0 address if
            any caller (32-byte padded).
        value:
          $ref: '#/components/schemas/Uint256'
          description: The amount to be transferred.
        salt:
          $ref: '#/components/schemas/Bytes32'
          description: An arbitrary value chosen by the user to be unique.
        hookData:
          $ref: '#/components/schemas/Hex'
          description: Arbitrary bytes that may be used for onchain composition (optional).
      required:
        - version
        - sourceDomain
        - destinationDomain
        - sourceContract
        - destinationContract
        - sourceToken
        - destinationToken
        - sourceDepositor
        - destinationRecipient
        - sourceSigner
        - destinationCaller
        - value
        - salt
    RecipientSetupOptions:
      type: object
      description: >-
        Options for automatic Associated Token Account (ATA) creation on Solana.
        When the destination chain is Solana, the destinationRecipient must be
        an initialized USDC token account. If the recipient does not already
        have one, the Forwarding Service can create the ATA as part of the mint
        transaction. Omit this field if the recipient already has a USDC token
        account.
      properties:
        includeRecipientSetup:
          type: boolean
          description: >-
            Set to true to request automatic ATA creation. The Solana rent cost
            for token account creation will be included in the forwarding fee.
        recipientOwnerAddress:
          $ref: '#/components/schemas/Bytes32'
          description: >-
            The recipient's Solana wallet address in bytes32 hex format (32
            bytes, hex-encoded).
      required:
        - includeRecipientSetup
        - recipientOwnerAddress
    EstimateTransferSpec:
      type: object
      description: >-
        Transfer specification with addresses in their canonical format (not
        padded to 32 bytes).

        Note: This schema parallels TransferSpec but documents addresses as
        returned (canonical format)

        rather than as submitted (Bytes32 padded format). Keep in sync with
        TransferSpec for non-address fields.
      properties:
        version:
          type: integer
          minimum: 0
          maximum: 4294967295
          description: Version of the transfer spec (uint32).
          example: 1
        sourceDomain:
          type: integer
          minimum: 0
          maximum: 4294967295
          description: The domain of the wallet contract this transfer came from (uint32).
          example: 0
        destinationDomain:
          type: integer
          minimum: 0
          maximum: 4294967295
          description: >-
            The domain of the minter contract this transfer is valid for
            (uint32).
          example: 4
        sourceContract:
          $ref: '#/components/schemas/CanonicalAddress'
          description: The address of the wallet contract on the source domain.
        destinationContract:
          $ref: '#/components/schemas/CanonicalAddress'
          description: The address of the minter contract on the destination domain.
        sourceToken:
          $ref: '#/components/schemas/CanonicalAddress'
          description: The token address on the source domain.
        destinationToken:
          $ref: '#/components/schemas/CanonicalAddress'
          description: The token address on the destination domain.
        sourceDepositor:
          $ref: '#/components/schemas/CanonicalAddress'
          description: >-
            The address to debit within the wallet contract on the source
            domain.
        destinationRecipient:
          $ref: '#/components/schemas/CanonicalAddress'
          description: The address that should receive the funds on the destination domain.
        sourceSigner:
          $ref: '#/components/schemas/CanonicalAddress'
          description: The signer who signed for the transfer.
        destinationCaller:
          $ref: '#/components/schemas/CanonicalAddress'
          description: >-
            The address of the caller who may use the attestation, 0 address if
            any caller.
        value:
          $ref: '#/components/schemas/Uint256'
          description: The amount to be transferred.
        salt:
          $ref: '#/components/schemas/Bytes32'
          description: An arbitrary value chosen by the user to be unique.
        hookData:
          $ref: '#/components/schemas/Hex'
          description: Arbitrary bytes that may be used for onchain composition (optional).
      required:
        - version
        - sourceDomain
        - destinationDomain
        - sourceContract
        - destinationContract
        - sourceToken
        - destinationToken
        - sourceDepositor
        - destinationRecipient
        - sourceSigner
        - destinationCaller
        - value
        - salt
    EstimateRecipientSetupOptions:
      type: object
      description: >-
        Options for automatic Associated Token Account (ATA) creation on Solana,
        as returned from the estimate endpoint. The recipientOwnerAddress is in
        canonical format (not Bytes32 padded).
      properties:
        includeRecipientSetup:
          type: boolean
          description: >-
            Set to true to request automatic ATA creation. The Solana rent cost
            for token account creation will be included in the forwarding fee.
        recipientOwnerAddress:
          $ref: '#/components/schemas/CanonicalAddress'
          description: >-
            The recipient's Solana wallet address in canonical format
            (base58-encoded public key).
          example: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
      required:
        - includeRecipientSetup
        - recipientOwnerAddress
    Token:
      type: string
      description: Supported tokens for Gateway
      enum:
        - USDC
    IntentFee:
      type: object
      description: Fee breakdown for a single burn intent.
      properties:
        transferSpecHash:
          $ref: '#/components/schemas/Bytes32'
          description: Keccak256 hash of the encoded transfer specification.
        domain:
          $ref: '#/components/schemas/Domain'
          description: >-
            The domain ID of the chain where the burn intent originated
            (uint32).
        baseFee:
          type: string
          description: Fixed gas fee charged for the burn transaction.
          example: '2'
        transferFee:
          type: string
          description: Variable fee based on transfer amount. Omitted for same-chain burns.
          example: '0.125'
      required:
        - transferSpecHash
        - domain
        - baseFee
    Bytes32:
      type: string
      pattern: ^0x[a-fA-F0-9]{64}$
      example: '0x1234567890123456789012345678901234567890123456789012345678901234'
      description: A 32-byte hex string.
    Hex:
      type: string
      pattern: ^0x[a-fA-F0-9]*$
      example: '0x1a2b3c4d'
      description: A hex string.
    CanonicalAddress:
      oneOf:
        - type: string
          pattern: ^0x[a-f0-9]{40}$
          description: EVM address in canonical format (20-byte hex lowercase)
        - type: string
          pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          description: Solana address in canonical format (32-byte base58)
      description: >-
        Address in canonical format (not padded to 32 bytes).

        Supports multiple blockchain formats:

        - EVM chains: 20-byte hex lowercase with 0x prefix (e.g.,
        0x1234567890123456789012345678901234567890)

        - Solana: 32-byte base58 encoded (e.g.,
        9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM)
      example: '0x1234567890123456789012345678901234567890'
    Domain:
      type: integer
      enum:
        - 0
        - 1
        - 2
        - 3
        - 5
        - 6
        - 7
        - 10
        - 13
        - 14
        - 16
        - 19
        - 26
      description: |
        Circle domain identifiers for supported chains:

        - 0 - Ethereum
        - 1 - Avalanche
        - 2 - OP
        - 3 - Arbitrum
        - 5 - Solana
        - 6 - Base
        - 7 - Polygon PoS
        - 10 - Unichain
        - 13 - Sonic
        - 14 - World Chain
        - 16 - Sei
        - 19 - HyperEVM
        - 26 - Arc

````