Gateway v1 Provider

Table of Contents

• Gateway v1 Provider
  • Table of Contents
  • Overview
    • Why Gateway v1 Provider?
  • Installation
  • Quick Start
    • Option 1: With Unified Balance Kit (Recommended)
    • Option 2: Direct Provider Usage
  • Features
  • Supported Chains
  • Usage Examples
    • Basic Operations
    • Balance Queries
  • Error Handling
  • Spend Process
  • Integration with Unified Balance Kit
  • Development
  • License

Overview

The Gateway v1 Provider is a strongly-typed implementation of Circle's Gateway protocol that enables instant cross-chain USDC transfers with unified balance management across supported blockchain networks.

While primarily designed to power the Unified Balance Kit, this provider can also be used directly in applications that need fine-grained control over Gateway operations or want to integrate Gateway without the full Stablecoin Kits framework.

Why Gateway v1 Provider?

• ⚡ Instant cross-chain moves: Pull from multiple source chains and mint on destination in one flow
• 🌐 Unified balance model: Deposit once, spend anywhere—no waiting for finality between chains
• 🔒 Circle's official protocol: Uses Circle's Gateway infrastructure for security and reliability
• 🔧 Type-safe operations: Built with TypeScript strict mode and comprehensive validation
• 🛠️ Direct integration: Use standalone or with custom orchestration logic

Installation

npm install @circle-fin/provider-gateway-v1
# or
yarn add @circle-fin/provider-gateway-v1

Note: This provider is included by default with the Unified Balance Kit. You can import this provider if you need to do a custom Gateway integration.

Quick Start

Option 1: With Unified Balance Kit (Recommended)

import {
  createUnifiedBalanceKitContext,
  deposit,
  spend,
  getBalances,
} from '@circle-fin/unified-balance-kit'

// Provider included by default
const context = createUnifiedBalanceKitContext()

const result = await deposit(context, {
  from: { adapter, chain: 'Ethereum' },
  amount: '100',
})

const spendResult = await spend(context, {
  amount: '50',
  from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
  to: { adapter, chain: 'Base' },
})

const balances = await getBalances(context, { sources: { adapter } })

Option 2: Direct Provider Usage

import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'

const provider = createGatewayV1Provider()

// Get supported chains
const chains = provider.getSupportedChains()

// Deposit USDC on a chain
await provider.deposit({
  from: { adapter, chain: 'Ethereum' },
  amount: '100',
  token: 'USDC',
})

// Estimate spend fees
const estimate = await provider.estimateSpend({
  from: {
    adapter,
    allocations: { amount: '100', chain: 'Ethereum' },
  },
  to: { adapter, chain: 'Base' },
  token: 'USDC',
})

// Execute spend (mint on destination)
const result = await provider.spend({
  from: {
    adapter,
    allocations: { amount: '100', chain: 'Ethereum' },
  },
  to: { adapter, chain: 'Base' },
  token: 'USDC',
})

// Query balances
const balances = await provider.getBalances({
  token: 'USDC',
  sources: { adapter, chains: ['Ethereum', 'Base'] },
})

Features

• ✅ Deposits - Deposit USDC into Gateway accounts on any supported chain
• ✅ Spends (mints) - Pull from one or more chains and mint on destination
• ✅ Balance queries - Aggregated and per-chain USDC balances
• ✅ Delegation - Add/remove delegates for Gateway accounts
• ✅ Fund removal - Initiate and complete withdrawals from Gateway
• ✅ Multi-source spends - Allocate amounts from multiple chains in one operation
• ✅ Type safety - Full TypeScript support with structured KitError handling

Supported Chains

The provider supports all chains with Gateway v1 configuration. Call getSupportedChains() for the full list. Mainnet examples include Ethereum, Arbitrum, Base, Solana; testnet examples include Ethereum Sepolia, Base Sepolia, Solana Devnet.

import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'

const provider = createGatewayV1Provider()
const chains = provider.getSupportedChains()
console.log(chains.map((c) => c.name))

Usage Examples

Basic Operations

const provider = createGatewayV1Provider()

// Deposit
await provider.deposit({
  from: { adapter, chain: 'Ethereum' },
  amount: '100',
  token: 'USDC',
})

// Spend (single source)
const result = await provider.spend({
  from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
  to: { adapter, chain: 'Base' },
  token: 'USDC',
})
console.log(result.txHash, result.explorerUrl)

// Spend (multi-source)
const multiResult = await provider.spend({
  from: {
    adapter,
    allocations: [
      { amount: '30', chain: 'Ethereum' },
      { amount: '20', chain: 'Base' },
    ],
  },
  to: { adapter, chain: 'Avalanche' },
  token: 'USDC',
})

Balance Queries

const provider = createGatewayV1Provider()

// By adapter
const balances = await provider.getBalances({
  token: 'USDC',
  sources: { adapter, chains: ['Ethereum', 'Base'] },
})

// By account address (read-only)
const balancesByAddress = await provider.getBalances({
  token: 'USDC',
  sources: { address: '0x...', chains: ['Ethereum', 'Base'] },
})

// Include pending deposits
const withPending = await provider.getBalances({
  token: 'USDC',
  sources: { adapter },
  includePending: true,
})

Error Handling

The provider throws structured KitError instances for validation and execution failures:

import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'
import { isKitError } from '@circle-fin/unified-balance-kit'

const provider = createGatewayV1Provider()

try {
  const result = await provider.spend(params)
  console.log('Success:', result.txHash)
} catch (error) {
  if (isKitError(error)) {
    console.error(`Error ${error.code}: ${error.name}`, error.message)
    if (error.recoverability === 'RESUMABLE' && error.cause?.trace) {
      const { attestation, signature, missingTokenAccounts } = error.cause
        .trace as {
        attestation: string
        signature: string
        missingTokenAccounts?: { tokenAccount: string; mint: string }[]
      }
      if (missingTokenAccounts?.length) {
        // Solana only: create the listed token accounts first, then retry
        // with the same attestation. Retrying now fails the same way.
        throw error
      }
      // Mint failed after transfer—retry with config.retry
      await provider.spend({
        ...params,
        config: { retry: { attestation, signature } },
      })
    }
  }
  throw error
}

Spend Process

The Gateway v1 provider handles the complete spend (mint) flow:

1. Estimate - Fetch fee estimate from Gateway API
2. Sign - Build and sign burn intents for each source chain
3. Fetch Attestation - Submit signed intents to Gateway API, receive attestation
4. Mint - Execute mint transaction on destination chain using attestation

When the mint step fails after the attestation is fetched (funds locked), the provider throws a KitError with recoverability: 'RESUMABLE' and attestation/signature in cause.trace. Use config.retry to reattempt the mint without re-running the fetch.

On Solana, the mint does not create recipient token accounts. Both errors below list the missing accounts in cause.trace.missingTokenAccounts. If the missing account belongs to the Circle fee recipient, contact Circle support instead.

• Before the transfer (non-forwarder spends and estimateSpend): the provider checks the recipient token accounts before requesting an attestation. A missing account throws a VALIDATION_FAILED KitError that is FATAL. Nothing was submitted; create the accounts, then call spend again.
• At mint time (for example on config.retry): a missing account throws a VALIDATION_FAILED KitError that is RESUMABLE. Create the accounts, then retry with config.retry. Retrying before they exist fails with the same error.

Integration with Unified Balance Kit

This provider is designed specifically for the Unified Balance Kit:

import { UnifiedBalanceKit } from '@circle-fin/unified-balance-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new UnifiedBalanceKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
})

// Monitor gateway events
kit.on('*', (event) => console.log('Event:', event))
kit.on('gateway.deposit.succeeded', (payload) =>
  console.log('Deposit:', payload.data),
)
kit.on('gateway.spend.succeeded', (payload) =>
  console.log('Spend succeeded:', payload.data.txHash),
)

// Execute operations
await kit.deposit({ from: { adapter, chain: 'Ethereum' }, amount: '100' })
const result = await kit.spend({
  amount: '50',
  from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
  to: { adapter, chain: 'Base' },
})

Development

This package is part of the Stablecoin Kits monorepo.

# Build
nx build @circle-fin/provider-gateway-v1

# Test
nx test @circle-fin/provider-gateway-v1

License

This project is licensed under the Apache 2.0 License. Contact support for details.