> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# USDC Gateway
## Overview
New to USDC Gateway? See the [USDC Gateway Overview](https://support.fireblocks.io/hc/en-us/articles/27419996238620-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](https://developers.circle.com/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](#automate-deposits-optional).
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](/reference/createtransaction) 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](https://console.fireblocks.io/v2/settings/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](https://support.fireblocks.io/hc/en-us/articles/28897919442588-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](/docs/work-with-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](/reference/signing-a-request-jwt-structure) 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.
```mermaid theme={"system"}
flowchart LR
A[Activate Gateway wallet] --> B[Deposit USDC]
B --> C[Check Gateway balance]
C --> D[Withdraw USDC]
D --> E[Deactivate optional]
```
### 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](/api-reference/vaults/activate-a-circle-gateway-wallet).
**Request body**
```json theme={"system"}
{
"vaultAccountId": "1267"
}
```
**Response**
```json theme={"system"}
{
"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](/reference/createtransaction) 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**
```json theme={"system"}
{
"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](https://support.fireblocks.io/hc/en-us/sections/28833527780252-USDC-Gateway).
* `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](/api-reference/transactions/get-a-transaction-by-id) or [transaction webhooks](/reference/monitoring-transaction-status).
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](/api-reference/vaults/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](https://developers.circle.com/gateway/references/supported-blockchains#required-block-confirmations) for details.
### Step 4: Withdraw USDC from Gateway
Submit a withdrawal using the [Create a new transaction](/reference/createtransaction) 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)**
```json theme={"system"}
{
"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)**
```json theme={"system"}
{
"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](/api-reference/vaults/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](/api-reference/vaults/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**
```json theme={"system"}
{
"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**
```json theme={"system"}
{
"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](/api-reference/vaults/read-the-usdc-gateway-deposit-automations-for-a-vault-account).
**Response**
```json theme={"system"}
{
"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](/api-reference/vaults/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**
```json theme={"system"}
{
"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](/api-reference/vaults/stop-a-usdc-gateway-deposit-automations-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](https://support.fireblocks.io/hc/en-us/sections/28833527780252-USDC-Gateway).
## 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](https://developers.circle.com/).
## 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](https://support.fireblocks.io/hc/en-us/sections/28833527780252-USDC-Gateway) for the current list. |
## Related
* [Create vault wallets](/reference/create-vault-wallet) — create USDC asset wallets before activating Gateway.
* [Set transaction authorization policy](/docs/set-transaction-authorization-policy) — configure `TRANSFER` and `APPROVE` rules.
* [Work with Gas Station](/docs/work-with-gas-station) — automate native gas for deposit transactions.
* [Monitoring transaction statuses](/reference/monitoring-transaction-status) — track deposit and withdrawal progress via webhooks.