USDC Gateway - Fireblocks Developer Docs

Overview

New to USDC Gateway? See the USDC Gateway Overview for a product introduction to the Circle Gateway integration and a console overview, before following this API guide. USDC Gateway connects your Fireblocks vault accounts to Circle Gateway, a cross-chain liquidity layer for USDC. Each vault account can have one Gateway wallet that holds a unified USDC balance across supported chains. You deposit USDC from a vault asset wallet into Gateway, then withdraw to any supported chain without managing per-chain inventory yourself. Deposits can also be put on a recurring schedule instead of submitted manually — see Automate deposits. This guide covers the full API flow: activate a Gateway wallet, deposit USDC, check balance, withdraw USDC, and deactivate the wallet. Deposits and withdrawals use the standard Create a new transaction endpoint with subType: VIRTUAL_ACCOUNT on the source or destination.

Beta feature: USDC Gateway is currently in beta and available through the Fireblocks API and Console. Behavior, endpoints, and limits may change. To request access, contact your Customer Success Manager, or enable it yourself from Labs in the Fireblocks Console (Settings → Labs).

Requirements

Fireblocks workspace

Prerequisite	Details
Policy rules	Enable both `APPROVE` and `TRANSFER` rules for deposits. The `APPROVE` rule covers the first contract call on each chain when you deposit from a vault address to Gateway. See Setting up policy rules for USDC Gateway for step-by-step guidance.
Vault account	A vault account to host the Gateway wallet. Each Gateway wallet is bound to exactly one vault account.
USDC asset wallets	The vault account has at least one USDC asset wallet with a generated address.
Native gas balance	The vault account holds enough native gas (for example, ETH on Ethereum or MATIC on Polygon) on every chain you plan to deposit from, unless Gas Station or Universal Gasless is configured for the workspace. This requirement applies to deposits only — for deposits into Gateway, you’re responsible for source-chain gas. For withdrawals, Circle covers the destination-chain gas and bills it to your Gateway balance, so you don’t need a native gas balance on chains you only withdraw to. For example, if you only ever deposit on Ethereum, you need an ETH gas balance — but you can withdraw to Base or Arbitrum without holding native gas on those chains.

API user

Create a Fireblocks API user in the Console, download the .pem private key, and note the API key UUID. Every request must be signed as a JWT using RS256. See Authenticate: Signing a Request for the full JWT structure.

API flow

The integration follows this order: Activate → Deposit → Check balance → Withdraw. Deactivation is optional and does not move funds.

Step 1: Activate the Gateway wallet

Activation creates the Gateway wallet bound to the vault account. No funds move. See Activate a Circle Gateway wallet. Request body

{
  "vaultAccountId": "1267"
}

Response

{
  "walletId": "9b...",
  "status": "ACTIVATED"
}

Re-run the activate endpoint on a deactivated wallet to re-enable it.

Step 2: Deposit USDC into Gateway

Submit a deposit using the Create a new transaction endpoint. Set subType: VIRTUAL_ACCOUNT on the destination to route funds into the Gateway wallet instead of a standard asset wallet. POST /v1/transactions Request body

{
  "assetId": "USDC_ETH_TEST5",
  "amount": "10",
  "source": {
    "type": "VAULT_ACCOUNT",
    "id": "0"
  },
  "destination": {
    "type": "VAULT_ACCOUNT",
    "id": "0",
    "subType": "VIRTUAL_ACCOUNT"
  }
}

Field notes:

assetId: the USDC asset ID for the source chain. For the current list of Gateway-supported chains, see the Fireblocks Help Center.
source.id and destination.id: the same vault account ID that hosts the Gateway wallet.
destination.subType: must be VIRTUAL_ACCOUNT for Gateway deposits.

The deposit reaches COMPLETED once your workspace’s transaction confirmation policy is satisfied — either a policy you’ve defined, or the Fireblocks default if you haven’t set one. Track status via the Transactions API or transaction webhooks.

Because completion is driven by your confirmation policy rather than by Circle Gateway’s own balance-credit confirmation, a deposit can occasionally show as COMPLETED slightly before on-chain finality and the Gateway balance update are fully reflected.

The first deposit from a vault address on a given chain triggers an automatic APPROVE transaction for Gateway smart contract approval. If your workspace Policies do not already cover this, add an APPROVE rule before initiating your first deposit on each chain. Once approved, subsequent deposits on the same chain proceed without an additional approval step.

Step 3: Check Gateway balance

Retrieve your total balance and per-chain breakdown. See Get Circle Gateway wallet info. Response fields

Field	Description
`status`	`ACTIVATED` or `DEACTIVATED`
`symbol`	Always `USDC`
`totalBalance`	Total USDC balance across all supported chains
`balanceBreakdown`	Per-chain breakdown showing how funds are distributed
`assetIds`	Fireblocks asset IDs covered by this Gateway wallet

Gateway balance may be delayed depending on Circle’s required block confirmations per chain. See Circle’s supported blockchain reference for details.

Step 4: Withdraw USDC from Gateway

Submit a withdrawal using the Create a new transaction endpoint. Set subType: VIRTUAL_ACCOUNT on the source to draw from the Gateway wallet instead of a standard asset wallet. POST /v1/transactions Request body (one-time address destination)

{
  "assetId": "USDC_ETH_TEST5",
  "amount": "10",
  "source": {
    "type": "VAULT_ACCOUNT",
    "id": "0",
    "subType": "VIRTUAL_ACCOUNT"
  },
  "destination": {
    "type": "ONE_TIME_ADDRESS",
    "oneTimeAddress": {
      "address": "0x..."
    }
  }
}

Request body (vault account destination)

{
  "assetId": "USDC_ETH_TEST5",
  "amount": "10",
  "source": {
    "type": "VAULT_ACCOUNT",
    "id": "0",
    "subType": "VIRTUAL_ACCOUNT"
  },
  "destination": {
    "type": "VAULT_ACCOUNT",
    "id": "1"
  }
}

Field notes:

assetId: the USDC asset ID for the destination chain.
source.subType: must be VIRTUAL_ACCOUNT for Gateway withdrawals.
destination: another Fireblocks vault account or a one-time address.

You specify only the destination chain and amount. Fireblocks selects which chain to draw from based on your current Gateway balance. The transaction reaches COMPLETED when destination-chain delivery is confirmed. Track status via the Transactions API or webhooks.

Step 5: Deactivate the Gateway wallet (optional)

Deactivation stops using Gateway on a vault account. It does not move funds. Any USDC already held in Circle Gateway remains and is accessible again by re-activating. See Deactivate a Circle Gateway wallet.

Automate deposits (optional)

Instead of submitting each deposit manually (Step 2), you can configure a deposit automation that sweeps USDC from a vault account’s asset wallets into its Gateway wallet on a recurring schedule, once the balance clears a threshold you set.

Beta feature: Deposit automation is currently in beta and may be subject to change.

Set up a deposit automation

POST /vault/accounts/{vaultAccountId}/virtual_asset_wallet/usdc_gateway/deposit_automation See Set up a USDC Gateway deposit automation for a vault account. Returns an error if an automation already exists for this vault account and asset — use PATCH to change an existing one instead. Request body

{
  "automationType": "USDC_GATEWAY_DEPOSIT",
  "assetId": "USDC_ETH",
  "timeBased": {
    "intervalValue": 60,
    "intervalUnit": "MINUTES",
    "balanceThreshold": "1000"
  }
}

Field notes:

automationType: must be USDC_GATEWAY_DEPOSIT.
assetId: optional. Scopes the automation to a single Fireblocks asset ID; omit to cover all supported USDC Gateway assets.
timeBased.intervalValue / timeBased.intervalUnit: how often the automation runs. intervalUnit is one of MINUTES, HOURS, or DAYS.
timeBased.balanceThreshold: minimum USDC balance required before a deposit runs. Set to "0" to sweep the full available balance every time, with no minimum.

Response

{
  "automationId": "b68a9e08-b59c-4ff9-893f-52d4f78c21e6"
}

Read configured automations

GET /vault/accounts/{vaultAccountId}/virtual_asset_wallet/usdc_gateway/deposit_automation See Read the USDC Gateway deposit automations for a vault account. Response

{
  "settings": [
    {
      "automationId": "b68a9e08-b59c-4ff9-893f-52d4f78c21e6",
      "vaultAccountId": "42",
      "assetId": "USDC_ETH",
      "automationType": "USDC_GATEWAY_DEPOSIT",
      "timeBased": {
        "intervalValue": 60,
        "intervalUnit": "MINUTES",
        "balanceThreshold": "1000"
      }
    }
  ]
}

Change an automation

PATCH /vault/accounts/{vaultAccountId}/virtual_asset_wallet/usdc_gateway/deposit_automation/{automationId} See Change a USDC Gateway deposit automation. Only the schedule (timeBased) can be changed; automationType and assetId are fixed for the lifetime of the automation. Request body

{
  "timeBased": {
    "intervalValue": 30,
    "intervalUnit": "MINUTES",
    "balanceThreshold": "500"
  }
}

Stop an automation’s schedule

DELETE /vault/accounts/{vaultAccountId}/virtual_asset_wallet/usdc_gateway/deposit_automation/{automationId} See Stop a USDC Gateway deposit automation’s schedule. This stops the schedule without deleting the automation’s configuration — turn it back on later with PATCH, without setting it up again from scratch.

Supported chains

For the current list of chains supported by USDC Gateway, refer to the Fireblocks Help Center.

Limits and fees

Limits

No minimum or maximum deposit or withdrawal amount is enforced at the Fireblocks layer. Standard Fireblocks API rate limits apply. If Circle Gateway rate-limits an operation on its side, the transaction fails with the error surfaced from Circle.

Fees

Withdrawals incur the following fees, charged in USDC against your Gateway balance:

Fee	Amount
Circle transfer rate	0.005% of the withdrawal amount
Withdrawal source-chain gas	Variable. Quoted by Circle per source chain at withdrawal time.

Deposits incur only the standard source-chain gas fee. This is paid from the vault account’s native gas balance, unless Gas Station or Universal Gasless is enabled. There is no Fireblocks-side or Circle-side fee for deposits. Fees are set by Circle Gateway and may change. For the current fee schedule, refer to Circle’s documentation.

Errors

All errors are also reflected as transaction sub-statuses on the corresponding transaction record, visible via the Transactions API or webhooks.

Error	Meaning	What to do
`WALLET_NOT_FOUND`	No Gateway wallet exists for this vault account.	Activate the Gateway wallet first (Step 1).
`WALLET_NOT_ACTIVATED`	The Gateway wallet exists but is deactivated.	Call the activate endpoint again to re-enable it.
`VAULT_ACCOUNT_HAS_NO_ADDRESSES`	The vault account has no asset wallets or addresses.	Create at least one USDC asset wallet before activating.
`UNSUPPORTED_TENANT_TYPE`	Workspace type is not supported by Gateway.	Contact your CSM.
`INSUFFICIENT_BALANCE`	The source vault does not have enough USDC to deposit.	Top up the source vault and retry.
`INSUFFICIENT_FEE_BALANCE`	The source vault does not have enough native gas to deposit.	Top up native gas on the source chain.
`INSUFFICIENT_GATEWAY_BALANCE`	Withdrawal amount exceeds your Gateway balance.	Deposit more USDC or lower the withdrawal amount.
`INSUFFICIENT_GATEWAY_BALANCE_FOR_FEES`	Withdrawal amount plus fees exceeds your Gateway balance.	Lower the amount or deposit more USDC.
`INVALID_SIGNATURE`	Burn intent signature failed Circle’s verification.	Retry. If the error persists, contact Fireblocks support.
`DOMAIN_NOT_IN_GATEWAY_INFO`	The requested chain is not supported by Circle Gateway.	Use a chain supported by USDC Gateway. See the Fireblocks Help Center for the current list.

Create vault wallets — create USDC asset wallets before activating Gateway.
Set transaction authorization policy — configure TRANSFER and APPROVE rules.
Work with Gas Station — automate native gas for deposit transactions.
Monitoring transaction statuses — track deposit and withdrawal progress via webhooks.

​Overview

​Requirements

​Fireblocks workspace

​API user

​API flow

​Step 1: Activate the Gateway wallet

​Step 2: Deposit USDC into Gateway

​Step 3: Check Gateway balance

​Step 4: Withdraw USDC from Gateway

​Step 5: Deactivate the Gateway wallet (optional)

​Automate deposits (optional)

​Set up a deposit automation

​Read configured automations

​Change an automation

​Stop an automation’s schedule

​Supported chains

​Limits and fees

​Limits

​Fees

​Errors

​Related

Overview

Requirements

Fireblocks workspace

API user

API flow

Step 1: Activate the Gateway wallet

Step 2: Deposit USDC into Gateway

Step 3: Check Gateway balance

Step 4: Withdraw USDC from Gateway

Step 5: Deactivate the Gateway wallet (optional)

Automate deposits (optional)

Set up a deposit automation

Read configured automations

Change an automation

Stop an automation’s schedule

Supported chains

Limits and fees

Limits

Fees

Errors

Related