# Agent Stack
Source: https://developers.circle.com/agent-stack

Empower your AI agents to autonomously operate wallets, transact onchain, and pay for API services through Circle's agent-native tooling.

Circle Agent Stack lets your AI agent hold and transact USDC and other tokens
across blockchains, discover and pay for x402 services, and operate within
built-in compliance guardrails. Use with
[Claude Code](https://claude.com/claude-code), [Cursor](https://cursor.com/),
[Codex](https://openai.com/codex), [OpenClaw](https://openclaw.ai/), or any
custom AI agent.

## What you can do

* **Build with an agent-native interface**: Use
  [Circle CLI](/agent-stack/circle-cli) and [Circle Skills](/ai/skills) to give
  your agent access to [Circle Wallets](/wallets), [CCTP](/cctp), and
  [Gateway](/gateway) from a single command interface.
* **Give your AI agent wallets**: Use
  [Agent Wallets](/agent-stack/agent-wallets) to hold and spend USDC and other
  tokens with customizable spending controls and built-in compliance guardrails.
* **Discover and pay for services on demand**: Search
  [x402-compatible APIs](https://agents.circle.com/services) and pay per
  request, without subscriptions or API keys.
* **Operate onchain across blockchains**: Trade tokens, bridge USDC, and execute
  onchain strategies across
  [supported blockchains](/agent-stack/agent-wallets/supported-blockchains).

## The agent stack

<CardGroup>
  <Card title="Circle CLI" icon="terminal" href="/agent-stack/circle-cli">
    A command-line tool for managing agent wallets, installing skills, and
    accessing the Circle product suite from any agent framework.
  </Card>

  <Card title="Agent Wallets" icon="wallet" href="/agent-stack/agent-wallets">
    Wallets for AI agents with custom spending policies, multichain support, and
    built-in compliance controls. Gasless across blockchains.
  </Card>

  <Card title="Agent Nanopayments" icon="bolt" href="/agent-stack/agent-nanopayments">
    Gasless USDC payments at sub-cent scale. Pay for x402-compatible services
    from your AI agent. Powered by Gateway.
  </Card>

  <Card title="Agent Marketplace" icon="store" href="https://agents.circle.com/services">
    A curated, compliance-first service catalog where AI agents can discover and
    pay for USDC-priced services.
  </Card>

  <Card title="Circle Skills" icon="puzzle-piece" href="/ai/skills">
    Open-source skills that give your AI agent specialized knowledge for
    building with Circle products.
  </Card>
</CardGroup>

## Dive deeper

* Get started with the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart).
* Make your first nanopayment with the
  [Agent Nanopayments quickstart](/agent-stack/agent-nanopayments/quickstart).
* Browse [Circle CLI commands](/agent-stack/circle-cli/command-reference).


# Agent Nanopayments
Source: https://developers.circle.com/agent-stack/agent-nanopayments

Gas-free, batched USDC payments at sub-cent scale for AI agents.

Agent Nanopayments, built on [Gateway Nanopayments](/gateway/nanopayments), let
your AI agent pay for [x402](/gateway/nanopayments/concepts/x402)-compatible
services in sub-cent USDC. These payments would normally be uneconomical due to
per-payment gas costs, but batching them into a single onchain settlement makes
high-frequency machine-to-machine commerce viable.

Your agent uses [Circle CLI](/agent-stack/circle-cli) to deposit USDC into a
Gateway balance, discover services, and pay for them.

## Get started

Follow the [quickstart](/agent-stack/agent-nanopayments/quickstart) to deposit
USDC, find a service, and make a nanopayment.

## Use cases

<CardGroup>
  <Card title="Pay for APIs and services" icon="bolt">
    Pay for x402-compatible APIs on a per-request basis. No subscriptions or
    per-service sign-ups.
  </Card>

  <Card title="On-demand compute and data" icon="server">
    Pay for compute, data, or storage at usage scale. Sub-cent payments make
    granular billing viable.
  </Card>

  <Card title="Agent-to-agent commerce" icon="arrows-left-right">
    Enable machine-to-machine payments at high frequency, with batched
    settlement keeping costs predictable.
  </Card>

  <Card title="Service discovery" icon="store">
    Find x402-compatible services on [Circle Agent
    Marketplace](https://agents.circle.com/services) and pay using your [agent
    wallet](/agent-stack/agent-wallets).
  </Card>
</CardGroup>

## Features

<AccordionGroup>
  <Accordion title="Batched settlement" icon="gas-pump">
    Gateway batches many payment authorizations and settles them onchain in a
    single transaction, amortizing gas across thousands of payments. Your agent
    pays no per-transaction gas. Learn more about [batched
    settlement](/gateway/nanopayments/concepts/batched-settlement).
  </Accordion>

  <Accordion title="x402 protocol" icon="code">
    Nanopayments use the [x402 standard](/gateway/nanopayments/concepts/x402),
    an open HTTP-native payment protocol built around the `402 Payment Required`
    status code. Sellers declare payment requirements, your agent signs a
    payment payload, and the exchange happens in a single request-response
    cycle.
  </Accordion>

  <Accordion title="Crosschain balance" icon="arrow-right-arrow-left">
    Your nanopayments balance can live on any [Gateway-supported
    blockchain](/gateway/references/supported-blockchains).
  </Accordion>
</AccordionGroup>

<Tip>
  To integrate x402 and Gateway Nanopayments in your application code instead of
  Circle CLI, see the [Nanopayments buyer
  quickstart](/gateway/nanopayments/quickstarts/buyer).
</Tip>


# Nanopayment Operations
Source: https://developers.circle.com/agent-stack/agent-nanopayments/operations

Tasks your agent can perform using Circle CLI to deposit USDC, pay for services, and withdraw funds.

Nanopayment operations are tasks your agent can perform using
[Circle CLI](/agent-stack/circle-cli). Full command syntax is in the
[CLI Command Reference](/agent-stack/circle-cli/command-reference).

The following table describes common nanopayment operations and the CLI commands
to perform them.

| Operation                                                                       | What it does                                                                                         | Command                   |
| :------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------- | :------------------------ |
| [Deposit for nanopayments](/agent-stack/agent-nanopayments/operations/deposit)  | Add USDC to your Gateway balance to fund nanopayments.                                               | `circle gateway deposit`  |
| [Pay for a service](/agent-stack/agent-nanopayments/operations/pay-for-service) | Discover and pay for [x402](/gateway/nanopayments/concepts/x402)-compatible API services using USDC. | `circle services pay`     |
| [Withdraw your balance](/agent-stack/agent-nanopayments/operations/withdraw)    | Move remaining USDC from your Gateway balance back to your agent wallet on the same blockchain.      | `circle gateway withdraw` |


# How to: Deposit for Nanopayments
Source: https://developers.circle.com/agent-stack/agent-nanopayments/operations/deposit

Deposit USDC into Gateway to enable gas-free, sub-cent payments powered by Circle Gateway.

Deposit USDC into Gateway once, then make payments without incurring gas costs
on each transaction.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* Completed the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
  (authenticates and funds your wallet).

## Steps

<Steps>
  <Step title="Deposit USDC into Gateway">
    Deposit USDC with your amount, wallet address, and blockchain. Direct
    deposits work from any
    [Gateway-supported blockchain](/gateway/references/supported-blockchains):

    ```bash theme={null}
    circle gateway deposit --amount 5 --address 0xYourWalletAddress --chain BASE --method direct
    ```

    <Tip>
      Use `--method eco` for fast deposits through Eco, which supports Base
      as the source blockchain and settles balances on Polygon PoS. Eco is a
      third-party fast-deposit service that Circle does not operate or
      audit. Review
      [Eco's docs](https://eco.com/docs/getting-started/programmable-addresses/gateway-deposits)
      and test the flow before using it in production.
    </Tip>
  </Step>

  <Step title="Check your Gateway balance">
    Confirm the deposit arrived:

    ```bash theme={null}
    circle gateway balance --address 0xYourWalletAddress --chain BASE
    ```

    The command returns your current Gateway balance. A non-zero value
    confirms the deposit arrived.
  </Step>
</Steps>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options.


# How to: Pay for a Service
Source: https://developers.circle.com/agent-stack/agent-nanopayments/operations/pay-for-service

Discover and pay for x402-compatible API services using USDC.

Pay for [x402](/gateway/nanopayments/concepts/x402)-compatible API services
directly from your agent wallet. Payment is processed before the request is
forwarded to the service.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* Completed the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
  (authenticates and funds your wallet).

<Note>
  Most x402 services require a Gateway balance. See [Deposit for
  nanopayments](/agent-stack/agent-nanopayments/operations/deposit) to set one
  up.
</Note>

## Steps

<Steps>
  <Step title="Find a service">
    Browse available services at
    [agents.circle.com/services](https://agents.circle.com/services), or search
    by keyword from the CLI:

    ```bash theme={null}
    circle services search "weather data"
    ```

    To inspect the payment requirements for a specific URL before paying:

    ```bash theme={null}
    circle services inspect https://api.example.com/weather
    ```
  </Step>

  <Step title="Pay for the service">
    Run `circle services pay` with the service URL and your wallet details. Use
    `--max-amount` to set a spending cap and avoid unexpected charges. Use
    `--estimate` to preview payment requirements without paying:

    ```bash theme={null}
    # Preview payment requirements without paying
    circle services pay https://api.example.com/weather \
      --address 0xYourWalletAddress \
      --chain BASE \
      --estimate

    # Pay for the service
    circle services pay https://api.example.com/weather \
      --address 0xYourWalletAddress \
      --chain BASE \
      --max-amount 0.01
    ```

    The CLI prints the service's response body.
  </Step>
</Steps>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `-X` for HTTP method and `-d` for a request
body.


# How to: Withdraw Your Balance
Source: https://developers.circle.com/agent-stack/agent-nanopayments/operations/withdraw

Withdraw remaining USDC from your Gateway balance back to your agent wallet.

Withdraw remaining USDC from your Gateway balance back to your agent wallet on
the same blockchain. Useful when you're done making nanopayments and want to
recover unused funds.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* Completed the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
  (authenticates and funds your wallet).

<Note>
  USDC is minted on the same blockchain as your Gateway balance. Crosschain
  withdrawals aren't supported.
</Note>

## Steps

<Steps>
  <Step title="Withdraw from Gateway">
    Run `circle gateway withdraw` with the amount, your wallet address, and
    the blockchain where your Gateway balance lives:

    ```bash theme={null}
    circle gateway withdraw --amount 1 --address 0xYourWalletAddress --chain BASE
    ```

    To send the withdrawn USDC to a different address, add `--recipient`:

    ```bash theme={null}
    circle gateway withdraw --amount 1 --address 0xYourWalletAddress --chain BASE --recipient 0xOtherAddress
    ```

    <Tip>
      Not sure which blockchain your balance lives on? Run
      `circle gateway balance --all` to see all blockchains.
    </Tip>
  </Step>

  <Step title="Confirm the withdrawal">
    Check that your Gateway balance decreased:

    ```bash theme={null}
    circle gateway balance --address 0xYourWalletAddress --chain BASE
    ```

    Then check that your wallet balance increased:

    ```bash theme={null}
    circle wallet balance --address 0xYourWalletAddress --chain BASE
    ```
  </Step>
</Steps>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options.


# Quickstart: Make a Nanopayment
Source: https://developers.circle.com/agent-stack/agent-nanopayments/quickstart

Deposit USDC into Gateway, find an x402-compatible service, and pay for it with your agent wallet.

By the end of this quickstart, your agent will have made a nanopayment to an
x402-compatible service.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* Completed the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
  (authenticates and funds your wallet).

## Steps

<Steps>
  <Step title="Deposit USDC into your nanopayments balance">
    Deposit 5 USDC from your wallet on Base:

    ```bash theme={null}
    circle gateway deposit --amount 5 --address 0xYourWalletAddress --chain BASE --method direct
    ```
  </Step>

  <Step title="Find an x402-compatible service">
    Search the Circle Agent Marketplace for available services:

    ```bash theme={null}
    circle services search "weather"
    ```

    Pick a service and inspect its payment requirements:

    ```bash theme={null}
    circle services inspect https://api.example.com/weather
    ```
  </Step>

  <Step title="Pay for the service">
    Pay with your Gateway balance on Base. Replace `0xYourWalletAddress` with
    your wallet address:

    ```bash theme={null}
    circle services pay https://api.example.com/weather \
      --address 0xYourWalletAddress \
      --chain BASE \
      --max-amount 0.01
    ```

    The CLI prints the service's response body. The payment settles against
    your Gateway balance.
  </Step>

  <Step title="Check your balance">
    Confirm your remaining Gateway balance:

    ```bash theme={null}
    circle gateway balance --address 0xYourWalletAddress --chain BASE
    ```
  </Step>
</Steps>

## Next steps

* [Pay for more services](/agent-stack/agent-nanopayments/operations/pay-for-service)
  using your remaining balance.
* [Withdraw your balance](/agent-stack/agent-nanopayments/operations/withdraw)
  back to your wallet when you're done.


# Agent Wallets
Source: https://developers.circle.com/agent-stack/agent-wallets

Wallets that let your agent autonomously hold, spend, trade, and earn USDC and other tokens with built-in spending controls.

Agent Wallets let your AI agent hold funds and transact onchain autonomously,
within spending policies you define. Your agent operates the wallet through
Circle CLI without writing integration code.

Built on [Circle's user-controlled wallets](/wallets/user-controlled) with
2-of-2 MPC key management, key shares are never exposed to the agent. The user
retains custody, and Circle cannot unilaterally move funds without their
involvement. All transfers are screened against sanctions controls before
submission onchain.

## Get started

Paste this prompt into your AI agent:

```text theme={null}
curl -sL https://agents.circle.com/skills/setup.md and follow the instructions to set up Circle Agent Wallet
```

The agent installs Circle CLI, creates and funds your agent wallet, and helps
you discover and pay for services with it. Prefer a manual setup? Follow the
[quickstart](/agent-stack/agent-wallets/quickstart) instead.

## Use cases

<CardGroup>
  <Card title="Autonomous trading" icon="chart-line">
    Run onchain strategies like dollar-cost averaging or token monitoring for
    autonomous execution within user-defined rules.
  </Card>

  <Card title="AI assistants with budgets" icon="robot">
    Execute real-world tasks like booking flights or paying for subscriptions
    within a scoped USDC budget.
  </Card>

  <Card title="Crosschain operations" icon="arrow-right-arrow-left">
    Hold, transfer, bridge, and swap USDC across all [supported
    blockchains](/agent-stack/agent-wallets/supported-blockchains) from a single
    agent wallet.
  </Card>

  <Card title="Custom spending policies" icon="sliders">
    Set [transfer limits, recipient allowlists, and contract
    blocklists](/agent-stack/agent-wallets/wallet-operations/custom-policies)
    per agent wallet. Your agent operates only within rules you define.
  </Card>
</CardGroup>

<Warning>
  When running autonomous trading strategies, start with small amounts and
  validate your approach before scaling. Only commit funds you are comfortable
  spending.
</Warning>

## Features

<AccordionGroup>
  <Accordion title="User-custody wallet" icon="shield-check">
    Built on [Circle user-controlled wallets](/wallets/user-controlled). Key
    shares are never exposed to the agent. Users retain custody while agents
    operate in defined spending limits.
  </Accordion>

  <Accordion title="Command-line interface" icon="terminal">
    Operate wallets through Circle CLI commands from any agent framework. No
    custom integration code required.
  </Accordion>

  <Accordion title="Spending policies" icon="sliders">
    Set USDC spending limits for outbound transfers and x402 payments. Limits
    can be time-bound (for example, daily, or monthly). Configure allowlists and
    blocklists for wallet and contract addresses.
  </Accordion>

  <Accordion title="x402 and nanopayments" icon="coins">
    Pair your agent wallet with [Agent
    Nanopayments](/agent-stack/agent-nanopayments) for gasless, sub-cent USDC
    payments to [x402](/gateway/nanopayments/concepts/x402)-compatible services.
  </Accordion>

  <Accordion title="Built-in compliance controls" icon="scale-balanced">
    All transfers are screened against sanctions controls before submission
    onchain. Transactions involving sanctioned entities are blocked, ensuring
    agents operate within regulatory requirements.
  </Accordion>

  <Accordion title="Token support" icon="coins">
    Agent Wallets support USDC, EURC, and other ERC20 tokens, and native tokens
    (for example, ETH, MATIC). USDC is the primary asset for transfers,
    bridging, and x402 payments.
  </Accordion>
</AccordionGroup>

<Note>
  Agent wallet transactions are gas-sponsored. Sponsorship is capped and subject
  to change. See [Fees](/agent-stack/agent-wallets/fees) for the full breakdown.
</Note>


# Agent Wallet Fees
Source: https://developers.circle.com/agent-stack/agent-wallets/fees

Fee breakdown for agent wallet operations, including bridging, swapping, and payments.

The following fees may apply depending on the operations your agent wallet
performs:

| Fee                    | Amount                           | When it applies                                |
| :--------------------- | :------------------------------- | :--------------------------------------------- |
| Gas                    | \$0 (sponsored)                  | All onchain transactions                       |
| CCTP fast transfer fee | Varies by source blockchain      | Bridging                                       |
| Forwarding service fee | \$0.20                           | Bridging                                       |
| Forwarding gas fee     | Varies by destination blockchain | Bridging                                       |
| Swap provider fee      | 2 bps                            | Swapping                                       |
| Gateway protocol fee   | 0.5 bps                          | Crosschain x402 payments (free for same-chain) |
| Eco deposit fee        | Set by Eco                       | Gasless Gateway deposits using Eco             |

<Note>
  Eco is a third-party fast-deposit service that Circle does not operate or
  audit. Review [Eco's
  docs](https://eco.com/docs/getting-started/programmable-addresses/gateway-deposits)
  and test the flow before using it in production.
</Note>

What to know about agent wallet fees:

* **Gas sponsorship**: Onchain transactions on agent wallets are gas-sponsored
  at no cost to you. Sponsorship is capped, subject to fair use, and may change
  over time.
* **CCTP fast transfer**: Agent Wallets use CCTP fast transfer only for
  bridging, which provides near-instant finality at a higher fee than standard
  transfers. For fast transfer rates by source blockchain, see
  [CCTP fees](/cctp/concepts/fees).
* **Forwarding gas fee**: Bridging also incurs a forwarding gas fee that varies
  by destination blockchain.


# Quickstart: Create an Agent Wallet
Source: https://developers.circle.com/agent-stack/agent-wallets/quickstart

Get your first agent wallet set up in minutes.

Create an agent wallet and fund it with USDC on Base.

Prefer a guided setup?
[Prompt your AI agent](/agent-stack/agent-wallets#get-started) to set it up.

<Note>
  Your agent can only operate the wallet if it has access to the email address
  used during authentication. By default, only you receive the OTP. If you grant
  your agent access to your inbox, it can authenticate on your behalf and
  perform all wallet operations.
</Note>

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

## Steps

Follow these steps to create an agent wallet and fund it with USDC.

<Steps>
  <Step title="Authenticate">
    ```bash theme={null}
    circle wallet login you@example.com
    ```

    <Note>
      To use testnet, add `--testnet` to the command. Sessions are stored separately
      for mainnet and testnet and expire after 7 days.
    </Note>

    On first run, Circle CLI prompts you to accept the Terms of Use and
    Privacy Policy. Then Circle sends a one-time password to verify your
    identity. After authentication, agent wallets are created automatically
    on all supported blockchains.
  </Step>

  <Step title="Get your wallet address">
    ```bash theme={null}
    circle wallet list --type agent --chain BASE
    ```

    Copy the wallet address returned. You will use it in the steps below.
  </Step>

  <Step title="Fund your wallet">
    Run `circle wallet fund` to add USDC to your wallet from another wallet you
    own. Replace `0xYourWalletAddress` with the address from the previous step:

    ```bash theme={null}
    circle wallet fund --address 0xYourWalletAddress --chain BASE --amount 10 --method crypto
    ```

    The CLI prints a terminal QR code and an
    [EIP-681](https://eips.ethereum.org/EIPS/eip-681) deposit URI. Scan the QR
    code with your mobile wallet to send the funds.

    To buy USDC with a card instead, pass `--method fiat` to open the onramp
    provider in your browser. See
    [Fund wallet](/agent-stack/agent-wallets/wallet-operations/fund) for all
    funding options.

    <Note>
      To use testnet, replace `BASE` with a testnet blockchain (for example,
      `ARC-TESTNET`) and omit `--method` and `--amount`. Testnet wallets are
      auto-funded with 20 USDC from the Circle faucet. See [supported
      blockchains](/agent-stack/agent-wallets/supported-blockchains) for the full
      list.
    </Note>
  </Step>

  <Step title="Check your balance">
    Confirm the funds arrived. Replace `0xYourWalletAddress` with your wallet
    address:

    ```bash theme={null}
    circle wallet balance --address 0xYourWalletAddress --chain BASE
    ```
  </Step>
</Steps>

## Next steps

Now that you have a funded wallet, you can:

* [Deposit for nanopayments](/agent-stack/agent-nanopayments/operations/deposit)
  and
  [pay for a service](/agent-stack/agent-nanopayments/operations/pay-for-service).
* [Transfer USDC](/agent-stack/agent-wallets/wallet-operations/transfer) to
  another address.
* [Bridge USDC](/agent-stack/agent-wallets/wallet-operations/bridge) to another
  blockchain.
* [Swap tokens](/agent-stack/agent-wallets/wallet-operations/swap) using your
  agent wallet.
* Explore [wallet operations](/agent-stack/agent-wallets/wallet-operations) for
  more tasks.


# Agent Wallet Supported Blockchains
Source: https://developers.circle.com/agent-stack/agent-wallets/supported-blockchains

Blockchains supported by Agent Wallets on mainnet and testnet.

Agent Wallets support the following blockchains on both mainnet and testnet,
except Arc Testnet (testnet only). Pass the blockchain identifier to the
`--chain` flag in CLI commands.

Run `circle blockchain list` to retrieve the current list.

| Blockchain  | Mainnet identifier | Testnet identifier |
| :---------- | :----------------: | :----------------: |
| Arbitrum    |        `ARB`       |    `ARB-SEPOLIA`   |
| Arc Testnet |          -         |    `ARC-TESTNET`   |
| Avalanche   |       `AVAX`       |     `AVAX-FUJI`    |
| Base        |       `BASE`       |   `BASE-SEPOLIA`   |
| Ethereum    |        `ETH`       |    `ETH-SEPOLIA`   |
| Monad       |       `MONAD`      |   `MONAD-TESTNET`  |
| Optimism    |        `OP`        |    `OP-SEPOLIA`    |
| Polygon PoS |       `MATIC`      |    `MATIC-AMOY`    |
| Unichain    |        `UNI`       |    `UNI-SEPOLIA`   |


# Wallet Operations
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations

Tasks you can perform with an agent wallet using Circle CLI, including transfers, bridging, payments, and more.

Wallet operations are tasks you can perform with an agent wallet using
[Circle CLI](/agent-stack/circle-cli). Full command syntax is in the
[CLI Command Reference](/agent-stack/circle-cli/command-reference).

The following table describes common wallet operations and the CLI commands to
perform them.

| Operation                                                                         | What it does                                                                                | Command                   |
| :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | :------------------------ |
| [Authenticate](/agent-stack/agent-wallets/wallet-operations/authenticate)         | Sign up or log in to your agent wallet using email OTP. Creates a session valid for 7 days. | `circle wallet login`     |
| [Fund wallet](/agent-stack/agent-wallets/wallet-operations/fund)                  | Add funds to your agent wallet using a wallet transfer or fiat onramp.                      | `circle wallet fund`      |
| [Transfer USDC](/agent-stack/agent-wallets/wallet-operations/transfer)            | Send USDC and other tokens to a designated wallet address.                                  | `circle wallet transfer`  |
| [Bridge USDC](/agent-stack/agent-wallets/wallet-operations/bridge)                | Move USDC from one blockchain to another using CCTP.                                        | `circle bridge transfer`  |
| [Swap tokens](/agent-stack/agent-wallets/wallet-operations/swap)                  | Swap one token for another directly from your agent wallet.                                 | `circle wallet swap`      |
| [Execute contract](/agent-stack/agent-wallets/wallet-operations/execute-contract) | Interact with a smart contract by calling a write function.                                 | `circle wallet execute`   |
| [Sign messages](/agent-stack/agent-wallets/wallet-operations/sign)                | Sign a message or EIP-712 typed data with your wallet.                                      | `circle wallet sign`      |
| [Set policies](/agent-stack/agent-wallets/wallet-operations/custom-policies)      | Set USDC transfer limits or allow/block specific recipient or contract addresses.           | `circle wallet limit set` |

For deposits into Gateway, payments to x402-compatible services, and
withdrawals, see [Agent Nanopayments](/agent-stack/agent-nanopayments).


# How to: Authenticate an Agent Wallet
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/authenticate

Log in with your email to create an agent wallet session on all supported blockchains.

Authenticating creates an agent session and provisions agent wallets on all
[supported blockchains](/agent-stack/agent-wallets/supported-blockchains)
automatically. You only need to do this once per environment. Sessions last 7
days.

This is a prerequisite for all other wallet operations, including
[Fund wallet](/agent-stack/agent-wallets/wallet-operations/fund),
[Transfer USDC](/agent-stack/agent-wallets/wallet-operations/transfer),
[Bridge USDC](/agent-stack/agent-wallets/wallet-operations/bridge), and
[Pay for service](/agent-stack/agent-nanopayments/operations/pay-for-service).

<Note>
  Your agent can only operate the wallet if it has access to the email address
  used during authentication. By default, only you receive the OTP. If you grant
  your agent access to your inbox, it can authenticate on your behalf and
  perform all wallet operations.
</Note>

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

## Steps

Choose the flow that matches your environment. Use **Interactive** when you can
respond to prompts in a terminal. Use **Non-interactive** for scripts and AI
agents that can't respond to interactive prompts.

<Tabs>
  <Tab title="Interactive">
    <Steps>
      <Step title="Run the login command">
        Run `circle wallet login` with your email address:

        ```bash theme={null}
        circle wallet login you@example.com
        ```

        <Note>
          To use testnet, add `--testnet` to the command. Sessions are stored separately
          for mainnet and testnet and expire after 7 days.
        </Note>

        On first run, Circle CLI prompts you to accept the Terms of Use and
        Privacy Policy.
      </Step>

      <Step title="Enter the one-time password">
        Check your email for the one-time password from Circle. Enter it in
        the terminal to verify your identity. You should see output similar
        to:

        ```text theme={null}
        Logged in as you@example.com
        ```

        Agent wallets are created automatically on all
        [supported blockchains](/agent-stack/agent-wallets/supported-blockchains).
      </Step>

      <Step title="Get your wallet address">
        List your wallets to find the address for the blockchain you want to
        use:

        ```bash theme={null}
        circle wallet list --type agent --chain BASE
        ```

        Copy the address returned. You'll need it for
        [funding your wallet](/agent-stack/agent-wallets/wallet-operations/fund),
        [transferring USDC](/agent-stack/agent-wallets/wallet-operations/transfer),
        [depositing for nanopayments](/agent-stack/agent-nanopayments/operations/deposit),
        and other operations.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Non-interactive (scripts and AI agents)">
    <Steps>
      <Step title="Initialize the login">
        Run `circle wallet login` with `--init` to send the OTP and capture a
        request ID. The `CIRCLE_ACCEPT_TERMS=1` prefix accepts the Circle CLI
        Terms of Use and Privacy Policy so the command doesn't pause for
        input on first run:

        ```bash theme={null}
        CIRCLE_ACCEPT_TERMS=1 circle wallet login you@example.com --init
        ```

        The CLI prints a request ID. Request IDs expire after 10 minutes and
        are consumed on first use.
      </Step>

      <Step title="Complete the login">
        Pass the request ID and the OTP from your inbox:

        ```bash theme={null}
        circle wallet login --request <request-id> --otp B1X-123456
        ```

        OTP codes are alphanumeric. Once login completes, agent wallets are
        created automatically on all
        [supported blockchains](/agent-stack/agent-wallets/supported-blockchains).
      </Step>

      <Step title="Get your wallet address">
        List your wallets to find the address for the blockchain you want to
        use:

        ```bash theme={null}
        circle wallet list --type agent --chain BASE
        ```

        Copy the address returned. You'll need it for
        [funding your wallet](/agent-stack/agent-wallets/wallet-operations/fund),
        [transferring USDC](/agent-stack/agent-wallets/wallet-operations/transfer),
        [depositing for nanopayments](/agent-stack/agent-nanopayments/operations/deposit),
        and other operations.
      </Step>
    </Steps>
  </Tab>
</Tabs>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options.


# How to: Bridge USDC
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/bridge

Move USDC from one blockchain to another using CCTP.

Bridge USDC across blockchains using [CCTP](/cctp). Circle handles attestation
and minting on the destination chain. You don't need a funded wallet or gas on
the destination.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* Completed the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
  (authenticates and funds your wallet).

## Steps

Follow these steps to bridge USDC to another blockchain.

<Steps>
  <Step title="Check the fee">
    Get the estimated fee before bridging:

    ```bash theme={null}
    circle bridge get-fee ARB --chain BASE
    ```
  </Step>

  <Step title="Bridge USDC">
    Run `circle bridge transfer` with the destination chain, amount, and your
    wallet details:

    ```bash theme={null}
    circle bridge transfer ARB --amount 10.0 --address 0xYourWalletAddress --chain BASE
    ```

    USDC is burned on the source chain and minted on the destination. The
    command returns once the bridge is complete:

    ```json theme={null}
    {
      "data": {
        "message": "Bridge complete: 10.0 USDC from BASE to ARB",
        "burnTxHash": "0xabc...",
        "forwardTxHash": "0xdef...",
        "fromChain": "BASE",
        "toChain": "ARB"
      }
    }
    ```

    If the bridge is still processing, you can check its status:

    ```bash theme={null}
    circle bridge status 0xabc... --chain BASE
    ```
  </Step>
</Steps>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including specifying a different recipient address on
the destination chain.


# How to: Set Spending Policies
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/custom-policies

Set transfer limits or address allowlists and blocklists on your agent wallet to control how it can move USDC and interact with contracts.

Spending policies let you cap your agent wallet's USDC transfers over a rolling
time window, or restrict the wallet to specific recipient or contract addresses.
Policies apply to mainnet agent wallets only.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* [Authenticated](/agent-stack/agent-wallets/wallet-operations/authenticate)
  your agent wallet.

<Note>
  Spending policies require a mainnet agent wallet. Testnet is not supported.
  Setting a policy triggers a second email OTP to confirm the change. The OTP is
  used once and not stored.
</Note>

## Steps

Choose the policy type that matches your goal.

<Tabs>
  <Tab title="Transfer limits">
    <Steps>
      <Step title="Set the limits">
        Run `circle wallet limit set` with per-transaction, daily, weekly, and
        monthly caps:

        ```bash theme={null}
        circle wallet limit set \
          --address 0xYourWalletAddress \
          --chain BASE \
          --policy-type stablecoin \
          --per-tx 100 \
          --daily 500 \
          --weekly 2000 \
          --monthly 5000
        ```

        Circle sends an email OTP to your agent session email to confirm the
        policy change. Limits must satisfy: per-transaction ≤ daily ≤ weekly
        ≤ monthly.
      </Step>

      <Step title="Verify the policy">
        Confirm the limits are in effect:

        ```bash theme={null}
        circle wallet limit --address 0xYourWalletAddress --chain BASE
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Allowlists and blocklists">
    Allowlists and blocklists restrict your wallet to specific recipient or
    contract addresses.

    <Steps>
      <Step title="Set the rule">
        Run `circle wallet limit set` with `--rule-type` and a bracketed,
        comma-separated `--targets` list of EVM addresses. The example below
        blocks transfers to two recipient addresses:

        ```bash theme={null}
        circle wallet limit set \
          --address 0xYourWalletAddress \
          --chain BASE \
          --policy-type stablecoin \
          --rule-type recipient-blocklist \
          --targets "[0xBAD1,0xBAD2]"
        ```

        `--rule-type` accepts:

        * `recipient-allowlist` / `recipient-blocklist`: allow or block USDC
          transfers to specific addresses.
        * `contract-allowlist` / `contract-blocklist`: allow or block contract
          interactions with specific addresses.

        Circle sends an email OTP to your agent session email to confirm the
        policy change.
      </Step>

      <Step title="Verify the policy">
        Confirm the rule is in effect:

        ```bash theme={null}
        circle wallet limit --address 0xYourWalletAddress --chain BASE
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options.


# How to: Execute a Smart Contract
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/execute-contract

Call a write function on a smart contract from your agent wallet.

Execute write functions on any smart contract from your agent wallet. Common
uses include approving token allowances, interacting with DeFi protocols, or
calling custom contract logic.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* Completed the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
  (authenticates and funds your wallet).

## Steps

Follow these steps to execute a smart contract function.

<Steps>
  <Step title="Find the contract address">
    For Circle contracts (USDC, CCTP, Gateway), look up the address for your
    blockchain:

    ```bash theme={null}
    circle contract address usdc --chain BASE
    ```
  </Step>

  <Step title="Execute the contract function">
    Run `circle wallet execute` with the ABI function signature, parameters,
    and contract address:

    ```bash theme={null}
    circle wallet execute "approve(address,uint256)" 0xSpender 1000000 \
      --contract 0xUSDC \
      --address 0xYourWalletAddress \
      --chain BASE
    ```

    The CLI waits for the transaction to reach a terminal state and returns the
    result:

    ```json theme={null}
    {
      "data": {
        "id": "abc-123-...",
        "state": "CONFIRMED",
        "blockchain": "BASE",
        "txHash": "0xabc...",
        "operation": "CONTRACT_EXECUTION",
        "contractAddress": "0xUSDC",
        "abiFunctionSignature": "approve(address,uint256)"
      }
    }
    ```

    If the transaction fails, the CLI prints the reason. Verify the contract
    address, function signature, and parameters, then retry.
  </Step>
</Steps>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `--amount` to send native token value with
the call.


# How to: Fund an Agent Wallet
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/fund

Add USDC to your agent wallet using a wallet transfer or fiat onramp.

Add USDC to your agent wallet before sending transfers or paying for services.

This is a prerequisite for
[transferring USDC](/agent-stack/agent-wallets/wallet-operations/transfer),
[bridging USDC](/agent-stack/agent-wallets/wallet-operations/bridge),
[paying for services](/agent-stack/agent-nanopayments/operations/pay-for-service),
and other operations that spend USDC.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* [Authenticated](/agent-stack/agent-wallets/wallet-operations/authenticate)
  your agent wallet.

## Steps

<Steps>
  <Step title="Fund your wallet">
    Run `circle wallet fund` with your wallet address, blockchain, amount, and
    method (crypto or fiat). Replace `0xYourWalletAddress` with your wallet
    address.

    <Tabs>
      <Tab title="Crypto">
        ```bash theme={null}
        circle wallet fund --address 0xYourWalletAddress \
          --chain BASE --amount 10 --method crypto
        ```

        The CLI prints a terminal QR code and an
        [EIP-681](https://eips.ethereum.org/EIPS/eip-681) deposit URI. Scan
        the QR code with your mobile wallet to send the funds. Pass
        `--export <dir>` to save a PNG instead, or `--open` to render the QR
        code in a browser tab.
      </Tab>

      <Tab title="Fiat">
        ```bash theme={null}
        circle wallet fund --address 0xYourWalletAddress \
          --chain BASE --amount 10 --method fiat
        ```

        Your browser opens to the onramp provider where you can purchase USDC
        with a card or bank transfer. Pass `--no-open` to print the URL
        instead of opening the browser.
      </Tab>
    </Tabs>

    <Note>
      To use testnet, replace `BASE` with a testnet blockchain (for example,
      `ARC-TESTNET`) and omit `--method` and `--amount`. Testnet wallets are
      auto-funded with 20 USDC from the Circle faucet. See [supported
      blockchains](/agent-stack/agent-wallets/supported-blockchains) for the full
      list.
    </Note>
  </Step>

  <Step title="Verify the funds arrived">
    Check your balance to confirm the deposit:

    ```bash theme={null}
    circle wallet balance --address 0xYourWalletAddress --chain BASE
    ```
  </Step>
</Steps>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `--token` to fund with ETH or native tokens.


# How to: Sign a Message
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/sign

Sign a plain text message or EIP-712 typed data with your agent wallet.

Sign messages or EIP-712 typed data with your agent wallet. Signing is commonly
used to prove wallet ownership or authorize offchain actions.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* [Authenticated](/agent-stack/agent-wallets/wallet-operations/authenticate)
  your agent wallet.

## Sign a message

Run `circle wallet sign` with your message and wallet details. Each command
returns a signature (`0xabcdef1234...`):

```bash theme={null}
# Sign a plain text message
circle wallet sign message "hello world" --address 0xYourWalletAddress --chain BASE

# Sign a hex-encoded message
circle wallet sign message "0xdeadbeef" --hex --address 0xYourWalletAddress --chain BASE

# Sign EIP-712 typed data (EVM only)
circle wallet sign typed-data \
  '{"types":{...},"primaryType":"Mail","domain":{...},"message":{...}}' \
  --address 0xYourWalletAddress \
  --chain BASE
```

<Note>Typed data signing is supported on EVM blockchains only.</Note>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options.


# How to: Swap Tokens
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/swap

Swap one token for another from your agent wallet.

Swap tokens from your agent wallet using `circle wallet swap`. Optionally get a
price quote first to verify the expected output before committing funds.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* Completed the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
  (authenticates and funds your wallet).

## Steps

<Steps>
  <Step title="Get a quote (optional)">
    Run `circle wallet swap` with `--quote` to see the estimated output without
    executing the swap:

    ```bash theme={null}
    circle wallet swap EURC 10 USDC --chain BASE --quote
    ```

    ```json theme={null}
    {
      "data": {
        "message": "Quote: 10 EURC → ~9.95 USDC (min 0.000001) on BASE",
        "sellToken": "EURC",
        "sellAmount": "10",
        "buyToken": "USDC",
        "chain": "BASE",
        "estimatedOutput": "9.95",
        "stopLimit": "0.000001"
      }
    }
    ```
  </Step>

  <Step title="Swap tokens">
    Run `circle wallet swap` with your wallet address and a `<buyAmount>`
    stop-limit. If the estimated output falls below this value onchain, the swap
    fails instead of settling at an unfavorable rate:

    ```bash theme={null}
    circle wallet swap EURC 10 USDC 9.9 --address 0xYourWalletAddress --chain BASE
    ```

    ```json theme={null}
    {
      "data": {
        "message": "Swap complete: 10 EURC → min 9.9 USDC on BASE",
        "sellToken": "EURC",
        "sellAmount": "10",
        "buyToken": "USDC",
        "buyMin": "9.9",
        "chain": "BASE"
      }
    }
    ```
  </Step>
</Steps>

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `--slippage-bps` to set maximum slippage.


# How to: Transfer USDC
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/transfer

Send USDC from your agent wallet to another address on a supported blockchain.

The transfer confirms onchain before the command returns, so no manual polling
is required.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v20.18.2 or later](https://nodejs.org/).

* Installed Circle CLI:

  ```bash theme={null}
  npm install -g @circle-fin/cli
  ```

* Completed the
  [Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
  (authenticates and funds your wallet).

## Send USDC

Run `circle wallet transfer` with the recipient address, amount, and your wallet
details:

```bash theme={null}
circle wallet transfer 0xRecipient --amount 1.0 --address 0xYourWalletAddress --chain BASE
```

The command returns the result once the transaction reaches a terminal state:

```json theme={null}
{
  "data": {
    "id": "abc-123-...",
    "state": "CONFIRMED",
    "blockchain": "BASE",
    "txHash": "0xabc...",
    "sourceAddress": "0xYourWalletAddress",
    "destinationAddress": "0xRecipient",
    "amounts": ["1"],
    "operation": "TRANSFER"
  }
}
```

If the transfer fails, the command prints the reason. Check your wallet balance
and retry.

See the [CLI Command Reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `--token` to transfer tokens other than USDC.


# Circle CLI
Source: https://developers.circle.com/agent-stack/circle-cli

A command-line tool to access Circle's product suite, including agent wallets, x402-compatible payments, and crosschain transfers.

Circle CLI gives developers and AI agents a unified interface for onchain
operations. Create and manage wallets, transfer, swap, and bridge USDC across
blockchains, execute smart contracts, and discover or pay for services. All
through a single command interface, without integrating multiple APIs and SDKs.

Use Circle CLI to access:

* **[Agent Wallets](/agent-stack/agent-wallets)**: Wallets with email OTP
  authentication, full onchain capabilities, and customizable policy
  enforcement.
* **Local wallets**: Self-custodial wallets imported from a private key or
  mnemonic, stored using the
  [Open Wallet Standard](https://github.com/open-wallet-standard/core).
* **Circle products**: [CCTP](/cctp) for USDC bridging and [Gateway](/gateway)
  for [x402 nanopayments](/gateway/nanopayments).

## Installation

Install Circle CLI from [npm](https://www.npmjs.com/) (requires
[Node.js v20.18.2 or later](https://nodejs.org/)):

```bash theme={null}
npm install -g @circle-fin/cli
```

Verify the installation:

```bash theme={null}
circle --version
```

Once installed, you can run any
[Circle CLI command](/agent-stack/circle-cli/command-reference).

## Get started

<CardGroup>
  <Card title="Create an Agent Wallet" icon="wallet" href="/agent-stack/agent-wallets/quickstart">
    Create an agent wallet and fund it with USDC.
  </Card>

  <Card title="CLI Command Reference" icon="book" href="/agent-stack/circle-cli/command-reference">
    All Circle CLI commands, options, and examples.
  </Card>
</CardGroup>


# CLI Command Reference
Source: https://developers.circle.com/agent-stack/circle-cli/command-reference

Complete command reference for Circle's agent command-line tool, organized by resource.

Circle CLI follows a `circle <resource> <verb> [options]` pattern. All commands
support `--help` for inline documentation.

## Global options

| Option                      | Description                            |
| :-------------------------- | :------------------------------------- |
| `--output json\|text\|yaml` | Set output format. Defaults to `text`. |
| `-q, --quiet`               | Minimal output, suitable for piping.   |
| `-h, --help`                | Show help for any command.             |
| `-v, --version`             | Print the Circle CLI version and exit. |

***

## Wallet commands

Manage your [agent wallet](/agent-stack/agent-wallets).

### `circle wallet login`

Authenticate using email OTP to create or access an agent wallet session.

**Syntax**

```bash theme={null}
circle wallet login <email> [options]
circle wallet login <email> --init
circle wallet login --request <id> --otp <code>
```

**Options**

| Option           | Description                                                                                                          |
| :--------------- | :------------------------------------------------------------------------------------------------------------------- |
| `--type`         | Wallet type. Defaults to `agent`.                                                                                    |
| `--testnet`      | Authenticate against testnet. Sessions are stored separately from mainnet.                                           |
| `--init`         | Two-step login for scripts and AI agents. Sends the OTP and returns a request ID. Pair with `--request`.             |
| `--request <id>` | Complete a `--init` login. Combine with `--otp <code>`.                                                              |
| `--otp <code>`   | One-time password for the request ID. Required with `--request`. Codes are alphanumeric (for example, `B1X-123456`). |

**Examples**

```bash theme={null}
# Interactive login (mainnet)
circle wallet login you@example.com

# Two-step login for scripts and AI agents
circle wallet login you@example.com --init
circle wallet login --request <request-id> --otp B1X-123456
```

<Note>
  Request IDs from `--init` are stored at `~/.circle/login-requests/<id>.json`,
  expire after 10 minutes, and are deleted after a successful `--request`.
</Note>

***

### `circle wallet logout`

Clear stored credentials for the current session.

**Syntax**

```bash theme={null}
circle wallet logout [options]
```

**Options**

| Option   | Description                                                          |
| :------- | :------------------------------------------------------------------- |
| `--type` | Clear credentials for a specific wallet type (for example, `agent`). |

**Example**

```bash theme={null}
circle wallet logout --type agent
```

***

### `circle wallet status`

Show the current authentication status and session details.

**Syntax**

```bash theme={null}
circle wallet status [options]
```

**Options**

| Option   | Description                                                    |
| :------- | :------------------------------------------------------------- |
| `--type` | Show status for a specific wallet type (for example, `agent`). |

**Example**

```bash theme={null}
circle wallet status --type agent
```

***

### `circle wallet create`

Create an additional wallet, separate from the wallets provisioned during login.
Each user can have at most 5 agent wallets.

**Syntax**

```bash theme={null}
circle wallet create [options]
```

**Options**

| Option              | Description                                               |
| :------------------ | :-------------------------------------------------------- |
| `--type`            | Wallet type: `agent` (default) or `local`.                |
| `--testnet`         | Create a testnet wallet. Omit for mainnet.                |
| `--idempotency-key` | Unique key to prevent duplicate wallet creation on retry. |

**Example**

```bash theme={null}
circle wallet create --type agent --testnet
```

***

### `circle wallet list`

List wallets associated with your account.

**Syntax**

```bash theme={null}
circle wallet list --chain <chain> [options]
```

**Options**

| Option    | Description                                |
| :-------- | :----------------------------------------- |
| `--chain` | Blockchain to list wallets on.             |
| `--type`  | Filter by wallet type: `agent` or `local`. |

**Example**

```bash theme={null}
circle wallet list --chain ARC-TESTNET --type agent
```

***

### `circle wallet limit`

Show spending policy limits for an agent wallet. Mainnet only.

**Syntax**

```bash theme={null}
circle wallet limit --address <addr> --chain <chain>
```

**Options**

| Option      | Description                                       |
| :---------- | :------------------------------------------------ |
| `--address` | Agent wallet address.                             |
| `--chain`   | Mainnet blockchain. Testnet chains not supported. |

**Examples**

```bash theme={null}
circle wallet limit --address 0x... --chain BASE
circle wallet limit --address 0x... --chain BASE --output json
```

***

### `circle wallet limit set`

Set a custom spending policy for an agent wallet. Requires a second email OTP to
confirm the change. Mainnet only.

Use `--rule-type` to choose the kind of policy:

* `transfer-limit` (default): cap how much USDC the wallet can transfer per
  transaction or over a rolling time window. Set with `--per-tx`, `--daily`,
  `--weekly`, `--monthly`.
* `recipient-allowlist` / `recipient-blocklist`: allow or block transfers to
  specific recipient addresses. Set with `--targets`.
* `contract-allowlist` / `contract-blocklist`: allow or block contract
  interactions with specific addresses. Set with `--targets`.

**Syntax**

```bash theme={null}
# Transfer limit (default)
circle wallet limit set --address <addr> --chain <chain> \
  --policy-type <type> \
  [--per-tx <amount>] [--daily <amount>] [--weekly <amount>] [--monthly <amount>] \
  [options]

# Allowlist or blocklist
circle wallet limit set --address <addr> --chain <chain> \
  --policy-type <type> \
  --rule-type <recipient-allowlist|recipient-blocklist|contract-allowlist|contract-blocklist> \
  --targets "[0xAddr1,0xAddr2]" \
  [options]
```

**Options**

| Option          | Description                                                                                                                                           |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--address`     | Agent wallet address.                                                                                                                                 |
| `--chain`       | Mainnet blockchain. Testnet blockchains are not supported.                                                                                            |
| `--policy-type` | Policy category: `stablecoin` for transfer-based rules, `contract` for contract-based rules. Auto-set when `--rule-type` is a contract rule.          |
| `--rule-type`   | Rule shape: `transfer-limit` (default), `recipient-allowlist`, `recipient-blocklist`, `contract-allowlist`, or `contract-blocklist`.                  |
| `--per-tx`      | Per-transaction spending cap. Used with `--rule-type transfer-limit`.                                                                                 |
| `--daily`       | Daily rolling-window cap. Used with `--rule-type transfer-limit`.                                                                                     |
| `--weekly`      | Weekly rolling-window cap. Used with `--rule-type transfer-limit`.                                                                                    |
| `--monthly`     | Monthly rolling-window cap. Used with `--rule-type transfer-limit`.                                                                                   |
| `--targets`     | Bracketed comma-separated list of EVM addresses (for example, `"[0xA,0xB]"`). Required for allowlist and blocklist rule types. Validated client-side. |
| `--email`       | Email address for the confirmation OTP. Defaults to the agent session email.                                                                          |

<Note>
  Transfer limits must satisfy: per-transaction ≤ daily ≤ weekly ≤ monthly.
</Note>

**Examples**

```bash theme={null}
# Transfer limits
circle wallet limit set \
  --address 0x... \
  --chain BASE \
  --policy-type stablecoin \
  --per-tx 100 \
  --daily 500 \
  --weekly 2000 \
  --monthly 5000

# Recipient blocklist
circle wallet limit set \
  --address 0x... \
  --chain BASE \
  --policy-type stablecoin \
  --rule-type recipient-blocklist \
  --targets "[0xBAD1,0xBAD2]"
```

***

### `circle wallet limit reset`

Reset all custom spending policies for an agent wallet back to defaults.
Requires a second email OTP to confirm. Mainnet only.

**Syntax**

```bash theme={null}
circle wallet limit reset --address <addr> --chain <chain> [options]
```

**Options**

| Option        | Description                                       |
| :------------ | :------------------------------------------------ |
| `--address`   | Agent wallet address.                             |
| `--chain`     | Mainnet blockchain. Testnet chains not supported. |
| `--yes`, `-y` | Skip the confirmation prompt.                     |

**Example**

```bash theme={null}
circle wallet limit reset --address 0x... --chain BASE --yes
```

***

### `circle wallet limit budget`

Show remaining spending budgets for an agent wallet. Displays per-transaction
limits and rolling-window remaining amounts (daily, weekly, monthly). Budgets
are EVM-wide and not blockchain-specific. Mainnet only.

**Syntax**

```bash theme={null}
circle wallet limit budget --address <addr>
```

**Options**

| Option      | Description           |
| :---------- | :-------------------- |
| `--address` | Agent wallet address. |

**Example**

```bash theme={null}
circle wallet limit budget --address 0x...
```

***

### `circle wallet balance`

Show the token balance for a wallet address on a given blockchain.

**Syntax**

```bash theme={null}
circle wallet balance --address <addr> --chain <chain> [options]
```

**Options**

| Option      | Description                                                                     |
| :---------- | :------------------------------------------------------------------------------ |
| `--address` | Wallet address.                                                                 |
| `--chain`   | Blockchain.                                                                     |
| `--rpc-url` | RPC endpoint override. Required for local wallets without a configured default. |

**Example**

```bash theme={null}
circle wallet balance --address 0x... --chain BASE
```

***

### `circle wallet fund`

Add funds to a wallet by transfer from another wallet (crypto), through a fiat
onramp, or from the testnet faucet.

**Syntax**

```bash theme={null}
circle wallet fund --address <addr> --chain <chain> --amount <usdc> --method <crypto|fiat> [options]
```

**Options**

| Option           | Description                                                                                                                                    |
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `--address`      | Wallet address to fund.                                                                                                                        |
| `--chain`        | Blockchain.                                                                                                                                    |
| `--amount`       | Amount to fund. Ignored on testnet.                                                                                                            |
| `--token`        | Token: `usdc` (default), `eth`, `native`.                                                                                                      |
| `--method`       | Funding method: `crypto` or `fiat`. Required on mainnet. Omit on testnet, where wallets auto-fund from the Circle faucet.                      |
| `--export <dir>` | With `--method crypto`, write a PNG QR code into `<dir>` instead of printing it to the terminal.                                               |
| `--open`         | Open the result in your browser. With `--method fiat`, opens the onramp provider. With `--method crypto`, opens an HTML page with the QR code. |
| `--no-open`      | Print the onramp URL without opening it. Used with `--method fiat` only.                                                                       |

**Examples**

```bash theme={null}
# Fund with crypto from another wallet
circle wallet fund --address 0x... --chain BASE --amount 10 --method crypto

# Fund with fiat through the onramp provider
circle wallet fund --address 0x... --chain BASE --amount 10 --method fiat

# Testnet auto-funded from faucet (omit --method and --amount)
circle wallet fund --address 0x... --chain ARC-TESTNET
```

***

### `circle wallet transfer`

Transfer tokens from a wallet to another address.

**Syntax**

```bash theme={null}
circle wallet transfer <toAddress> --amount <amount> --address <addr> --chain <chain> [options]
```

**Arguments**

| Argument      | Description        |
| :------------ | :----------------- |
| `<toAddress>` | Recipient address. |

**Options**

| Option       | Description                                                                     |
| :----------- | :------------------------------------------------------------------------------ |
| `--amount`   | Amount to transfer.                                                             |
| `--address`  | Source wallet address.                                                          |
| `--chain`    | Blockchain.                                                                     |
| `--token`    | Token contract address. Omit to use USDC.                                       |
| `--rpc-url`  | RPC endpoint override. Required for local wallets without a configured default. |
| `--estimate` | Show estimated fees without submitting the transfer.                            |

**Example**

```bash theme={null}
circle wallet transfer 0xRecipient --amount 5.0 --address 0x... --chain ARC-TESTNET
```

***

### `circle wallet swap`

Swap one token for another. Requires an agent wallet. Arc Testnet is the only
testnet supported.

**Syntax**

```bash theme={null}
circle wallet swap <sellToken> <sellAmount> <buyToken> [<buyAmount>] --address <addr> --chain <chain> [options]
```

**Arguments**

| Argument        | Description                                                            |
| :-------------- | :--------------------------------------------------------------------- |
| `<sellToken>`   | Token to sell. Use a symbol (for example, `EURC`) or contract address. |
| `<sellAmount>`  | Amount to sell.                                                        |
| `<buyToken>`    | Token to buy. Use a symbol (for example, `USDC`) or contract address.  |
| `[<buyAmount>]` | Minimum acceptable output (stop-limit). Omit when using `--quote`.     |

**Options**

| Option              | Description                                                                                     |
| :------------------ | :---------------------------------------------------------------------------------------------- |
| `--address`         | Agent wallet address. Optional when using `--quote`.                                            |
| `--chain`           | Blockchain.                                                                                     |
| `--quote`           | Get a price quote without executing the swap. Does not require wallet ownership or `buyAmount`. |
| `--slippage-bps`    | Maximum slippage in basis points (for example, `50` = 0.5%).                                    |
| `--idempotency-key` | Unique key to prevent duplicate swaps on retry.                                                 |

**Examples**

```bash theme={null}
circle wallet swap EURC 100 USDC 99.5 --address 0x... --chain ARC-TESTNET
circle wallet swap EURC 100 USDC --chain ARC-TESTNET --quote
```

***

### `circle wallet sign message`

Sign a plain text or hex-encoded message with your wallet.

**Syntax**

```bash theme={null}
circle wallet sign message <message> --address <addr> --chain <chain> [options]
```

**Arguments**

| Argument    | Description                          |
| :---------- | :----------------------------------- |
| `<message>` | Message to sign (plain text or hex). |

**Options**

| Option      | Description                                    |
| :---------- | :--------------------------------------------- |
| `--address` | Wallet address.                                |
| `--chain`   | Blockchain.                                    |
| `--hex`     | Message is hex-encoded (must start with `0x`). |

**Example**

```bash theme={null}
circle wallet sign message "hello world" --address 0x... --chain ARC-TESTNET
```

***

### `circle wallet sign typed-data`

Sign EIP-712 typed data with your wallet.

**Syntax**

```bash theme={null}
circle wallet sign typed-data <data> --address <addr> --chain <chain>
```

**Arguments**

| Argument | Description                          |
| :------- | :----------------------------------- |
| `<data>` | EIP-712 typed data as a JSON string. |

**Options**

| Option      | Description     |
| :---------- | :-------------- |
| `--address` | Wallet address. |
| `--chain`   | Blockchain.     |

**Example**

```bash theme={null}
circle wallet sign typed-data '{"types":{...},"primaryType":"Mail","domain":{...},"message":{...}}' \
  --address 0x... \
  --chain ARC-TESTNET
```

***

### `circle wallet execute`

Execute a smart contract write function from a wallet.

**Syntax**

```bash theme={null}
circle wallet execute <abiFunctionSignature> [<abiParameters>...] \
  --contract <addr> \
  --address <addr> \
  --chain <chain> \
  [options]
```

**Arguments**

| Argument                 | Description                                                       |
| :----------------------- | :---------------------------------------------------------------- |
| `<abiFunctionSignature>` | ABI function signature (for example, `approve(address,uint256)`). |
| `[<abiParameters>...]`   | ABI parameters, space-separated.                                  |

**Options**

| Option       | Description                                                                     |
| :----------- | :------------------------------------------------------------------------------ |
| `--contract` | Contract address.                                                               |
| `--address`  | Wallet address.                                                                 |
| `--chain`    | Blockchain.                                                                     |
| `--amount`   | Native token value to send with the call. Defaults to `0`.                      |
| `--rpc-url`  | RPC endpoint override. Required for local wallets without a configured default. |
| `--estimate` | Show estimated fees without submitting the transaction.                         |

**Example**

```bash theme={null}
circle wallet execute "approve(address,uint256)" 0xSpender 1000000 \
  --contract 0xUSDC \
  --address 0x... \
  --chain ARC-TESTNET
```

***

### `circle wallet import`

Import a local wallet from a private key or mnemonic phrase. Stored using the
Open Wallet Standard at `~/.ows/wallets/<name>`.

<Warning>
  Local wallets bypass Circle's compliance and safety controls. Spending
  policies, OFAC screening, and audit logging only apply to agent wallets.
</Warning>

**Syntax**

```bash theme={null}
circle wallet import <name> [--private-key | --mnemonic]
```

**Options**

| Option          | Description                                                              |
| :-------------- | :----------------------------------------------------------------------- |
| `--private-key` | Import from a private key. You'll be prompted to enter the key securely. |
| `--mnemonic`    | Import from a mnemonic phrase. You'll be prompted to enter it securely.  |

<Warning>
  Do not pass your private key or mnemonic as a command-line argument or
  environment variable in plain text. Enter it at the prompt or use a secrets
  manager.
</Warning>

**Example**

```bash theme={null}
circle wallet import my-wallet --private-key
```

***

## Services commands

Discover and pay for [x402](/gateway/nanopayments/concepts/x402)-compatible API
services.

### `circle services search`

Search for available services by keyword. Omit the query to list all services.

**Syntax**

```bash theme={null}
circle services search [<query>] [options]
```

**Arguments**

| Argument    | Description                                                  |
| :---------- | :----------------------------------------------------------- |
| `[<query>]` | Optional search keyword or phrase. Omit to list all results. |

**Options**

| Option       | Description                                                                    |
| :----------- | :----------------------------------------------------------------------------- |
| `--category` | Filter by category (for example, `FINANCIAL_ANALYSIS`, `WEB_SEARCH_RESEARCH`). |
| `--type`     | Filter by service type.                                                        |
| `--limit`    | Maximum number of results to return. Defaults to `50`.                         |
| `--offset`   | Number of results to skip, for pagination. Defaults to `0`.                    |

**Example**

```bash theme={null}
circle services search "weather" --category WEB_SEARCH_RESEARCH --limit 20
```

***

### `circle services inspect`

Inspect the payment requirements for a service URL. The CLI auto-detects the
HTTP method from the service's discovery metadata and auto-generates a minimal
request body from its input schema. Override either with the flags below.

**Syntax**

```bash theme={null}
circle services inspect <url> [options]
```

**Arguments**

| Argument | Description             |
| :------- | :---------------------- |
| `<url>`  | Service URL to inspect. |

**Options**

| Option           | Description                                                              |
| :--------------- | :----------------------------------------------------------------------- |
| `--method`, `-X` | HTTP method override: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`.           |
| `--data`, `-d`   | Request body as a JSON string. Overrides the auto-generated body.        |
| `--header`, `-H` | Custom request header as `Key: Value`. Repeat the flag to send multiple. |

**Example**

```bash theme={null}
circle services inspect https://api.example.com/weather -X POST -d '{"city":"SF"}'
```

***

### `circle services pay`

Pay for a service using your agent wallet.

**Syntax**

```bash theme={null}
circle services pay <url> --address <address> --chain <chain> [options]
```

**Arguments**

| Argument | Description             |
| :------- | :---------------------- |
| `<url>`  | Service URL to pay for. |

**Options**

| Option                | Description                                                              |
| :-------------------- | :----------------------------------------------------------------------- |
| `--address`           | Agent wallet address.                                                    |
| `--chain`             | Blockchain to pay from.                                                  |
| `--max-amount <usdc>` | Refuse to pay more than this amount in USDC (for example, `0.01`).       |
| `--method`, `-X`      | HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. Defaults to `GET`. |
| `--data`, `-d`        | Request body as a JSON string.                                           |
| `--header`, `-H`      | Custom request header as `Key: Value`.                                   |
| `--estimate`          | Show payment requirements without submitting payment.                    |
| `--quiet`, `-q`       | Print response body only (useful for piping).                            |
| `--timeout <seconds>` | Per-step timeout in seconds. Defaults to `30`.                           |

**Example**

```bash theme={null}
circle services pay https://api.example.com/weather --address 0x... --chain BASE
```

<Tip>
  Failed payments write debug logs to `~/.circle-cli/payments/`. Check the most
  recent file for the request, response, and stage where the failure occurred.
</Tip>

***

## Bridge commands

Bridge USDC across blockchains using [CCTP](/cctp).

### `circle bridge transfer`

Bridge USDC from one blockchain to another.

**Syntax**

```bash theme={null}
circle bridge transfer <toChain> [<recipient>] --amount <amount> --address <addr> --chain <from>
```

**Arguments**

| Argument        | Description                                                                 |
| :-------------- | :-------------------------------------------------------------------------- |
| `<toChain>`     | Destination blockchain (for example, `ARB`, `ETH`).                         |
| `[<recipient>]` | Recipient address on the destination. Defaults to the value of `--address`. |

**Options**

| Option              | Description                                         |
| :------------------ | :-------------------------------------------------- |
| `--amount`          | USDC amount the recipient will receive.             |
| `--address`         | Sender wallet address.                              |
| `--chain`           | Source blockchain.                                  |
| `--rpc-url`         | RPC endpoint override for the source blockchain.    |
| `--idempotency-key` | Unique key to prevent duplicate transfers on retry. |
| `--quiet`, `-q`     | Print transaction hash only (useful for piping).    |

**Example**

```bash theme={null}
circle bridge transfer ARB-SEPOLIA --amount 10.0 --address 0x... --chain ARC-TESTNET
```

***

### `circle bridge status`

Check the status of a bridge transfer by transaction hash.

**Syntax**

```bash theme={null}
circle bridge status <txHash> --chain <chain>
```

**Arguments**

| Argument   | Description                               |
| :--------- | :---------------------------------------- |
| `<txHash>` | Transaction hash of the burn transaction. |

**Options**

| Option    | Description        |
| :-------- | :----------------- |
| `--chain` | Source blockchain. |

**Example**

```bash theme={null}
circle bridge status 0xabc... --chain ARC-TESTNET
```

***

### `circle bridge get-fee`

Get the estimated fee for bridging from a given blockchain.

**Syntax**

```bash theme={null}
circle bridge get-fee <to> --chain <from>
```

**Arguments**

| Argument | Description                                         |
| :------- | :-------------------------------------------------- |
| `<to>`   | Destination blockchain (for example, `ARB`, `ETH`). |

**Options**

| Option    | Description        |
| :-------- | :----------------- |
| `--chain` | Source blockchain. |

**Example**

```bash theme={null}
circle bridge get-fee ETH --chain ARC-TESTNET
```

***

## Gateway commands

Interact with [Circle Gateway](/gateway).

### `circle gateway balance`

Show your Gateway balance for nanopayments.

**Syntax**

```bash theme={null}
circle gateway balance --address <addr> --chain <chain> [options]
```

**Options**

| Option      | Description                                                                                                                |
| :---------- | :------------------------------------------------------------------------------------------------------------------------- |
| `--address` | Wallet address.                                                                                                            |
| `--chain`   | Blockchain where the wallet lives. Any [Gateway-supported blockchain](/gateway/references/supported-blockchains) is valid. |
| `--all`     | Show all blockchains including those with zero balances.                                                                   |
| `--rpc-url` | RPC endpoint override. Required for local wallets without a configured default.                                            |

**Examples**

```bash theme={null}
circle gateway balance --address 0x... --chain BASE
circle gateway balance --address 0x... --chain BASE --all
```

***

### `circle gateway deposit`

Deposit USDC into Circle Gateway for nanopayments. Minimum deposit is `0.5`
USDC.

**Syntax**

```bash theme={null}
circle gateway deposit --amount <usdc> --address <addr> --chain <chain> --method <method> [options]
```

**Options**

| Option      | Description                                                                                                                                                                             |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--amount`  | Amount of USDC to deposit.                                                                                                                                                              |
| `--address` | Wallet address.                                                                                                                                                                         |
| `--chain`   | Source blockchain. With `--method direct`, any [Gateway-supported blockchain](/gateway/references/supported-blockchains) is valid. With `--method eco`, only `BASE` and `BASE-SEPOLIA`. |
| `--method`  | Deposit method: `eco` or `direct`. Eco deposits always settle on Polygon (`MATIC` mainnet, `MATIC-AMOY` testnet) regardless of source.                                                  |
| `--timeout` | Transaction poll timeout in seconds. Defaults to `120`.                                                                                                                                 |

<Note>
  Eco is a third-party fast-deposit service that Circle does not operate or
  audit. Review [Eco's
  docs](https://eco.com/docs/getting-started/programmable-addresses/gateway-deposits)
  and test the flow before using it in production.
</Note>

**Example**

```bash theme={null}
circle gateway deposit --amount 5 --address 0x... --chain BASE --method eco
```

***

### `circle gateway withdraw`

Withdraw USDC from Circle Gateway back to a wallet on the same blockchain.

**Syntax**

```bash theme={null}
circle gateway withdraw --amount <usdc> --address <addr> --chain <chain> [options]
```

**Options**

| Option        | Description                                                                                                |
| :------------ | :--------------------------------------------------------------------------------------------------------- |
| `--amount`    | Amount of USDC to withdraw.                                                                                |
| `--address`   | Source wallet address (the Gateway depositor).                                                             |
| `--chain`     | Source blockchain. Any [Gateway-supported blockchain](/gateway/references/supported-blockchains) is valid. |
| `--recipient` | Destination address to receive USDC. Defaults to `--address`.                                              |
| `--timeout`   | Mint transaction poll timeout in seconds. Defaults to `120`. Agent wallets only.                           |

<Note>
  Withdrawals are same-chain only. The withdrawn USDC is minted on `--chain`.
  Agent wallets must be Smart Contract Accounts (SCAs). Pass the SCA address as
  `--address`. JSON output includes `transferId`, `estimatedFee`, and
  `chargedFee`.
</Note>

**Examples**

```bash theme={null}
# Withdraw to your own wallet
circle gateway withdraw --amount 0.1 --address 0x... --chain BASE

# Withdraw to a different recipient
circle gateway withdraw --amount 5 --address 0x... --chain BASE --recipient 0xOTHER
```

***

## Blockchain commands

Query supported blockchain information.

### `circle blockchain list`

List all blockchains supported by Circle CLI.

**Syntax**

```bash theme={null}
circle blockchain list
```

***

### `circle blockchain config`

Show or update the RPC URL for a blockchain.

**Syntax**

```bash theme={null}
circle blockchain config --chain <chain> [options]
```

**Options**

| Option      | Description                                                    |
| :---------- | :------------------------------------------------------------- |
| `--chain`   | Blockchain to configure.                                       |
| `--rpc-url` | Set a custom RPC URL override for this blockchain.             |
| `--default` | Reset to the default RPC URL. Cannot be used with `--rpc-url`. |

**Examples**

```bash theme={null}
circle blockchain config --chain ARC-TESTNET --output json
circle blockchain config --chain ARC-TESTNET --rpc-url https://my-node.example.com
circle blockchain config --chain ARC-TESTNET --default
```

***

## Transaction commands

Manage pending and submitted transactions.

### `circle transaction list`

List transaction history for a wallet.

**Syntax**

```bash theme={null}
circle transaction list --address <addr> --chain <chain> [options]
```

**Options**

| Option           | Description                                                                                                                   |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `--address`      | Wallet address.                                                                                                               |
| `--chain`        | Blockchain.                                                                                                                   |
| `--operation`    | Filter by operation: `transfer` or `execute`.                                                                                 |
| `--state`        | Filter by state: `initiated`, `queued`, `sent`, `confirmed`, `complete`, `failed`, `cancelled`, `denied`, `cleared`, `stuck`. |
| `--tx-type`      | Filter by direction: `inbound` or `outbound`.                                                                                 |
| `--lowest-nonce` | Return only the lowest-nonce pending transaction. Ignores other filters.                                                      |
| `--cursor`       | Pagination token: return transactions after this ID.                                                                          |
| `--limit`        | Maximum number of transactions to return. Defaults to `50`.                                                                   |

**Examples**

```bash theme={null}
circle transaction list --address 0x... --chain ARC-TESTNET
circle transaction list --address 0x... --chain ARC-TESTNET --operation transfer --state confirmed
```

***

### `circle transaction cancel`

Cancel a pending transaction.

**Syntax**

```bash theme={null}
circle transaction cancel <id> --address <addr> --chain <chain>
```

**Arguments**

| Argument | Description     |
| :------- | :-------------- |
| `<id>`   | Transaction ID. |

**Options**

| Option      | Description     |
| :---------- | :-------------- |
| `--address` | Wallet address. |
| `--chain`   | Blockchain.     |

**Example**

```bash theme={null}
circle transaction cancel abc-123 --address 0x... --chain ARC-TESTNET
```

***

### `circle transaction accelerate`

Accelerate a pending transaction by increasing the gas fee.

**Syntax**

```bash theme={null}
circle transaction accelerate <id> --address <addr> --chain <chain>
```

**Arguments**

| Argument | Description     |
| :------- | :-------------- |
| `<id>`   | Transaction ID. |

**Options**

| Option      | Description     |
| :---------- | :-------------- |
| `--address` | Wallet address. |
| `--chain`   | Blockchain.     |

**Example**

```bash theme={null}
circle transaction accelerate abc-123 --address 0x... --chain ARC-TESTNET
```

***

## Contract commands

Interact with onchain contracts.

### `circle contract address`

Show Circle contract addresses, optionally filtered by category and blockchain.

**Syntax**

```bash theme={null}
circle contract address [category] [--chain <chain>]
```

**Arguments**

| Argument     | Description                                                              |
| :----------- | :----------------------------------------------------------------------- |
| `[category]` | Contract category to filter by (for example, `usdc`, `cctp`, `gateway`). |

**Options**

| Option    | Description           |
| :-------- | :-------------------- |
| `--chain` | Filter by blockchain. |

**Examples**

```bash theme={null}
circle contract address usdc --chain ARC-TESTNET
circle contract address cctp --output json
```

***

### `circle contract query`

Execute a read-only contract call.

**Syntax**

```bash theme={null}
circle contract query <abiFunctionSignature> [abiParameters...] --contract <address> --chain <chain>
```

**Arguments**

| Argument                 | Description                                                 |
| :----------------------- | :---------------------------------------------------------- |
| `<abiFunctionSignature>` | ABI function signature (for example, `balanceOf(address)`). |
| `[abiParameters...]`     | ABI parameters, space-separated (for example, `0x1234...`). |

**Options**

| Option       | Description          |
| :----------- | :------------------- |
| `--contract` | Contract address.    |
| `--chain`    | Blockchain to query. |

**Examples**

```bash theme={null}
circle contract query "balanceOf(address)" 0xWALLET --contract 0xUSDC --chain ARC-TESTNET
circle contract query "totalSupply()" --contract 0xUSDC --chain ARC-TESTNET --output json
```

***

## Skill commands

Discover and install skills from the
[`circlefin/skills`](https://github.com/circlefin/skills) catalog.

<Note>
  The `--tool` option specifies your agent framework. Common values:
  `claude-code`, `cursor`, `codex`.
</Note>

### `circle skill list`

List all available skills from the catalog.

**Syntax**

```bash theme={null}
circle skill list [--output json]
```

**Options**

| Option          | Description             |
| :-------------- | :---------------------- |
| `--output json` | Return results as JSON. |

***

### `circle skill info`

Show details and full content for a specific skill.

**Syntax**

```bash theme={null}
circle skill info --name <name>
```

**Options**

| Option   | Description                   |
| :------- | :---------------------------- |
| `--name` | Name of the skill to inspect. |

**Example**

```bash theme={null}
circle skill info --name <skill-name>
```

***

### `circle skill install`

Install a skill into your agent framework.

**Syntax**

```bash theme={null}
circle skill install --tool <tool> [--name <name>]
```

**Options**

| Option   | Description                                                                                 |
| :------- | :------------------------------------------------------------------------------------------ |
| `--tool` | Agent framework to install into. Use multiple `--tool` options for more than one framework. |
| `--name` | Skill name to install. Omit to install all available skills.                                |

**Examples**

```bash theme={null}
circle skill install --tool claude-code --name <skill-name>
circle skill install --tool cursor --tool codex --name <skill-name>
```

***

### `circle skill update`

Update installed skills for an agent framework.

**Syntax**

```bash theme={null}
circle skill update --tool <tool>
```

**Options**

| Option   | Description                           |
| :------- | :------------------------------------ |
| `--tool` | Agent framework to update skills for. |

***

## Terms commands

Inspect, accept, or reset your local Circle CLI Terms of Use acceptance record.

The first time you run any command, Circle CLI prompts you to accept the Terms
of Use and Privacy Policy. Acceptance is stored locally and reused on subsequent
runs. To handle Terms acceptance non-interactively in scripts and AI agents, use
`circle terms accept` or set `CIRCLE_ACCEPT_TERMS=1` in the environment.

### `circle terms`

Show the current acceptance status and the canonical Terms of Use and Privacy
Policy URLs. Default verb is `show`.

**Syntax**

```bash theme={null}
circle terms [show] [options]
```

**Options**

| Option   | Description                                                                                                              |
| :------- | :----------------------------------------------------------------------------------------------------------------------- |
| `--init` | Return Terms info (version, URLs, notice text) for an agent to present before calling `accept`. Implies `--output json`. |

**Examples**

```bash theme={null}
circle terms
circle terms --output json
circle terms show --init --output json
```

**JSON output**

```json theme={null}
{
  "accepted": true,
  "currentVersion": "1.0.0",
  "termsOfUseUrl": "https://www.circle.com/legal/circle-cli-terms-of-use",
  "privacyPolicyUrl": "https://www.circle.com/legal/privacy-policy",
  "acceptance": {
    "version": "1.0.0",
    "acceptedAt": "2026-05-07T12:34:56Z"
  }
}
```

***

### `circle terms accept`

Explicitly accept the Terms of Use and Privacy Policy. Use this in scripts and
AI agent workflows after the user provides explicit consent.

**Syntax**

```bash theme={null}
circle terms accept [--output json]
```

**Example**

```bash theme={null}
circle terms accept --output json
```

***

### `circle terms reset`

Clear the local acceptance record. The next command run prompts you to accept
the Terms again.

**Syntax**

```bash theme={null}
circle terms reset
```

***

## Telemetry commands

Manage CLI telemetry preferences. Telemetry collects privacy-preserving usage
data to help improve Circle CLI.

### `circle telemetry status`

Show the current telemetry preference.

**Syntax**

```bash theme={null}
circle telemetry status [options]
```

**Example**

```bash theme={null}
circle telemetry status
```

***

### `circle telemetry enable`

Enable telemetry for future commands.

**Syntax**

```bash theme={null}
circle telemetry enable
```

***

### `circle telemetry disable`

Disable telemetry for future commands.

**Syntax**

```bash theme={null}
circle telemetry disable
```


# Start building with AI
Source: https://developers.circle.com/ai/chatbot



Collaborate with AI to generate code or learn how to build with Circle. You can
generate code for any of these Circle products: Circle Wallets, Contracts, CCTP,
Gateway. For AI-assisted development in your IDE, you can also use
[Circle's MCP Server](/ai/mcp) or install [AI skills](/ai/skills) for
specialized guidance.

<ChatIframe />


# Use Circle's MCP Server in Your IDE
Source: https://developers.circle.com/ai/mcp



Integrate Circle's MCP server to let your LLM or AI-assisted IDE generate and
fix code for crypto apps using Circle's offerings, including Wallets, Contracts,
CCTP, and Gateway.

<MCPSetupButtons />

<span>CLI commands</span>

<CodeGroup>
  ```shell Claude Code icon="https://mintcdn.com/circle-167b8d39/5X_H2DLmIxVDSWCs/images/claude-logo.png?fit=max&auto=format&n=5X_H2DLmIxVDSWCs&q=85&s=2711bd5dc795308c62570a011248ef2d" theme={null}
  claude mcp add --transport http circle https://api.circle.com/v1/codegen/mcp --scope user
  ```

  ```shell Codex icon="https://mintcdn.com/circle-167b8d39/5X_H2DLmIxVDSWCs/images/open-ai-logo-1.png?fit=max&auto=format&n=5X_H2DLmIxVDSWCs&q=85&s=6a603cbffbbef93cfa078c899e8f19e8" theme={null}
  codex mcp add circle --url https://api.circle.com/v1/codegen/mcp
  ```
</CodeGroup>

## Quick setup

Add Circle's MCP server to your client with the following details:

* **Server Name**: `circle`
* **Server URL**: `https://api.circle.com/v1/codegen/mcp`

## Installation with your IDE

Select your MCP client to view detailed setup instructions:

> **Note:** If you are using a client that is not listed here, you can still use
> the Circle MCP server by manually adding the server URL to your client's
> configuration.

<Tabs>
  <Tab title="Cursor">
    Download and install [Cursor](https://cursor.com) if you haven't already.

    [1-Click Set Up](cursor://anysphere.cursor-deeplink/mcp/install?name=circle\&config=eyJ1cmwiOiJodHRwczovL2FwaS5jaXJjbGUuY29tL3YxL2NvZGVnZW4vbWNwIn0%3D)

    Manual steps:

    1. Open a project in Cursor and navigate to **Cursor Settings**.

    2. In the settings menu, go to the **MCP** section.

    3. Click **New MCP Server**. This will open your `mcp.json` configuration file.

    4. Add the following configuration:

       ```json theme={null}
       {
         "mcpServers": {
           "circle": {
             "url": "https://api.circle.com/v1/codegen/mcp"
           }
         }
       }
       ```

    5. Return to the MCP settings page and enable the server using the toggle switch
       next to `circle`. Start generating code for Circle Wallets, Contracts, CCTP,
       and Gateway.

    For more information on how to use MCP with Cursor, see the
    [Cursor MCP documentation](https://cursor.com/docs/context/mcp).
  </Tab>

  <Tab title="Claude Code">
    Download and install
    [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) if you
    haven't already.

    1. Using the Claude Code command line add the MCP server with the following
       command:

    ```shell theme={null}
    claude mcp add --transport http circle https://api.circle.com/v1/codegen/mcp --scope user
    ```

    2. Verify the server is added by running the following command:

    ```shell theme={null}
    claude mcp get circle
    ```

    3. Start generating code for Circle Wallets, Contracts, CCTP, and Gateway.

    For more information on how to use MCP with Claude Code, see the
    [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp).
  </Tab>

  <Tab title="Windsurf">
    Download and install
    [Windsurf](https://docs.windsurf.com/windsurf/getting-started) if you haven't
    already.

    1. Open the `~/.codeium/windsurf/mcp_config.json` file and add the following:

       ```json theme={null}
       {
         "mcpServers": {
           "circle": {
             "url": "https://api.circle.com/v1/codegen/mcp"
           }
         }
       }
       ```

    2. Enable the Circle MCP server in your MCP settings. Start generating code for
       Circle Wallets, Contracts, CCTP, and Gateway.

    For more information on how to use MCP with Windsurf, see the
    [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp).
  </Tab>

  <Tab title="Kiro">
    Download and install [Kiro](https://kiro.dev) if you haven't already.

    1. Open Kiro and go to **Preferences/Settings** → search for "MCP" → enable MCP
       support.

    2. Create or open the MCP config file:
       * **Workspace-level**: `./.kiro/settings/mcp.json` (recommended for
         project-specific)
       * **User-level**: `~/.kiro/settings/mcp.json`

    3. Add a server configuration entry for Circle:

       ```json theme={null}
       {
         "mcpServers": {
           "circle": {
             "command": "npx",
             "args": ["-y", "@circle/mcp-server"],
             "env": {
               "CIRCLE_BASE_URL": "https://api.circle.com/v1/codegen/mcp"
             },
             "disabled": false
           }
         }
       }
       ```

    4. Save and then restart Kiro (or reload the MCP server list) so the new server
       appears in the MCP tab.

    5. In Kiro's side panel → **MCP Servers** tab → you should see "circle-mcp"
       listed. Start generating code for Circle Wallets, Contracts, CCTP, and
       Gateway.

    Kiro's general MCP setup: [Kiro Docs - MCP](https://kiro.dev/docs/mcp/).
  </Tab>
</Tabs>

```
```


# AI Skills for Building with Circle
Source: https://developers.circle.com/ai/skills



Use Circle's open source AI skills to accelerate development with AI-assisted
IDEs. Skills provide specialized knowledge for building with Circle's products,
including wallets, crosschain transfers, and smart contracts.

Skills are available in the
[circlefin/skills](https://github.com/circlefin/skills) repository.

## Installation

Use the following commands to install Circle Skills with the command-line.

<CodeGroup>
  ```shell Claude Code icon="https://mintcdn.com/circle-167b8d39/5X_H2DLmIxVDSWCs/images/claude-logo.png?fit=max&auto=format&n=5X_H2DLmIxVDSWCs&q=85&s=2711bd5dc795308c62570a011248ef2d" theme={null}
  /plugin marketplace add circlefin/skills
  /plugin install circle-skills@circle
  ```

  ```shell Vercel Skills CLI icon="https://mintcdn.com/circle-167b8d39/kF52uen9TY9sspam/images/vercel_logo.png?fit=max&auto=format&n=kF52uen9TY9sspam&q=85&s=20d2a3e59acc98f14fe41854458cfcd5" theme={null}
  npx skills add circlefin/skills
  ```
</CodeGroup>

## Available skills

The following skills are available to help you build with Circle's products.

### `bridge-stablecoin`

Build apps that bridge USDC between chains using Circle's
[Cross-Chain Transfer Protocol (CCTP)](/cctp). Includes UX patterns, progress
tracking, destination chain linking, and
[Bridge Kit](https://docs.arc.io/app-kit/bridge) SDK implementation patterns for
EVM and Solana chains.

### `use-arc`

Build on Arc, Circle's blockchain where USDC is the native gas token. Covers
chain configuration, [smart contract](/contracts) deployment with Foundry or
Hardhat, frontend integration with viem/wagmi, and bridging USDC to Arc via
[CCTP](/cctp).

### `use-circle-wallets`

Choose the right [Circle wallet](/wallets) type for your application. Compares
[developer-controlled](/wallets/dev-controlled),
[user-controlled](/wallets/user-controlled), and [modular](/wallets/modular)
(passkey) wallets across custody model, key management, account types, and
blockchain support.

### `use-developer-controlled-wallets`

[Developer-controlled wallets](/wallets/dev-controlled) where developers manage
wallet creation, storage, and key management. Use for custodial or operational
flows like payouts, treasury movements, subscriptions, and automation.

### `use-gateway`

Implement [Circle Gateway](/gateway) unified balance for crosschain USDC
transfers. Supports instant transfers (under 500ms) across EVM and Solana chains
with deposit, balance query, and transfer workflows.

### `use-modular-wallets`

Build [modular wallets](/wallets/modular) with passkey authentication, gasless
transactions, and modular architecture. Supports ERC-4337 account abstraction
and ERC-6900 modular framework.

### `use-smart-contract-platform`

Deploy, import, interact with, and monitor smart contracts using
[Circle's Smart Contract Platform](/contracts). Supports bytecode deployment,
template contracts (ERC-20/721/1155), ABI-based read/write calls, and event
monitoring.

### `use-user-controlled-wallets`

Build embedded [user-controlled wallets](/wallets/user-controlled) where users
control their own assets. Supports Web2-like login experiences (Google,
Facebook, Apple, email OTP, PIN) without seed phrases.


# API Reference
Source: https://developers.circle.com/api-reference

Overview of Circle's available APIs and endpoints.

Circle provides a suite of REST APIs for building financial applications on
blockchain infrastructure. Whether you're creating wallets, deploying smart
contracts, moving USDC across blockchains, or building institutional payment
flows, there is an API tailored to your use case.

## Before you begin

Many Circle APIs require an API key to authenticate requests. Permissionless
products like CCTP and Gateway are open and require no API key.

<CardGroup>
  <Card title="API keys" icon="key" href="/api-reference/keys">
    Learn about API keys, client keys, and kit keys, and how to authenticate
    requests to Circle's platform
  </Card>

  <Card title="Idempotent requests" icon="arrows-rotate" href="/api-reference/idempotent-requests">
    Use idempotency keys to safely retry API calls without creating duplicate
    operations
  </Card>
</CardGroup>

## Available APIs

<CardGroup>
  <Card title="Wallets" icon="wallet" href="/api-reference/wallets/common/ping">
    Create and manage developer-controlled and user-controlled wallets, execute
    transactions, and sign messages across EVM, Solana, and other supported
    blockchains
  </Card>

  <Card title="Contracts" icon="file-contract" href="/api-reference/contracts/common/ping">
    Deploy and interact with smart contracts using Circle's managed
    infrastructure, including event monitoring and contract templates
  </Card>

  <Card title="CCTP" icon="bridge" href="/api-reference/cctp/all/get-public-keys-v2">
    Fetch attestations and support native USDC transfers across blockchains
    using Cross-Chain Transfer Protocol
  </Card>

  <Card title="Gateway" icon="dungeon" href="/api-reference/gateway/all/get-token-balances">
    Access and manage a unified USDC balance across multiple blockchains with
    instant transfers in under 500 ms
  </Card>

  <Card title="Circle Mint" icon="building-columns" href="/api-reference/circle-mint/account/list-business-balances">
    Manage USDC and EURC balances, process crypto deposits and payouts, execute
    cross-currency trades, and manage reserves
  </Card>

  <Card title="Circle Payments Network" icon="chart-network" href="/api-reference/cpn/common/ping">
    Route and settle stablecoin payments across Circle's network with support
    for quotes, payments, and transactions
  </Card>

  <Card title="StableFX" icon="swap" href="/api-reference/stablefx/all/create-quote">
    Request quotes and execute institutional FX trades between USDC and EURC
    with onchain settlement on Arc
  </Card>

  <Card title="xReserve" icon="vault" href="/api-reference/xreserve/all/get-balances">
    Deposit USDC into xReserve, retrieve attestations, and manage withdrawals
    for USDC-backed stablecoins
  </Card>
</CardGroup>


# Get an attestation
Source: https://developers.circle.com/api-reference/cctp/all/get-attestation

/openapi/cctp.yaml get /v1/attestations/{messageHash}
Retrieves the signed attestation for a USDC burn event on the source chain.



# Get USDC transfer fees
Source: https://developers.circle.com/api-reference/cctp/all/get-burn-usdc-fees

/openapi/cctp.yaml get /v2/burn/USDC/fees/{sourceDomainId}/{destDomainId}
Retrieves the applicable fees for a USDC transfer between the specified source and destination domains. The fee is returned in basis points (1 = 0.01%).



# Get USDC Fast Transfer allowance
Source: https://developers.circle.com/api-reference/cctp/all/get-fast-burn-usdc-allowance

/openapi/cctp.yaml get /v2/fastBurn/USDC/allowance
Retrieves the available USDC Fast Transfer allowance remaining.



# Get a list of messages
Source: https://developers.circle.com/api-reference/cctp/all/get-messages

/openapi/cctp.yaml get /v1/messages/{sourceDomainId}/{transactionHash}
Retrieves message and attestation details for CCTP V1 messages.



# Get messages and attestations
Source: https://developers.circle.com/api-reference/cctp/all/get-messages-v2

/openapi/cctp.yaml get /v2/messages/{sourceDomainId}
Retrieves messages and attestations for a given transaction hash or nonce. Each message for a given transaction hash is ordered by ascending log index.



# List attestation public keys
Source: https://developers.circle.com/api-reference/cctp/all/get-public-keys

/openapi/cctp.yaml get /v1/publicKeys
Retrieves a list of the currently active public keys for verifying attestation signatures.



# Get public keys
Source: https://developers.circle.com/api-reference/cctp/all/get-public-keys-v2

/openapi/cctp.yaml get /v2/publicKeys
Returns the public keys for validating attestations across all supported versions of CCTP.



# Re-attest a pre-finality message
Source: https://developers.circle.com/api-reference/cctp/all/reattest-message

/openapi/cctp.yaml post /v2/reattest/{nonce}
The re-attestation flow allows the relayer to obtain a higher level of finality than was originally requested on the source chain, while still being forced to pay the fee since allowance was reserved. This flow resolves the case where a sender specifies a finality threshold lower than the destination chain recipient requires.




# Create a CUBIX bank account
Source: https://developers.circle.com/api-reference/circle-mint/account/create-business-cubix-account

/openapi/account.yaml post /v1/businessAccount/banks/cubix



# Create a deposit address
Source: https://developers.circle.com/api-reference/circle-mint/account/create-business-deposit-address

/openapi/account.yaml post /v1/businessAccount/wallets/addresses/deposit
Generates a new blockchain address for a wallet for a given currency/chain pair. Circle may reuse addresses on blockchains that support reuse. For example, if you're requesting two addresses for depositing USD and ETH, both on Ethereum, you may see the same Ethereum address returned. Depositing cryptocurrency to a generated address will credit the associated wallet with the value of the deposit. Note: Circle Mint Singapore customers must verify all transfer recipients using the UI in the Circle Console, as transfers from unverified addresses will be held in `pending` status. 




# Create a payout
Source: https://developers.circle.com/api-reference/circle-mint/account/create-business-payout

/openapi/account.yaml post /v1/businessAccount/payouts
Create a redemption (offramp) payout. This payout converts a digital asset to fiat currency.




# Create a PIX bank account
Source: https://developers.circle.com/api-reference/circle-mint/account/create-business-pix-account

/openapi/account.yaml post /v1/businessAccount/banks/pix



# Create a recipient address
Source: https://developers.circle.com/api-reference/circle-mint/account/create-business-recipient-address

/openapi/account.yaml post /v1/businessAccount/wallets/addresses/recipient
Stores an external blockchain address. Once added, the recipient address must be verified to ensure that you know and trust each new address. 

**For France customers:**

Circle Mint France customers must verify all transfer recipients using the UI in the Circle Console, as transfers from unverified addresses will be held in pending status. Please see Help Center articles below for details:
- [Circle Mint France Travel Rule](https://help.circle.com/s/article/Circle-Mint-France-Travel-Rule)
- [Circle Mint France wallet verification](https://help.circle.com/s/article/Circle-Mint-France-wallet-verification)




# Create a transfer
Source: https://developers.circle.com/api-reference/circle-mint/account/create-business-transfer

/openapi/account.yaml post /v1/businessAccount/transfers
A transfer can be made from an existing business account to a blockchain location.



# Create a wire bank account
Source: https://developers.circle.com/api-reference/circle-mint/account/create-business-wire-account

/openapi/account.yaml post /v1/businessAccount/banks/wires



# Create a mock Wire payment
Source: https://developers.circle.com/api-reference/circle-mint/account/create-mock-wire-payment

/openapi/account.yaml post /v1/mocks/payments/wire
In the sandbox environment, initiate a mock wire payment that mimics the behavior of funds sent through the bank (wire) account linked to master wallet.



# Delete a recipient address
Source: https://developers.circle.com/api-reference/circle-mint/account/delete-business-recipient-address

/openapi/account.yaml delete /v1/businessAccount/wallets/addresses/recipient/{id}
Deletes an external blockchain address. The recipient address must be in an 'active' or 'pending' state in order to be deleted successfully.




# Get associated accounts
Source: https://developers.circle.com/api-reference/circle-mint/account/get-associated-accounts

/openapi/account.yaml get /v1/businessAccount/associatedAccounts
Returns a list of sibling CMAs that are associated with the current account under unified credentials. These accounts can be used as destinations for cross-entity transfers.



# Get a CUBIX bank account
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-cubix-account

/openapi/account.yaml get /v1/businessAccount/banks/cubix/{id}



# Get CUBIX instructions
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-cubix-account-instructions

/openapi/account.yaml get /v1/businessAccount/banks/cubix/{id}/instructions
Get the CUBIX transfer instructions into the Circle bank account given your fiat account id.



# List all deposit addresses
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-deposit-address

/openapi/account.yaml get /v1/businessAccount/wallets/addresses/deposit
Returns a list of deposit addresses for a given wallet.



# Get a deposit by ID
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-deposit-by-id

/openapi/account.yaml get /v1/businessAccount/deposits/{id}
Returns a deposit by ID.



# Get a payout
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-payout

/openapi/account.yaml get /v1/businessAccount/payouts/{id}



# Get a PIX bank account
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-pix-account

/openapi/account.yaml get /v1/businessAccount/banks/pix/{id}



# Get PIX instructions
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-pix-account-instructions

/openapi/account.yaml get /v1/businessAccount/banks/pix/{id}/instructions
Get the PIX transfer instructions into the Circle bank account given your bank account id.



# Get a transfer
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-transfer

/openapi/account.yaml get /v1/businessAccount/transfers/{id}



# Get a wire bank account
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-wire-account

/openapi/account.yaml get /v1/businessAccount/banks/wires/{id}



# Get wire instructions
Source: https://developers.circle.com/api-reference/circle-mint/account/get-business-wire-account-instructions

/openapi/account.yaml get /v1/businessAccount/banks/wires/{id}/instructions
Get the wire transfer instructions into the Circle bank account given your bank account ID.



# Get PIX routing info
Source: https://developers.circle.com/api-reference/circle-mint/account/get-pix-routing-info

/openapi/account.yaml get /v1/businessAccount/banks/pix/{fiatAccountId}/routingInfo
Retrieves available settlement banks and current routing configuration for a PIX fiat account.



# Get report by ID
Source: https://developers.circle.com/api-reference/circle-mint/account/get-report-by-id

/openapi/account.yaml get /v1/reports/{id}
Returns the current metadata for a report, including a fresh pre-signed `downloadUrl` when the report is `ready`.
Use this endpoint to check the status of a `pending` report or to obtain a new download URL after the previous one has expired.




# Download report content
Source: https://developers.circle.com/api-reference/circle-mint/account/get-report-content

/openapi/account.yaml get /v1/reports/{id}/content
Streams the raw report content as a file download, an alternative to following `downloadUrl` from the JSON response.
Returns `409` if the report is not yet `ready`.




# Get wire routing info
Source: https://developers.circle.com/api-reference/circle-mint/account/get-wire-routing-info

/openapi/account.yaml get /v1/businessAccount/banks/wires/{fiatAccountId}/routingInfo
Retrieves available settlement banks and current routing configuration for a wire fiat account.



# List all balances
Source: https://developers.circle.com/api-reference/circle-mint/account/list-business-balances

/openapi/account.yaml get /v1/businessAccount/balances
Retrieves the balance of funds that are available for use.



# List all CUBIX bank accounts.
Source: https://developers.circle.com/api-reference/circle-mint/account/list-business-cubix-accounts

/openapi/account.yaml get /v1/businessAccount/banks/cubix



# List all deposits
Source: https://developers.circle.com/api-reference/circle-mint/account/list-business-deposits

/openapi/account.yaml get /v1/businessAccount/deposits
Searches for deposits sent to your business account. If the date parameters are omitted, returns the most recent deposits. This endpoint returns up to 50 deposits in descending chronological order or pageSize, if provided.



# List all payouts
Source: https://developers.circle.com/api-reference/circle-mint/account/list-business-payouts

/openapi/account.yaml get /v1/businessAccount/payouts
Lists all payouts for your account.

Note that this endpoint does not return the tracking reference number for the payouts in the response. If you need that information you must get each payout individually by ID.




# List all PIX bank accounts.
Source: https://developers.circle.com/api-reference/circle-mint/account/list-business-pix-accounts

/openapi/account.yaml get /v1/businessAccount/banks/pix



# List all recipient addresses
Source: https://developers.circle.com/api-reference/circle-mint/account/list-business-recipient-addresses

/openapi/account.yaml get /v1/businessAccount/wallets/addresses/recipient
Returns a list of recipient addresses that have each been verified and are eligible for transfers. Any recipient addresses pending administrator verification are not included in the response.




# List all transfers
Source: https://developers.circle.com/api-reference/circle-mint/account/list-business-transfers

/openapi/account.yaml get /v1/businessAccount/transfers
Searches for transfers from your business account. If the date parameters are omitted, returns the most recent transfers. This endpoint returns up to 50 transfers in descending chronological order or pageSize, if provided.



# List all wire bank accounts
Source: https://developers.circle.com/api-reference/circle-mint/account/list-business-wire-accounts

/openapi/account.yaml get /v1/businessAccount/banks/wires



# List daily burn fee calculations
Source: https://developers.circle.com/api-reference/circle-mint/account/list-net-burn-fee-daily-calculations

/openapi/account.yaml get /v1/fees/redemption/dailyReports
Returns daily burn fee calculations. This endpoint returns up to 50 daily fee calculations in descending chronological order or `pageSize`, if provided.



# Request a report
Source: https://developers.circle.com/api-reference/circle-mint/account/request-report

/openapi/account.yaml post /v1/reports
Submits a report generation request. `reportType` specifies the type of report and required fields.
If ready, returns `200` with a pre-signed `downloadUrl`. If not, returns `202` with status `pending`. Poll `GET /v1/reports/{id}` for status, or download using `GET /v1/reports/{id}/content` when ready.
Requests are idempotent: the same entity and request parameters always produce the same report ID. Retries return the existing report.




# Update PIX routing preferences
Source: https://developers.circle.com/api-reference/circle-mint/account/update-pix-routing-preferences

/openapi/account.yaml put /v1/businessAccount/banks/pix/{fiatAccountId}/routingPreferences
Creates or updates the settlement bank routing preferences for a PIX fiat account.

At least one of `inboundBankLabel` or `outboundBankLabel` must be provided in the request.

Note: This endpoint will reject updates if the account has active Express routes configured. Accounts with Express routes must update preferences through the Circle Mint UI.




# Update wire routing preferences
Source: https://developers.circle.com/api-reference/circle-mint/account/update-wire-routing-preferences

/openapi/account.yaml put /v1/businessAccount/banks/wires/{fiatAccountId}/routingPreferences
Creates or updates the settlement bank routing preferences for a wire fiat account.

At least one of `inboundBankLabel` or `outboundBankLabel` must be provided in the request.

Note: This endpoint will reject updates if the account has active Express routes configured. Accounts with Express routes must update preferences through the Circle Mint UI.




# Cancel reserved funds
Source: https://developers.circle.com/api-reference/circle-mint/credit/cancel-credit-transfer-reserve

/openapi/credit.yaml put /v1/credit/transfers/{id}/cancelReserve
Cancels a `funds_reserved` transfer and releases the reserved amount back to available credit.

The transfer must be in `funds_reserved` status for this operation.

**Note:** This endpoint is only available for Settlement Advance products.




# Initiate a crypto repayment
Source: https://developers.circle.com/api-reference/circle-mint/credit/create-credit-crypto-repayment

/openapi/credit.yaml post /v1/credit/cryptoRepayment
Initiates a crypto repayment for a credit transfer.

The requested amount is capped at the outstanding balance. If the minimum of the requested amount and outstanding balance is zero, the request will be rejected with HTTP 400.

**Note:** This endpoint is only available for Line of Credit products. Crypto repayment is not supported for Settlement Advance products.




# Create a credit transfer
Source: https://developers.circle.com/api-reference/circle-mint/credit/create-credit-transfer

/openapi/credit.yaml post /v1/credit/transfers
Requests a new credit transfer (drawdown) from the credit line. Disbursement is asynchronous.

**Note:** This endpoint is only available for Line of Credit products. Settlement Advance products must use the reserve funds flow.




# Create a mock wire repayment
Source: https://developers.circle.com/api-reference/circle-mint/credit/create-mock-wire-repayment

/openapi/credit.yaml post /v1/credit/mocks/repayments
In the sandbox environment, initiate a mock wire repayment that simulates an incoming wire payment to repay an outstanding credit transfer. The fiat account will be automatically linked as a repayment account if not already linked.



# Get a credit fee
Source: https://developers.circle.com/api-reference/circle-mint/credit/get-credit-fee

/openapi/credit.yaml get /v1/credit/fees/{id}
Returns detailed information about a specific fee.



# Get credit line details
Source: https://developers.circle.com/api-reference/circle-mint/credit/get-credit-line

/openapi/credit.yaml get /v1/credit
Provides overall credit line details, including status, available limit, and outstanding balance.



# Get a credit repayment
Source: https://developers.circle.com/api-reference/circle-mint/credit/get-credit-repayment

/openapi/credit.yaml get /v1/credit/repayments/{id}
Returns detailed information about a specific repayment.



# Get a credit transfer
Source: https://developers.circle.com/api-reference/circle-mint/credit/get-credit-transfer

/openapi/credit.yaml get /v1/credit/transfers/{id}
Returns detailed information about a specific credit transfer.

Fields `outstanding`, `fees`, `dueDate`, and `disbursedDate` are only present once the transfer reaches `disbursed`, `paid`, or `past_due` status.




# Get repayment account details
Source: https://developers.circle.com/api-reference/circle-mint/credit/get-repayment-account-detail

/openapi/credit.yaml get /v1/credit/repaymentAccounts/{fiatAccountId}
Returns repayment account details and wire instructions for making a credit repayment using the specified fiat account.



# List all credit fees
Source: https://developers.circle.com/api-reference/circle-mint/credit/list-credit-fees

/openapi/credit.yaml get /v1/credit/fees
Returns a paginated list of all historical fees. Filterable by create date range, currency, and status.



# List all credit repayments
Source: https://developers.circle.com/api-reference/circle-mint/credit/list-credit-repayments

/openapi/credit.yaml get /v1/credit/repayments
Returns a paginated list of all repayments (fiat and crypto). Filterable by create date range, transfer ID, type, and status.



# List all credit transfers
Source: https://developers.circle.com/api-reference/circle-mint/credit/list-credit-transfers

/openapi/credit.yaml get /v1/credit/transfers
Returns a paginated list of all credit transfers. Filterable by create date range and status. Transfer items in list responses do not include outstanding and fees properties.



# Request reserved funds
Source: https://developers.circle.com/api-reference/circle-mint/credit/request-credit-transfer-reserved-funds

/openapi/credit.yaml put /v1/credit/transfers/{id}/requestReservedFunds
Transitions a `funds_reserved` transfer to `requested` status by uploading evidence (wire proof). This initiates the manual approval process for Settlement Advance transfers.

The request must include an evidence file (wire proof) as multipart form data. Allowed file types are `application/pdf`, `image/jpeg`, and `image/png`.

**Note:** This endpoint is only available for Settlement Advance products.




# Reserve funds for a credit transfer
Source: https://developers.circle.com/api-reference/circle-mint/credit/reserve-credit-transfer-funds

/openapi/credit.yaml post /v1/credit/transfers/reserveFunds
Reserves funds for a Settlement Advance draw. This is the first mandatory step in the Settlement Advance transfer flow.

Reserved funds expire after 30 minutes if not progressed to `requested` status via the request reserved funds endpoint.

Only one transfer may be in `funds_reserved` status per credit line at a time.

**Note:** This endpoint is only available for Settlement Advance products.




# Create FX account
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/create-fx-account

/openapi/cross-currency.yaml put /v1/exchange/fxConfigs/accounts
Creates a currency trading account



# Create FX trade
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/create-fx-trade

/openapi/cross-currency.yaml post /v1/exchange/trades
Creates a cross-currency trade



# Create a mock PIX payment
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/create-mock-pix-payment

/openapi/cross-currency.yaml post /v1/mocks/payments/pix
Initiates a mock PIX payment in the sandbox environment that mimics the behavior of funds sent through the bank account linked to the main wallet.



# Get daily currency exchange limits
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/get-daily-fx-limits

/openapi/cross-currency.yaml get /v1/exchange/fxConfigs/dailyLimits
Returns daily currency exchange limits and usages.



# Get FX trade
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/get-fx-trade-id

/openapi/cross-currency.yaml get /v1/exchange/trades/{id}
Returns an FX trade by ID.



# Get all FX trades
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/get-fx-trades

/openapi/cross-currency.yaml get /v1/exchange/trades
Returns all cross-currency trades. You can include an optional `settlementId` query parameter to filter the trades to only a specific settlement.



# Get quote
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/get-quote

/openapi/cross-currency.yaml post /v1/exchange/quotes
Fetches an indicative exchange rate between two currencies. Either the from currency or to currency must be USD.
Note: The current market exchange rate will be applied when Circle receives the deposit.




# Get settlement
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/get-settlement-id

/openapi/cross-currency.yaml get /v1/exchange/trades/settlements/{id}
Returns a settlement by ID.



# Get settlement instructions
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/get-settlement-instructions

/openapi/cross-currency.yaml get /v1/exchange/trades/settlements/instructions/{currency}
Returns settlement instructions for a specific currency.



# Get all settlements
Source: https://developers.circle.com/api-reference/circle-mint/cross-currency/get-settlements

/openapi/cross-currency.yaml get /v1/exchange/trades/settlements
Returns all settlements.



# Create a notification subscription
Source: https://developers.circle.com/api-reference/circle-mint/general/create-subscription

/openapi/general.yaml post /v1/notifications/subscriptions
Subscribe to receiving notifications at a given endpoint. The endpoint should be able to handle AWS SNS subscription requests. For more details see https://docs.aws.amazon.com/mobile/sdkforxamarin/developerguide/sns-send-http.html. Note, the sandbox environment allows a maximum of 3 active subscriptions; otherwise, this is limited to 1 active subscription and subsequent create requests will be rejected with a Limit Exceeded error.




# Remove a notification subscription
Source: https://developers.circle.com/api-reference/circle-mint/general/delete-subscription

/openapi/general.yaml delete /v1/notifications/subscriptions/{id}
To remove a subscription, all its subscription requests' statuses must be either 'confirmed', 'deleted' or a combination of those. A subscription with at least one 'pending' subscription request cannot be removed.



# Get configuration info
Source: https://developers.circle.com/api-reference/circle-mint/general/get-account-config

/openapi/general.yaml get /v1/configuration
Retrieves general configuration information.



# List all stablecoins
Source: https://developers.circle.com/api-reference/circle-mint/general/list-stablecoins

/openapi/general.yaml get /v1/stablecoins
Retrieves total circulating supply for supported stablecoins across all chains. This endpoint is rate limited to one call per minute (based on IP).



# List all notification subscriptions
Source: https://developers.circle.com/api-reference/circle-mint/general/list-subscriptions

/openapi/general.yaml get /v1/notifications/subscriptions
Retrieve a list of existing notification subscriptions with details.



# Ping
Source: https://developers.circle.com/api-reference/circle-mint/general/ping

/openapi/general.yaml get /ping
Checks that the service is running.



# Create an external entity
Source: https://developers.circle.com/api-reference/circle-mint/institutional/create-external-entity

/openapi/institutional.yaml post /v1/externalEntities
Creates an external entity for the institutional account.

To access the Core API for Institutions, contact your Circle account representative.




# Get all external entities
Source: https://developers.circle.com/api-reference/circle-mint/institutional/get-all-external-entities

/openapi/institutional.yaml get /v1/externalEntities
Returns all external entities for the institutional account.

To access the Core API for Institutions, contact your Circle account representative.

Note that the `businessUniqueIdentifier` and `identifierIssuingCountryCode` must both be provided, or not at all. Only providing one will result in an error.




# Get an external entity by wallet ID
Source: https://developers.circle.com/api-reference/circle-mint/institutional/get-external-entity-by-wallet-id

/openapi/institutional.yaml get /v1/externalEntities/{walletId}
Returns an external entity by wallet ID.

To access the Core API for Institutions, contact your Circle account representative.




# Create a payment intent
Source: https://developers.circle.com/api-reference/circle-mint/payments/create-payment-intent

/openapi/payments.yaml post /v1/paymentIntents
Create a continuous (default) or transient payment intent. Continuous payment intents are created by default. To create a transient payment intent, the type field must be explicitly set to 'transient'.



# Expire a payment intent
Source: https://developers.circle.com/api-reference/circle-mint/payments/expire-payment-intent

/openapi/payments.yaml post /v1/paymentIntents/{id}/expire



# Get a payment
Source: https://developers.circle.com/api-reference/circle-mint/payments/get-payment

/openapi/payments.yaml get /v1/payments/{id}



# Get a payment intent
Source: https://developers.circle.com/api-reference/circle-mint/payments/get-payment-intent

/openapi/payments.yaml get /v1/paymentIntents/{id}



# List all payment intents
Source: https://developers.circle.com/api-reference/circle-mint/payments/list-payment-intents

/openapi/payments.yaml get /v1/paymentIntents



# List all payments
Source: https://developers.circle.com/api-reference/circle-mint/payments/list-payments

/openapi/payments.yaml get /v1/payments



# Refund a payment intent
Source: https://developers.circle.com/api-reference/circle-mint/payments/refund-payment-intent

/openapi/payments.yaml post /v1/paymentIntents/{id}/refund



# Create a recipient
Source: https://developers.circle.com/api-reference/circle-mint/payouts/create-address-book-recipient

/openapi/payouts.yaml post /v1/addressBook/recipients
Creates an address book recipient. Required fields depend on your Circle entity; use the request body options that match your integration.

Validation failures can return error codes in the `2024`–`2037` range (for example `2024` when `identity` is required but missing, `2025` when `ownership` is required but missing).




# Create a payout
Source: https://developers.circle.com/api-reference/circle-mint/payouts/create-payout

/openapi/payouts.yaml post /v1/payouts

Create a stablecoin payout.

The following table includes the supported pairs of `amount.currency` and `toAmount.currency` for stablecoin address book payouts:

| amount.currency  | toAmount.currency |
| ---------------- | ----------------- |
| USD              | USD               |
| EUR              | EUR               |

Required fields depend on your Circle entity; use the request body options that match your integration.

For Singapore (CIRCLE_SG) entities, `purposeOfTransfer` is **required** and must use a payment reason code from [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). Invalid or missing values can return error code `5020`.




# Delete a recipient
Source: https://developers.circle.com/api-reference/circle-mint/payouts/delete-address-book-recipient

/openapi/payouts.yaml delete /v1/addressBook/recipients/{id}



# Get a recipient
Source: https://developers.circle.com/api-reference/circle-mint/payouts/get-address-book-recipient

/openapi/payouts.yaml get /v1/addressBook/recipients/{id}



# Get a payout
Source: https://developers.circle.com/api-reference/circle-mint/payouts/get-payout

/openapi/payouts.yaml get /v1/payouts/{id}



# List all recipients
Source: https://developers.circle.com/api-reference/circle-mint/payouts/list-address-book-recipients

/openapi/payouts.yaml get /v1/addressBook/recipients



# List VASPs
Source: https://developers.circle.com/api-reference/circle-mint/payouts/list-address-book-vasps

/openapi/payouts.yaml get /v1/addressBook/vasps
Returns active Virtual Asset Service Providers (VASPs) available for the customer's jurisdiction. Use returned `id` values as `vaspId` in `ownership.custody` when creating a recipient and custody is `hosted`.

**Note:** This operation is supported only for Circle Singapore (SG) customers.




# List all payouts
Source: https://developers.circle.com/api-reference/circle-mint/payouts/list-payouts

/openapi/payouts.yaml get /v1/payouts



# Modify a recipient
Source: https://developers.circle.com/api-reference/circle-mint/payouts/modify-address-book-recipient

/openapi/payouts.yaml patch /v1/addressBook/recipients/{id}
Updates address book recipient metadata.



# Create daily custody balance report
Source: https://developers.circle.com/api-reference/circle-mint/reserve-management/report-daily-custody-balances

/openapi/reserve-management.yaml post /v2/reserveManagement/dailyCustodyBalances
Creates a daily custody balance report for USDC and EURC and sends it to Circle.

For `reportType=eea`, this endpoint represents the four reportable cells of EBA Template S 08.00 for one token and one reference date: CASP total token count and EUR value, plus the EU-client subset token count and EUR value.

MiCA / EBA S 08.00 mapping (`reportType=eea`):
- S 08.00 Row 0010 / Col 0010 maps to `additionalFields.totalBalance`
- S 08.00 Row 0010 / Col 0020 maps to `additionalFields.equivalentEuroTotalBalance`
- S 08.00 Row 0020 / Col 0010 maps to `localBalance`
- S 08.00 Row 0020 / Col 0020 maps to `additionalFields.equivalentEuroLocalBalance`

`localBalance` and `totalBalance` are token-unit counts. `equivalentEuroLocalBalance` and `equivalentEuroTotalBalance` are EUR values. EU clients are determined by habitual residence for natural persons and registered office for legal persons. USD/EUR FX conversion should be based on the ECB rate applicable for that date, as available on the ECB website.

Validation rules:
- `localBalance` must be less than or equal to `additionalFields.totalBalance`
- `equivalentEuroLocalBalance` must be less than or equal to `equivalentEuroTotalBalance`
- Only one submission per day per currency
- USDC and EURC require separate submissions




# Create a notification subscription
Source: https://developers.circle.com/api-reference/contracts/common/create-subscription

/openapi/configurations_2.yaml post /v2/notifications/subscriptions
Create a notification subscription by configuring an endpoint to receive notifications. For details, see the [Notification Flows](https://developers.circle.com/wallets/webhook-notification-flows) guide.




# Delete a notification subscription
Source: https://developers.circle.com/api-reference/contracts/common/delete-subscription

/openapi/configurations_2.yaml delete /v2/notifications/subscriptions/{id}
Delete an existing subscription.



# Get a notification signature public key
Source: https://developers.circle.com/api-reference/contracts/common/get-notification-signature

/openapi/configurations_2.yaml get /v2/notifications/publicKey/{id}
Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

In the headers of each webhook, you can find
  1. `X-Circle-Signature`: a header containing the digital signature generated by Circle.
  2. `X-Circle-Key-Id`: a header containing the UUID. This is will be used as the `ID` as URL parameter to retrieve the relevant public key.




# Retrieve a notification subscription
Source: https://developers.circle.com/api-reference/contracts/common/get-subscription

/openapi/configurations_2.yaml get /v2/notifications/subscriptions/{id}
Retrieve an existing notification subscription.



# Get all notification subscriptions
Source: https://developers.circle.com/api-reference/contracts/common/get-subscriptions

/openapi/configurations_2.yaml get /v2/notifications/subscriptions
Retrieve an array of existing notification subscriptions.



# Ping
Source: https://developers.circle.com/api-reference/contracts/common/ping

/openapi/configurations_2.yaml get /ping
Checks that the service is running.



# Update a notification subscription
Source: https://developers.circle.com/api-reference/contracts/common/update-subscription

/openapi/configurations_2.yaml patch /v2/notifications/subscriptions/{id}
Update subscription endpoint to receive notifications.




# Create Event Monitor
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/create-event-monitor

/openapi/smart-contract-platform.yaml post /v1/w3s/contracts/monitors
Create a new event monitor based on the provided blockchain, contract address, and event signature.



# Delete Event Monitor
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/delete-event-monitor

/openapi/smart-contract-platform.yaml delete /v1/w3s/contracts/monitors/{id}
Delete an existing event monitor given its ID.



# Deploy a contract
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/deploy-contract

/openapi/smart-contract-platform.yaml post /v1/w3s/contracts/deploy
Deploy a smart contract on a specified blockchain using the contract's ABI and bytecode. The deployment will originate from one of your Circle Wallets.



# Deploy a contract from a template
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/deploy-contract-template

/openapi/smart-contract-platform.yaml post /v1/w3s/templates/{id}/deploy
Deploy a smart contract using a template.



# Estimate a contract deployment
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/estimate-contract-deploy

/openapi/smart-contract-platform.yaml post /v1/w3s/contracts/deploy/estimateFee
Estimate the network fee for deploying a smart contract on a specified blockchain, given the contract bytecode.



# Estimate fee for a contract template deployment
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/estimate-contract-template-deploy

/openapi/smart-contract-platform.yaml post /v1/w3s/templates/{id}/deploy/estimateFee
Estimate the fee required to deploy contract by template.



# Get a contract
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/get-contract

/openapi/smart-contract-platform.yaml get /v1/w3s/contracts/{id}
Get a single contract that you've imported or deployed. Retrieved using the contracts ID as opposed to the on-chain address.



# Get Event Monitors
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/get-event-monitors

/openapi/smart-contract-platform.yaml get /v1/w3s/contracts/monitors
Fetch a list of event monitors, optionally filtered by blockchain, contract address, and event signature.



# Import a contract
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/import-contract

/openapi/smart-contract-platform.yaml post /v1/w3s/contracts/import
Add an existing smart contract to your library of contracts. It also can be done in the Developer Services Console.



# List contracts
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/list-contracts

/openapi/smart-contract-platform.yaml get /v1/w3s/contracts
Fetch a list of contracts that you've imported and/or deployed.



# Get Event Logs
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/list-event-logs

/openapi/smart-contract-platform.yaml get /v1/w3s/contracts/events
Fetch all event logs, optionally filtered by blockchain and contract address.



# Execute a query function on a contract
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/query-contract

/openapi/smart-contract-platform.yaml post /v1/w3s/contracts/query
Query the state of a contract by providing the address and blockchain.



# Update a contract
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/update-contract

/openapi/smart-contract-platform.yaml patch /v1/w3s/contracts/{id}
Update the off-chain properties, such as description, of a contract that you've imported or deployed. Updated using the contracts ID as opposed to the on-chain address.



# Update an Event Monitor
Source: https://developers.circle.com/api-reference/contracts/smart-contract-platform/update-event-monitor

/openapi/smart-contract-platform.yaml put /v1/w3s/contracts/monitors/{id}
Update an existing event monitor given its ID.



# Create a webhook subscription
Source: https://developers.circle.com/api-reference/cpn/common/create-subscription

/openapi/configurations.yaml post /v2/cpn/notifications/subscriptions
Create a webhook subscription by configuring an endpoint to receive notifications.




# Delete a notification subscription
Source: https://developers.circle.com/api-reference/cpn/common/delete-subscription

/openapi/configurations.yaml delete /v2/cpn/notifications/subscriptions/{id}
Delete an existing subscription.



# Get a notification signature public key
Source: https://developers.circle.com/api-reference/cpn/common/get-notification-signature

/openapi/configurations.yaml get /v2/cpn/notifications/publicKey/{id}
Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

In the headers of each webhook, you can find

  - `X-Circle-Signature`: a header containing the digital signature generated by Circle.

  - `X-Circle-Key-Id`: a header containing the UUID. This is will be used as the `ID` as URL parameter to retrieve the relevant public key.




# Get a notification subscription
Source: https://developers.circle.com/api-reference/cpn/common/get-subscription

/openapi/configurations.yaml get /v2/cpn/notifications/subscriptions/{id}
Returns an existing notification subscription.



# Get all webhook subscriptions
Source: https://developers.circle.com/api-reference/cpn/common/get-subscriptions

/openapi/configurations.yaml get /v2/cpn/notifications/subscriptions
Returns an array of existing webhook subscriptions.



# Ping
Source: https://developers.circle.com/api-reference/cpn/common/ping

/openapi/configurations.yaml get /ping
Checks that the service is running.



# Update a notification subscription
Source: https://developers.circle.com/api-reference/cpn/common/update-subscription

/openapi/configurations.yaml patch /v2/cpn/notifications/subscriptions/{id}
Update subscription endpoint to receive notifications.




# Accelerate a stuck transaction
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/accelerate-transaction

/openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/transactions/accelerate
- Accelerate a transaction based on the payment ID. It should be used when a transaction associated with the payment is broadcasted but not confirmed for a long period of time (i.e 10 minutes). This is usually due to gas fees being too low and not picked up by any miner/validator.

- The /accelerate endpoint essentially creates another transaction with the same params as the broadcasted transaction. If multiple broadcasted transactions exist, it will use the newest created one. Afterwards, OFI can sign with a higher gas fee and submit via /submit endpoint to accelerate blockchain confirmation.

- Requirements for using this endpoint:

  - No COMPLETED transaction exist for the payment (otherwise onchain transaction has completed)

  - No CREATED transaction exist for the payment, otherwise OFI should sign that transaction and submit

  - No PENDING transaction exist for the payment, otherwise OFI should wait for transaction to be broadcasted

- In another word, all existing transaction for the payment should either be FAILED (which is no longer effective) or BROADCASTED (which means they are stuck onchain and not confirmed)




# Create a payment
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-payment

/openapi/cpn-ofi.yaml post /v1/cpn/payments
Creates a payment by using the quote created previously and submitting recipient information (travel rule). The payment will remain valid if the onchain settlement occurs before settlementExpireDate.



# Create a quote
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-quotes

/openapi/cpn-ofi.yaml post /v1/cpn/quotes
Creates one or more quotes for the given source/destination parameters. Returns quotes sorted in the following order:

  - Ascending of `sourceAmount` if your quote is based on `destinationAmount`.

  - Descending of `destinationAmount` if your quote is based on `sourceAmount`.




# Create a support ticket
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-support-ticket

/openapi/cpn-ofi.yaml post /v1/cpn/supportTickets
Create transaction-related issues (for example, settlement delays, missing information, or refunds). These tickets are stored centrally in the CPN platform and routed to the appropriate party for resolution.




# Create a transaction
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-transaction

/openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/transactions
Creates an unsigned onchain transaction for a specific payment.



# Create a transaction (V2)
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/create-transaction-v2

/openapi/cpn-ofi.yaml post /v2/cpn/payments/{paymentId}/transactions
Create a V2 transaction for signing



# Get a payment
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-payment

/openapi/cpn-ofi.yaml get /v1/cpn/payments/{paymentId}
Returns the PII fields needed to collect to make this payment (i.e. travel rule and beneficiary account data)



# Get payment configurations
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-payment-configurations-overview

/openapi/cpn-ofi.yaml get /v1/cpn/configurations/overview
Returns the overview of supported countries, currencies, payment methods, blockchains.



# Get payment requirements for a quote
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-payment-requirements

/openapi/cpn-ofi.yaml get /v1/cpn/payments/requirements
Retrieves the PII fields needed to collect to make this payment (travel rule and beneficiary account data).



# Get details of a quote
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-quote

/openapi/cpn-ofi.yaml get /v1/cpn/quotes/{quoteId}
Retrieve details of a specific quote (e.g., re-check expiration, fees).



# Get refund details
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-refund

/openapi/cpn-ofi.yaml get /v1/cpn/payments/{paymentId}/refunds/{refundId}
Retrieves the full refund object associated with a specific payment. This can be used by OFIs to reconcile refund status and verify refund completion.



# Get details for an RFI
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-rfi

/openapi/cpn-ofi.yaml get /v1/cpn/payments/{paymentId}/rfis/{rfiId}
Retrieve details of a specific RFI for a payment. If the BFI initiates an RFI after the payment is created, the OFI will be notified via webhook. This webhook will detail what specific information the OFI needs to send. 

After receiving the webhook. The OFI is expected to encrypt the requested data and send it to the BFI using CPN's RFI submit endpoint. Failure to respond to an RFI will result in a failed payment. The OFI will receive webhooks with the decision based on the submitted information.




# Get a transaction
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-transaction

/openapi/cpn-ofi.yaml get /v1/cpn/payments/{paymentId}/transactions/{transactionId}
Retrieves a specific transaction by its ID for a given payment



# Get a transaction by ID (V2)
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/get-transaction-v2

/openapi/cpn-ofi.yaml get /v2/cpn/payments/{paymentId}/transactions/{transactionId}
Get a transaction by ID



# List payments
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/list-payments

/openapi/cpn-ofi.yaml get /v1/cpn/payments
Returns a list of all payments that fit the specified parameters.



# Get supported payment routes
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/list-routes

/openapi/cpn-ofi.yaml get /v1/cpn/configurations/routes
Returns a list of route details including trade limits. This information can determine
what corridors and parameters are valid for subsequent quote creation.




# Submit RFI data
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/submit-rfi

/openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/rfis/{rfiId}/submit
Submit encrypted RFI data to complete an RFI request from the BFI.



# Submit a signed transaction for broadcast
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/submit-transaction

/openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/transactions/{transactionId}/submit
Return the signed hex string of the transaction, Circle will validate the content and broadcast to the chain.



# Submit a signed transaction for broadcast (V2)
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/submit-transaction-v2

/openapi/cpn-ofi.yaml post /v2/cpn/payments/{paymentId}/transactions/{transactionId}/submit
Submit a signed V2 transaction for broadcast



# Upload RFI file
Source: https://developers.circle.com/api-reference/cpn/cpn-platform/upload-rfi-file

/openapi/cpn-ofi.yaml post /v1/cpn/payments/{paymentId}/rfis/{rfiId}/files
Upload encrypted RFI file.



# Create an account
Source: https://developers.circle.com/api-reference/cpn/managed-payments/accounts/create-account

/openapi/accounts.yaml post /v1/accounts
Creates a new account. This account can be used to create accounts for Mint, or
intermediary accounts for a Managed Payments customer. For Managed Payments, the
account created represents a business entity that will settle stablecoin payments
via the customer.

Routing for this endpoint is body based. Requests that include the `businessPii`
field are routed to the Managed Payments intermediary account creation flow, while
requests that omit the `businessPii` field are routed to the standard account creation
flow.

For the standard account creation flow, If `clientEntityId` is not provided, the
account type will be `customer`. If `clientEntityId` is provided, the account type
will be `client`.




# Get an account
Source: https://developers.circle.com/api-reference/cpn/managed-payments/accounts/get-account

/openapi/accounts.yaml get /v1/accounts/{accountId}
Retrieves a single account by `accountId`.



# List all accounts
Source: https://developers.circle.com/api-reference/cpn/managed-payments/accounts/list-accounts

/openapi/accounts.yaml get /v1/accounts
Retrieves the accounts available to the calling entity.



# Create a recipient
Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/create-address-book-recipient

/openapi/payouts.yaml post /v1/addressBook/recipients
Creates an address book recipient. Required fields depend on your Circle entity; use the request body options that match your integration.

Validation failures can return error codes in the `2024`–`2037` range (for example `2024` when `identity` is required but missing, `2025` when `ownership` is required but missing).




# Delete a recipient
Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/delete-address-book-recipient

/openapi/payouts.yaml delete /v1/addressBook/recipients/{id}



# Get a recipient
Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/get-address-book-recipient

/openapi/payouts.yaml get /v1/addressBook/recipients/{id}



# List all recipients
Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/list-address-book-recipients

/openapi/payouts.yaml get /v1/addressBook/recipients



# Modify a recipient
Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/modify-address-book-recipient

/openapi/payouts.yaml patch /v1/addressBook/recipients/{id}
Updates address book recipient metadata.



# Borrow against line of credit
Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/create-managed-payments-credit-transfer

/openapi/managed-payments.yaml post /v1/managedPayments/credit/lines/{lineId}/transfers
Initiates a transfer (borrowing) against the line of credit.



# Get credit line details
Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-line

/openapi/managed-payments.yaml get /v1/managedPayments/credit/lines
Retrieves the details of the Managed Payments credit line.



# Get a credit transfer
Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-transfer

/openapi/managed-payments.yaml get /v1/managedPayments/credit/lines/{lineId}/transfers/{transferId}
Returns detailed information about a specific credit transfer.

Fields `outstanding`, `dueDate`, and `disbursedDate` are present when the transfer status is `disbursed`, `paid`, or `past_due`. Field `paidDate` is present only when status is `paid`.




# Get repayment wire instructions
Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-wire-instructions

/openapi/managed-payments.yaml get /v1/managedPayments/credit/lines/{lineId}/wireInstructions
Fetches the necessary wire transfer instructions for repaying funds borrowed against the line of credit.



# List credit transfers
Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/list-managed-payments-credit-transfers

/openapi/managed-payments.yaml get /v1/managedPayments/credit/lines/{lineId}/transfers
Returns a list of credit transfers for the specified credit line. Filterable by status and date range.



# Get an account bank deposit
Source: https://developers.circle.com/api-reference/cpn/managed-payments/deposits/get-account-deposit

/openapi/accounts.yaml get /v1/accounts/deposits/{id}
Returns a bank deposit by ID.



# List all account bank deposits
Source: https://developers.circle.com/api-reference/cpn/managed-payments/deposits/list-account-deposits

/openapi/accounts.yaml get /v1/accounts/deposits
Searches for bank deposits sent to accounts. If the date parameters are omitted, returns the most recent deposits. This endpoint returns up to 50 deposits in descending chronological order or pageSize, if provided.




# Create a payment intent
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/create-payment-intent

/openapi/payments.yaml post /v1/paymentIntents
Create a continuous (default) or transient payment intent. Continuous payment intents are created by default. To create a transient payment intent, the type field must be explicitly set to 'transient'.



# Expire a payment intent
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/expire-payment-intent

/openapi/payments.yaml post /v1/paymentIntents/{id}/expire



# Get a payment intent
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/get-payment-intent

/openapi/payments.yaml get /v1/paymentIntents/{id}



# List all payment intents
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/list-payment-intents

/openapi/payments.yaml get /v1/paymentIntents



# Refund a payment intent
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/refund-payment-intent

/openapi/payments.yaml post /v1/paymentIntents/{id}/refund



# Get a payment
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payments/get-payment

/openapi/payments.yaml get /v1/payments/{id}



# List all payments
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payments/list-payments

/openapi/payments.yaml get /v1/payments



# Create a payout
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payouts/create-payout

/openapi/payouts.yaml post /v1/payouts

Create a stablecoin payout.

The following table includes the supported pairs of `amount.currency` and `toAmount.currency` for stablecoin address book payouts:

| amount.currency  | toAmount.currency |
| ---------------- | ----------------- |
| USD              | USD               |
| EUR              | EUR               |

Required fields depend on your Circle entity; use the request body options that match your integration.

For Singapore (CIRCLE_SG) entities, `purposeOfTransfer` is **required** and must use a payment reason code from [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). Invalid or missing values can return error code `5020`.




# Get a payout
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payouts/get-payout

/openapi/payouts.yaml get /v1/payouts/{id}



# List all payouts
Source: https://developers.circle.com/api-reference/cpn/managed-payments/payouts/list-payouts

/openapi/payouts.yaml get /v1/payouts



# Create a wire bank account
Source: https://developers.circle.com/api-reference/cpn/managed-payments/wires/create-account-wire-account

/openapi/accounts.yaml post /v1/banks/wires
Create a bank account for wire transfers.



# Get a wire bank account
Source: https://developers.circle.com/api-reference/cpn/managed-payments/wires/get-account-wire-account

/openapi/accounts.yaml get /v1/banks/wires/{id}
Retrieves a specific wire bank account.



# Get wire instructions
Source: https://developers.circle.com/api-reference/cpn/managed-payments/wires/get-account-wire-account-instructions

/openapi/accounts.yaml get /v1/banks/wires/{id}/instructions
Retrieves wire transfer instructions for a specific bank account.



# List all wire bank accounts
Source: https://developers.circle.com/api-reference/cpn/managed-payments/wires/list-account-wire-accounts

/openapi/accounts.yaml get /v1/banks/wires
Retrieves a list of bank accounts for wire transfers.



# Create an account bank withdrawal
Source: https://developers.circle.com/api-reference/cpn/managed-payments/withdrawals/create-account-withdrawal

/openapi/accounts.yaml post /v1/accounts/withdrawals
Create a bank withdrawal from an account. This converts a digital asset to fiat currency and sends it to the specified destination bank account.




# Get an account bank withdrawal
Source: https://developers.circle.com/api-reference/cpn/managed-payments/withdrawals/get-account-withdrawal

/openapi/accounts.yaml get /v1/accounts/withdrawals/{id}
Retrieves a specific bank withdrawal.



# List all account bank withdrawals
Source: https://developers.circle.com/api-reference/cpn/managed-payments/withdrawals/list-account-withdrawals

/openapi/accounts.yaml get /v1/accounts/withdrawals
Lists all bank withdrawals for accounts.



# Create a webhook subscription
Source: https://developers.circle.com/api-reference/gateway/all/create-permissionless-subscription

/openapi/gateway.yaml post /v2/notifications/subscriptions/permissionless
Create a permissionless webhook subscription by configuring an endpoint to receive event notifications. Specify the environment, wallet addresses to monitor, blockchain domains to watch, and event types to receive.




# Create a transfer attestation for transferring tokens
Source: https://developers.circle.com/api-reference/gateway/all/create-transfer-attestation

/openapi/gateway.yaml post /v1/transfer
Generates a transfer attestation and operator signature for transferring tokens between domains



# Delete a webhook subscription
Source: https://developers.circle.com/api-reference/gateway/all/delete-permissionless-subscription

/openapi/gateway.yaml delete /v2/notifications/subscriptions/permissionless/{id}
Delete an existing permissionless webhook subscription.



# Estimate fees and expiration block heights for a transfer
Source: https://developers.circle.com/api-reference/gateway/all/estimate-transfer

/openapi/gateway.yaml post /v1/estimate
Calculates the required fees and expiration block heights for a transfer without requiring signatures or executing the transaction.



# Get pending deposits for specified addresses
Source: https://developers.circle.com/api-reference/gateway/all/get-deposits

/openapi/gateway.yaml post /v1/deposits
Returns pending deposits for each specified depositor address across different domains where that address is valid.



# Get Gateway info for supported domains and tokens
Source: https://developers.circle.com/api-reference/gateway/all/get-gateway-info

/openapi/gateway.yaml get /v1/info
Provides information about the API and details of the supported domains and tokens.



# Get a notification signature public key
Source: https://developers.circle.com/api-reference/gateway/all/get-permissionless-notification-signature

/openapi/gateway.yaml get /v2/notifications/publicKey/{id}
Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

In the headers of each webhook, you can find
  1. `X-Circle-Signature`: a header containing the digital signature generated by Circle.
  2. `X-Circle-Key-Id`: a header containing the UUID. This value is used as the `ID` URL parameter to retrieve the relevant public key.




# Retrieve a webhook subscription
Source: https://developers.circle.com/api-reference/gateway/all/get-permissionless-subscription

/openapi/gateway.yaml get /v2/notifications/subscriptions/permissionless/{id}
Retrieve an existing permissionless webhook subscription.



# Get all webhook subscriptions
Source: https://developers.circle.com/api-reference/gateway/all/get-permissionless-subscriptions

/openapi/gateway.yaml get /v2/notifications/subscriptions/permissionless
Retrieve an array of existing permissionless webhook subscriptions.



# Get supported x402 payment kinds
Source: https://developers.circle.com/api-reference/gateway/all/get-supported-x402payment-kinds

/openapi/gateway.yaml get /v1/x402/supported
Returns the payment kinds supported by Circle Gateway for x402 batching.

Each kind includes the GatewayWallet contract address in
`extra.verifyingContract` which clients use for EIP-712 signing, and an
`extra.assets` array containing the supported tokens with their addresses,
symbols, and decimals.




# Get token balances for specified addresses
Source: https://developers.circle.com/api-reference/gateway/all/get-token-balances

/openapi/gateway.yaml post /v1/balances
Returns the current available balance of each specified address across different domains where that address is valid



# Get a transfer by ID
Source: https://developers.circle.com/api-reference/gateway/all/get-transfer-by-id

/openapi/gateway.yaml get /v1/transfer/{id}
Returns detailed information about a transfer.



# Get full TransferSpec by transferSpecHash
Source: https://developers.circle.com/api-reference/gateway/all/get-transfer-spec

/openapi/gateway.yaml get /v1/transferSpec/{transferSpecHash}
Retrieve the full TransferSpec for a given transferSpecHash.



# Get an x402 transfer by ID
Source: https://developers.circle.com/api-reference/gateway/all/get-x402transfer-by-id

/openapi/gateway.yaml get /v1/x402/transfers/{id}
Retrieves a single x402 transfer by its unique identifier.



# Search x402 transfers
Source: https://developers.circle.com/api-reference/gateway/all/search-x402transfers

/openapi/gateway.yaml get /v1/x402/transfers
Returns a paginated list of x402 transfers matching the given filters.
Supports cursor-based pagination via pageAfter / pageBefore.




# Send a test notification
Source: https://developers.circle.com/api-reference/gateway/all/send-permissionless-subscription-test-notification

/openapi/gateway.yaml post /v2/notifications/subscriptions/permissionless/{id}/test
Send a test notification to the subscriber endpoint. The notification has notificationType "webhooks.test".




# Settle an x402 payment
Source: https://developers.circle.com/api-reference/gateway/all/settle-x402payment

/openapi/gateway.yaml post /v1/x402/settle
Settles an x402 payment by submitting the EIP-3009 authorization.
The authorization will be verified, the sender's balance locked, and
the transaction queued for batch processing.




# Submit an EIP-3009 authorization to be batched
Source: https://developers.circle.com/api-reference/gateway/all/submit-batch-authorization

/openapi/gateway.yaml post /v1/batch/submit
Submit a single-chain transfer authorization using EIP-3009 signature.
The authorization will be verified, the sender's balance locked, and
the transaction queued for batch processing.




# Test subscription connection
Source: https://developers.circle.com/api-reference/gateway/all/test-permissionless-subscription-connection

/openapi/gateway.yaml post /v2/notifications/subscriptions/permissionless/{id}/testConnection
Verify that the subscriber endpoint for the given subscription is reachable.



# Update a webhook subscription
Source: https://developers.circle.com/api-reference/gateway/all/update-permissionless-subscription

/openapi/gateway.yaml patch /v2/notifications/subscriptions/permissionless/{id}
Update a webhook subscription. Metadata fields can be updated independently. To update filters, provide `notificationTypes`, `addresses`, and `domains` together; those fields fully replace the existing filters.




# Verify an x402 payment payload
Source: https://developers.circle.com/api-reference/gateway/all/verify-x402payment

/openapi/gateway.yaml post /v1/x402/verify
Verifies that an x402 payment payload can be processed by running
all read-only validation checks (scheme, network, token, signature,
temporal constraints, address/amount matching). A valid result does
not guarantee settlement — balance and nonce checks only happen at
settle time.




# Idempotent Requests
Source: https://developers.circle.com/api-reference/idempotent-requests

Idempotency keys let you safely retry Circle API calls.

Circle APIs support
[idempotent requests](https://en.wikipedia.org/wiki/Idempotence), so making the
same request multiple times produces the same result. This lets you safely retry
API calls if something goes wrong.

## Idempotency keys

Certain endpoints require you to generate an idempotency key to identify the
request. For endpoints that require an idempotency key, each request must have a
unique key.

The server uses this key to identify a specific request. When a request is made
with the same idempotency key, the server returns the original response instead
of executing the operation again.

For endpoints that require it, the idempotency key must be in
[UUID version 4](https://en.wikipedia.org/wiki/Universally_unique_identifier)
format.

The following example demonstrates how to generate an idempotency key in
Node.js:

```typescript theme={null}
import crypto from "crypto";

function generateIdempotencyKey(): string {
  return crypto.randomUUID();
}

const idempotencyKey: string = generateIdempotencyKey();
console.log(idempotencyKey); // e.g. "f47ac10b-58cc-4372-a567-0e02b2c3d479"
```


# API Keys
Source: https://developers.circle.com/api-reference/keys

Learn about the different types of API keys used to authenticate requests to Circle's platform.

Certain products use API keys to authenticate requests. Circle provides three
types of keys for different use cases: [API keys](#api-keys) for server-side
access, [client keys](#client-keys) for frontend applications, and
[kit keys](#kit-keys) for SDK integrations.

<Note>
  Permissionless products like CCTP and Gateway do not require an API key.
</Note>

<CardGroup>
  <Card title="API key" icon="server">
    Authenticate server-side requests to Circle's RESTful APIs.
  </Card>

  <Card title="Client key" icon="browser">
    Authenticate client applications with domain or app binding. Required for
    frontend SDKs.
  </Card>

  <Card title="Kit key" icon="cube">
    Authenticate kit access with a single key that works on both testnet and
    mainnet.
  </Card>
</CardGroup>

## API keys

An API key is a unique string used to authenticate and enable access to
privileged operations on Circle's APIs. It's required for any RESTful API
requests to Circle services. Without it, requests will fail.

### Keep your API keys safe

API keys allow access to sensitive operations, so you must secure them.

* **Avoid public exposure**: Never share API keys or include them in client-side
  code, public repositories, or other public mediums.
* **Manage securely**: Use the Circle Console to generate and manage API keys.
  When generating a key, copy it exactly as displayed.

<Warning>Losing control of your API key can result in financial loss.</Warning>

### API key authentication

Use the headers below to authenticate requests on testnet or mainnet.

#### Testnet authorization header example

```text theme={null}
authorization: Bearer TEST_API_KEY:ebb3ad72232624921abc4b162148bb84:019ef3358ef9cd6d08fc32csfe89a68d
```

#### Mainnet authorization header example

```text theme={null}
authorization: Bearer LIVE_API_KEY:ebb3ad72232624921abc4b162148bb84:019ef3358ef9cd6d08fc32csfe89a68d
```

### Test authentication

To verify your API key setup, use the following `curl` command to retrieve
wallets:

```bash theme={null}
curl --request GET \
     --url https://api.circle.com/v1/w3s/wallets \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>'
```

A successful response looks like this:

```json theme={null}
{
  "data": {
    "wallets": []
  }
}
```

An error response looks like this:

```json theme={null}
{
  "code": 401,
  "message": "Malformed authorization. Are the credentials properly encoded?"
}
```

***

## Client keys

A client key is a unique string used to authenticate and authorize API access
for apps using Circle's SDKs. A client key is linked to either a specific host
domain (websites), bundle ID (iOS), or package name (Android). This restricts
access to pre-configured apps.

<Note>
  A client key must be included in the headers of all modular wallets SDK API
  calls.
</Note>

### Best practices for client keys

Client keys enable access to sensitive application operations, so protecting
them is critical. Follow these best practices:

1. **Use separate keys for each application**: Create separate keys for web and
   mobile apps (iOS, Android) to prevent shared vulnerabilities.
2. **Monitor for misuse**: Set up alerts for unusual activity, such as
   unexpected spikes in API calls, and use monitoring tools to detect anomalies.
3. **Rotate keys regularly**: Regenerate client keys periodically and update
   them in your apps to reduce risk if a key is compromised.
4. **Store keys securely**: Use secure storage options like Local Storage or
   Secure Storage for mobile apps, and avoid unnecessary exposure.
5. **Restrict access**: Limit the scope of client keys by associating them with
   specific apps or domains to minimize potential misuse.

***

## Kit keys

A kit key is a unique string used to authenticate access for Circle's developer
kits. Kit keys simplify integration by providing a single credential that works
across both testnet and mainnet environments, reducing configuration overhead
when building. Kit keys are free to create and do not require KYC.

<Note>
  **Testnet and mainnet compatibility**

  Unlike API keys and client keys, kit keys work on both testnet and mainnet. You
  can use the same key during development and in production.
</Note>

### Keep your kit keys safe

Kit keys enable access to SDK features, so protecting them is essential.

* **Avoid public exposure**: Never share kit keys or include them in client-side
  code, public repositories, or other public mediums.
* **Manage securely**: Use your
  [Circle Developer account](https://console.circle.com/api-keys) to generate
  and manage kit keys. When generating a key, copy it exactly as displayed.

<Warning>
  Losing control of your kit key can result in unauthorized access to SDK
  capabilities.
</Warning>


# Maker deliver operation failed
Source: https://developers.circle.com/api-reference/stablefx/all/contract-maker-deliver-failed

/openapi/stablefx.yaml webhook contractMakerDeliverFailed
The maker deliver operation on the contract has failed. The maker's deliver transaction failed to confirm onchain.



# Record trade operation failed
Source: https://developers.circle.com/api-reference/stablefx/all/contract-record-trade-failed

/openapi/stablefx.yaml webhook contractRecordTradeFailed
The record trade operation on the contract has failed. The initial onchain recording of the trade was unsuccessful.



# Taker deliver operation failed
Source: https://developers.circle.com/api-reference/stablefx/all/contract-taker-deliver-failed

/openapi/stablefx.yaml webhook contractTakerDeliverFailed
The taker deliver operation on the contract has failed. The taker's deliver transaction failed to confirm onchain.



# Create a quote
Source: https://developers.circle.com/api-reference/stablefx/all/create-quote

/openapi/stablefx.yaml post /v1/exchange/stablefx/quotes
Creates a quote for a trade between two currencies. You should provide an `amount` for the `from` parameter or the `to` parameter, but not for both. Use `type:tradable` for an executable quote or `type:reference` for an indicative quote. Tradable quotes include presign `typedData` for signing.



# Create a webhook subscription
Source: https://developers.circle.com/api-reference/stablefx/all/create-subscription

/openapi/stablefx.yaml post /v2/stablefx/notifications/subscriptions
Create a webhook subscription by configuring an endpoint to receive notifications.




# Create a trade
Source: https://developers.circle.com/api-reference/stablefx/all/create-trade

/openapi/stablefx.yaml post /v1/exchange/stablefx/trades
Accepts a quote and creates a trade.



# Delete a notification subscription
Source: https://developers.circle.com/api-reference/stablefx/all/delete-subscription

/openapi/stablefx.yaml delete /v2/stablefx/notifications/subscriptions/{id}
Delete an existing subscription.



# Fund trades
Source: https://developers.circle.com/api-reference/stablefx/all/fund-trade

/openapi/stablefx.yaml post /v1/exchange/stablefx/fund
Executes funding for trades using Permit2 signatures. This endpoint relays the signed permit data to complete the funding operation for trades.




# Generate funding presign data
Source: https://developers.circle.com/api-reference/stablefx/all/generate-funding-presign-data

/openapi/stablefx.yaml post /v1/exchange/stablefx/signatures/funding/presign
Returns the Permit2 EIP-712 payload that the trader must sign for funding operations. `fundingMode` net option is supported for maker funding requests.



# Generate trade presign data
Source: https://developers.circle.com/api-reference/stablefx/all/generate-trade-signature-data

/openapi/stablefx.yaml get /v1/exchange/stablefx/signatures/presign/{tradeId}
Returns the EIP-712 payload that the trader must sign for a CPS trade.



# Get a notification signature public key
Source: https://developers.circle.com/api-reference/stablefx/all/get-notification-signature

/openapi/stablefx.yaml get /v2/stablefx/notifications/publicKey/{id}
Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

In the headers of each webhook, you can find

  - `X-Circle-Signature`: a header containing the digital signature generated by Circle.

  - `X-Circle-Key-Id`: a header containing the UUID. This is will be used as the `ID` as URL parameter to retrieve the relevant public key.




# Get a notification subscription
Source: https://developers.circle.com/api-reference/stablefx/all/get-subscription

/openapi/stablefx.yaml get /v2/stablefx/notifications/subscriptions/{id}
Returns an existing notification subscription.



# Get all webhook subscriptions
Source: https://developers.circle.com/api-reference/stablefx/all/get-subscriptions

/openapi/stablefx.yaml get /v2/stablefx/notifications/subscriptions
Returns an array of all webhook subscriptions.



# Get a trade
Source: https://developers.circle.com/api-reference/stablefx/all/get-trade-by-id

/openapi/stablefx.yaml get /v1/exchange/stablefx/trades/{tradeId}
Returns a trade specified by the ID path parameter



# Get fee for a trade
Source: https://developers.circle.com/api-reference/stablefx/all/get-trade-fee

/openapi/stablefx.yaml get /v1/exchange/stablefx/fees/{tradeId}
Returns the fee associated with the trade ID provided in the path parameter.



# Get all trades
Source: https://developers.circle.com/api-reference/stablefx/all/list-trades

/openapi/stablefx.yaml get /v1/exchange/stablefx/trades
Returns a paginated list of all trades.



# Register a trade signature
Source: https://developers.circle.com/api-reference/stablefx/all/register-trade-signature

/openapi/stablefx.yaml post /v1/exchange/stablefx/signatures
Registers a signed EIP-712 payload from the trader that confirms trade intent.



# Trade breached
Source: https://developers.circle.com/api-reference/stablefx/all/trade-breached

/openapi/stablefx.yaml webhook tradeBreached
The StableFX trade has breached its maturity date.



# Trade completed
Source: https://developers.circle.com/api-reference/stablefx/all/trade-completed

/openapi/stablefx.yaml webhook tradeCompleted
The StableFX trade has been completed successfully. Both the maker and the taker have funded their side and the trade is fully settled.



# Trade confirmed
Source: https://developers.circle.com/api-reference/stablefx/all/trade-confirmed

/openapi/stablefx.yaml webhook tradeConfirmed
The StableFX trade has been confirmed by the exchange.



# Trade failed
Source: https://developers.circle.com/api-reference/stablefx/all/trade-failed

/openapi/stablefx.yaml webhook tradeFailed
The StableFX trade has failed.



# Trade maker funded
Source: https://developers.circle.com/api-reference/stablefx/all/trade-maker-funded

/openapi/stablefx.yaml webhook tradeMakerFunded
The maker has funded their side of the trade. The maker's fund delivery transaction has been confirmed onchain.



# Trade pending settlement
Source: https://developers.circle.com/api-reference/stablefx/all/trade-pending-settlement

/openapi/stablefx.yaml webhook tradePendingSettlement
The StableFX trade has been confirmed onchain and is awaiting funding from taker and maker.



# Trade refunded
Source: https://developers.circle.com/api-reference/stablefx/all/trade-refunded

/openapi/stablefx.yaml webhook tradeRefunded
The StableFX trade has been refunded.



# Trade taker funded
Source: https://developers.circle.com/api-reference/stablefx/all/trade-taker-funded

/openapi/stablefx.yaml webhook tradeTakerFunded
The taker has funded their side of the trade. The taker's fund delivery transaction has been confirmed onchain.



# Update a notification subscription
Source: https://developers.circle.com/api-reference/stablefx/all/update-subscription

/openapi/stablefx.yaml patch /v2/stablefx/notifications/subscriptions/{id}
Update a notification subscription by configuring an endpoint to receive notifications.




# Retrieve a transfer
Source: https://developers.circle.com/api-reference/wallets/buidl/get-transfer

/openapi/buidl-wallets.yaml get /v1/w3s/buidl/transfers/{id}
Retrieve an existing transfer.



# Retrieve a user operation
Source: https://developers.circle.com/api-reference/wallets/buidl/get-user-op

/openapi/buidl-wallets.yaml get /v1/w3s/buidl/userOps/{id}
Retrieve an existing user operation.



# List transfers
Source: https://developers.circle.com/api-reference/wallets/buidl/list-transfers

/openapi/buidl-wallets.yaml get /v1/w3s/buidl/transfers
Retrieve a list of transfers that fit the specified parameters.



# List user operations
Source: https://developers.circle.com/api-reference/wallets/buidl/list-user-ops

/openapi/buidl-wallets.yaml get /v1/w3s/buidl/userOps
Retrieve a list of all user operations that fit the specified parameters.



# Get wallet balances by blockchain and address
Source: https://developers.circle.com/api-reference/wallets/buidl/list-wallet-balances-by-blockchain-address

/openapi/buidl-wallets.yaml get /v1/w3s/buidl/wallets/{blockchain}/{address}/balances
Retrieve wallet balances by blockchain and address.



# Get wallet balances
Source: https://developers.circle.com/api-reference/wallets/buidl/list-wallet-balances-by-id

/openapi/buidl-wallets.yaml get /v1/w3s/buidl/wallets/{id}/balances
Retrieve the balances of a wallet by its ID.



# Get wallet NFTs by blockchain and address
Source: https://developers.circle.com/api-reference/wallets/buidl/list-wallet-nfts-by-blockchain-address

/openapi/buidl-wallets.yaml get /v1/w3s/buidl/wallets/{blockchain}/{address}/nfts
Retrieve the NFTs of a wallet by applicable blockchain and address.



# Get wallet NFTs
Source: https://developers.circle.com/api-reference/wallets/buidl/list-wallet-nfts-by-id

/openapi/buidl-wallets.yaml get /v1/w3s/buidl/wallets/{id}/nfts
Retrieve the NFTs of a wallet by its ID.



# Create a notification subscription
Source: https://developers.circle.com/api-reference/wallets/common/create-subscription

/openapi/configurations_2.yaml post /v2/notifications/subscriptions
Create a notification subscription by configuring an endpoint to receive notifications. For details, see the [Notification Flows](https://developers.circle.com/wallets/webhook-notification-flows) guide.




# Delete a notification subscription
Source: https://developers.circle.com/api-reference/wallets/common/delete-subscription

/openapi/configurations_2.yaml delete /v2/notifications/subscriptions/{id}
Delete an existing subscription.



# Get a notification signature public key
Source: https://developers.circle.com/api-reference/wallets/common/get-notification-signature

/openapi/configurations_2.yaml get /v2/notifications/publicKey/{id}
Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

In the headers of each webhook, you can find
  1. `X-Circle-Signature`: a header containing the digital signature generated by Circle.
  2. `X-Circle-Key-Id`: a header containing the UUID. This is will be used as the `ID` as URL parameter to retrieve the relevant public key.




# Retrieve a notification subscription
Source: https://developers.circle.com/api-reference/wallets/common/get-subscription

/openapi/configurations_2.yaml get /v2/notifications/subscriptions/{id}
Retrieve an existing notification subscription.



# Get all notification subscriptions
Source: https://developers.circle.com/api-reference/wallets/common/get-subscriptions

/openapi/configurations_2.yaml get /v2/notifications/subscriptions
Retrieve an array of existing notification subscriptions.



# Ping
Source: https://developers.circle.com/api-reference/wallets/common/ping

/openapi/configurations_2.yaml get /ping
Checks that the service is running.



# Update a notification subscription
Source: https://developers.circle.com/api-reference/wallets/common/update-subscription

/openapi/configurations_2.yaml patch /v2/notifications/subscriptions/{id}
Update subscription endpoint to receive notifications.




# Screen a blockchain address
Source: https://developers.circle.com/api-reference/wallets/compliance/screen-address

/openapi/compliance.yaml post /v1/w3s/compliance/screening/addresses
Create a screening request for a specific blockchain address and chain.



# Accelerate a transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-accelerate

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/transactions/{id}/accelerate
Accelerates a specified transaction from a developer-controlled wallet. Additional gas fees may be incurred.



# Cancel a transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-cancel

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/transactions/{id}/cancel
Cancels a specified transaction from a developer-controlled wallet. Gas fees may still be incurred. 
This is a best-effort operation, it won't be effective if the original transaction has already been processed by the blockchain.




# Create a contract execution transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-contract-execution

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/transactions/contractExecution
Creates a transaction which executes a smart contract. ABI parameters must be passed in the request.
Related transactions may be submitted as a batch transaction in a single call.

You must provide either a `walletId` or a `walletAddress` and `blockchain` pair in the request body.




# Create a transfer transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-transfer

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/transactions/transfer
Initiates an on-chain digital asset transfer from a specified developer-controlled wallet.

You must provide either a `walletId` or a `walletAddress` and `blockchain` pair in the request body.




# Create a wallet upgrade transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-wallet-upgrade

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/transactions/walletUpgrade
Creates a transaction which upgrades a wallet.



# Estimate fee for a contract execution transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-transaction-estimate-fee

/openapi/developer-controlled-wallets.yaml post /v1/w3s/transactions/contractExecution/estimateFee
Estimates gas fees that will be incurred for a contract execution transaction, given its ABI parameters and blockchain.



# Estimate fee for a transfer transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-transfer-estimate-fee

/openapi/developer-controlled-wallets.yaml post /v1/w3s/transactions/transfer/estimateFee
Estimates gas fees that will be incurred for a transfer transaction; given its amount, blockchain, and token.



# Validate an address
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-validate-address

/openapi/developer-controlled-wallets.yaml post /v1/w3s/transactions/validateAddress
Confirms that a specified address is valid for a given token on a certain blockchain.



# Create wallets
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-wallet

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/wallets
Creates a new developer-controlled wallet or a batch of wallets within a wallet set, given the target blockchain and wallet name.

**Note:** Each `walletSetId` supports a maximum of 10 million wallets.




# Create a new wallet set
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-wallet-set

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/walletSets
Creates a new developer-controlled wallet set.

**Note:** A developer account can create up to 1,000 wallet sets, with each set supporting up to 10 million wallets.
To ensure EVM wallets are created with the same address across chains, see [Unified Wallet Addressing on EVM Chains](/w3s/unified-wallet-addressing-evm).




# Derive a wallet
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/derive-wallet

/openapi/developer-controlled-wallets.yaml put /v1/w3s/developer/wallets/{id}/blockchains/{blockchain}
Derives an EOA (Externally Owned Account) or SCA (Smart Contract Account) wallet using the address of the specified wallet and blockchain. If the target wallet already exists, its metadata will be updated with the provided metadata. This operation is only supported for EVM-based blockchains.



# Derive wallet by address
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/derive-wallet-by-address

/openapi/developer-controlled-wallets.yaml put /v1/w3s/developer/wallets/derive
Creates a wallet on the target blockchain using the same address as the source wallet identified by source blockchain and wallet address. If the target wallet already exists, its metadata is updated.



# Get fee parameters of a blockchain
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-fee-parameters

/openapi/developer-controlled-wallets.yaml get /v1/w3s/developer/transactions/feeParameters
Get latest fee parameters of a blockchain with an optional account type (default to 'EOA').



# Get the lowest nonce pending transaction for a wallet
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-lowest-nonce-transaction

/openapi/developer-controlled-wallets.yaml get /v1/w3s/transactions/lowestNonceTransaction
For a nonce-supported blockchain, get the lowest nonce transaction that's in QUEUED or SENT or STUCK state for the provided wallet.



# Get token details
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-token-id

/openapi/developer-controlled-wallets.yaml get /v1/w3s/tokens/{id}
Fetches details of a specific token given its unique identifier. Every token in your network of wallets has a UUID associated with it, regardless of whether it's already recognized or was added as a monitored token.



# Get a transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-transaction

/openapi/developer-controlled-wallets.yaml get /v1/w3s/transactions/{id}
Retrieves info for a single transaction using it's unique identifier.



# Retrieve a wallet
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallet

/openapi/developer-controlled-wallets.yaml get /v1/w3s/wallets/{id}
Retrieve an existing wallet



# Get a wallet set
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallet-set

/openapi/developer-controlled-wallets.yaml get /v1/w3s/walletSets/{id}
Retrieve an existing wallet set.



# Get all wallet sets
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallet-sets

/openapi/developer-controlled-wallets.yaml get /v1/w3s/walletSets
Retrieve an array of existing wallet sets.



# List wallets
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallets

/openapi/developer-controlled-wallets.yaml get /v1/w3s/wallets
Retrieves a list of all wallets that fit the specified parameters.



# List wallets with balances
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallets-with-balances

/openapi/developer-controlled-wallets.yaml get /v1/w3s/developer/wallets/balances
Retrieves a list of all wallets that match the specified parameters. Wallet balances update automatically after each transfer.

**Note**: On Aptos, this endpoint only returns balances for tokens stored in primary storage. Tokens held in [AIP-21](https://github.com/aptos-labs/aptos-core/releases/tag/aptos-node-v1.5.0) secondary storage are excluded from balance queries and deposit notifications to prevent incorrect or misleading results from secondary storage-based state changes.



# List transactions
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/list-transactions

/openapi/developer-controlled-wallets.yaml get /v1/w3s/transactions
Lists all transactions. Includes details such as status, source/destination, and transaction hash.



# Get token balance for a wallet
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/list-wallet-balance

/openapi/developer-controlled-wallets.yaml get /v1/w3s/wallets/{id}/balances
Fetches the digital asset balance for a single developer-controlled wallet using its unique identifier.

**Note**: On Aptos, this endpoint only returns balances for tokens stored in primary storage. Tokens held in [AIP-21](https://github.com/aptos-labs/aptos-core/releases/tag/aptos-node-v1.5.0) secondary storage are excluded from balance queries and deposit notifications to prevent incorrect or misleading results from secondary storage-based state changes.



# Get NFTs for a wallet
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/list-wallet-nfts

/openapi/developer-controlled-wallets.yaml get /v1/w3s/wallets/{id}/nfts
Fetches the info for all NFTs stored in a single developer-controlled wallet, using the wallets unique identifier.



# Sign delegate action
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-delegate-action

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/sign/delegateAction
Sign a delegate action from a specific developer-controlled wallet.

NOTE: This endpoint is only available for NEAR and NEAR-TESTNET.



# Sign message
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-message

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/sign/message
Sign a message from a specified developer-controlled wallet. This endpoint supports message signing for Ethereum-based blockchains (using EIP-191), Solana and Aptos (using Ed25519 signatures). Note that Smart Contract Accounts (SCA) are specific to Ethereum and EVM-compatible chains. The difference between Ethereum's EOA and SCA can be found in the [account types guide](https://developers.circle.com/wallets/account-types). You can also check the list of Ethereum Dapps that support SCA: https://eip1271.io/."

You must provide either a `walletId` or a `walletAddress` and `blockchain` pair in the request body.




# Sign transaction
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-transaction

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/sign/transaction
Sign a transaction from a specific developer-controlled wallet.

You must provide either a `walletId` or a `walletAddress` and `blockchain` pair in the request body.

NOTE: This endpoint is only available for the following chains: `SOL`, `SOL-DEVNET`, `NEAR`, `NEAR-TESTNET`, `EVM`, `EVM-TESTNET`. Each chain defines its own standard, please refer to [Signing APIs doc](https://learn.circle.com/w3s/signing-apis).




# Sign typed data
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-typed-data

/openapi/developer-controlled-wallets.yaml post /v1/w3s/developer/sign/typedData
| Sign the EIP-712 typed structured data from a specified developer-controlled wallet.
You must provide either a `walletId` or a `walletAddress` and `blockchain` pair in the request body.
This endpoint only supports Ethereum and EVM-compatible blockchains. Please note that not all apps currently support Smart Contract Accounts (SCA); the difference between Ethereum's EOA and SCA can be found in the [account types guide](https://developers.circle.com/wallets/account-types). You can also check the list of Ethereum apps that support SCA: https://eip1271.io/.



# Update a wallet
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/update-wallet

/openapi/developer-controlled-wallets.yaml put /v1/w3s/wallets/{id}
Updates info metadata of a wallet.



# Update a wallet set
Source: https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/update-wallet-set

/openapi/developer-controlled-wallets.yaml put /v1/w3s/developer/walletSets/{id}
Update the name of the wallet set



# Set monitored tokens
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/create-monitored-tokens

/openapi/configurations_1.yaml post /v1/w3s/config/entity/monitoredTokens
Add a new token to the monitored token list.



# Delete monitored tokens
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/delete-monitored-tokens

/openapi/configurations_1.yaml post /v1/w3s/config/entity/monitoredTokens/delete
Delete tokens from the monitored token list.



# Get configuration for entity
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/get-entity-config

/openapi/configurations_1.yaml get /v1/w3s/config/entity
Get the app ID associated to the entity.



# Get public key for entity
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/get-public-key

/openapi/configurations_1.yaml get /v1/w3s/config/entity/publicKey
Get the public key associated with the entity.



# Retrieve existing monitored tokens.
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/list-monitored-tokens

/openapi/configurations_1.yaml get /v1/w3s/config/entity/monitoredTokens
Get monitored tokens



# Request testnet tokens
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/request-testnet-tokens

/openapi/configurations_1.yaml post /v1/faucet/drips
Request testnet tokens for your wallet.

**Note:** Calling the `/v1/faucet/drips` API requires upgrading to mainnet.




# Update monitored tokens
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/update-monitored-tokens

/openapi/configurations_1.yaml put /v1/w3s/config/entity/monitoredTokens
Upsert the monitored token list.



# Update monitored tokens scope
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/update-monitored-tokens-scope

/openapi/configurations_1.yaml put /v1/w3s/config/entity/monitoredTokens/scope
Select between monitoring all tokens or selected tokens added to the monitored tokens list.



# Get a deviceToken to log in with email OTP
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-device-token-email-login

/openapi/user-controlled-wallets.yaml post /v1/w3s/users/email/token
Get a deviceToken to login with email OTP in SDK



# Get deviceToken to perform social login
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-device-token-social-login

/openapi/user-controlled-wallets.yaml post /v1/w3s/users/social/token
Get deviceToken to perform social login in SDK



# Estimate fee for a contract execution transaction
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-transaction-estimate-fee

/openapi/user-controlled-wallets.yaml post /v1/w3s/transactions/contractExecution/estimateFee
Estimates gas fees that will be incurred for a contract execution transaction, given its ABI parameters and blockchain.



# Estimate fee for a transfer transaction
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-transfer-estimate-fee

/openapi/user-controlled-wallets.yaml post /v1/w3s/transactions/transfer/estimateFee
Estimates gas fees that will be incurred for a transfer transaction; given its amount, blockchain, and token.



# Create a user
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user

/openapi/user-controlled-wallets.yaml post /v1/w3s/users
Create a user.



# Create a challenge for PIN setup
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-pin-challenge

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/pin
Creates a challenge for PIN setup without setting up the wallets.



# Create a challenge for PIN restore
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-pin-restore-challenge

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/pin/restore
Creates a challenge to restore a user's PIN using security questions.



# Create a Challenge to accelerate a transaction
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-accelerate-challenge

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/{id}/accelerate
Generates a challenge to accelerate a specific transaction from a user-controlled wallet. Additional gas fees may apply.



# Create a challenge to cancel a transaction
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-cancel-challenge

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/{id}/cancel
Generates a challenge to cancel a specific transaction from a user-controlled wallet. Gas fees may still apply.



# Create a challenge for contract execution
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-contract-execution-challenge

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/contractExecution
Generates a challenge for creating a transaction which executes a smart contract. ABI parameters must be passed in the request.



# Create a challenge for a transfer
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-transfer-challenge

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/transfer
Generates a challenge for initiating an on-chain digital asset transfer from a specified user-controlled wallet



# Create a challenge for a wallet upgrade
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-wallet-upgrade-challenge

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/walletUpgrade
Generates a challenge to create a transaction that upgrades a wallet.



# Create wallets
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-wallet

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/wallets
Generates a challenge to create a new user-controlled wallet or a batch of wallets. You must specify the blockchain and wallet name.



# Create a challenge for user initialization with wallet creation
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-with-pin-challenge

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/initialize
Creates a challenge for user initialization and creates one or more wallets.



# Validate an address
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-validate-address

/openapi/user-controlled-wallets.yaml post /v1/w3s/transactions/validateAddress
Confirms that a specified address is valid for a given token on a certain blockchain.



# Get the lowest nonce pending transaction for a wallet
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-lowest-nonce-transaction

/openapi/user-controlled-wallets.yaml get /v1/w3s/transactions/lowestNonceTransaction
For a nonce-supported blockchain, get the lowest nonce transaction that's in QUEUED or SENT or STUCK state for the provided wallet.



# Get token details
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-token-id

/openapi/user-controlled-wallets.yaml get /v1/w3s/tokens/{id}
Fetches details of a specific token given its unique identifier. Every token in your network of wallets has a UUID associated with it, regardless of whether it's already recognized or was added as a monitored token.



# Get a transaction
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-transaction

/openapi/user-controlled-wallets.yaml get /v1/w3s/transactions/{id}
Retrieves info for a single transaction using it's unique identifier.



# Get a user by ID
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user

/openapi/user-controlled-wallets.yaml get /v1/w3s/users/{id}
Get user by ID.



# Get user
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-by-token

/openapi/user-controlled-wallets.yaml get /v1/w3s/user
Retrieve the user by token.



# Get a challenge
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-challenge

/openapi/user-controlled-wallets.yaml get /v1/w3s/user/challenges/{id}
Retrieve a user challenge.



# Create a user token
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-token

/openapi/user-controlled-wallets.yaml post /v1/w3s/users/token
Generate user session and SDK secret key.



# Get a wallet
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-wallet

/openapi/user-controlled-wallets.yaml get /v1/w3s/wallets/{id}
Retrieves info for a single user-controlled wallet using it's unique identifier.



# List transactions
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-transactions

/openapi/user-controlled-wallets.yaml get /v1/w3s/transactions
Lists all transactions. Includes details such as status, source/destination, and transaction hash.



# List challenges
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-user-challenges

/openapi/user-controlled-wallets.yaml get /v1/w3s/user/challenges
List all challenges by status for a user.



# List users
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-users

/openapi/user-controlled-wallets.yaml get /v1/w3s/users
Get all the users under the entity.



# Get token balance for a wallet
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallet-balance

/openapi/user-controlled-wallets.yaml get /v1/w3s/wallets/{id}/balances
Fetches the digital asset balance for a single user-controlled wallet using its unique identifier.

**Note**: On Aptos, this endpoint only returns balances for tokens stored in primary storage. Tokens held in [AIP-21](https://github.com/aptos-labs/aptos-core/releases/tag/aptos-node-v1.5.0) secondary storage are excluded from balance queries and deposit notifications to prevent incorrect or misleading results from secondary storage-based state changes.



# Get NFTs for a wallet
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallet-nfts

/openapi/user-controlled-wallets.yaml get /v1/w3s/wallets/{id}/nfts
Fetches the info for all NFTs stored in a single user-controlled wallet, using the wallets unique identifier.



# List wallets
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallets

/openapi/user-controlled-wallets.yaml get /v1/w3s/wallets
Retrieves a list of all user-controlled wallets that fit the specified parameters.



# Get a new userToken with the refreshToken
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/refresh-user-token

/openapi/user-controlled-wallets.yaml post /v1/w3s/users/token/refresh
Get a new userToken with the refreshToken passed over from sdk/performLogin which matches to the current userToken



# Resend an OTP email to the user
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/resend-otp

/openapi/user-controlled-wallets.yaml post /v1/w3s/users/email/resendOTP
When the users don’t receive the OTP email,  you can call this API to resend OTP email. The prior OTP email would expire after the new one is sent out.



# Create a challenge to sign message
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-message

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/sign/message
Generates a challenge for signing a message from a specified user-controlled wallet. This endpoint supports Ethereum-based blockchains (using EIP-191), Solana and Aptos (using Ed25519 signatures). Note that Smart Contract Accounts (SCA) are specific to Ethereum and EVM-compatible chains. The difference between Ethereum's EOA and SCA can be found in the [account types guide](https://developers.circle.com/wallets/account-types). You can also check the list of Ethereum Dapps that support SCA: https://eip1271.io/.



# Create a challenge to sign transaction
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-transaction

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/sign/transaction
Generate a challenge for signing the transaction from a specific user-controlled wallet.



NOTE: This endpoint supports the following blockchains: SOL, SOL-DEVNET, EVM, EVM-TESTNET. Each chain defines its own standard. For more details, see [Signing APIs](https://developers.circle.com/w3s/signing-apis).



# Create a challenge to sign typed data
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-typed-data

/openapi/user-controlled-wallets.yaml post /v1/w3s/user/sign/typedData
Generates a challenge for signing the EIP-712 typed structured data from a specified user-controlled wallet. This endpoint only supports Ethereum and EVM-compatible blockchains. Please note that not all Dapps currently support Smart Contract Accounts (SCA); the difference between Ethereum's EOA and SCA can be found in the [account types guide](https://developers.circle.com/wallets/account-types). You can also check the list of Ethereum Dapps that support SCA: https://eip1271.io/.



# Create a challenge to update PIN
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/update-user-pin-challenge

/openapi/user-controlled-wallets.yaml put /v1/w3s/user/pin
Creates a challenge to update a user's PIN using the current PIN.



# Update a wallet
Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/update-wallet

/openapi/user-controlled-wallets.yaml put /v1/w3s/wallets/{id}
Updates info for a single user-controlled wallet using it's unique identifier.



# Get an attestation for a crosschain transfer
Source: https://developers.circle.com/api-reference/xreserve/all/get-attestation

/openapi/xreserve.yaml get /v1/attestations/{depositMessageHash}
Returns the attestation for a specified crosschain transfer using the deposit message hash.



# Get attestations by source transaction hash
Source: https://developers.circle.com/api-reference/xreserve/all/get-attestations-by-tx-hash

/openapi/xreserve.yaml get /v1/attestations
Returns all attestations associated with the specified source chain transaction hash.
A single transaction may produce multiple attestations across different remote domains.




# Get token balances on a remote domain
Source: https://developers.circle.com/api-reference/xreserve/all/get-balances

/openapi/xreserve.yaml get /v1/balances/{remoteDomain}
Returns the expected token balances for a specified remote domain based on the deposit amounts made into xReserve.



# Get domain information
Source: https://developers.circle.com/api-reference/xreserve/all/get-info

/openapi/xreserve.yaml get /v1/info
Returns information on source and remote domains, including its supported tokens and configuration details.



# Get withdrawal status
Source: https://developers.circle.com/api-reference/xreserve/all/get-withdrawal-status

/openapi/xreserve.yaml get /v1/withdrawal/{withdrawalId}
Returns the status and transfer details of a specified withdrawal group.



# List attestations for crosschain transfers
Source: https://developers.circle.com/api-reference/xreserve/all/list-attestations

/openapi/xreserve.yaml get /v1/remote-domains/{remoteDomain}/attestations
Returns an array of attestations for the specified crosschain transfers, filtered by remote domain.

Use the Link header in the response to navigate between pages.




# Prepare a withdrawal request
Source: https://developers.circle.com/api-reference/xreserve/all/prepare-withdrawal

/openapi/xreserve.yaml post /v1/prepare-withdrawal
Turns the user's burn transaction data on the remote chain into fully encoded burn intents to send to the `/withdraw` endpoint. This endpoint performs the following:
- Resolves contract and token addresses across networks.
- Determines the optimal forwarding strategy, such as redepositing to another xReserve remote domain or forwarding to a CCTP domain.
- Calculates transfer amounts and fees.
- Encodes forwarding call data with the calculated transfer amounts.
- Generates `maxBlockHeight` and `maxFee` values with safety buffers.
- Returns data in the structure expected by the withdraw endpoint.

Note: The `/withdraw` endpoint requires signatures and the remote chain `burnTxId` in addition to the burn intent prepared by this endpoint.




# Submit signed burn intents for withdrawal
Source: https://developers.circle.com/api-reference/xreserve/all/submit-withdrawal

/openapi/xreserve.yaml post /v1/withdraw
Submits up to five signed burn intent batches per request call. Each batch may contain one burn intent or a set of up to 10.



# Assets
Source: https://developers.circle.com/assets

Build on trusted digital money: USDC and EURC for open integration, USYC for yield, and xReserve to issue branded, USDC-backed stablecoins.

## Stablecoins

The foundation of programmable money: stable, interoperable assets that move
value across borders and blockchains.

<div>
  <a href="/stablecoins/what-is-usdc">
    <div>
      <img alt="USDC token" />
    </div>

    <div>
      <h3>USDC</h3>

      <p>
        Access the most trusted digital dollar for payments, DeFi, and
        settlement.
      </p>
    </div>
  </a>

  <a href="/stablecoins/what-is-eurc">
    <div>
      <img alt="EURC token" />
    </div>

    <div>
      <h3>EURC</h3>
      <p>Launch euro experiences with MiCA-compliant infrastructure.</p>
    </div>
  </a>

  <a href="/xreserve/">
    <div>
      <Icon icon="coins" />
    </div>

    <div>
      <h3>xReserve</h3>
      <p>Issue branded stablecoins that stay 100% backed by USDC reserves.</p>
    </div>
  </a>
</div>

## Tokenized money market

Circle's USYC provides institutions with 24/7 access to a yield-bearing money
market fund settled onchain with real-time subscriptions and redemptions.

<div>
  <a href="/tokenized/usyc/overview">
    <div>
      <img alt="USYC token" />
    </div>

    <div>
      <h3>USYC</h3>
      <p>Offer yield exposure via tokenized short-term U.S. Treasuries.</p>
    </div>
  </a>
</div>

## Dive deeper

* Follow the [USDC quickstarts](/stablecoins/quickstarts/transfer-usdc-evm) to
  test transfers on any supported L1 or L2.
* Use the [EURC quickstart](/stablecoins/quickstarts/transfer-eurc-evm) to stand
  up euro rails in minutes.
* Explore
  [USYC subscribe and redeem guides](/tokenized/usyc/subscribe-and-redeem) to
  wire funds in and out of tokenized Treasuries.
* Learn about [Circle Mint](/circle-mint) and how institutions can mint USDC and
  EURC.


# Build Onchain Experiences
Source: https://developers.circle.com/build-onchain

Compose wallets, contracts, gas sponsorship, and compliance to ship onchain apps faster.

## What you can build

* [**Embedded wallets**](/wallets): build flexible, secure, and scalable wallets
  into your application.
* [**Gasless UX**](/wallets/gas-station): give end users a gasless experience
  with Gas Station and Paymaster.
* [**Smart contracts**](/contracts): create, deploy, and execute smart contracts
  through intuitive APIs.
* [**Compliance operations**](/wallets/compliance-engine): screen transactions
  and automate alerts.

## Compose your stack

Mix and match these building blocks based on who controls the keys, how you
cover fees, and the level of automation you need.

<CardGroup>
  <Card title="Wallets: Dev-Controlled" icon="wallet" href="/wallets/dev-controlled">
    Use APIs to create wallets, move funds, and manage policies on behalf of
    your users with instant scale.
  </Card>

  <Card title="Wallets: User-Controlled" icon="user" href="/wallets/user-controlled">
    Ship passkeys, social logins, and custom signing UIs so end users truly own
    their keys across devices.
  </Card>

  <Card title="Wallets: Modular" icon="layer-group" href="/wallets/modular">
    Plug in modules like permissions, recovery, or automation to ship custom
    smart-accounts.
  </Card>

  <Card title="Gas Station" icon="gas-pump" href="/wallets/gas-station">
    Sponsor gas to create a gasless UX for end-users.
  </Card>

  <Card title="Paymaster" icon="coin-vertical" href="/paymaster">
    Let anyone pay gas directly in USDC through permissionless ERC-4337
    paymasters.
  </Card>

  <Card title="Contracts" icon="code" href="/contracts">
    Deploy and operate smart contracts via audited templates, APIs, and
    monitoring.
  </Card>

  <Card title="Compliance Engine" icon="shield-check" href="/wallets/compliance-engine">
    Screen transactions, manage rules, and investigate alerts.
  </Card>
</CardGroup>

## Building something crosschain?

Wallets and contracts become more powerful when they connect across ecosystems.
Use these primitives to move liquidity crosschain and expose a unified balance.

<Tip>
  **Use dedicated SDKs for crosschain transfers**

  [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit) and
  [Unified Balance Kit](https://www.npmjs.com/package/@circle-fin/unified-balance-kit)
  let you move USDC across blockchains without low-level protocol work. Both
  support multiple blockchains and wallet providers.
</Tip>

<CardGroup>
  <Card title="CCTP" icon="arrow-up-arrow-down" href="/cctp">
    Burn-and-mint native USDC between supported chains with guarantees.

    <PermissionlessBadge />
  </Card>

  <Card title="Gateway" icon="dungeon" href="/gateway">
    Give users a single USDC balance they can spend anywhere while Circle
    handles settlement.

    <PermissionlessBadge />
  </Card>
</CardGroup>

## Dive deeper

* Follow the
  [dev-controlled wallet quickstart](/wallets/dev-controlled/create-your-first-wallet)
  to stand up API-driven wallets in minutes.
* Use the [user-controlled wallet tutorials](/wallets/user-controlled) to embed
  passkey flows and branded signing experiences.
* Head to the [Contracts quickstart](/contracts/scp-deploy-smart-contract) to
  deploy an audited template and connect to wallets.
* Explore
  [Gas Station quickstarts](/wallets/gas-station/send-a-gasless-transaction) and
  [Paymaster guides](/paymaster/pay-gas-fees-usdc) to abstract gas across
  networks.


# Cross-Chain Transfer Protocol
Source: https://developers.circle.com/cctp



Cross-Chain Transfer Protocol (CCTP) is a permissionless onchain utility that
facilitates native USDC transfers across blockchains. CCTP burns USDC on the
source blockchain and mints it on the destination blockchain, enabling secure
1:1 transfers without traditional bridge liquidity pools or wrapped tokens.

<Tip>
  **Use [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit) to
  simplify crosschain transfers with CCTP.**

  Bridge Kit is a lightweight SDK that uses CCTP as its protocol provider, letting
  you transfer USDC between blockchains in just a few lines of code.
</Tip>

## Key features

<CardGroup>
  <Card title="Native USDC transfers" icon="coins">
    Transfer native USDC across blockchains without wrapped tokens or liquidity
    pools
  </Card>

  <Card title="Configurable transfer speeds" icon="gauge-high">
    Choose between [Fast
    Transfer](/cctp/concepts/finality-and-block-confirmations#fast-transfer-attestation-times)
    for speed or [Standard
    Transfer](/cctp/concepts/finality-and-block-confirmations#standard-transfer-attestation-times)
    for cost efficiency
  </Card>

  <Card title="Programmable hooks" icon="code">
    Trigger automated actions on the destination blockchain after USDC arrives
  </Card>
</CardGroup>

## What you can build

CCTP enables you to build applications that require moving USDC across
blockchains. Here are some common use cases:

<AccordionGroup>
  <Accordion title="Crosschain liquidity management" icon="arrow-right-arrow-left">
    Rebalance USDC holdings across blockchains to meet liquidity demands, manage
    treasury positions, or take advantage of market opportunities with minimal
    latency.
  </Accordion>

  <Accordion title="Crosschain swaps" icon="shuffle">
    Enable users to swap tokens on one blockchain for tokens on another blockchain
    by routing through USDC. Build seamless crosschain trading experiences that feel
    like a single transaction.
  </Accordion>

  <Accordion title="Crosschain payments" icon="credit-card">
    Accept USDC payments on one blockchain and automatically transfer funds to
    another blockchain where your business operations are based or where recipients
    prefer to receive funds.
  </Accordion>

  <Accordion title="Composable crosschain applications" icon="layer-group">
    Use CCTP hooks to chain together crosschain actions. Transfer USDC across
    blockchains and automatically deposit it into DeFi protocols, purchase NFTs, or
    execute smart contract logic.
  </Accordion>
</AccordionGroup>

## Get started

<CardGroup>
  <Card title="Transfer USDC from Ethereum to Arc" icon="rocket" href="/cctp/quickstarts/transfer-usdc-ethereum-to-arc">
    Build a script to transfer USDC between EVM blockchains using CCTP
  </Card>

  <Card title="Transfer USDC from Solana to Arc" icon="rocket" href="/cctp/quickstarts/transfer-usdc-solana-to-arc">
    Transfer USDC from Solana to an EVM blockchain using CCTP
  </Card>

  <Card title="Transfer USDC to and from Stellar" icon="rocket" href="/cctp/quickstarts/transfer-usdc-stellar-arc">
    Transfer USDC between Arc and Stellar using CCTP
  </Card>
</CardGroup>

## Related products

CCTP and Gateway offer different approaches to crosschain transfers. This table
compares the two approaches.

| Attribute                 | CCTP                                                                               | Gateway                                                            |
| ------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Use case**              | Transfer USDC from one blockchain to another                                       | Hold a unified USDC balance accessible on any supported blockchain |
| **Transfer speed**        | Fast Transfer: \~8-20 seconds<br />Standard Transfer: 15-19 minutes (Ethereum/L2s) | Instant (\<500 ms) after balance is established                    |
| **Balance model**         | Point-to-point transfers                                                           | Unified crosschain balance                                         |
| **Custody**               | Non-custodial                                                                      | Non-custodial with 7-day trustless withdrawal option               |
| **Supported blockchains** | [View list](/cctp/concepts/supported-chains-and-domains)                           | [View list](/gateway/references/supported-blockchains)             |


# CCTP-Enabled HyperCore Transfers
Source: https://developers.circle.com/cctp/concepts/cctp-on-hypercore



CCTP lets you transfer USDC from all supported CCTP domains to HyperCore using a
`CoreDepositWallet` contract deployed on HyperEVM. The `CoreDepositWallet`
handles depositing and withdrawing USDC between HyperEVM and HyperCore. This
topic explains how the HyperCore workflow works and covers HyperCore-specific
considerations.

<Note>
  **Note:** HyperCore balances reflect protocol-level credits, not Circle-issued
  USDC. Native USDC remains in the `CoreDepositWallet` contract on HyperEVM and
  withdrawals are required to [redeem native USDC from
  HyperEVM](/cctp/howtos/withdraw-usdc-from-hypercore-to-evm).
</Note>

## How it works

The HyperCore workflow from source chains that are not HyperEVM is a two-step
process: funds are transferred in the standard CCTP workflow to HyperEVM, then
forwarded to HyperCore by depositing them into the `CoreDepositWallet` contract.

The burn transaction uses one of two contracts depending on the source chain:

* `TokenMessengerV2` contract
* `CctpExtension` contract

The burn transaction includes a hook that calls the `CctpForwarder` contract on
HyperEVM to forward the USDC to the recipient address on HyperCore.

Here's how the HyperCore deposit workflow works:

1. Check the CCTP API for fees. Fast transfers from Arbitrum with a HyperCore
   destination have no fast transfer fee. Using Circle's Forwarder Service to
   forward to HyperCore is optional and has a dynamic destination chain gas fee.
2. Calculate the USDC amounts minus fees.
3. Approve the contract to spend the amount of USDC you want to burn. If you are
   interacting with the `TokenMessengerV2` contract, you can do this with a call
   to the `approve` function on the USDC contract. If you are interacting with
   the `CctpExtension` contract on Arbitrum, you sign a
   `ReceiveWithAuthorization` message.
4. Sign and broadcast a burn transaction. The type depends on the source domain:
   * **CctpExtension contract on Arbitrum**: Sign and broadcast a
     `batchDepositForBurnWithAuth` transaction. Set HyperEVM as the destination.
     Include hook data to call the `CctpForwarder` contract on HyperEVM.
   * **TokenMessengerV2 contract**: Sign and broadcast a `depositForBurn`
     transaction. Set HyperEVM as the destination. Include hook data to call the
     `CctpForwarder` contract on HyperEVM.

HyperCore deposits and withdrawals are supported to/from any CCTP-supported
blockchain. Forwarding for these transfers is optional and is supported for all
[Forwarder-supported blockchains](/cctp/concepts/supported-chains-and-domains#supported-blockchains)
except for withdrawals to Solana.

## Important considerations

Keep these things in mind when using CCTP with HyperCore.

### Testnet recipient address limitations

When you test USDC transfers to HyperCore on testnet, the recipient address has
limits:

* The recipient address must already exist on HyperCore mainnet.
* Addresses that already exist on mainnet can only receive up to \$1000 testnet
  USDC.
* Transfers to addresses without mainnet state fail silently.

To check if an address exists on mainnet, use Hyperliquid's info API:

```shell theme={null}
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '
{
    "type": "userRole",
    "user": "${USER_ADDRESS}"
}
'
```

### Account activation fee on HyperCore

New HyperCore accounts are subject to a one-time 1 USDC activation fee, managed
entirely by the Hyperliquid protocol. Circle's `CoreDepositWallet` contract does
not collect or enforce this fee.

When a new user first deposits USDC to HyperCore, the full deposit amount is
credited to their tradable balance. The 1 USDC activation fee is earmarked at
the account level and charged on the user's first outbound action, such as a
withdrawal or `SendAsset` transfer. Until that first outbound action, the
account is considered unactivated and cannot perform
[CoreWriter actions](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/activation-gas-fee).

This means:

* There is no minimum deposit amount. Deposits of any size, including less than
  1 USDC, will succeed.
* The user's first outbound action (withdrawal, transfer, etc.) requires a
  balance of at least 1 USDC. If the balance is below 1 USDC at that time, the
  action will fail.
* After the activation fee is paid, subsequent outbound actions are not subject
  to it.

<Note>
  The activation fee is separate from CCTP forwarding fees. When calculating
  total costs for a new user's first withdrawal, account for both the 1 USDC
  activation fee (charged by Hyperliquid) and any applicable CCTP forwarding
  fee.
</Note>

### Best practices for new account deposits

When your integration deposits USDC to a new HyperCore account:

* Ensure the deposit is large enough that the recipient will have at least 1
  USDC available for their first outbound action.
* Inform end users that their first withdrawal or transfer from HyperCore
  includes a one-time 1 USDC activation fee deducted by the Hyperliquid
  protocol.
* If your integration creates accounts programmatically (for example, contract
  addresses), you can pre-activate the account by sending an activation
  transaction to the EVM contract address on HyperCore, as described in
  [Hyperliquid's documentation](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/activation-gas-fee).


# Fast Transfer Allowance
Source: https://developers.circle.com/cctp/concepts/fast-transfer-allowance

Understanding Circle's Fast Transfer allowance mechanism

The Fast Transfer allowance is Circle's mechanism for providing
faster-than-finality USDC transfers. It limits the total value of USDC that can
be minted through Fast Transfer before related burns reach hard finality.

## How it works

Circle maintains a Fast Transfer allowance pool that backs all in-process CCTP
Fast Transfers. The following steps describe how the allowance works:

1. **Initial state**: Circle maintains a Fast Transfer allowance pool (for
   example, 10 million USDC).

2. **Fast Transfer initiated**: When you burn USDC on the source blockchain with
   Fast Transfer:
   * The burn amount temporarily debits the allowance
   * Circle's Attestation Service issues an attestation after
     [soft finality](/cctp/concepts/finality-and-block-confirmations)
   * You can immediately mint USDC on the destination blockchain

3. **Allowance depleted**: If the allowance reaches zero, Fast Transfers are
   temporarily unavailable until the allowance replenishes.

4. **Allowance replenished**: Once burns reach hard finality on source
   blockchains, the corresponding amounts are credited back to the allowance.

<Note>
  **Note:** The Fast Transfer allowance is global across all supported
  blockchains. It's not specific to a particular source or destination blockchain,
  but rather tracks the total value of in-process Fast Transfers.
</Note>

## Check the current allowance

To check the remaining Fast Transfer allowance, call the
[`GET /v2/fastBurn/USDC/allowance`](/api-reference/cctp/all/get-fast-burn-usdc-allowance)
endpoint. For a detailed guide on checking the allowance, see
[Get the Fast Transfer allowance](/cctp/howtos/get-fast-transfer-allowance).

## When allowance is insufficient

If the Fast Transfer allowance is insufficient for your transfer, you have two
options:

### Option 1: Wait for replenishment

The allowance automatically replenishes as pending Fast Transfers reach hard
finality.

Monitor the allowance until sufficient capacity is available:

```ts TypeScript theme={null}
async function waitForAllowance(requiredAmount: bigint, timeoutMs = 1200000) {
  const startTime = Date.now();

  while (Date.now() - startTime < timeoutMs) {
    const response = await fetch(
      "https://iris-api-sandbox.circle.com/v2/fastBurn/USDC/allowance",
    );
    const { allowance } = await response.json();

    // Convert USDC string to 6-decimal subunits without float precision loss
    const [whole, frac = ""] = String(allowance).split(".");
    const allowanceSubunits =
      BigInt(whole) * 1_000_000n + BigInt((frac + "000000").slice(0, 6));

    if (allowanceSubunits >= requiredAmount) {
      console.log("Sufficient allowance available");
      return true;
    }

    console.log(`Current allowance: ${allowance} USDC, waiting...`);
    await new Promise((resolve) => setTimeout(resolve, 30000)); // Check every 30 seconds
  }

  throw new Error("Timeout waiting for allowance replenishment");
}
```

### Option 2: Use Standard Transfer

Change `minFinalityThreshold` to 2000 or higher to use
[Standard Transfer](/cctp/concepts/finality-and-block-confirmations#standard-transfer-attestation-times),
which doesn't consume the Fast Transfer allowance.

## Allowance lifecycle

Understanding what happens during each phase of the allowance lifecycle helps
you build more robust applications:

<Steps>
  <Step title="Burn initiated">
    The user calls `depositForBurn` with `minFinalityThreshold` ≤ 1000. The
    transaction confirms on the source blockchain, and the allowance is debited by
    the burn amount.
  </Step>

  <Step title="Soft finality reached">
    Circle's Attestation Service issues an attestation, and the attestation becomes
    available through the API. The user can now mint USDC on the destination
    blockchain.
  </Step>

  <Step title="Hard finality reached">
    The burn transaction reaches hard finality on the source blockchain. The
    allowance is credited back by the burn amount, and capacity is restored for new
    Fast Transfers.
  </Step>
</Steps>


# CCTP Fees
Source: https://developers.circle.com/cctp/concepts/fees

Understanding CCTP transfer fees for Fast and Standard transfers

CCTP charges fees on Fast Transfers only. Standard Transfers are free.

[Fast Transfer](/cctp/concepts/finality-and-block-confirmations#fast-transfer-attestation-times)
enables USDC transfers at faster-than-finality speeds by leveraging Circle's
[Fast Transfer allowance](/cctp/concepts/fast-transfer-allowance). These
transfers incur a fee that varies by route.

* **Fee range**: 0-14 basis points depending on source blockchain, for example
  \$0–\$1.40 per \$1,000 transferred
* **When and how the fee is collected**: The fee is deducted from the
  transferred amount when USDC is minted on the destination blockchain

## Get the current fee

To retrieve the current Fast Transfer fee for your route, call the
[`GET /v2/burn/USDC/fees`](/api-reference/cctp/all/get-burn-usdc-fees) endpoint.
For more details, see
[Get the fee for your transfer](/cctp/howtos/get-transfer-fee).

## Maximum fee parameter

When calling
[`depositForBurn`](/cctp/references/contract-interfaces#depositforburn), you
specify a `maxFee` parameter that sets the maximum fee you're willing to pay:

```ts TypeScript theme={null}
await tokenMessenger.depositForBurn(
  amount,
  destinationDomain,
  mintRecipient,
  burnToken,
  destinationCaller,
  500n, // maxFee: 500 subunits (0.0005 USDC)
  1000, // minFinalityThreshold: Fast Transfer
);
```

If the actual fee exceeds your specified `maxFee`, the transaction will revert
on the source blockchain, and no USDC will be burned.

To avoid transaction failures:

1. Retrieve the current fee before initiating a transfer
2. Add a small buffer (for example, 10-20%) to account for potential fee
   fluctuations
3. Set `maxFee` to this buffered amount

Example:

```ts TypeScript theme={null}
async function calculateMaxFee(
  sourceDomain: number,
  destDomain: number,
  transferAmountUSDC: string, // USDC amount like "1" or "10.5"
) {
  // Convert USDC to subunits (6 decimals)
  const [whole, decimal = ""] = transferAmountUSDC.split(".");
  const decimal6 = (decimal + "000000").slice(0, 6);
  const transferAmount = BigInt(whole + decimal6);

  // Get current fee
  const response = await fetch(
    `https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/${sourceDomain}/${destDomain}`,
  );
  const fees = await response.json();

  // Extract minimumFee for Fast Transfer (finalityThreshold 1000)
  const minimumFee = fees[0].minimumFee; // Fee in basis points

  // Calculate fee as percentage of transfer amount
  const protocolFee =
    (transferAmount * BigInt(Math.round(minimumFee * 100))) / 1_000_000n;

  // Add 20% buffer to protocol fee (protocolFee × 1.2) - result in subunits
  const maxFee = (protocolFee * 120n) / 100n;

  return maxFee; // denominated in USDC subunits (6 decimals)
}

// Use in your burn call
const maxFee = await calculateMaxFee(0, 1, "10.5");
```

## Fee tables

The following tables show the current fee rates by source blockchain for Fast
and Standard Transfers. Fees are subject to change at any time.

<Warning>
  **Do not hardcode fee values.** Fees can change at any time. Always retrieve the
  current fee by calling the [fee API](/api-reference/cctp/all/get-burn-usdc-fees)
  at least once per week. Hardcoding fees can cause:

  * **Insufficient fees**: If fees increase, your Fast Transfers may be degraded
    to Standard Transfers when the provided `maxFee` is below the required
    threshold.
  * **Overstated fees**: If fees decrease, users may see higher fees than
    necessary in your UI, even though the excess is refunded during minting.
</Warning>

<Tabs>
  <Tab title="Fast Transfer fee">
    | Source blockchain | Fee              |
    | ----------------- | ---------------- |
    | Arbitrum          | 1.3 bps (0.013%) |
    | Base              | 1.3 bps (0.013%) |
    | Codex             | 1.5 bps (0.015%) |
    | EDGE              | 1.5 bps (0.015%) |
    | Ethereum          | 1 bps (0.01%)    |
    | Ink               | 2 bps (0.02%)    |
    | Linea             | 11 bps (0.11%)   |
    | Morph             | 4 bps (0.04%)    |
    | OP Mainnet        | 1.3 bps (0.013%) |
    | Plume             | 2 bps (0.02%)    |
    | Solana            | 1 bps (0.01%)    |
    | Starknet          | 14 bps (0.14%)   |
    | Unichain          | 1.5 bps (0.015%) |
    | World Chain       | 1.3 bps (0.013%) |

    <Note>
      **Blockchains without Fast Transfer fees**

      Some blockchains don't appear in the Fast Transfer fee table because their
      standard attestation times are already fast enough. Consequently, Fast Transfer
      is not applicable when these blockchains are used as the source blockchain for
      burns. For affected blockchains, see
      [CCTP supported blockchains](/cctp/concepts/supported-chains-and-domains).
    </Note>
  </Tab>

  <Tab title="Standard Transfer fee">
    | Source blockchain | Fee        |
    | ----------------- | ---------- |
    | Arbitrum          | 0 bps (0%) |
    | Arc Testnet       | 0 bps (0%) |
    | Avalanche         | 0 bps (0%) |
    | Base              | 0 bps (0%) |
    | Codex             | 0 bps (0%) |
    | EDGE              | 0 bps (0%) |
    | Ethereum          | 0 bps (0%) |
    | HyperEVM          | 0 bps (0%) |
    | Injective         | 0 bps (0%) |
    | Ink               | 0 bps (0%) |
    | Linea             | 0 bps (0%) |
    | Monad             | 0 bps (0%) |
    | Morph             | 0 bps (0%) |
    | OP Mainnet        | 0 bps (0%) |
    | Pharos            | 0 bps (0%) |
    | Plume             | 0 bps (0%) |
    | Polygon PoS       | 0 bps (0%) |
    | Sei               | 0 bps (0%) |
    | Solana            | 0 bps (0%) |
    | Sonic             | 0 bps (0%) |
    | Starknet          | 0 bps (0%) |
    | Unichain          | 0 bps (0%) |
    | World Chain       | 0 bps (0%) |
    | XDC               | 0 bps (0%) |
  </Tab>
</Tabs>

## Standard Transfer fee switch

Some blockchains support a Standard Transfer fee switch, which enables enforcing
a minimum fee during a CCTP Standard Transfer.

* Some deployments of the `TokenMessengerV2` contract include a fee switch that
  enforces a minimum onchain fee. This fee is collected during USDC minting in a
  Standard Transfer. See tables below for supported blockchains.
* `TokenMessengerV2` contracts with fee switch support include the
  `getMinFeeAmount` function, which calculates and returns the minimum fee
  required for a given burn amount, in units of the `burnToken`.

<Note>
  **Important:** Calling `getMinFeeAmount` on a blockchain that uses an older
  `TokenMessengerV2` contract (without fee switch support) results in an error.
  Refer to the tables below to determine which contract version is deployed on
  each EVM blockchain.
</Note>

### `TokenMessenger` contracts without fee switch support

| Source blockchain | Contract source code                                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| Arbitrum          | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| Avalanche         | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| Base              | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| Codex             | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| Ethereum          | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| Linea             | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| OP Mainnet        | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| Polygon PoS       | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| Sonic             | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| Unichain          | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |
| World Chain       | [`7d70310`](https://github.com/circlefin/evm-cctp-contracts/pull/57/commits/7d703109a2cfcb3f76375fef5f1a97f03c447b94) |

### `TokenMessenger` contracts with fee switch support

| Source blockchain | Contract source code                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
| Sei               | [`2f9a2ba`](https://github.com/circlefin/evm-cctp-contracts/commit/2f9a2ba993b96a442c75bf21b3cb6d6292d81439) |

## Fee optimization strategies

To minimize fees while maximizing transfer speed:

* **Choose the right method**: Use Fast Transfer when speed is critical and
  Standard Transfer when cost optimization is the priority.
* **Monitor allowance**: For high-volume applications, monitor the
  [Fast Transfer allowance](/cctp/concepts/fast-transfer-allowance) and switch
  to Standard Transfer when it's low.
* **Batch transfers**: If you're making multiple transfers, consider batching
  them during periods when Fast Transfer allowance is high.
* **Set appropriate `maxFee`**: Always retrieve the current fee before
  initiating a transfer and set `maxFee` with a buffer to account for minor
  fluctuations.


# Finality and Block Confirmations
Source: https://developers.circle.com/cctp/concepts/finality-and-block-confirmations

Block confirmation requirements and attestation timing for CCTP

Before signing an attestation, Circle waits for blockchain transactions to
achieve the appropriate level of transaction finality. The required finality
level depends on whether you use Fast Transfer or Standard Transfer.

* Fast Transfer: Attestations are issued after the transaction is confirmed and
  included in a block, typically in seconds. Because of the faster finality
  time, Fast Transfers are subject to a global allowance to mitigate
  reorganization risks.
* Standard Transfer: Attestations are issued after hard finality, when the
  transaction is unlikely to be reversed by a chain reorganization, typically in
  minutes.

## Fast Transfer attestation times

The table below shows the average time for attestations to become available when
using Fast Transfer (`minFinalityThreshold` ≤ 1000):

| Source blockchain | Block confirmations | Average time |
| ----------------- | ------------------- | ------------ |
| **Ethereum**      | 2                   | \~20 seconds |
| **Arbitrum**      | 1                   | \~8 seconds  |
| **Base**          | 1                   | \~8 seconds  |
| **Codex**         | 1                   | \~8 seconds  |
| **EDGE**          | 1                   | \~8 seconds  |
| **Ink**           | 1                   | \~8 seconds  |
| **Linea**         | 1                   | \~8 seconds  |
| **Morph**         | 1                   | \~8 seconds  |
| **OP Mainnet**    | 1                   | \~8 seconds  |
| **Plume**         | 1                   | \~8 seconds  |
| **Solana**        | 2-3                 | \~8 seconds  |
| **Starknet**      | 4                   | \~20 seconds |
| **Unichain**      | 1                   | \~8 seconds  |
| **World Chain**   | 1                   | \~8 seconds  |

<Note>
  **Blockchains without Fast Transfer:**

  Some blockchains don't support Fast Transfer as a source blockchain because
  their standard attestation times are already fast. For those
  [CCTP supported blockchains](/cctp/concepts/supported-chains-and-domains) where
  Fast Transfer is disabled as a source, use Standard Transfer instead.
</Note>

## Standard Transfer attestation times

The table below shows the average time for attestations to become available when
using Standard Transfer (`minFinalityThreshold` ≥ 2000):

| Source blockchain   | Block confirmations | Average time    |
| ------------------- | ------------------- | --------------- |
| **Ethereum**        | \~65                | \~15-19 minutes |
| **Arbitrum**        | \~65 ETH blocks     | \~15-19 minutes |
| **Arc Testnet**     | 1                   | \~0.5 seconds   |
| **Avalanche**       | 1                   | \~8 seconds     |
| **Base**            | \~65 ETH blocks     | \~15-19 minutes |
| **BNB Smart Chain** | 3                   | \~2 seconds     |
| **Codex**           | \~65 ETH blocks     | \~15-19 minutes |
| **EDGE**            | \~65 ETH blocks     | \~16-21 minutes |
| **HyperEVM**        | 1                   | \~5 seconds     |
| **Injective**       | 1                   | \~0.65 seconds  |
| **Ink**             | \~65 ETH blocks     | \~30 minutes    |
| **Linea**           | 1                   | \~6-32 hours    |
| **Monad**           | 1                   | \~5 seconds     |
| **Morph**           | \~65 ETH blocks     | \~20-30 minutes |
| **OP Mainnet**      | \~65 ETH blocks     | \~15-19 minutes |
| **Pharos**          | 1                   | \~7 seconds     |
| **Plume**           | \~65 ETH blocks     | \~15-19 minutes |
| **Polygon PoS**     | 2-3                 | \~8 seconds     |
| **Sei**             | 1                   | \~5 seconds     |
| **Solana**          | 32                  | \~25 seconds    |
| **Sonic**           | 1                   | \~8 seconds     |
| **Starknet**        | \~65 ETH Blocks     | \~4 to 8 hours  |
| **Stellar**         | 1                   | \~5 seconds     |
| **Unichain**        | \~65 ETH blocks     | \~15-19 minutes |
| **World Chain**     | \~65 ETH blocks     | \~15-19 minutes |
| **XDC**             | 3                   | \~10 seconds    |

## Layer 2 finality

Layer 2 (L2) blockchains built on Ethereum publish transaction data in batches
to Ethereum Layer 1. The finality characteristics of L2 chains depend on when
batches are posted and when those batches achieve finality on Ethereum L1.

<CardGroup>
  <Card title="OP Stack chains" icon="layer-group">
    OP Stack-based chains (including Base, OP Mainnet, and World Chain) post
    state updates using [EIP-4844](https://www.eip4844.com/) blob transactions
    approximately every 15 minutes. Circle waits for the Ethereum L1 block
    containing the batch to finalize, which typically takes \~65 blocks (15-19
    minutes) after the batch is posted.
  </Card>

  <Card title="Linea" icon="clock">
    Linea has a longer finality period compared to other L2 chains. Standard
    Transfer on Linea typically requires 6-32 hours before attestations become
    available.
  </Card>

  <Card title="Starknet" icon="clock">
    The typical time to reach hard finality on Starknet is 4–8 hours, as finality
    depends on when the zk-rollup proof is posted to Ethereum and when its
    corresponding L1 block finalizes.
  </Card>
</CardGroup>

## Solana finality

Solana uses a different finality model:

<CardGroup>
  <Card title="Fast Transfer" icon="bolt">
    Circle waits for the block to be confirmed (votes from validators
    representing over two-thirds of total stake). This typically takes 2-3
    blocks (\~8 seconds).
  </Card>

  <Card title="Standard Transfer" icon="shield-check">
    Circle waits for block finality, which takes 32 blocks (\~25 seconds).
  </Card>
</CardGroup>


# Circle Forwarding Service for CCTP
Source: https://developers.circle.com/cctp/concepts/forwarding-service

Forward destination chain mints to simplify crosschain transfers

The Circle Forwarding Service is a service for CCTP that simplifies integration
by removing the need for you to run multichain infrastructure. This can improve
user experience for crosschain transfers by ensuring reliability and eliminating
the need to handle destination chain gas fees.

## How it works

A CCTP transfer without the Forwarding Service is a three-step process:

1. Create a transaction to burn USDC on the source chain and wait for Circle to
   sign an attestation.
2. Request an attestation from the Circle API.
3. Create a transaction to mint USDC on the destination chain.

This process requires you to have a wallet that can sign transactions on the
source and destination chains, and native tokens for paying the transaction gas
fee on both chains.

You use the Forwarding Service by including a forward request in the hook data
of the burn transaction on the source chain. Circle validates the hook data,
signs the attestation, and broadcasts the mint transaction on the destination
chain for you, removing the need for you to handle the transaction on the
destination chain.

For a full example of how to use the Forwarding Service, see
[Transfer USDC with the Forwarding Service](/cctp/howtos/transfer-usdc-with-forwarding-service).

### Hook format

The hook data for Forwarding Service begins with the reserved magic bytes
`cctp-forward` followed by versioning and payload fields. You can append your
own custom hook data after Circle's reserved space. Forwarding Service doesn't
support forwarding to wrapper contracts (for example, when `destinationCaller`
is set).

| Bytes | Type      | Data                                              |
| ----- | --------- | ------------------------------------------------- |
| 0-23  | `bytes24` | `cctp-forward`                                    |
| 24-27 | `uint32`  | Version, set to `0`                               |
| 28-31 | `uint32`  | Length of additional Circle hook data, set to `0` |
| 32-51 | `any`     | Developer-defined hook data                       |

If no additional integrator hook data is required, a static hex string can be
used for the forwarding hook data:

```javascript theme={null}
// Includes magic bytes ("cctp-forward") + hook version (0) + empty data length (0)
const forwardHookData =
  "0x636374702d666f72776172640000000000000000000000000000000000000000";
```

### Solana `mintRecipient`

When the destination blockchain is Solana, the `mintRecipient` parameter in
`depositForBurnWithHook` must be the recipient's USDC
[Associated Token Account (ATA)](https://spl.solana.com/associated-token-account)
address, not the recipient's wallet address. Unlike EVM destinations where
`mintRecipient` is the wallet address, Solana requires the address of the SPL
token account that will hold the minted USDC.

You can derive the ATA address from the recipient's wallet address and the USDC
mint address using the
[`getAssociatedTokenAddressSync`](https://solana-labs.github.io/solana-program-library/token/js/functions/getAssociatedTokenAddressSync.html)
function from the `@solana/spl-token` library:

```typescript theme={null}
import { getAssociatedTokenAddressSync } from "@solana/spl-token";
import { PublicKey } from "@solana/web3.js";

const recipientWallet = new PublicKey("RecipientWalletAddress");
const USDC_MINT = new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"); // Solana devnet

const recipientAta = getAssociatedTokenAddressSync(USDC_MINT, recipientWallet);
const mintRecipient = `0x${Buffer.from(recipientAta.toBytes()).toString("hex")}`;
```

### Solana hook data for ATA creation

If the recipient does not have an existing USDC ATA, you can request the
Forwarding Service to create it by encoding additional fields in the hook data.
The extended hook data format is:

| Bytes | Type      | Data                                               |
| ----- | --------- | -------------------------------------------------- |
| 0-23  | `bytes24` | `cctp-forward`                                     |
| 24-27 | `uint32`  | Version, set to `0`                                |
| 28-31 | `uint32`  | Length of additional Circle hook data, set to `33` |
| 32    | `uint8`   | `1` (request ATA creation)                         |
| 33-64 | `bytes32` | Recipient wallet address (ATA owner)               |
| 65+   | `any`     | Developer-defined hook data                        |

When using this format, the `mintRecipient` must be the ATA derived from the
wallet address in bytes 33-64 and the USDC mint. The Forwarding Service
validates that these values are consistent before creating the account.

The following example shows how to construct the extended hook data for Solana
with ATA creation:

```typescript theme={null}
import { PublicKey } from "@solana/web3.js";

// Magic bytes "cctp-forward" padded to 24 bytes
const magicBytes = Buffer.alloc(24);
magicBytes.write("cctp-forward", "utf-8");

// Version (uint32, big-endian) = 0
const version = Buffer.alloc(4);

// Length of additional Circle hook data (uint32, big-endian) = 33
const length = Buffer.alloc(4);
length.writeUInt32BE(33);

// ATA creation flag = 1
const ataFlag = Buffer.from([1]);

// Recipient wallet address (32 bytes)
const recipientWallet = new PublicKey("RecipientWalletAddress");
const walletBytes = Buffer.from(recipientWallet.toBytes());

const forwardHookData =
  "0x" +
  Buffer.concat([magicBytes, version, length, ataFlag, walletBytes]).toString(
    "hex",
  );
```

If the recipient already has a USDC ATA and no ATA creation is needed, use the
same static hook data as EVM:

```typescript theme={null}
// Includes magic bytes ("cctp-forward") + hook version (0) + empty data length (0)
const forwardHookData =
  "0x636374702d666f72776172640000000000000000000000000000000000000000";
```

## Fees and execution

The Forwarding Service charges a fee for each transfer, in addition to the CCTP
protocol fee. The Forwarding Service fee charged is to cover gas costs on the
destination chain and a small service fee. The Forwarding Service prioritizes
fast execution and quotes gas dynamically. If gas used is less than gas needed
for execution, the remainder is spent as an additional priority fee where they
are supported. On all chains, a higher fee provides a safety buffer for
successful transaction delivery on the destination chain. Circle does not refund
for excess gas and does not keep the excess gas, except in cases where excess
priority fees are rejected.

The
[`depositForBurnWithHook`](/cctp/references/contract-interfaces#depositforburnwithhook)
transaction includes a `maxFee` parameter. When using the Forwarding Service,
this parameter should be set to a value that is large enough to cover the CCTP
protocol fee and the Forwarding Service fee. Because the gas budget for the
destination chain comes from a USDC fee on the source chain, choosing a lower
`maxFee` results in a lower priority fee on the destination chain. A higher
`maxFee` results in a higher priority fee on the destination chain and can
result in faster confirmation.

The Forwarding Service charges a service fee for each transfer:

| Destination chain | Service fee (USDC) |
| ----------------- | ------------------ |
| All chains        | \$0.20             |

<Warning>
  If the `maxFee` parameter is insufficient to cover the both Fast Transfer
  protocol fee and the Forwarding Service fee, CCTP will prioritize forwarding
  execution over Fast Transfer. This means that the transfer will execute as a
  Standard Transfer with the Forwarding Service.
</Warning>

### Solana fees

When forwarding to Solana, the Forwarding Service fee includes both a gas
component and a rent component. Rent covers the cost of creating onchain
accounts required by each transfer. The fee estimate API returns `forwardFee`
values that already include rent, so no additional calculation is needed on your
part.

If the recipient does not already have a USDC
[Associated Token Account (ATA)](https://spl.solana.com/associated-token-account)
on Solana, the transfer will fail. To have the Forwarding Service create the
ATA, you must:

1. Pass `includeRecipientSetup=true` when calling the fee estimate API so the
   returned `forwardFee` covers the ATA creation cost.
2. Encode the ATA creation fields in the
   [hook data](#solana-hook-data-for-ata-creation) of the burn transaction.

```http theme={null}
GET /v2/burn/USDC/fees/{sourceDomain}/{destDomain}?forward=true&includeRecipientSetup=true
```

For full details on this endpoint, see the
[`GET /v2/burn/USDC/fees` API reference](/api-reference/cctp/all/get-burn-usdc-fees).

<Note>
  `includeRecipientSetup` only applies when the destination blockchain is Solana.
  It has no effect for EVM destination blockchains.
</Note>

## Supported blockchains

For a full list of supported blockchains, see
[CCTP Supported Blockchains](/cctp/concepts/supported-chains-and-domains).


# Supported Blockchains and Domains
Source: https://developers.circle.com/cctp/concepts/supported-chains-and-domains

Blockchains and domain identifiers supported by CCTP

CCTP is available on multiple blockchains where USDC is natively issued. Each
blockchain is assigned a unique domain identifier used in
[CCTP contracts](/cctp/references/contract-addresses) and API calls.

## Supported blockchains

CCTP provides
[Standard Transfer](/cctp/concepts/finality-and-block-confirmations#standard-transfer-attestation-times),
[Fast Transfer](/cctp/concepts/finality-and-block-confirmations#fast-transfer-attestation-times),
Hooks, and [Forwarding Service](/cctp/concepts/forwarding-service) capabilities
on the following blockchains. All chains listed below are supported as
destination chains.

| Blockchain                  | Source (Standard transfer) | Source (Fast transfer) | Forwarding Service |
| --------------------------- | -------------------------- | ---------------------- | ------------------ |
| Arc Testnet                 | ✅                          | ❌                      | ✅                  |
| Arbitrum                    | ✅                          | ✅                      | ✅                  |
| Avalanche                   | ✅                          | ❌                      | ✅                  |
| Base                        | ✅                          | ✅                      | ✅                  |
| BNB Smart Chain (USYC only) | ✅                          | ✅                      | ❌                  |
| Codex                       | ✅                          | ✅                      | ✅                  |
| EDGE                        | ✅                          | ✅                      | ✅                  |
| Ethereum                    | ✅                          | ✅                      | ✅                  |
| HyperEVM                    | ✅                          | ❌                      | ✅                  |
| Injective                   | ✅                          | ❌                      | ❌                  |
| Ink                         | ✅                          | ✅                      | ✅                  |
| Linea                       | ✅                          | ✅                      | ✅                  |
| Monad                       | ✅                          | ❌                      | ✅                  |
| Morph                       | ✅                          | ✅                      | ❌                  |
| OP Mainnet                  | ✅                          | ✅                      | ✅                  |
| Pharos                      | ✅                          | ❌                      | ❌                  |
| Plume                       | ✅                          | ✅                      | ✅                  |
| Polygon PoS                 | ✅                          | ❌                      | ✅                  |
| Sei                         | ✅                          | ❌                      | ✅                  |
| Solana                      | ✅                          | ✅                      | ✅                  |
| Sonic                       | ✅                          | ❌                      | ✅                  |
| Starknet                    | ✅                          | ✅                      | ❌                  |
| Stellar                     | ✅                          | ✅                      | ❌                  |
| Unichain                    | ✅                          | ✅                      | ✅                  |
| World Chain                 | ✅                          | ✅                      | ✅                  |
| XDC                         | ✅                          | ❌                      | ✅                  |

<Note>
  On Stellar, USDC precision and address encoding differ from other CCTP-supported
  blockchains. For inbound transfers, use
  [`CctpForwarder`](/cctp/references/stellar#use-cctpforwarder-for-stellar-recipients)
  so funds reach the correct recipient. See
  [CCTP on Stellar](/cctp/references/stellar).
</Note>

<Note>
  **Forwarding Service support:**

  The column labeled "Forwarding Service" indicates whether the blockchain is
  available as a destination chain for the
  [Circle Forwarding Service](/cctp/concepts/forwarding-service).

  **Testnet support:**

  If a mainnet is listed, its official testnet is also supported. For example,
  Ethereum includes both Ethereum Mainnet and Ethereum Sepolia.

  **Fast Transfer availability:**

  [Fast Transfer](/cctp/concepts/fast-transfer-allowance) is available for source
  chains only when it provides a meaningful speed improvement over standard burn
  attestation times. For blockchains where standard attestation is already fast,
  Fast Transfer does not provide additional value.
</Note>

## Domain identifiers

A domain is a Circle-issued identifier for a blockchain where CCTP contracts are
deployed. Domain identifiers don't map to existing public chain IDs.

Use domain identifiers when calling CCTP contracts and API endpoints:

| Domain | Blockchain      |
| :----- | :-------------- |
| 0      | Ethereum        |
| 1      | Avalanche       |
| 2      | OP Mainnet      |
| 3      | Arbitrum        |
| 5      | Solana          |
| 6      | Base            |
| 7      | Polygon PoS     |
| 10     | Unichain        |
| 11     | Linea           |
| 12     | Codex           |
| 13     | Sonic           |
| 14     | World Chain     |
| 15     | Monad           |
| 16     | Sei             |
| 17     | BNB Smart Chain |
| 18     | XDC             |
| 19     | HyperEVM        |
| 21     | Ink             |
| 22     | Plume           |
| 25     | Starknet        |
| 26     | Arc Testnet     |
| 27     | Stellar         |
| 28     | EDGE            |
| 29     | Injective       |
| 30     | Morph           |
| 31     | Pharos          |

## Supported tokens

Not all domains support the same tokens:

* [USDC](/stablecoins/what-is-usdc): Supported on all CCTP domains except BNB
  Smart Chain
* [USYC](/tokenized/usyc/overview): Supported only on Ethereum and BNB Smart
  Chain

## CCTP V1 (Legacy) only

The following blockchains are supported only by CCTP V1 (Legacy). If you are
building on these chains, refer to the [V1 documentation](/cctp/v1) for
integration guides and contract references.

| Blockchain | Domain | Documentation                                                                                                 |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| Aptos      | 9      | [Aptos packages](/cctp/v1/aptos-packages), [Quickstart](/cctp/v1/transfer-usdc-on-testnet-from-aptos-to-base) |
| Noble      | 4      | [Noble Cosmos module](/cctp/v1/noble-cosmos-module)                                                           |
| Sui        | 8      | [Sui packages](/cctp/v1/sui-packages), [Quickstart](/cctp/v1/transfer-usdc-on-testnet-from-sui-to-ethereum)   |


# Get the Fast Transfer Allowance
Source: https://developers.circle.com/cctp/howtos/get-fast-transfer-allowance

Check the remaining Fast Transfer allowance for USDC transfers

This how-to shows you how to retrieve the remaining Fast Transfer allowance
using the [CCTP API](/api-reference/cctp/all/get-fast-burn-usdc-allowance). The
Fast Transfer allowance is Circle's mechanism for backing faster-than-finality
USDC transfers before burns reach hard finality on source chains.

## Prerequisites

Before you begin, ensure you have:

* Installed cURL on your development machine

## Get the Fast Transfer allowance

Call the
[`GET /v2/fastBurn/USDC/allowance`](/api-reference/cctp/all/get-fast-burn-usdc-allowance)
endpoint to retrieve the current remaining Fast Transfer allowance.

**Example request**

```shell Shell theme={null}
curl --request GET \
  --url 'https://iris-api-sandbox.circle.com/v2/fastBurn/USDC/allowance' \
  --header 'Accept: application/json'
```

**Response**

```json theme={null}
{ "allowance": 99999999225.24174, "lastUpdated": "2025-12-02T13:17:02.453Z" }
```

The response includes:

* `allowance`: The remaining Fast Transfer allowance in USDC units
* `lastUpdated`: The UTC timestamp when the allowance was last updated

<Note>
  **Fast Transfer allowance details:**

  * The allowance represents the total value of USDC that can be minted through
    Fast Transfer before related burns on source chains reach hard finality.
  * When you initiate a Fast Transfer, the burn amount temporarily debits the
    allowance.
  * Once the burn reaches finality on the source chain, the corresponding amount
    is credited back to the allowance.
  * If the allowance is insufficient for your transfer, you should either wait for
    the allowance to replenish or use Standard Transfer instead.
</Note>


# Get the Fee for Your Transfer
Source: https://developers.circle.com/cctp/howtos/get-transfer-fee

Retrieve CCTP transfer fees using the API

This guide shows you how to retrieve the fee for a USDC transfer using the CCTP
API. Fees vary based on the source and destination blockchains, and whether you
use Fast Transfer or Standard Transfer.

## Prerequisites

Before you begin, ensure you have:

* Installed cURL on your development machine

## Get the transfer fee

Call the [`GET /v2/burn/USDC/fees`](/api-reference/cctp/all/get-burn-usdc-fees)
endpoint to retrieve the fees for transferring USDC between two blockchains.

**Request parameters**

* `sourceDomainId`: The
  [domain ID](/cctp/concepts/supported-chains-and-domains#domain-identifiers) of
  the source blockchain
* `destDomainId`: The domain ID of the destination blockchain

**Example request**

```shell Shell theme={null}
curl --request GET \
  --url 'https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/0/26' \
  --header 'Accept: application/json'
```

This example retrieves the fees for transferring USDC from Ethereum Sepolia
(domain 0) to Arc Testnet (domain 26).

**Response**

```json theme={null}
[
  { "finalityThreshold": 1000, "minimumFee": 1 },
  { "finalityThreshold": 2000, "minimumFee": 0 }
]
```

<Note>
  **Fee details:**

  * Fees are specified in basis points (bps), for example, 1 = 0.01%.
  * Fast Transfer fees vary by route.
  * You specify the maximum fee you're willing to pay when calling
    `depositForBurn`. The actual fee charged will not exceed this amount.
</Note>


# Resolve Attestation Issues
Source: https://developers.circle.com/cctp/howtos/resolve-stuck-attestation

Troubleshoot and resolve common problems with CCTP attestations

This guide helps you resolve issues when a CCTP attestation takes longer than
expected to become available or when the attestation API returns unexpected
responses.

## Understanding attestation timing

After a successful burn transaction, Circle's Attestation Service (Iris) must:

1. Observe the burn event on the source blockchain
2. Wait for sufficient block confirmations
3. Sign the message and make the attestation available through the
   [CCTP API](/api-reference/cctp/all/get-messages-v2)

This process takes different amounts of time depending on the transfer type:

| Transfer type     | Finality threshold | Typical wait time                                                                                              |
| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------------- |
| Fast Transfer     | ≤ 1000             | Seconds to a few minutes                                                                                       |
| Standard Transfer | ≥ 2000             | Varies by blockchain (see [Finality and Block Confirmations](/cctp/concepts/finality-and-block-confirmations)) |

## Why 404 responses are expected

The attestation API returns a 404 response until the attestation service has
observed and processed your burn transaction. This is expected and does not
indicate an error.

The API returns 404 when:

* The burn transaction hasn't reached the required block confirmations
* The attestation service hasn't yet indexed the transaction
* The transaction hash or domain ID is incorrect

Don't treat 404 as a failure. Instead, implement polling with appropriate
intervals.

## Check attestation status

Query the [`GET /v2/messages`](/api-reference/cctp/all/get-messages-v2) endpoint
to check the current status of your attestation.

The following table explains the possible responses and what to do next:

| Response                   | Meaning                             | Action                                                     |
| -------------------------- | ----------------------------------- | ---------------------------------------------------------- |
| 404                        | Attestation not yet observed        | Continue polling until the attestation is available        |
| `{ "messages": [] }`       | Transaction found but not processed | Continue polling until the transaction is processed        |
| `{ "status": "pending" }`  | Awaiting block confirmations        | Continue polling until the block confirmations are reached |
| `{ "status": "complete" }` | Attestation ready                   | Proceed to mint                                            |

## Implement effective polling

Poll the attestation API at regular intervals without exceeding rate limits:

```ts TypeScript theme={null}
async function waitForAttestation(
  sourceDomain: number,
  transactionHash: string,
) {
  const pollInterval = 5000; // Poll every 5 seconds
  const maxWaitTime = 1200000; // 20 minutes maximum
  const startTime = Date.now();

  while (Date.now() - startTime < maxWaitTime) {
    try {
      const response = await fetch(
        `https://iris-api-sandbox.circle.com/v2/messages/${sourceDomain}?transactionHash=${transactionHash}`,
      );

      // 404 is expected while waiting - continue polling
      if (response.status === 404) {
        console.log("Attestation not yet available (404), waiting...");
        await new Promise((resolve) => setTimeout(resolve, pollInterval));
        continue;
      }

      // Rate limited - wait before retrying
      if (response.status === 429) {
        console.log("Rate limited, waiting 5 minutes...");
        await new Promise((resolve) => setTimeout(resolve, 300000));
        continue;
      }

      if (!response.ok) {
        throw new Error(`Unexpected HTTP error: ${response.status}`);
      }

      const data = await response.json();

      // Empty messages array - transaction found but not processed
      if (!data.messages || data.messages.length === 0) {
        console.log("Transaction found, awaiting processing...");
        await new Promise((resolve) => setTimeout(resolve, pollInterval));
        continue;
      }

      const message = data.messages[0];

      // Attestation complete
      if (message.status === "complete" && message.attestation) {
        console.log("Attestation retrieved successfully!");
        return {
          message: message.message,
          attestation: message.attestation,
          decodedMessage: message.decodedMessage,
        };
      }

      // Still pending
      console.log(`Attestation status: ${message.status}`);
      await new Promise((resolve) => setTimeout(resolve, pollInterval));
    } catch (error) {
      console.error("Error fetching attestation:", (error as Error).message);
      await new Promise((resolve) => setTimeout(resolve, pollInterval));
    }
  }

  throw new Error("Attestation not received within maximum wait time");
}
```

### Avoid rate limiting

The attestation service limits requests to 35 per second. If you exceed this
limit, the service blocks all API requests for 5 minutes and returns HTTP 429.

Best practices:

* Use a poll interval of at least 5 seconds
* Implement exponential back-off for repeated 429 responses
* Don't poll from multiple clients for the same transaction

## Troubleshooting checklist

If your attestation isn't available after the expected wait time:

<Steps>
  <Step title="Verify the burn transaction">
    Check the source blockchain's block explorer to confirm:

    * The transaction succeeded (not reverted)
    * The transaction is included in a mined block
    * Sufficient blocks have been confirmed since the transaction
  </Step>

  <Step title="Confirm request parameters">
    Verify you're using the correct:

    * Source domain ID (see
      [Supported Chains and Domains](/cctp/concepts/supported-chains-and-domains))
    * Transaction hash (full hash, including `0x` prefix for EVM chains)
    * API environment (sandbox vs. production)
  </Step>

  <Step title="Check finality requirements">
    Standard Transfers require full finality. For some blockchains, this can take
    significantly longer than Fast Transfers. Check
    [Finality and Block Confirmations](/cctp/concepts/finality-and-block-confirmations)
    for expected times.
  </Step>

  <Step title="Verify API connectivity">
    Test that you can reach the API:

    ```shell Shell theme={null}
    curl --request GET \
      --url 'https://iris-api-sandbox.circle.com/v2/publicKeys' \
      --header 'Accept: application/json'
    ```

    If this fails, check your network connectivity and firewall settings.
  </Step>
</Steps>


# Retry a Failed Mint
Source: https://developers.circle.com/cctp/howtos/retry-failed-mint

Complete a CCTP transfer when the mint transaction fails

This guide helps you complete a CCTP transfer when you have a valid attestation
but the mint transaction on the destination blockchain fails or was never
submitted.

## Minting is safe to retry

CCTP minting is idempotent. Each attestation contains a unique nonce that can
only be used once. If you submit the same attestation multiple times, only the
first successful transaction mints USDC. Subsequent attempts revert with a
"nonce already used" error but don't result in duplicate minting.

This means you can safely retry a failed mint without risking double-spending.

## Common mint failure reasons

| Failure reason                       | Symptoms                                    | Solution                                                                                      |
| ------------------------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Insufficient gas                     | Transaction reverts or times out            | Increase gas limit and retry                                                                  |
| Nonce already used                   | Transaction reverts with nonce error        | The mint already succeeded; check recipient balance                                           |
| Wrong contract address               | Transaction may succeed with no USDC minted | Verify you're using the correct `MessageTransmitterV2` address for the destination blockchain |
| Destination caller restriction       | Transaction reverts                         | Check if the burn specified a `destinationCaller`; only that address can mint                 |
| Token account doesn't exist (Solana) | Transaction fails                           | Create the recipient's USDC token account first                                               |
| Attestation expired                  | Transaction reverts                         | Use re-attestation API to get a fresh attestation                                             |

## Verify the current state

Before retrying, check whether the mint already succeeded:

<Steps>
  <Step title="Check recipient balance">
    Query the recipient's USDC balance on the destination blockchain. If the
    expected amount is present, the mint already completed.
  </Step>

  <Step title="Check for existing mint transaction">
    Search the destination blockchain's block explorer for `receiveMessage`
    transactions from your wallet to the `MessageTransmitterV2` contract.
  </Step>

  <Step title="Check attestation status">
    Query the [attestation API](/api-reference/cctp/all/get-messages-v2) to confirm
    you have a `complete` status:
  </Step>
</Steps>

## Retry the mint transaction

If the mint hasn't completed, submit a new `receiveMessage` transaction using
your attestation.

<Tabs>
  <Tab title="EVM chains">
    Call `receiveMessage` on the `MessageTransmitterV2` contract:

    ```ts TypeScript theme={null}
    import {
      createWalletClient,
      createPublicClient,
      http,
      encodeFunctionData,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet } from "viem/chains";

    interface AttestationData {
      message: string;
      attestation: string;
    }

    const PRIVATE_KEY = process.env.EVM_PRIVATE_KEY!;
    const account = privateKeyToAccount(PRIVATE_KEY as `0x${string}`);

    const walletClient = createWalletClient({
      chain: arcTestnet,
      transport: http(),
      account,
    });
    const publicClient = createPublicClient({
      chain: arcTestnet,
      transport: http(),
    });

    // MessageTransmitterV2 contract address - verify for your destination chain
    // See: https://developers.circle.com/cctp/references/contract-addresses
    const MESSAGE_TRANSMITTER_V2 = "0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275";

    async function retryMint(data: AttestationData) {
      console.log("Retrying mint transaction...");

      try {
        const txHash = await walletClient.sendTransaction({
          to: MESSAGE_TRANSMITTER_V2,
          data: encodeFunctionData({
            abi: [
              {
                type: "function",
                name: "receiveMessage",
                stateMutability: "nonpayable",
                inputs: [
                  { name: "message", type: "bytes" },
                  { name: "attestation", type: "bytes" },
                ],
                outputs: [],
              },
            ],
            functionName: "receiveMessage",
            args: [
              data.message as `0x${string}`,
              data.attestation as `0x${string}`,
            ],
          }),
        });

        console.log(`Mint transaction submitted: ${txHash}`);

        // Wait for confirmation
        const receipt = await publicClient.waitForTransactionReceipt({
          hash: txHash,
        });

        if (receipt.status === "success") {
          console.log("Mint successful!");
          return { success: true, txHash };
        } else {
          console.log("Mint transaction reverted");
          return { success: false, txHash };
        }
      } catch (error) {
        // Check if the error indicates nonce already used
        const errorMessage = error instanceof Error ? error.message : String(error);
        if (errorMessage.includes("nonce") || errorMessage.includes("already")) {
          console.log(
            "Nonce already used - mint may have already completed. Check recipient balance.",
          );
        }
        throw error;
      }
    }

    // Use attestation data from the API
    const attestationData: AttestationData = {
      message: "0x00000001000000000000001a...", // Full message hex from API
      attestation: "0xde09db65dea64090570d8143...", // Full attestation hex from API
    };

    await retryMint(attestationData);
    ```
  </Tab>

  <Tab title="Solana">
    Call `receiveMessage` on the `MessageTransmitterV2` program. For Solana, ensure
    the recipient's USDC token account exists before calling `receiveMessage`.

    ```ts TypeScript theme={null}
    import crypto from "crypto";
    import {
      address,
      createKeyPairSignerFromBytes,
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      createTransactionMessage,
      getAddressEncoder,
      getProgramDerivedAddress,
      getSignatureFromTransaction,
      pipe,
      sendAndConfirmTransactionFactory,
      setTransactionMessageFeePayerSigner,
      setTransactionMessageLifetimeUsingBlockhash,
      appendTransactionMessageInstruction,
      signTransactionMessageWithSigners,
    } from "@solana/kit";
    import { SYSTEM_PROGRAM_ADDRESS } from "@solana-program/system";
    import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";

    interface AttestationData {
      message: string;
      attestation: string;
    }

    // Solana Configuration
    const SOLANA_RPC = "https://api.devnet.solana.com";
    const SOLANA_WS = "wss://api.devnet.solana.com";
    const rpc = createSolanaRpc(SOLANA_RPC);
    const rpcSubscriptions = createSolanaRpcSubscriptions(SOLANA_WS);
    const solanaPrivateKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY!);
    const solanaKeypair = await createKeyPairSignerFromBytes(
      Uint8Array.from(solanaPrivateKey),
    );

    // Solana CCTP Program Addresses (Devnet)
    const MESSAGE_TRANSMITTER_PROGRAM = address(
      "CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC",
    );
    const TOKEN_MESSENGER_MINTER_PROGRAM = address(
      "CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe",
    );
    const USDC_MINT = address("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");
    const ASSOCIATED_TOKEN_PROGRAM = address(
      "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
    );

    async function retryMintOnSolana(
      attestationData: AttestationData,
      sourceDomain: number,
    ) {
      console.log("Retrying mint on Solana...");

      const addressEncoder = getAddressEncoder();

      // Derive receiver's USDC token account
      const [receiverUsdcAccount] = await getProgramDerivedAddress({
        programAddress: ASSOCIATED_TOKEN_PROGRAM,
        seeds: [
          addressEncoder.encode(solanaKeypair.address),
          addressEncoder.encode(TOKEN_PROGRAM_ADDRESS),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      // Derive required PDAs
      const [messageTransmitter] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("message_transmitter")],
      });

      const [authorityPda] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("message_transmitter_authority")],
      });

      // Calculate used nonces PDA
      const messageBytes = Buffer.from(attestationData.message.slice(2), "hex");
      const nonce = messageBytes.readBigUInt64BE(12);
      const firstNonce = (nonce / 6400n) * 6400n;
      const firstNonceBuffer = Buffer.alloc(8);
      firstNonceBuffer.writeBigUInt64BE(firstNonce);

      const sourceDomainBuffer = Buffer.alloc(4);
      sourceDomainBuffer.writeUInt32BE(sourceDomain);

      const [usedNonces] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("used_nonces"),
          sourceDomainBuffer,
          firstNonceBuffer,
        ],
      });

      // Derive TokenMessengerMinterV2 PDAs
      const [tokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_messenger")],
      });

      const [remoteTokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("remote_token_messenger"),
          new TextEncoder().encode(sourceDomain.toString()),
        ],
      });

      const [tokenMinter] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_minter")],
      });

      const [localToken] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("local_token"),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      const sourceTokenBytes = messageBytes.slice(133, 165);
      const [tokenPair] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("token_pair"),
          sourceDomainBuffer,
          sourceTokenBytes,
        ],
      });

      const [custody] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("custody"),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      const [eventAuthority] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });

      const [tokenProgramEventAuthority] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });

      // Build instruction
      const discriminator = crypto
        .createHash("sha256")
        .update("global:receive_message")
        .digest()
        .slice(0, 8);

      const messageBuffer = Buffer.from(attestationData.message.slice(2), "hex");
      const attestationBuffer = Buffer.from(
        attestationData.attestation.slice(2),
        "hex",
      );

      const messageLenBuffer = Buffer.alloc(4);
      messageLenBuffer.writeUInt32LE(messageBuffer.length);

      const attestationLenBuffer = Buffer.alloc(4);
      attestationLenBuffer.writeUInt32LE(attestationBuffer.length);

      const instructionData = new Uint8Array(
        Buffer.concat([
          discriminator,
          messageLenBuffer,
          messageBuffer,
          attestationLenBuffer,
          attestationBuffer,
        ]),
      );

      const receiveMessageIx = {
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        accounts: [
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: solanaKeypair.address, role: 0 },
          { address: authorityPda, role: 0 },
          { address: messageTransmitter, role: 0 },
          { address: usedNonces, role: 1 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: SYSTEM_PROGRAM_ADDRESS, role: 0 },
          { address: eventAuthority, role: 0 },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
          { address: tokenMessenger, role: 0 },
          { address: remoteTokenMessenger, role: 0 },
          { address: tokenMinter, role: 1 },
          { address: localToken, role: 1 },
          { address: tokenPair, role: 0 },
          { address: receiverUsdcAccount, role: 1 },
          { address: custody, role: 1 },
          { address: TOKEN_PROGRAM_ADDRESS, role: 0 },
          { address: tokenProgramEventAuthority, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
        ],
        data: instructionData,
      };

      const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

      const transactionMessage = pipe(
        createTransactionMessage({ version: 0 }),
        (tx) => setTransactionMessageFeePayerSigner(solanaKeypair, tx),
        (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
        (tx) => appendTransactionMessageInstruction(receiveMessageIx, tx),
      );

      const signedTransaction =
        await signTransactionMessageWithSigners(transactionMessage);

      const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
        rpc,
        rpcSubscriptions,
      });

      try {
        await sendAndConfirmTransaction(
          signedTransaction as Parameters<typeof sendAndConfirmTransaction>[0],
          {
            commitment: "confirmed",
          },
        );

        const signature = getSignatureFromTransaction(signedTransaction);
        console.log(`Mint successful! Signature: ${signature}`);
        return signature;
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error);
        if (message.includes("already been processed")) {
          console.log("Nonce already used - mint may have already completed.");
        }
        throw error;
      }
    }

    // Use attestation data from the API
    const attestationData: AttestationData = {
      message: "0x000000000000000500000000...", // Full message hex from API
      attestation: "0xdc485fb2f9a8f68c871f4ca7386dee9086ff9d43...", // Full attestation hex from API
    };

    await retryMintOnSolana(attestationData, 0); // 0 = Ethereum Sepolia domain
    ```

    <Note>
      **Note:** The recipient's USDC token account must exist before calling
      `receiveMessage`. If the account doesn't exist, create it using the Associated
      Token Program before retrying the mint.
    </Note>
  </Tab>
</Tabs>

## Handle destination caller restrictions

If the burn specified a `destinationCaller` address, only that address can call
`receiveMessage`. If you're seeing authorization errors:

1. Check the `destinationCaller` field in the attestation's `decodedMessage`
2. If it's not `0x0000...0000`, ensure you're calling from the specified address


# Transfer USDC from Arbitrum to HyperCore
Source: https://developers.circle.com/cctp/howtos/transfer-usdc-from-arbitrum-to-hypercore



This guide shows how to transfer USDC from Arbitrum to HyperCore using the
`CctpExtension` contract.

<Note>
  Fast Transfers from Arbitrum to HyperEVM have no fees, however there is a flat
  forwarding fee for Arbitrum transfers to HyperCore. Fast Transfer is the default
  for transfers from Arbitrum to HyperEVM.
</Note>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)

* Prepared an EVM testnet wallet with the private key available
  * Added Arbitrum Sepolia network to your wallet
    ([network details](https://docs.arbitrum.io/build-decentralized-apps/reference/node-providers))

* Funded your wallet with the following testnet tokens:
  * Arbitrum Sepolia ETH (native token) from a
    [public faucet](https://faucet.quicknode.com/arbitrum/sepolia)
  * Arbitrum Sepolia USDC from the [Circle Faucet](https://faucet.circle.com)

* Created a new Node project and installed dependencies:

  ```bash theme={null}
  npm install viem
  npm install -D tsx typescript @types/node
  ```

* Created a `.env` file with required environment variables:

  ```text theme={null}
  PRIVATE_KEY=0x...
  FORWARD_RECIPIENT=0x...  # Your HyperCore address to receive the USDC
  ```

## Steps

Use the following steps to transfer USDC from Arbitrum to HyperCore.

### Step 1. Get CCTP fees from the API

Query the CCTP API for the fees for transferring USDC from Arbitrum to
HyperCore. This value is passed to the `maxFee` parameter in the
`batchDepositForBurnWithAuth` transaction. The following is an example request
to the CCTP using source domain 3 (Arbitrum) and destination domain 19
(HyperEVM):

```shell theme={null}
curl --request GET \
  --url 'https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/3/19?forward=true&hyperCoreDeposit=true' \
  --header 'Content-Type: application/json'
```

**Response:**

```json theme={null}
[
  {
    "finalityThreshold": 1000, // fast transfer
    "minimumFee": 0, // no protocol fee
    "forwardFee": {
      "low": 200000, // 0.20 USDC
      "med": 200000, // low, med, high will be the same static fee
      "high": 200000
    }
  },
  {
    "finalityThreshold": 2000, // standard transfer
    "minimumFee": 0,
    "forwardFee": {
      "low": 200000,
      "med": 200000,
      "high": 200000
    }
  }
]
```

### Step 2. Calculate the USDC amounts minus fees

There is no fee to deposit USDC from Arbitrum to HyperEVM, but there is a flat
forwarding fee for the transfer to HyperCore. The forwarding fee is 0.20 USDC
(`0_200_000` subunits). For a 10 USDC transfer from Arbitrum to HyperCore, the
total fee is 0.20 USDC.

<Note>
  The forwarding fee is deducted from your transfer amount. For a 10 USDC
  transfer, you will receive 9.80 USDC on HyperCore.
</Note>

### Step 3. Sign a `ReceiveWithAuthorization` transaction on the USDC contract

Create a `ReceiveWithAuthorization` transaction for the USDC contract with the
following parameters:

* `from`: Your wallet address
* `to`: The `CctpExtension` contract address
* `value`: The amount of USDC to transfer
* `validAfter`: The timestamp after which the transaction is valid
* `validBefore`: The timestamp before which the transaction is valid
* `nonce`: A random nonce

Sign the hash of the transaction with your private key, and derive the `v`, `r`,
`s` values. Broadcast the transaction to the blockchain.

### Step 4. Sign and broadcast a `batchDepositForBurnWithAuth` transaction on the `CctpExtension` contract

Create a `batchDepositForBurnWithAuth` transaction for the `CctpExtension`
contract with the following parameters:

* `destinationDomain`: 19 (HyperEVM)
* `mintRecipient`: The `CctpForwarder` contract address on HyperEVM
* `destinationCaller`: The `CctpForwarder` contract address on HyperEVM
* `maxFee`: `0_200_000` (0.20 USDC, from step 2)
* `minFinalityThreshold`: `1000` (Fast Transfer)
* `hookData`: The hook data to call the `CctpForwarder` contract on HyperEVM

<Warning>
  Always set both `mintRecipient` and `destinationCaller` to the `CctpForwarder`
  [contract address](/cctp/references/hypercore-contract-addresses) on HyperEVM
  when you transfer USDC to HyperCore.

  * If `destinationCaller` is wrong, the forwarder cannot complete the transfer.
  * If `mintRecipient` is wrong, the minted USDC is not sent to the forwarder.

  In either case, funds become permanently stuck and **cannot be recovered**.
</Warning>

The `hookData` is the data to execute the forwarder to HyperCore. The following
is an example of the hook data:

```ts TypeScript theme={null}
/**
 * Generate CCTP forwarder hook data for HyperCore
 *
 * Hook Data Format:
 * Field                        Bytes      Type       Index
 * magicBytes                   24         bytes24    0     ASCII prefix "cctp-forward", followed by padding
 * version                      4          uint32     24
 * dataLength                   4          uint32     28
 * hyperCoreMintRecipient       20         address    32    EVM address - optional, included if requesting a deposit to HyperCore
 * hyperCoreDestinationDex      4          uint32     52    The destinationDexId on HyperCore (0 for perp and uint32.max for spot)
 */
function encodeForwardHookData(
  hyperCoreMintRecipient?: `0x${string}`,
  hyperCoreDestinationDex: number = 0,
): `0x${string}` {
  // Validate hex prefix if recipient provided
  if (hyperCoreMintRecipient && !hyperCoreMintRecipient.startsWith("0x")) {
    throw new Error("Address must start with 0x");
  }

  // Magic bytes: "cctp-forward" (12 chars) padded to 24 bytes with zeros
  const magic = "cctp-forward";
  const magicHex = Buffer.from(magic, "utf-8").toString("hex").padEnd(48, "0");

  // Version: uint32 = 0 (4 bytes, big-endian)
  const version = "00000000";

  if (!hyperCoreMintRecipient) {
    // No recipient: dataLength = 0, return header only (32 bytes)
    const dataLength = "00000000";
    return `0x${magicHex}${version}${dataLength}`;
  }

  // With recipient: dataLength = 24 (20 bytes address + 4 bytes dex)
  const dataLength = "00000018"; // 24 in hex

  // Address: 20 bytes (remove 0x prefix)
  const address = hyperCoreMintRecipient.slice(2).toLowerCase();

  // Destination DEX: uint32 big-endian
  // 0 = perps, 4294967295 (0xFFFFFFFF) = spot
  const dex = (hyperCoreDestinationDex >>> 0).toString(16).padStart(8, "0");

  return `0x${magicHex}${version}${dataLength}${address}${dex}`;
}
```

Once the deposit transaction is confirmed, the USDC is minted on HyperEVM and
automatically forwarded to your address on HyperCore.

By default (when `hyperCoreDestinationDex` is `0`), deposits credit the perps
balance on HyperCore. To deposit to the spot balance, set
`hyperCoreDestinationDex` to `4294967295` (uint32 max value).

## Full example code

The following is a complete example of how to transfer USDC from Arbitrum to
HyperCore.

```ts script.ts expandable theme={null}
/**
 * Script: Call CctpExtension.batchDepositForBurnWithAuth
 * - Generates EIP-3009 receiveWithAuthorization signature
 * - Executes a CCTP burn via the extension
 * - Supports Forwarder hook data to auto-forward to HyperCore
 */

import {
  createWalletClient,
  createPublicClient,
  http,
  parseUnits,
  formatUnits,
  type Address,
  type Hex,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { arbitrumSepolia } from "viem/chains";

// -------- Contract ABIs --------
const CCTP_EXTENSION_ABI = [
  {
    name: "batchDepositForBurnWithAuth",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [
      {
        name: "_receiveWithAuthorizationData",
        type: "tuple",
        components: [
          { name: "amount", type: "uint256" },
          { name: "authValidAfter", type: "uint256" },
          { name: "authValidBefore", type: "uint256" },
          { name: "authNonce", type: "bytes32" },
          { name: "v", type: "uint8" },
          { name: "r", type: "bytes32" },
          { name: "s", type: "bytes32" },
        ],
      },
      {
        name: "_depositForBurnData",
        type: "tuple",
        components: [
          { name: "amount", type: "uint256" },
          { name: "destinationDomain", type: "uint32" },
          { name: "mintRecipient", type: "bytes32" },
          { name: "destinationCaller", type: "bytes32" },
          { name: "maxFee", type: "uint256" },
          { name: "minFinalityThreshold", type: "uint32" },
          { name: "hookData", type: "bytes" },
        ],
      },
    ],
    outputs: [],
  },
] as const;

// -------- Configuration --------
const config = {
  privateKey: (process.env.PRIVATE_KEY || "0x") as Hex,

  // Contract addresses (Arbitrum Sepolia Testnet)
  cctpExtension: "0x8E4e3d0E95C1bEC4F3eC7F69aa48473E0Ab6eB8D" as Address,
  usdcToken: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d" as Address,

  // Transfer parameters
  amount: "2", // USDC amount to transfer
  maxFee: "0.2", // Max fee in USDC

  // CCTP parameters
  destinationDomain: 19, // HyperEVM domain
  cctpForwarder: "0x02e39ECb8368b41bF68FF99ff351aC9864e5E2a2" as Address, // HyperEVM testnet

  // HyperCore recipient
  forwardRecipient: process.env.FORWARD_RECIPIENT as Address,
  destinationDex: 0, // 0 = perps, 4294967295 = spot

  // EIP-3009 validity window (seconds)
  validAfter: Math.floor(Date.now() / 1000) - 3600, // 1 hour ago
  validBefore: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
};

// -------- Generate Hook Data --------
function encodeForwardHookData(
  hyperCoreMintRecipient?: `0x${string}`,
  hyperCoreDestinationDex: number = 0,
): `0x${string}` {
  if (hyperCoreMintRecipient && !hyperCoreMintRecipient.startsWith("0x")) {
    throw new Error("Address must start with 0x");
  }

  const magic = "cctp-forward";
  const magicHex = Buffer.from(magic, "utf-8").toString("hex").padEnd(48, "0");
  const version = "00000000";

  if (!hyperCoreMintRecipient) {
    const dataLength = "00000000";
    return `0x${magicHex}${version}${dataLength}`;
  }

  const dataLength = "00000018";
  const address = hyperCoreMintRecipient.slice(2).toLowerCase();
  const dex = (hyperCoreDestinationDex >>> 0).toString(16).padStart(8, "0");

  return `0x${magicHex}${version}${dataLength}${address}${dex}`;
}

// -------- Generate Random Nonce --------
function generateNonce(): Hex {
  const randomBytes = crypto.getRandomValues(new Uint8Array(32));
  return `0x${Array.from(randomBytes)
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("")}`;
}

// -------- Main Function --------
async function main() {
  // Validate private key and recipient
  if (!config.privateKey || config.privateKey === "0x") {
    throw new Error("Set PRIVATE_KEY");
  }
  if (!config.forwardRecipient) {
    throw new Error("Set FORWARD_RECIPIENT");
  }

  // Setup account and clients
  const account = privateKeyToAccount(config.privateKey);
  const publicClient = createPublicClient({
    chain: arbitrumSepolia,
    transport: http(),
  });
  const walletClient = createWalletClient({
    chain: arbitrumSepolia,
    transport: http(),
    account,
  });

  const amount = parseUnits(config.amount, 6);
  const maxFee = parseUnits(config.maxFee, 6);

  console.log("User:", account.address);
  console.log("Extension:", config.cctpExtension);
  console.log("USDC:", config.usdcToken);
  console.log("Total (USDC):", config.amount);
  console.log(
    "Dest Domain:",
    config.destinationDomain,
    "\nMint Recipient:",
    config.cctpForwarder,
  );
  console.log("Max Fee (USDC):", config.maxFee, "\nMin Finality:", 1000);

  // Check USDC balance
  const balance = await publicClient.readContract({
    address: config.usdcToken,
    abi: [
      {
        name: "balanceOf",
        type: "function",
        stateMutability: "view",
        inputs: [{ name: "account", type: "address" }],
        outputs: [{ name: "", type: "uint256" }],
      },
    ],
    functionName: "balanceOf",
    args: [account.address],
  });

  if (balance < amount) {
    throw new Error(
      `Insufficient USDC: have ${formatUnits(balance, 6)}, need ${config.amount}`,
    );
  }

  // Generate hook data
  const hookData = encodeForwardHookData(
    config.forwardRecipient,
    config.destinationDex,
  );
  console.log(
    "Forwarder hook enabled -> Final recipient:",
    config.forwardRecipient,
  );
  console.log("Hook Data:", hookData);

  // Convert addresses to bytes32
  const mintRecipientBytes32 =
    `0x${config.cctpForwarder.slice(2).padStart(64, "0")}` as Hex;
  const destinationCallerBytes32 =
    `0x${config.cctpForwarder.slice(2).padStart(64, "0")}` as Hex;
  console.log("Destination Caller (bytes32):", destinationCallerBytes32);

  // Generate nonce for EIP-3009
  const nonce = generateNonce();

  // Sign EIP-3009 ReceiveWithAuthorization
  const signature = await walletClient.signTypedData({
    domain: {
      name: "USD Coin",
      version: "2",
      chainId: arbitrumSepolia.id,
      verifyingContract: config.usdcToken,
    },
    types: {
      ReceiveWithAuthorization: [
        { name: "from", type: "address" },
        { name: "to", type: "address" },
        { name: "value", type: "uint256" },
        { name: "validAfter", type: "uint256" },
        { name: "validBefore", type: "uint256" },
        { name: "nonce", type: "bytes32" },
      ],
    },
    primaryType: "ReceiveWithAuthorization",
    message: {
      from: account.address,
      to: config.cctpExtension,
      value: amount,
      validAfter: BigInt(config.validAfter),
      validBefore: BigInt(config.validBefore),
      nonce,
    },
  });

  // Parse signature into v, r, s
  const r = signature.slice(0, 66) as Hex;
  const s = `0x${signature.slice(66, 130)}` as Hex;
  const v = parseInt(signature.slice(130, 132), 16);

  // Estimate gas
  const gasEstimate = await publicClient.estimateContractGas({
    address: config.cctpExtension,
    abi: CCTP_EXTENSION_ABI,
    functionName: "batchDepositForBurnWithAuth",
    args: [
      {
        amount,
        authValidAfter: BigInt(config.validAfter),
        authValidBefore: BigInt(config.validBefore),
        authNonce: nonce,
        v,
        r,
        s,
      },
      {
        amount,
        destinationDomain: config.destinationDomain,
        mintRecipient: mintRecipientBytes32,
        destinationCaller: destinationCallerBytes32,
        maxFee,
        minFinalityThreshold: 1000,
        hookData,
      },
    ],
    account,
  });

  console.log("Estimated gas:", gasEstimate.toString());

  // Execute batchDepositForBurnWithAuth
  const hash = await walletClient.writeContract({
    address: config.cctpExtension,
    abi: CCTP_EXTENSION_ABI,
    functionName: "batchDepositForBurnWithAuth",
    args: [
      {
        amount,
        authValidAfter: BigInt(config.validAfter),
        authValidBefore: BigInt(config.validBefore),
        authNonce: nonce,
        v,
        r,
        s,
      },
      {
        amount,
        destinationDomain: config.destinationDomain,
        mintRecipient: mintRecipientBytes32,
        destinationCaller: destinationCallerBytes32,
        maxFee,
        minFinalityThreshold: 1000,
        hookData,
      },
    ],
    gas: (gasEstimate * 120n) / 100n, // +20%
  });

  console.log("Tx hash:", hash);

  // Wait for transaction receipt
  const receipt = await publicClient.waitForTransactionReceipt({ hash });

  console.log("Status:", receipt.status === "success" ? "SUCCESS" : "FAILED");
  console.log(
    "Block:",
    receipt.blockNumber,
    "\nGas Used:",
    receipt.gasUsed.toString(),
  );
}

// Run
main().catch((error) => {
  console.error("Error:", error.message);
  process.exit(1);
});
```

Run the script:

```bash theme={null}
npx tsx --env-file=.env script.ts
```


# Transfer USDC from Ethereum to HyperCore
Source: https://developers.circle.com/cctp/howtos/transfer-usdc-from-ethereum-to-hypercore



This guide shows the steps to transfer USDC from Ethereum to HyperCore using the
`TokenMessengerV2` contract with hook data to call the `CctpForwarder` contract
on HyperEVM. This CCTP flow follows the same pattern as USDC transfers from
Ethereum to any other domain, except for the inclusion of hook data to call the
`CctpForwarder` contract on HyperEVM.

While this guide uses Ethereum as an example, the same steps apply to any EVM
chain that supports CCTP via `TokenMessengerV2`. Adjust the source domain ID and
contract addresses for your chain.

This guide does not provide full example code, you can find an example of
transfers from Ethereum in the
[CCTP quickstart](cctp/quickstarts/transfer-usdc-ethereum-to-arc).

<Note>
  Fast Transfers from Ethereum to HyperEVM incur a protocol fee and a dynamic
  forwarding fee for the HyperEVM chain relay transaction. Fast Transfer is the
  default for transfers from Ethereum to HyperCore.
</Note>

## Steps

Use the following steps to transfer USDC from Ethereum to HyperCore.

### Step 1. Get CCTP fees from the API

Query the CCTP API for the fees for transferring USDC from Ethereum to
HyperCore. This value is passed to the `maxFee` parameter in the
`depositForBurnWithHook` transaction. The following is an example request to the
CCTP using source domain 0 (Ethereum) and destination domain 19 (HyperEVM):

```shell theme={null}
curl --request GET \
  --url 'https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/0/19?forward=true&hyperCoreDeposit=true' \
  --header 'Content-Type: application/json'
```

**Response:**

```json theme={null}
[
  {
    "finalityThreshold": 1000, // fast transfer
    "minimumFee": 1, // in basis points
    "forwardFee": {
      "low": 211203,
      "med": 216109, // 0.216109 USDC
      "high": 221014
    }
  },
  {
    "finalityThreshold": 2000, // standard transfer
    "minimumFee": 0,
    "forwardFee": {
      "low": 211203,
      "med": 216109, // 0.216109 USDC
      "high": 221014
    }
  }
]
```

### Step 2. Calculate the USDC amounts minus fees

There is a protocol fee to deposit USDC from Ethereum to HyperEVM and a dynamic
forwarding fee for the HyperEVM chain relay transaction. The CCTP fast transfer
fee is 1 basis point (0.01%) of the transfer amount. The forwarding fee is 0.20
USDC (`0_200_000` subunits) plus a dynamic destination chain gas fee. For a 10
USDC transfer from Ethereum to HyperCore, the protocol fee is 0.001 USDC (10
USDC × 0.0001) and an example forwarding fee is 0.216109 USDC, for a total fee
of 0.217109 USDC.

Because the protocol fee scales with the transfer amount and the forwarding fee
is dynamic, you must recalculate `maxFee` for each transfer. For a programmatic
approach, see [`calculateMaxFee`](/cctp/concepts/fees#maximum-fee-parameter) on
the fees page.

### Step 3. Approve the USDC transfer

To allow the `TokenMessengerV2` contract to transfer the USDC on your behalf,
you need to approve the transfer. This is done by calling the `approve` function
on the USDC contract.

You can see an example of this contract call in the
[Ethereum CCTP V2 example on GitHub](https://github.com/circlefin/solana-cctp-contracts/blob/9f8cf26d059cf8927ae0a0b351f3a7a88c7bdade/examples/v2/evm.ts#L63).

### Step 4. Sign and broadcast a `depositForBurnWithHook` transaction on the `TokenMessengerV2` contract

Create a `depositForBurnWithHook` transaction for the `TokenMessengerV2`
contract with the following parameters:

* `amount`: The amount of USDC to transfer
* `destinationDomain`: 19 (HyperEVM)
* `mintRecipient`: The address of the `CctpForwarder` contract on HyperEVM
* `burnToken`: The address of the USDC contract on the source chain
* `destinationCaller`: The address of the `CctpForwarder` contract on HyperEVM
* `maxFee`: The protocol fee + forwarding fee calculated in Step 2
* `minFinalityThreshold`: `1000` (Fast Transfer)
* `hookData`: The hook data to call the `CctpForwarder` contract on HyperEVM

<Warning>
  Always set both `mintRecipient` and `destinationCaller` to the `CctpForwarder`
  [contract address](/cctp/references/hypercore-contract-addresses) on HyperEVM
  when you transfer USDC to HyperCore.

  * If `destinationCaller` is wrong, the forwarder cannot complete the transfer.
  * If `mintRecipient` is wrong, the minted USDC is not sent to the forwarder.

  In either case, funds become permanently stuck and **cannot be recovered**.
</Warning>

The `hookData` is the data to execute the forwarder to HyperCore. The following
is an example of the hook data:

```ts TypeScript theme={null}
/**
 * Generate CCTP forwarder hook data for HyperCore
 *
 * Hook Data Format:
 * Field                        Bytes      Type       Index
 * magicBytes                   24         bytes24    0     ASCII prefix "cctp-forward", followed by padding
 * version                      4          uint32     24
 * dataLength                   4          uint32     28
 * hyperCoreMintRecipient       20         address    32    EVM address - optional, included if requesting a deposit to HyperCore
 * hyperCoreDestinationDex      4          uint32     52    The destinationDexId on HyperCore (0 for perp and uint32.max for spot)
 */
function encodeForwardHookData(
  hyperCoreMintRecipient?: `0x${string}`,
  hyperCoreDestinationDex: number = 0,
): `0x${string}` {
  // Validate hex prefix if recipient provided
  if (hyperCoreMintRecipient && !hyperCoreMintRecipient.startsWith("0x")) {
    throw new Error("Address must start with 0x");
  }

  // Magic bytes: "cctp-forward" (12 chars) padded to 24 bytes with zeros
  const magic = "cctp-forward";
  const magicHex = Buffer.from(magic, "utf-8").toString("hex").padEnd(48, "0");

  // Version: uint32 = 0 (4 bytes, big-endian)
  const version = "00000000";

  if (!hyperCoreMintRecipient) {
    // No recipient: dataLength = 0, return header only (32 bytes)
    const dataLength = "00000000";
    return `0x${magicHex}${version}${dataLength}`;
  }

  // With recipient: dataLength = 24 (20 bytes address + 4 bytes dex)
  const dataLength = "00000018"; // 24 in hex

  // Address: 20 bytes (remove 0x prefix)
  const address = hyperCoreMintRecipient.slice(2).toLowerCase();

  // Destination DEX: uint32 big-endian
  // 0 = perps, 4294967295 (0xFFFFFFFF) = spot
  const dex = (hyperCoreDestinationDex >>> 0).toString(16).padStart(8, "0");

  return `0x${magicHex}${version}${dataLength}${address}${dex}`;
}
```

You can see an example of this contract call in the
[Ethereum V2 example on GitHub](https://github.com/circlefin/solana-cctp-contracts/blob/9f8cf26d059cf8927ae0a0b351f3a7a88c7bdade/examples/v2/evm.ts#L105)

Once the deposit transaction is confirmed, the USDC is minted on HyperEVM and
automatically forwarded to your address on HyperCore.

By default (when `hyperCoreDestinationDex` is `0`), deposits credit the perps
balance on HyperCore. To deposit to the spot balance, set
`hyperCoreDestinationDex` to `4294967295` (uint32 max value).


# Transfer USDC from HyperEVM to HyperCore
Source: https://developers.circle.com/cctp/howtos/transfer-usdc-from-hyperevm-to-hypercore



This guide shows how to transfer USDC from HyperEVM to HyperCore using the
`CoreDepositWallet` contract.

<Tip>
  **Tip:** The `CoreDepositWallet` contract provides `deposit`, `depositFor`,
  and `depositWithAuth` methods. This guide uses `deposit`. All methods accept a
  `destinationDex` parameter (`0` for perps, `4294967295` for spot). See the
  [CoreDepositWallet contract
  interface](/cctp/references/coredepositwallet-contract-interface) for detailed
  information.
</Tip>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)

* Prepared an EVM testnet wallet with the private key available

* Funded your wallet with HyperEVM testnet USDC from the
  [Circle Faucet](https://faucet.circle.com)

* Created a new Node project and installed dependencies:

  ```bash theme={null}
  npm install viem
  npm install -D tsx typescript @types/node
  ```

* Created a `.env` file with required environment variable:

  ```text theme={null}
  PRIVATE_KEY=0x...
  ```

## Steps

Use the following steps to transfer USDC from HyperEVM to HyperCore.

### Step 1. Approve the `CoreDepositWallet` to spend USDC

Approve the `CoreDepositWallet` contract to transfer USDC on your behalf:

```ts TypeScript theme={null}
const hash = await walletClient.writeContract({
  address: USDC_ADDRESS,
  abi: USDC_ABI,
  functionName: "approve",
  args: [CORE_DEPOSIT_WALLET, amount],
});

await publicClient.waitForTransactionReceipt({ hash });
```

### Step 2. Call the `deposit` function

Call the `deposit` function with your desired amount and destination:

```ts TypeScript theme={null}
const hash = await walletClient.writeContract({
  address: CORE_DEPOSIT_WALLET,
  abi: CORE_DEPOSIT_WALLET_ABI,
  functionName: "deposit",
  args: [amount, destinationDex], // 0 = perps, 4294967295 = spot
});

const receipt = await publicClient.waitForTransactionReceipt({ hash });
```

The `deposit` function transfers USDC from your account to the
`CoreDepositWallet` and credits your HyperCore balance.

## Full example code

The following is a complete example of how to transfer USDC from HyperEVM to
HyperCore.

```ts script.ts expandable theme={null}
/**
 * Script: Call CoreDepositWallet.deposit on HyperEVM
 * - Approves USDC spending
 * - Calls deposit(amount, destinationDex)
 */

import {
  createWalletClient,
  createPublicClient,
  http,
  parseUnits,
  formatUnits,
  type Address,
  type Hex,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { hyperliquidEvmTestnet } from "viem/chains";

// -------- Configuration --------
const config = {
  privateKey: (process.env.PRIVATE_KEY || "0x") as Hex,

  // Contract addresses (HyperEVM Testnet)
  coreDepositWallet: "0x0B80659a4076E9E93C7DbE0f10675A16a3e5C206" as Address,
  usdcToken: "0x2B3370eE501B4a559b57D449569354196457D8Ab" as Address,

  // Transfer parameters
  amount: "2", // USDC amount to deposit

  // HyperCore destination (0 = perps, 4294967295 = spot)
  destinationDex: 0,
};

// -------- Main Function --------
async function main() {
  // Validate private key
  if (!config.privateKey || config.privateKey === "0x") {
    throw new Error("Set PRIVATE_KEY");
  }

  // Setup account and clients
  const account = privateKeyToAccount(config.privateKey);
  const publicClient = createPublicClient({
    chain: hyperliquidEvmTestnet,
    transport: http(),
  });
  const walletClient = createWalletClient({
    chain: hyperliquidEvmTestnet,
    transport: http(),
    account,
  });

  const amount = parseUnits(config.amount, 6);

  console.log("User:", account.address);
  console.log("CoreDepositWallet:", config.coreDepositWallet);
  console.log("USDC:", config.usdcToken);
  console.log("Amount (USDC):", config.amount);
  console.log(
    "Destination DEX:",
    config.destinationDex === 0 ? "perps" : "spot",
  );

  // Check USDC balance
  const balance = await publicClient.readContract({
    address: config.usdcToken,
    abi: [
      {
        name: "balanceOf",
        type: "function",
        stateMutability: "view",
        inputs: [{ name: "account", type: "address" }],
        outputs: [{ name: "", type: "uint256" }],
      },
    ],
    functionName: "balanceOf",
    args: [account.address],
  });

  if (balance < amount) {
    throw new Error(
      `Insufficient USDC: have ${formatUnits(balance, 6)}, need ${config.amount}`,
    );
  }

  // Check current allowance
  const currentAllowance = await publicClient.readContract({
    address: config.usdcToken,
    abi: [
      {
        name: "allowance",
        type: "function",
        stateMutability: "view",
        inputs: [
          { name: "owner", type: "address" },
          { name: "spender", type: "address" },
        ],
        outputs: [{ name: "", type: "uint256" }],
      },
    ],
    functionName: "allowance",
    args: [account.address, config.coreDepositWallet],
  });

  // Step 1: Approve if needed
  if (currentAllowance < amount) {
    console.log("\nApproving USDC spending...");
    const hash = await walletClient.writeContract({
      address: config.usdcToken,
      abi: [
        {
          name: "approve",
          type: "function",
          stateMutability: "nonpayable",
          inputs: [
            { name: "spender", type: "address" },
            { name: "amount", type: "uint256" },
          ],
          outputs: [{ name: "", type: "bool" }],
        },
      ],
      functionName: "approve",
      args: [config.coreDepositWallet, amount],
    });

    console.log("Approve tx hash:", hash);
    await publicClient.waitForTransactionReceipt({ hash });
    console.log("Approval confirmed");
  } else {
    console.log("\nSufficient allowance already exists");
  }

  // Step 2: Deposit
  console.log("\nDepositing USDC to HyperCore...");
  const hash = await walletClient.writeContract({
    address: config.coreDepositWallet,
    abi: [
      {
        name: "deposit",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "amount", type: "uint256" },
          { name: "destinationDex", type: "uint32" },
        ],
        outputs: [],
      },
    ],
    functionName: "deposit",
    args: [amount, config.destinationDex],
  });

  console.log("Deposit tx hash:", hash);

  // Wait for transaction receipt
  const receipt = await publicClient.waitForTransactionReceipt({ hash });

  console.log("Status:", receipt.status === "success" ? "SUCCESS" : "FAILED");
  console.log(
    "Block:",
    receipt.blockNumber,
    "\nGas Used:",
    receipt.gasUsed.toString(),
  );
}

// Run
main().catch((error) => {
  console.error("Error:", error.message);
  process.exit(1);
});
```

Run the script:

```bash theme={null}
npx tsx --env-file=.env script.ts
```


# Transfer USDC from Solana to HyperCore
Source: https://developers.circle.com/cctp/howtos/transfer-usdc-from-solana-to-hypercore



This guide shows how to transfer USDC from Solana to HyperCore using the
`TokenMessengerV2` contract. Solana's CCTP implementation does not have the
`depositForBurnWithAuth`, and there is no `CctpExtension` contract for Solana.
As such, transfers from Solana to HyperCore follow the standard CCTP flow, with
the addition of hook data to call the `CctpForwarder` contract on HyperEVM.

This guide does not provide full example code for the transfer to HyperCore from
Solana.

<Note>
  Fast Transfers from Solana to HyperEVM incur a protocol fee and a dynamic
  forwarding fee for the HyperEVM chain relay transaction. Fast Transfer is the
  default for transfers from Solana to HyperCore.
</Note>

## Steps

Use the following steps to transfer USDC from Solana to HyperCore.

### Step 1. Get CCTP fees from the API

Query the CCTP API for the fees for transferring USDC from Solana to HyperCore.
This value is passed to the `maxFee` parameter in the `depositForBurnWithHook`
transaction. The following is an example request to the CCTP using source domain
5 (Solana) and destination domain 19 (HyperEVM):

```shell theme={null}
curl --request GET \
  --url 'https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/5/19?forward=true&hyperCoreDeposit=true' \
  --header 'Content-Type: application/json'
```

**Response:**

```json theme={null}
[
  {
    "finalityThreshold": 1000, // fast transfer
    "minimumFee": 1, // in basis points
    "forwardFee": {
      "low": 211203,
      "med": 216109, // 0.216109 USDC
      "high": 221014
    }
  },
  {
    "finalityThreshold": 2000, // standard transfer
    "minimumFee": 0,
    "forwardFee": {
      "low": 211203,
      "med": 216109, // 0.216109 USDC
      "high": 221014
    }
  }
]
```

### Step 2. Calculate the USDC amounts minus fees

There is a protocol fee to deposit USDC from Solana to HyperEVM and a dynamic
forwarding fee for the HyperEVM chain relay transaction. The CCTP fast transfer
fee is 1 basis point (0.01%) of the transfer amount. The forwarding fee is 0.20
USDC (`0_200_000` subunits) plus a dynamic destination chain gas fee. For a 10
USDC transfer from Solana to HyperCore, the protocol fee is 0.001 USDC (10 USDC
× 0.0001) and an example forwarding fee is 0.216109 USDC, for a total fee of
0.217109 USDC.

Because the protocol fee scales with the transfer amount and the forwarding fee
is dynamic, you must recalculate `maxFee` for each transfer. For a programmatic
approach, see [`calculateMaxFee`](/cctp/concepts/fees#maximum-fee-parameter) on
the fees page.

### Step 3. Sign and broadcast a `depositForBurnWithHook` transaction on the `TokenMessengerV2` contract

Create a `depositForBurnWithHook` transaction for the `TokenMessengerV2`
contract with the following parameters:

* `amount`: The amount of USDC to transfer
* `destinationDomain`: 19 (HyperEVM)
* `mintRecipient`: The address of the `CctpForwarder` contract on HyperEVM
* `destinationCaller`: The address of the `CctpForwarder` contract on HyperEVM
* `maxFee`: The protocol fee + forwarding fee calculated in Step 2
* `minFinalityThreshold`: `1000` (Fast Transfer)
* `hookData`: The hook data to call the `CctpForwarder` contract on HyperEVM

<Warning>
  Always set both `mintRecipient` and `destinationCaller` to the `CctpForwarder`
  [contract address](/cctp/references/hypercore-contract-addresses) on HyperEVM
  when you transfer USDC to HyperCore.

  * If `destinationCaller` is wrong, the forwarder cannot complete the transfer.
  * If `mintRecipient` is wrong, the minted USDC is not sent to the forwarder.

  In either case, funds become permanently stuck and **cannot be recovered**.
</Warning>

The `hookData` is the data to execute the forwarder to HyperCore. The following
is an example of the hook data:

```ts TypeScript theme={null}
/**
 * Generate CCTP forwarder hook data for HyperCore
 *
 * Hook Data Format:
 * Field                        Bytes      Type       Index
 * magicBytes                   24         bytes24    0     ASCII prefix "cctp-forward", followed by padding
 * version                      4          uint32     24
 * dataLength                   4          uint32     28
 * hyperCoreMintRecipient       20         address    32    EVM address - optional, included if requesting a deposit to HyperCore
 * hyperCoreDestinationDex      4          uint32     52    The destinationDexId on HyperCore (0 for perp and uint32.max for spot)
 */
function encodeForwardHookData(
  hyperCoreMintRecipient?: `0x${string}`,
  hyperCoreDestinationDex: number = 0,
): `0x${string}` {
  // Validate hex prefix if recipient provided
  if (hyperCoreMintRecipient && !hyperCoreMintRecipient.startsWith("0x")) {
    throw new Error("Address must start with 0x");
  }

  // Magic bytes: "cctp-forward" (12 chars) padded to 24 bytes with zeros
  const magic = "cctp-forward";
  const magicHex = Buffer.from(magic, "utf-8").toString("hex").padEnd(48, "0");

  // Version: uint32 = 0 (4 bytes, big-endian)
  const version = "00000000";

  if (!hyperCoreMintRecipient) {
    // No recipient: dataLength = 0, return header only (32 bytes)
    const dataLength = "00000000";
    return `0x${magicHex}${version}${dataLength}`;
  }

  // With recipient: dataLength = 24 (20 bytes address + 4 bytes dex)
  const dataLength = "00000018"; // 24 in hex

  // Address: 20 bytes (remove 0x prefix)
  const address = hyperCoreMintRecipient.slice(2).toLowerCase();

  // Destination DEX: uint32 big-endian
  // 0 = perps, 4294967295 (0xFFFFFFFF) = spot
  const dex = (hyperCoreDestinationDex >>> 0).toString(16).padStart(8, "0");

  return `0x${magicHex}${version}${dataLength}${address}${dex}`;
}
```

For full example code calling the `depositForBurnWithHook` function, see the
[Solana CCTP V2 example on GitHub](https://github.com/circlefin/solana-cctp-contracts/blob/9f8cf26d059cf8927ae0a0b351f3a7a88c7bdade/examples/v2/solana.ts#L94).

Once the deposit transaction is confirmed, the USDC is minted on HyperEVM and
automatically forwarded to your address on HyperCore.

By default (when `hyperCoreDestinationDex` is `0`), deposits credit the perps
balance on HyperCore. To deposit to the spot balance, set
`hyperCoreDestinationDex` to `4294967295` (uint32 max value).


# How-to: Transfer USDC with the Forwarding Service
Source: https://developers.circle.com/cctp/howtos/transfer-usdc-with-forwarding-service

Transfer USDC Crosschain with the Circle Forwarding Service

This guide shows how to transfer USDC crosschain using the
[Circle Forwarding Service](/cctp/concepts/forwarding-service). This example
shows a transfer from Base Sepolia to Avalanche Fuji, but you can use the same
steps to transfer to any supported
[destination blockchain](/cctp/concepts/supported-chains-and-domains), including
Solana.

When you use the Forwarding Service, Circle handles the mint transaction on the
destination blockchain, eliminating the need for you to hold native tokens for
gas on the destination blockchain or run multichain infrastructure.

## Prerequisites

Before you start, ensure you have:

* Installed [Node.js v22+](https://nodejs.org/)
* Created a TypeScript project and installed the `viem` package.
* Created a wallet with the private key available on the source chain.
* Funded the wallet with testnet USDC and native tokens for gas fees on the
  source chain.
* Created a `.env` file with your private key and recipient address.

## Steps

Use the following steps to transfer USDC with the Forwarding Service.

### Step 1. Get CCTP fees from the API

Query the CCTP API for the fees for transferring USDC from Base Sepolia to
Avalanche Fuji. This value is passed to the `maxFee` parameter in the
`depositForBurnWithHook` transaction. The following is an example request using
source domain 6 (Base Sepolia) and destination domain 1 (Avalanche Fuji):

```typescript theme={null}
const response = await fetch(
  "https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/6/1?forward=true",
  {
    method: "GET",
    headers: { "Content-Type": "application/json" },
  },
);

const fees = await response.json();
console.log(fees);
```

**Example response:**

```json theme={null}
[
  {
    "finalityThreshold": 1000, // Fast transfer
    "minimumFee": 1.3, // Basis points (0.013% fee rate)
    "forwardFee": {
      // Gas-based, fluctuates based on destination chain gas prices
      "low": 206035, // 0.206035 USDC
      "med": 207543, // 0.207543 USDC
      "high": 209052 // 0.209052 USDC
    }
  },
  {
    "finalityThreshold": 2000, // Standard transfer
    "minimumFee": 0, // No fee
    "forwardFee": {
      "low": 206035, // 0.206035 USDC
      "med": 207543, // 0.207543 USDC
      "high": 209052 // 0.209052 USDC
    }
  }
]
```

The `forwardFee` is the fee charged by the Forwarding Service. The `minimumFee`
is the CCTP protocol fee rate in basis points, applied as a percentage of the
transfer amount.

<Tip>
  Circle recommends selecting the `med` fee level or higher from the `forwardFee`
  object in the API response. Note that `forwardFee` values fluctuate based on
  destination chain gas prices. Make the query immediately before initiating your
  transfer.
</Tip>

<Accordion title="Forwarding to Solana">
  When the destination blockchain is Solana, the `forwardFee` values include both
  gas and rent costs. If the recipient does not have an existing USDC
  [Associated Token Account (ATA)](https://spl.solana.com/associated-token-account),
  add `includeRecipientSetup=true` to the fee query so the returned fee covers ATA
  creation:

  ```typescript theme={null}
  // Source domain 6 (Base Sepolia), destination domain 5 (Solana)
  const response = await fetch(
    "https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/6/5?forward=true&includeRecipientSetup=true",
    {
      method: "GET",
      headers: { "Content-Type": "application/json" },
    },
  );
  ```

  Unlike EVM destinations, the `mintRecipient` for Solana must be the recipient's
  **USDC token account address** (ATA), not the wallet address. Derive the ATA
  from the wallet address and the USDC mint:

  ```typescript theme={null}
  import { getAssociatedTokenAddressSync } from "@solana/spl-token";
  import { PublicKey } from "@solana/web3.js";

  const recipientWallet = new PublicKey("RecipientSolanaWalletAddress");
  const USDC_MINT = new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"); // Solana devnet

  const recipientAta = getAssociatedTokenAddressSync(USDC_MINT, recipientWallet);
  const mintRecipientBytes32 =
    `0x${Buffer.from(recipientAta.toBytes()).toString("hex")}` as `0x${string}`;
  ```

  If the recipient does not have an existing ATA and you passed
  `includeRecipientSetup=true` in the fee query, you must also encode ATA creation
  fields in the hook data. See
  [Solana hook data for ATA creation](/cctp/concepts/forwarding-service#solana-hook-data-for-ata-creation)
  for the extended hook data format.
</Accordion>

### Step 2. Calculate the USDC amounts and fees

Calculate the total fee by combining the protocol fee and the Forwarding Service
fee. The `maxFee` parameter must cover both fees for the transfer to succeed.

```typescript theme={null}
// Amount to transfer (10 USDC in subunits)
const transferAmount = 10_000_000n;

// Parse fees from API response
const feeData = fees[0]; // Use fast transfer fees (finalityThreshold: 1000)
const forwardFee = BigInt(feeData.forwardFee.med);

// Calculate protocol fee (minimumFee is in basis points)
const minimumFeeBps = feeData.minimumFee;
const protocolFee =
  (transferAmount * BigInt(Math.round(minimumFeeBps * 100))) / 1_000_000n;

// Total max fee should cover both fees
const maxFee = forwardFee + protocolFee;
const totalAmount = transferAmount + maxFee; // Total to burn

console.log("Transfer amount:", Number(transferAmount) / 1_000_000, "USDC");
console.log("Forward fee:", Number(forwardFee) / 1_000_000, "USDC");
console.log("Protocol fee:", Number(protocolFee) / 1_000_000, "USDC");
console.log("Max fee:", Number(maxFee) / 1_000_000, "USDC");
console.log("Total to burn:", Number(totalAmount) / 1_000_000, "USDC");
```

In this example, for a 10 USDC transfer with forwarding, the total fee is
0.208843 USDC (0.207543 USDC Forwarding Service fee + 0.0013 USDC CCTP protocol
fee). For the recipient to receive 10 USDC, you must burn 10.208843 USDC in
total.

<Warning>
  If the `maxFee` parameter is insufficient to cover the both Fast Transfer
  protocol fee and the Forwarding Service fee, CCTP will prioritize forwarding
  execution over Fast Transfer. This means that the transfer will execute as a
  Standard Transfer with the Forwarding Service.
</Warning>

### Step 3. Approve the USDC transfer

Grant approval for the
[`TokenMessengerV2` contract](/cctp/references/contract-addresses) deployed on
Base to transfer USDC from your wallet. Approve at least `totalAmount`
(including fees) calculated in Step 2.

```typescript theme={null}
import { createWalletClient, http, encodeFunctionData } from "viem";
import { baseSepolia } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

// Configuration
const BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
const BASE_SEPOLIA_TOKEN_MESSENGER =
  "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA";

// Set up wallet client
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({
  chain: baseSepolia,
  transport: http(),
  account,
});

async function approveUSDC(amount: bigint) {
  console.log("Approving USDC transfer...");
  const approveTx = await client.sendTransaction({
    to: BASE_SEPOLIA_USDC,
    data: encodeFunctionData({
      abi: [
        {
          type: "function",
          name: "approve",
          stateMutability: "nonpayable",
          inputs: [
            { name: "spender", type: "address" },
            { name: "amount", type: "uint256" },
          ],
          outputs: [{ name: "", type: "bool" }],
        },
      ],
      functionName: "approve",
      args: [BASE_SEPOLIA_TOKEN_MESSENGER, amount],
    }),
  });
  console.log("USDC Approval Tx:", approveTx);
  return approveTx;
}

// Approve the total amount (from Step 2)
await approveUSDC(totalAmount);
```

### Step 4. Sign and broadcast a `depositForBurnWithHook` transaction on the `TokenMessengerV2` contract

Create and send a `depositForBurnWithHook` transaction with the Forwarding
Service hook data. The hook data tells the CCTP Forwarding Service to
automatically forward the mint transaction on the destination chain.

The Forwarding Service hook data is a static 32-byte value containing the magic
bytes `cctp-forward`, version `0`, and length `0`. For details on the hook
format, see
[Forwarding Service hook format](/cctp/concepts/forwarding-service#hook-format).

```typescript theme={null}
// Forwarding Service hook data: magic bytes ("cctp-forward") + version (0) + additional data length (0)
const FORWARDING_SERVICE_HOOK_DATA =
  "0x636374702d666f72776172640000000000000000000000000000000000000000";
```

<Accordion title="Hook data for Solana destinations">
  When forwarding to Solana, use the same static hook data if the recipient
  already has a USDC
  [Associated Token Account (ATA)](https://spl.solana.com/associated-token-account).
  If the recipient does not have an ATA and you included
  `includeRecipientSetup=true` in the fee query (see Step 1), construct extended
  hook data that requests ATA creation:

  ```typescript theme={null}
  import { PublicKey } from "@solana/web3.js";

  // Magic bytes "cctp-forward" padded to 24 bytes
  const magicBytes = Buffer.alloc(24);
  magicBytes.write("cctp-forward", "utf-8");

  // Version (uint32, big-endian) = 0
  const version = Buffer.alloc(4);

  // Length of additional Circle hook data (uint32, big-endian) = 33
  const length = Buffer.alloc(4);
  length.writeUInt32BE(33);

  // ATA creation flag = 1
  const ataFlag = Buffer.from([1]);

  // Recipient wallet address (32 bytes)
  const recipientWallet = new PublicKey("RecipientSolanaWalletAddress");
  const walletBytes = Buffer.from(recipientWallet.toBytes());

  const FORWARDING_SERVICE_HOOK_DATA =
    ("0x" +
      Buffer.concat([magicBytes, version, length, ataFlag, walletBytes]).toString(
        "hex",
      )) as `0x${string}`;
  ```

  For the full hook data format, see
  [Solana hook data for ATA creation](/cctp/concepts/forwarding-service#solana-hook-data-for-ata-creation).
</Accordion>

Then, send the `depositForBurnWithHook` transaction:

<Note>
  Use `totalAmount` (transfer amount + fees) for the `amount` parameter. The
  recipient receives only the transfer amount after fees are deducted.
</Note>

```typescript theme={null}
import { pad, encodeFunctionData } from "viem";

// Configuration
const AVALANCHE_FUJI_DOMAIN = 1;
const DESTINATION_ADDRESS = "0xYOUR_DESTINATION_ADDRESS" as `0x${string}`;

// Convert address to bytes32 format
const mintRecipientBytes32 = pad(DESTINATION_ADDRESS, { size: 32 });

async function depositForBurnWithHook() {
  console.log("Burning USDC on Base with Forwarding Service hook...");

  const burnTx = await client.sendTransaction({
    to: BASE_SEPOLIA_TOKEN_MESSENGER,
    data: encodeFunctionData({
      abi: [
        {
          type: "function",
          name: "depositForBurnWithHook",
          stateMutability: "nonpayable",
          inputs: [
            { name: "amount", type: "uint256" },
            { name: "destinationDomain", type: "uint32" },
            { name: "mintRecipient", type: "bytes32" },
            { name: "burnToken", type: "address" },
            { name: "destinationCaller", type: "bytes32" },
            { name: "maxFee", type: "uint256" },
            { name: "minFinalityThreshold", type: "uint32" },
            { name: "hookData", type: "bytes" },
          ],
          outputs: [],
        },
      ],
      functionName: "depositForBurnWithHook",
      args: [
        totalAmount, // Total to burn (recipient receives transferAmount after fees)
        AVALANCHE_FUJI_DOMAIN,
        mintRecipientBytes32,
        BASE_SEPOLIA_USDC,
        pad("0x", { size: 32 }), // destinationCaller (empty = any caller)
        maxFee,
        1000,
        FORWARDING_SERVICE_HOOK_DATA,
      ],
    }),
  });
  console.log("Burn Tx:", burnTx);
  return burnTx;
}
```

Once the burn transaction is confirmed on Base, the Circle Forwarding Service
automatically handles the attestation and mint transaction on Avalanche. The
USDC is minted directly to the `mintRecipient` address on the destination chain.
The recipient receives `transferAmount` USDC (fees are automatically deducted
from the `totalAmount` on the destination chain).

### Step 5. Verify the mint transaction

After the burn transaction is confirmed, query the Circle Iris API to retrieve
the forwarding details. The API returns the `forwardTxHash`, which is the mint
transaction hash on the destination chain.

The attestation may take time to become available, depending on the destination
chain. Poll the API until the message is ready:

```typescript theme={null}
// Configuration
const BASE_SEPOLIA_DOMAIN = 6;

process.stdout.write("Waiting for attestation...");

let mintTx;
while (!mintTx) {
  const messageResponse = await fetch(
    `https://iris-api-sandbox.circle.com/v2/messages/${BASE_SEPOLIA_DOMAIN}?transactionHash=${burnTx}`,
  );
  const data = await messageResponse.json();

  if (data.messages?.[0]?.forwardTxHash) {
    mintTx = data.messages[0].forwardTxHash;
    console.log(); // New line after dots
  } else {
    process.stdout.write(".");
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

console.log("Mint Tx:", mintTx);
```

## Full example code

The following is a complete example of how to transfer USDC from Base Sepolia to
Avalanche Fuji using the Forwarding Service. Remember to set the `PRIVATE_KEY`
and `DESTINATION_ADDRESS` environment variables.

```typescript script.ts expandable theme={null}
import { createWalletClient, http, encodeFunctionData, pad } from "viem";
import { baseSepolia } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

// Validate environment variables
if (!process.env.PRIVATE_KEY || !process.env.DESTINATION_ADDRESS) {
  throw new Error(
    "PRIVATE_KEY and DESTINATION_ADDRESS environment variables are required",
  );
}

// Configuration
const BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
const BASE_SEPOLIA_TOKEN_MESSENGER =
  "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA";
const BASE_SEPOLIA_DOMAIN = 6;
const AVALANCHE_FUJI_DOMAIN = 1;
const DESTINATION_ADDRESS = process.env.DESTINATION_ADDRESS as `0x${string}`;

// Forwarding Service hook data
const FORWARDING_SERVICE_HOOK_DATA =
  "0x636374702d666f72776172640000000000000000000000000000000000000000" as `0x${string}`;

// Set up wallet client
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({
  chain: baseSepolia,
  transport: http(),
  account,
});

async function main() {
  console.log("Wallet address:", account.address);
  console.log("Destination address:", DESTINATION_ADDRESS);

  // Step 1: Get fees from API
  console.log("\nStep 1: Getting CCTP fees...");
  const feeResponse = await fetch(
    `https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/${BASE_SEPOLIA_DOMAIN}/${AVALANCHE_FUJI_DOMAIN}?forward=true`,
    {
      method: "GET",
      headers: { "Content-Type": "application/json" },
    },
  );
  const fees = await feeResponse.json();
  console.log("Fees:", JSON.stringify(fees, null, 2));

  // Step 2: Calculate amounts
  console.log("\nStep 2: Calculating amounts...");
  const transferAmount = 10_000_000n; // 10 USDC
  const feeData = fees[0]; // Fast transfer
  const forwardFee = BigInt(feeData.forwardFee.med);
  const minimumFeeBps = feeData.minimumFee;
  const protocolFee =
    (transferAmount * BigInt(Math.round(minimumFeeBps * 100))) / 1_000_000n;
  const maxFee = forwardFee + protocolFee;
  const totalAmount = transferAmount + maxFee; // Total to burn

  console.log("Transfer amount:", Number(transferAmount) / 1_000_000, "USDC");
  console.log("Forward fee:", Number(forwardFee) / 1_000_000, "USDC");
  console.log("Protocol fee:", Number(protocolFee) / 1_000_000, "USDC");
  console.log("Max fee:", Number(maxFee) / 1_000_000, "USDC");
  console.log("Total to burn:", Number(totalAmount) / 1_000_000, "USDC");

  // Step 3: Approve USDC
  console.log("\nStep 3: Approving USDC transfer...");
  const approveTx = await client.sendTransaction({
    to: BASE_SEPOLIA_USDC,
    data: encodeFunctionData({
      abi: [
        {
          type: "function",
          name: "approve",
          stateMutability: "nonpayable",
          inputs: [
            { name: "spender", type: "address" },
            { name: "amount", type: "uint256" },
          ],
          outputs: [{ name: "", type: "bool" }],
        },
      ],
      functionName: "approve",
      args: [BASE_SEPOLIA_TOKEN_MESSENGER, totalAmount],
    }),
  });
  console.log("Approval Tx:", approveTx);

  // Step 4: Burn USDC with Forwarding Service hook
  console.log("\nStep 4: Burning USDC with Forwarding Service hook...");

  const burnTx = await client.sendTransaction({
    to: BASE_SEPOLIA_TOKEN_MESSENGER,
    data: encodeFunctionData({
      abi: [
        {
          type: "function",
          name: "depositForBurnWithHook",
          stateMutability: "nonpayable",
          inputs: [
            { name: "amount", type: "uint256" },
            { name: "destinationDomain", type: "uint32" },
            { name: "mintRecipient", type: "bytes32" },
            { name: "burnToken", type: "address" },
            { name: "destinationCaller", type: "bytes32" },
            { name: "maxFee", type: "uint256" },
            { name: "minFinalityThreshold", type: "uint32" },
            { name: "hookData", type: "bytes" },
          ],
          outputs: [],
        },
      ],
      functionName: "depositForBurnWithHook",
      args: [
        totalAmount,
        AVALANCHE_FUJI_DOMAIN,
        pad(DESTINATION_ADDRESS as `0x${string}`, { size: 32 }),
        BASE_SEPOLIA_USDC,
        pad("0x", { size: 32 }),
        maxFee,
        1000, // Fast Transfer
        FORWARDING_SERVICE_HOOK_DATA,
      ],
    }),
  });
  console.log("Burn Tx:", burnTx);

  console.log(
    "\nTransfer initiated. The Forwarding Service will automatically mint USDC on Avalanche.",
  );

  // Step 5: Verify the mint transaction
  console.log("\nStep 5: Verifying mint transaction...");
  process.stdout.write("Waiting for attestation...");

  let mintTx;
  while (!mintTx) {
    const messageResponse = await fetch(
      `https://iris-api-sandbox.circle.com/v2/messages/${BASE_SEPOLIA_DOMAIN}?transactionHash=${burnTx}`,
    );
    const data = await messageResponse.json();

    if (data.messages?.[0]?.forwardTxHash) {
      mintTx = data.messages[0].forwardTxHash;
      console.log("\n"); // New line after dots
    } else {
      process.stdout.write(".");
      await new Promise((resolve) => setTimeout(resolve, 2000));
    }
  }

  console.log("Mint Tx:", mintTx);
}

main().catch(console.error);
```

Run the script:

```bash theme={null}
npx tsx script.ts
```


# Troubleshoot CCTP Transfers
Source: https://developers.circle.com/cctp/howtos/troubleshoot-transfers

Diagnose and resolve stuck or failed crosschain USDC transfers

This guide helps you diagnose and resolve issues with CCTP transfers that appear
stuck or fail to complete. A CCTP transfer involves three stages, and problems
can occur at any point in the process.

## Transfer stages

A CCTP transfer consists of three stages:

1. **Burn**: USDC is burned on the source blockchain
2. **Attestation**: Circle's Attestation Service observes the burn and signs a
   message
3. **Mint**: The signed attestation is submitted to mint USDC on the destination
   blockchain

If your transfer appears stuck, first identify which stage has the issue.

## Identify where your transfer is stuck

Use the following steps to determine the current state of your transfer:

<Steps>
  <Step title="Check the burn transaction">
    Verify the burn transaction succeeded on the source blockchain using a block
    explorer. If the transaction failed or is pending, the issue is at the burn
    stage.
  </Step>

  <Step title="Query the attestation API">
    Call the [`GET /v2/messages`](/api-reference/cctp/all/get-messages-v2) endpoint
    with your transaction hash.

    Interpret the response:

    * **404 response**: The attestation service hasn't observed the burn yet. This
      is normal and expected. See
      [Why 404 responses are expected](/cctp/howtos/resolve-stuck-attestation#why-404-responses-are-expected).
    * **Empty `messages` array**: The burn exists but hasn't been processed yet.
    * **Status `pending`**: The burn is awaiting block confirmations.
    * **Status `complete` with attestation**: The attestation is ready. If your
      transfer is stuck, the issue is at the mint stage.
  </Step>

  <Step title="Check the mint transaction">
    If you have an attestation but your destination wallet doesn't have the USDC,
    either:

    * The mint transaction was never submitted
    * The mint transaction failed

    Check your destination blockchain for any failed `receiveMessage` transactions.
  </Step>
</Steps>

## Common issues and solutions

| Issue                                | Cause                                                   | Solution                                                              |
| ------------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------- |
| 404 persists for extended time       | Burn transaction may have failed or is still confirming | Verify burn succeeded on block explorer, if it failed, retry the burn |
| Attestation status remains `pending` | Waiting for block confirmations                         | Wait for sufficient confirmations based on finality threshold         |
| Have attestation but mint fails      | Gas issues, incorrect parameters, or nonce already used | See [Retry a Failed Mint](/cctp/howtos/retry-failed-mint)             |


# Withdraw USDC from HyperCore to EVM chains
Source: https://developers.circle.com/cctp/howtos/withdraw-usdc-from-hypercore-to-evm



This guide shows how to withdraw USDC from a HyperCore `spot` or `perp` balance
to an external EVM blockchain (such as Arbitrum, Ethereum, or Base) using the
HyperCore API. Withdrawals from HyperCore to EVM chains default to the Fast
Transfer method, due to the fast finality of HyperEVM.

The withdrawal process:

1. Debits your HyperCore balance (`spot` or `perp`)
2. Routes through HyperEVM where USDC is burned via CCTP
3. CCTP attests to the burn and mints on the destination chain
4. If automatic forwarding is enabled, the recipient receives funds directly

<Note>
  Withdrawals include a HyperCore fee and (if using the Forwarding Service) a CCTP
  forwarding fee. Ensure your withdrawal amount exceeds combined fees depending on
  your transfer.
</Note>

## Important considerations

Keep these things in mind when withdrawing USDC from HyperCore to EVM chains:

* **Data field:** If the data field is empty, the `CoreDepositWallet`
  automatically sets a default hook that enables automatic message forwarding on
  the destination blockchain, provided that the blockchain supports CCTP
  forwarding. If the data field is not empty, its contents are passed to the
  CCTP protocol as the value of the `hookData` field.

* **Destination caller:** The CCTP `destinationCaller` is always set to the zero
  address. Passing your own hook data means that anyone can receive the message
  on the destination blockchain.

* **Withdrawal fees:** In addition to the `maxFee` charged by the HyperCore
  blockchain, an additional fixed forwarding fee may be charged by CCTP if
  automatic forwarding is enabled. The forwarding fee amount depends on the
  destination blockchain and can be viewed by querying the `CoreDepositWallet`
  smart contract. Initially, the fee for forwarding to Arbitrum is 0.2 USDC. If
  the withdrawal includes custom hook data, the forwarding fee is not set and
  users have to receive the message on the destination blockchain themselves.

* **Minimum withdrawal amount:** If the withdrawal amount is less than the
  required forwarding fee, the transaction on HyperEVM reverts. Make sure the
  withdrawal amount is larger than the fees.

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)

* Prepared an EVM wallet with the private key available

* Funded your HyperCore account with USDC in either `spot` or `perp` balance

* Created a new Node project and installed dependencies:

  ```bash theme={null}
  npm install ethers
  npm install -D tsx typescript @types/node
  ```

* Created a `.env` file with required environment variables:

  ```text theme={null}
  PRIVATE_KEY=0x...
  DESTINATION_RECIPIENT=0x...  # Recipient address on destination chain
  ```

## Steps

Use the following steps to withdraw USDC from HyperCore to an EVM blockchain.

### Step 1. Construct the `sendToEvmWithData` action

Create a `sendToEvmWithData` action object with the following parameters:

* `type`: `sendToEvmWithData`
* `hyperliquidChain`: `Mainnet` (or `Testnet` for testnet)
* `signatureChainId`: The destination chain's EVM chain ID in hexadecimal format
  (e.g., `"0xa4b1"` for Arbitrum, `"0x1"` for Ethereum). Must match the
  destination chain.
* `token`: `USDC`
* `amount`: The amount of USDC as a string (e.g., `"10"` for 10 USDC, `"1.5"`
  for 1.5 USDC)
* `sourceDex`: `"spot"` to withdraw from spot balance, or `""` for `perp`
  balance
* `destinationRecipient`: The recipient address on the destination blockchain
* `addressEncoding`: `hex` for EVM chains or `base58` for Solana
* `destinationChainId`: The CCTP destination domain ID (for example, `3` for
  Arbitrum, `0` for Ethereum, `6` for Base)
* `gasLimit`: Gas limit for the transaction on the destination chain
* `data`: CCTP hook data (use `"0x"` for automatic forwarding)
* `nonce`: Current timestamp in milliseconds

```ts TypeScript theme={null}
// Example action payload for sendToEvmWithData
const action = {
  type: "sendToEvmWithData",
  hyperliquidChain: "Mainnet",
  signatureChainId: "0xa4b1", // Arbitrum chain ID used for signing
  token: "USDC",
  amount: "10", // 10 USDC
  sourceDex: "spot", // or "" for perp
  destinationRecipient: "0x1234567890123456789012345678901234567890",
  addressEncoding: "hex",
  destinationChainId: 3, // Arbitrum CCTP domain
  gasLimit: 200000,
  data: "0x", // "0x" enables automatic forwarding on the destination
  nonce: Date.now(),
};
```

### Step 2. Sign the action using EIP-712

Sign the action using the EIP-712 typed data signing standard. The signature
proves that you authorize this withdrawal.

The signing domain should include:

* `name`: `"HyperliquidSignTransaction"`
* `version`: `"1"`
* `chainId`: The chain ID from `signatureChainId` (as a number)
* `verifyingContract`: `"0x0000000000000000000000000000000000000000"`

```ts TypeScript theme={null}
import { Wallet, Signature } from "ethers";

// Sign the action using EIP-712
const wallet = new Wallet(privateKey);
const chainId = parseInt(signatureChainId, 16);

const domain = {
  name: "HyperliquidSignTransaction",
  version: "1",
  chainId,
  verifyingContract: "0x0000000000000000000000000000000000000000",
};

const types = {
  "HyperliquidTransaction:SendToEvmWithData": [
    { name: "hyperliquidChain", type: "string" },
    { name: "token", type: "string" },
    { name: "amount", type: "string" },
    { name: "sourceDex", type: "string" },
    { name: "destinationRecipient", type: "string" },
    { name: "addressEncoding", type: "string" },
    { name: "destinationChainId", type: "uint32" },
    { name: "gasLimit", type: "uint64" },
    { name: "data", type: "bytes" },
    { name: "nonce", type: "uint64" },
  ],
};

const message = {
  hyperliquidChain: "Mainnet",
  token: "USDC",
  amount: "10",
  sourceDex: "spot",
  destinationRecipient: "0x...",
  addressEncoding: "hex",
  destinationChainId: 3,
  gasLimit: BigInt(200000),
  data: "0x",
  nonce: BigInt(Date.now()),
};

const sigHex = await wallet.signTypedData(domain, types, message);
const sig = Signature.from(sigHex);
const signature = { r: sig.r, s: sig.s, v: sig.v };
```

### Step 3. Submit the signed action to the exchange API

Call the
[exchange](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint)
endpoint with the action, nonce, and signature.

```ts TypeScript theme={null}
const response = await fetch("https://api.hyperliquid.xyz/exchange", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action,
    nonce: timestamp,
    signature,
  }),
});

const result = await response.json();

if (response.status === 200 && result.status === "ok") {
  console.log("Withdrawal initiated successfully:", result);
} else {
  throw new Error(`Withdrawal failed: ${JSON.stringify(result)}`);
}
```

## Full example code

The following is a complete example of how to withdraw USDC from HyperCore to an
external EVM blockchain. By default, it withdraws 10 USDC from your perp balance
to Arbitrum testnet with automatic forwarding enabled. For other destination
chains, update `destinationChainId` (CCTP domain ID) and `signatureChainId`
(destination chain's EVM chain ID in hex) accordingly.

```ts TypeScript expandable theme={null}
/**
 * Script: Withdraw USDC from HyperCore to EVM chain
 * - Signs EIP-712 sendToEvmWithData action
 * - Submits to Hyperliquid /exchange API
 */

import { Wallet, Signature } from "ethers";

// -------- Configuration --------
const config = {
  privateKey: process.env.PRIVATE_KEY as string,

  // Transfer parameters
  amount: process.env.AMOUNT || "10", // 10 USDC
  sourceDex: process.env.SOURCE_DEX || "", // "" for perp, "spot" for spot

  // Destination parameters
  destinationRecipient: process.env.DESTINATION_RECIPIENT as string,
  destinationChainId: Number(process.env.DESTINATION_CHAIN_ID || 3), // 3 = Arbitrum
  addressEncoding: process.env.ADDRESS_ENCODING || "hex",
  gasLimit: Number(process.env.GAS_LIMIT || 200000),
  data: process.env.DATA || "0x", // "0x" enables automatic forwarding

  // Hyperliquid environment
  isMainnet:
    String(process.env.HL_IS_MAINNET || "false").toLowerCase() === "true",
  signatureChainId: "0xa4b1", // Destination chain's EVM chain ID (hex) for EIP-712 signing
};

// -------- Main Function --------
async function main() {
  // Validate required parameters
  if (!config.privateKey) {
    throw new Error("Set PRIVATE_KEY");
  }
  if (!config.destinationRecipient) {
    throw new Error("Set DESTINATION_RECIPIENT");
  }

  const apiUrl = config.isMainnet
    ? "https://api.hyperliquid.xyz"
    : "https://api.hyperliquid-testnet.xyz";
  const hyperliquidChain = config.isMainnet ? "Mainnet" : "Testnet";
  const chainId = parseInt(config.signatureChainId, 16);
  const timestamp = Date.now();

  console.log("Withdrawing from HyperCore:", hyperliquidChain);
  console.log("Source balance:", config.sourceDex || "perp");
  console.log("Amount (USDC):", config.amount);
  console.log("Destination recipient:", config.destinationRecipient);
  console.log("Destination chain ID:", config.destinationChainId);
  console.log("Gas limit:", config.gasLimit);

  // EIP-712 Domain
  const domain = {
    name: "HyperliquidSignTransaction",
    version: "1",
    chainId,
    verifyingContract: "0x0000000000000000000000000000000000000000",
  };

  // EIP-712 Types
  const types = {
    "HyperliquidTransaction:SendToEvmWithData": [
      { name: "hyperliquidChain", type: "string" },
      { name: "token", type: "string" },
      { name: "amount", type: "string" },
      { name: "sourceDex", type: "string" },
      { name: "destinationRecipient", type: "string" },
      { name: "addressEncoding", type: "string" },
      { name: "destinationChainId", type: "uint32" },
      { name: "gasLimit", type: "uint64" },
      { name: "data", type: "bytes" },
      { name: "nonce", type: "uint64" },
    ],
  };

  // Message to sign
  const message = {
    hyperliquidChain,
    token: "USDC",
    amount: config.amount,
    sourceDex: config.sourceDex,
    destinationRecipient: config.destinationRecipient,
    addressEncoding: config.addressEncoding,
    destinationChainId: config.destinationChainId,
    gasLimit: BigInt(config.gasLimit),
    data: config.data,
    nonce: BigInt(timestamp),
  };

  // Sign the message using EIP-712
  const wallet = new Wallet(config.privateKey);
  const sigHex = await wallet.signTypedData(domain, types, message);
  const sig = Signature.from(sigHex);

  // Build action payload
  const action = {
    type: "sendToEvmWithData",
    hyperliquidChain,
    signatureChainId: config.signatureChainId,
    token: "USDC",
    amount: config.amount,
    sourceDex: config.sourceDex,
    destinationRecipient: config.destinationRecipient,
    addressEncoding: config.addressEncoding,
    destinationChainId: config.destinationChainId,
    gasLimit: config.gasLimit,
    data: config.data,
    nonce: timestamp,
  };

  // Submit to Hyperliquid exchange API
  const response = await fetch(`${apiUrl}/exchange`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      action,
      nonce: timestamp,
      signature: { r: sig.r, s: sig.s, v: sig.v },
    }),
  });

  const result = await response.json();

  console.log("\nStatus:", response.status);
  console.log("Response:", JSON.stringify(result, null, 2));

  if (response.status === 200 && result.status === "ok") {
    console.log("\nWithdrawal initiated successfully");
  } else {
    throw new Error(`Withdrawal failed: ${JSON.stringify(result)}`);
  }
}

// Run
main().catch((error) => {
  console.error("Error:", error.message);
  process.exit(1);
});
```

Run the script:

```bash theme={null}
npx tsx script.ts
```


# Withdraw USDC from HyperCore to HyperEVM
Source: https://developers.circle.com/cctp/howtos/withdraw-usdc-from-hypercore-to-hyperevm



This guide shows how to withdraw USDC from a HyperCore `spot` or `perp` balance
to HyperEVM using the HyperCore API.

<Note>
  You can only withdraw USDC from HyperCore to the same address on HyperEVM. It's
  not possible to specify a different recipient address.
</Note>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)

* Prepared an EVM wallet with the private key available

* Funded your HyperCore account with USDC in either `spot` or `perp` balance

* Created a new Node project and installed dependencies:

  ```bash theme={null}
  npm install ethers
  npm install -D tsx typescript @types/node
  ```

* Created a `.env` file with required environment variables:

  ```text theme={null}
  PRIVATE_KEY=0x...
  ```

## Steps

Use the following steps to withdraw USDC from HyperCore to HyperEVM.

### Step 1. Construct the `sendAsset` action

Create a `sendAsset` action object with the following parameters:

* `type`: `sendAsset`
* `hyperliquidChain`: `Mainnet` (or `Testnet` for testnet)
* `signatureChainId`: An EVM chain ID used for EIP-712 replay protection. Must
  match between signing and the action payload, but can be any valid chain ID
  (for example, `"0xa4b1"` for Arbitrum)
* `destination`: The USDC token system address
  (`0x2000000000000000000000000000000000000000`)
* `sourceDex`: `"spot"` to withdraw from spot balance, or `""` for perp balance
* `destinationDex`: `"spot"`
* `token`: `USDC`
* `amount`: The amount of USDC as a human-readable string (for example, `"10"`
  for 10 USDC)
* `fromSubAccount`: Set to `""` for main account, or the subaccount address
* `nonce`: Current timestamp in milliseconds

```ts TypeScript theme={null}
const action = {
  type: "sendAsset",
  hyperliquidChain: "Testnet",
  signatureChainId: "0xa4b1", // EVM chain ID for EIP-712 replay protection
  destination: "0x2000000000000000000000000000000000000000",
  sourceDex: "", // "" for perp, "spot" for spot
  destinationDex: "spot",
  token: "USDC",
  amount: "10", // 10 USDC (human-readable)
  fromSubAccount: "",
  nonce: Date.now(),
};
```

### Step 2. Sign the action using EIP-712

Sign the action using the EIP-712 typed data signing standard. The signature
proves that you authorize this withdrawal.

The signing domain should include:

* `name`: `"HyperliquidSignTransaction"`
* `version`: `"1"`
* `chainId`: The chain ID from `signatureChainId` (as a number)
* `verifyingContract`: `"0x0000000000000000000000000000000000000000"`

```ts TypeScript theme={null}
import { Wallet, Signature } from "ethers";

async function signSendAssetAction(
  action: any,
  privateKey: string,
): Promise<{ r: string; s: string; v: number }> {
  const wallet = new Wallet(privateKey);

  // Convert chainId from hex to number
  const chainId = parseInt(action.signatureChainId, 16);

  // EIP-712 domain
  const domain = {
    name: "HyperliquidSignTransaction",
    version: "1",
    chainId,
    verifyingContract: "0x0000000000000000000000000000000000000000",
  };

  // EIP-712 types (must match Hyperliquid SDK's SEND_ASSET_SIGN_TYPES)
  const types = {
    "HyperliquidTransaction:SendAsset": [
      { name: "hyperliquidChain", type: "string" },
      { name: "destination", type: "string" },
      { name: "sourceDex", type: "string" },
      { name: "destinationDex", type: "string" },
      { name: "token", type: "string" },
      { name: "amount", type: "string" },
      { name: "fromSubAccount", type: "string" },
      { name: "nonce", type: "uint64" },
    ],
  };

  // Message to sign (only fields defined in EIP-712 types, not signatureChainId)
  const value = {
    hyperliquidChain: action.hyperliquidChain,
    destination: action.destination,
    sourceDex: action.sourceDex,
    destinationDex: action.destinationDex,
    token: action.token,
    amount: action.amount,
    fromSubAccount: action.fromSubAccount,
    nonce: BigInt(action.nonce),
  };

  // Sign the typed data
  const signature = await wallet.signTypedData(domain, types, value);

  // Split signature into r, s, v components
  const sig = Signature.from(signature);

  return {
    r: sig.r,
    s: sig.s,
    v: sig.v,
  };
}
```

### Step 3. Submit the signed action to the exchange API

Call the
[exchange](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#send-asset)
endpoint with the action, nonce, and signature.

```ts TypeScript theme={null}
async function submitSendAsset(
  action: any,
  signature: { r: string; s: string; v: number },
) {
  // Use https://api.hyperliquid.xyz for mainnet
  const response = await fetch("https://api.hyperliquid-testnet.xyz/exchange", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: action,
      nonce: action.nonce,
      signature: signature,
    }),
  });

  const data = await response.json();

  if (data.status === "ok") {
    console.log("Withdrawal successful:", data);
    return data;
  } else {
    throw new Error(`Withdrawal failed: ${JSON.stringify(data)}`);
  }
}
```

## Full example code

The following is a complete example of how to withdraw USDC from HyperCore to
HyperEVM. By default, it withdraws 10 USDC from your perp balance to HyperEVM
testnet.

```ts TypeScript expandable theme={null}
/**
 * Script: Withdraw USDC from HyperCore to HyperEVM
 * - Constructs a SendAsset action
 * - Signs the action using EIP-712
 * - Submits the signed action to the HyperCore API
 */

import { Wallet, Signature } from "ethers";

// -------- Configuration --------
const config = {
  privateKey: process.env.PRIVATE_KEY as string,

  // Transfer parameters
  amount: process.env.AMOUNT || "10", // 10 USDC (human-readable)
  sourceDex: process.env.SOURCE_DEX || "", // "" for perp, "spot" for spot

  // Hyperliquid environment
  isMainnet:
    String(process.env.HL_IS_MAINNET || "false").toLowerCase() === "true",
};

// System address for USDC token on HyperCore
const USDC_SYSTEM_ADDRESS = "0x2000000000000000000000000000000000000000";

// -------- Main Function --------
async function main() {
  if (!config.privateKey) {
    throw new Error("Set PRIVATE_KEY");
  }

  const apiUrl = config.isMainnet
    ? "https://api.hyperliquid.xyz"
    : "https://api.hyperliquid-testnet.xyz";
  const hyperliquidChain = config.isMainnet ? "Mainnet" : "Testnet";
  const signingChainId = "0xa4b1"; // EVM chain ID for EIP-712 signing (any valid chain ID works)
  const chainId = parseInt(signingChainId, 16);
  const timestamp = Date.now();

  const wallet = new Wallet(config.privateKey);
  console.log("Withdrawing from HyperCore to HyperEVM:", hyperliquidChain);
  console.log("User Address:", wallet.address);
  console.log("Source balance:", config.sourceDex || "perp");
  console.log("Amount (USDC):", config.amount);

  // EIP-712 Domain
  const domain = {
    name: "HyperliquidSignTransaction",
    version: "1",
    chainId,
    verifyingContract: "0x0000000000000000000000000000000000000000",
  };

  // Build action for signing
  const actionForSigning = {
    hyperliquidChain,
    signatureChainId: signingChainId,
    destination: USDC_SYSTEM_ADDRESS,
    sourceDex: config.sourceDex,
    destinationDex: "spot",
    token: "USDC",
    amount: config.amount,
    fromSubAccount: "",
    nonce: timestamp,
  };

  // EIP-712 Types (must match Hyperliquid SDK's SEND_ASSET_SIGN_TYPES)
  const types = {
    "HyperliquidTransaction:SendAsset": [
      { name: "hyperliquidChain", type: "string" },
      { name: "destination", type: "string" },
      { name: "sourceDex", type: "string" },
      { name: "destinationDex", type: "string" },
      { name: "token", type: "string" },
      { name: "amount", type: "string" },
      { name: "fromSubAccount", type: "string" },
      { name: "nonce", type: "uint64" },
    ],
  };

  // Message to sign (only fields defined in EIP-712 types, not signatureChainId)
  const message = {
    hyperliquidChain: actionForSigning.hyperliquidChain,
    destination: actionForSigning.destination,
    sourceDex: actionForSigning.sourceDex,
    destinationDex: actionForSigning.destinationDex,
    token: actionForSigning.token,
    amount: actionForSigning.amount,
    fromSubAccount: actionForSigning.fromSubAccount,
    nonce: BigInt(actionForSigning.nonce),
  };

  // Sign the message using EIP-712
  const sigHex = await wallet.signTypedData(domain, types, message);
  const sig = Signature.from(sigHex);

  // Build action payload for API (includes type and signatureChainId)
  const action: any = {
    type: "sendAsset",
    ...actionForSigning,
  };

  // Submit to Hyperliquid exchange API
  const response = await fetch(`${apiUrl}/exchange`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      action,
      nonce: timestamp,
      signature: { r: sig.r, s: sig.s, v: sig.v },
    }),
  });

  const result = await response.json();

  console.log("\nStatus:", response.status);
  console.log("Response:", JSON.stringify(result, null, 2));

  if (response.status === 200 && result.status === "ok") {
    console.log("\nWithdrawal initiated successfully");
  } else {
    throw new Error(`Withdrawal failed: ${JSON.stringify(result)}`);
  }
}

// Run
main().catch((error) => {
  console.error("Error:", error.message);
  process.exit(1);
});
```

Run the script:

```bash theme={null}
npx tsx script.ts
```


# Migrate from CCTP V1 (Legacy) to V2
Source: https://developers.circle.com/cctp/migration-from-v1-to-v2

Complete migration guide for developers upgrading CCTP integrations

This guide provides a summary of the breaking changes when migrating from
Cross-Chain Transfer Protocol (CCTP) V1 to V2. CCTP V2 introduces enhancements
including Fast Transfer, Hooks features, and improved API endpoints, but
requires updating your integration due to breaking changes.

<Important>
  **Important**: CCTP V2 isn't backward compatible with V1. It uses separate
  contracts, APIs, and transfer speeds. It also introduces new blockchain support,
  while deprecating some chains. Plan for a complete integration update rather
  than incremental changes.

  Failure to migrate will eventually result in loss of crosschain capabilities for
  your integration.
</Important>

Arc App Kit's [Bridge](https://docs.arc.io/app-kit/bridge) capability can help
simplify your migration to CCTP V2. See the
[Migrating with App Kit](#migrating-with-app-kit) section for more information.

## V1 deprecation

Circle is deprecating CCTP V1 to focus on the newer version, which is upgradable
and provides a faster, more secure, and more robust crosschain experience across
a wider network of blockchains.

### Naming changes

CCTP V2 is now referred to as CCTP (except in this document). The V1 version of
CCTP is now CCTP V1 (Legacy).

### Deprecation timeline

CCTP V1 will be phased out over the course of 10 months beginning in July 2026.
CCTP V2 contracts are available on all CCTP V1 chains except for Aptos, Noble,
and Sui. Aptos and Sui will be supported by V2 before the phase out begins.
Circle is working with Noble and Cosmos ecosystem teams on an intermediate
solution to route USDC flows to and from Noble.

### Access to funds

You will not lose access to funds during the V1 phase out. All pending
redemptions will remain available as CCTP V1 (legacy) begins its phase out.
Circle will maintain minter allowances greater than the total of pending
attestations, ensuring every redemption can be processed before V1 contracts are
fully paused.

The deprecation process is designed to wind down activity gradually, message
limits will tighten over time until no new burns can be initiated, bringing
transfer volume to zero before contracts are fully paused.

### Additional resources

In addition to this guide and [Arc App Kit](https://docs.arc.io/app-kit), you
can contact the Circle team on the
[BuildOnCircle Discord](https://discord.com/invite/buildoncircle) for questions
and migration support.

## Summary of breaking changes

The latest version of CCTP introduces architectural changes that make it
incompatible with V1 integrations. You must update your implementation to use
the new contracts, APIs, and transfer speeds. Additionally, the overall flow of
the protocol has been streamlined, which means you need to update your
integration to use the new functions.

* Contracts are deployed at
  [different addresses](/cctp/references/contract-addresses) than V1 contracts.
  You should update your integration to point to the new contract addresses.
* [Contract interfaces](/cctp/references/contract-interfaces) have changed.
  Importantly, the
  [`depositForBurn` function](/cctp/references/contract-interfaces#depositforburn)
  now takes additional parameters. You should update your integration to use the
  new ABIs and contract calls.
* CCTP now allows you to specify a transfer speed. The `finalityThreshold`
  parameter specifies whether the transfer should be a
  [Fast Transfer](/cctp/concepts/finality-and-block-confirmations#fast-transfer-attestation-times)
  or a
  [Standard Transfer](/cctp/concepts/finality-and-block-confirmations#standard-transfer-attestation-times).
* You no longer need to extract the message from the onchain transaction to
  fetch an attestation. Instead, you can call the new
  `/v2/messages/{sourceDomainId}` endpoint with the transaction hash to get the
  message and attestation in a single call.
* API endpoints have changed. The new `/v2/` endpoints have different functions
  than the old `/v1/` endpoints. You should update your integration to use the
  new endpoints. Review the
  [CCTP API reference](/api-reference/cctp/all/get-public-keys-v2) for details
  on the changes to the CCTP offchain API.
* [Fees](/cctp/concepts/fees) have been introduced. Fast Transfer has a variable
  fee based on the source chain. You should update your integration to account
  for the new fees.

## Migrating with App Kit

[Arc App Kit](https://docs.arc.io/app-kit) provides a simplified migration path
by abstracting routine setup steps and standardizing bridging flows. This
enables you to integrate bridging operations with minimal code.

### Benefits of using App Kit to bridge

* **No contract management**: App Kit handles contract addresses, ABIs, and
  function calls for you.
* **No attestation polling**: Automatically retrieves attestations without
  manual API calls.
* **Built-in CCTP features**: Access Fast Transfer and other capabilities
  through simple configuration.
* **Type-safe interface**: Compatible with `viem` and `ethers` for safer
  development.
* **Fee collection**: Optionally collect fees from transfers to monetize your
  application.

### Example migration

Replace manual contract calls and API polling with a single method:

```typescript theme={null}
import { AppKit } from "@circle-fin/app-kit";
import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2";

// Initialize App Kit
const kit = new AppKit();

// Create adapter for your wallet
const adapter = createAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
});

// Transfer USDC with Fast Transfer
const result = await kit.bridge({
  from: { adapter, chain: "Ethereum" },
  to: { adapter, chain: "Base" },
  amount: "100",
  config: {
    transferSpeed: "FAST", // Use Fast Transfer
    maxFee: "5000000", // Max 5 USDC fee (optional)
  },
});

// Result includes transaction details and explorer URLs
console.log("Transfer complete:", result.steps);
```

For more information, see Arc App Kit's
[Bridge](https://docs.arc.io/app-kit/bridge) capability.

## Changes to smart contracts

CCTP uses new smart contracts with different names, addresses, and interfaces.
You must update your integration to use the new contracts and their new function
signatures.

### Contract name and address changes

All legacy contracts have V2 equivalents deployed at new addresses:

| Legacy contract      | V2 contract            | Documentation                                                   |
| -------------------- | ---------------------- | --------------------------------------------------------------- |
| `TokenMessenger`     | `TokenMessengerV2`     | [V2 Interface](/cctp/evm-smart-contracts#tokenmessengerv2)      |
| `MessageTransmitter` | `MessageTransmitterV2` | [V2 Interface](/cctp/evm-smart-contracts#messagetransmitterv2)  |
| `TokenMinter`        | `TokenMinterV2`        | [V2 Addresses](/cctp/evm-smart-contracts#tokenminterv2-mainnet) |
| `Message`            | `MessageV2`            | [V2 Addresses](/cctp/evm-smart-contracts#messagev2-mainnet)     |

<Important>
  **Important**: V2 contracts are deployed at different addresses than V1
  contracts. See the
  [CCTP Contract Addresses](/cctp/evm-smart-contracts#mainnet-contract-addresses)
  for the complete list of mainnet and testnet addresses.
</Important>

### TokenMessengerV2 changes

**Modified functions:**

* `depositForBurn()` now requires three additional parameters:
  * `destinationCaller` (bytes32) - Address that can call `receiveMessage` on
    destination
  * `maxFee` (uint256) - Maximum fee for Fast Transfer in units of burn token
  * `minFinalityThreshold` (uint32) - Minimum finality level (1000 for Fast,
    2000 for Standard)

**New functions:**

* `depositForBurnWithHook()` - Enables custom logic execution on destination
  chain via hook data
* `getMinFeeAmount()` - Calculates minimum fee for Standard Transfer (on
  supported chains only)

**Removed functions:**

* `depositForBurnWithCaller()` - Use `destinationCaller` parameter in
  `depositForBurn()` instead
* `replaceDepositForBurn()` - No V2 equivalent available

### Contract source code

Full contract source code is available on GitHub:

* [CCTP EVM Contracts](https://github.com/circlefin/evm-cctp-contracts) - Main
  repository
* [Contract ABIs](https://github.com/circlefin/evm-cctp-contracts/tree/master/docs/abis/cctp/v2) -
  Interface definitions

## API migration guide

CCTP streamlines the API workflow by combining message retrieval and attestation
into single calls, while introducing new endpoints for features like Fast
Transfer monitoring and re-attestation.

### Workflow changes

The API eliminates the need to extract the message emitted by the onchain
transaction:

**Legacy workflow:**

1. Get the transaction receipt from the onchain transaction
2. Find the MessageSent event in the transaction receipt
3. Hash the message bytes emitted by the MessageSent event
4. Call `/v1/attestations/{messageHash}` to get an attestation

**V2 workflow:**

1. Call `/v2/messages/{sourceDomainId}` with transaction hash or nonce to get
   message, attestation, and decoded data

#### Legacy workflow example

```javascript theme={null}
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";

// V1 requires multiple steps to extract message and get attestation
const burnTxHash = "0x1234..."; // Transaction hash from depositForBurn

// Step 1: Get the transaction receipt from the onchain transaction
const client = createPublicClient({
  chain: sepolia,
  transport: http(),
});
const transactionReceipt = await client.getTransactionReceipt({
  hash: burnTxHash,
});

// Step 2: Find the MessageSent event in the transaction receipt
const eventTopic = keccak256(toBytes("MessageSent(bytes)"));
const log = transactionReceipt.logs.find((l) => l.topics[0] === eventTopic);
const messageBytes = decodeAbiParameters([{ type: "bytes" }], log.data)[0];

// Step 3: Hash the message bytes emitted by the MessageSent event
const messageHash = keccak256(messageBytes);

// Step 4: Call attestation API with the message hash
let attestationResponse = { status: "pending" };
while (attestationResponse.status !== "complete") {
  const response = await fetch(
    `https://iris-api-sandbox.circle.com/attestations/${messageHash}`,
  );
  attestationResponse = await response.json();
  await new Promise((r) => setTimeout(r, 2000));
}

const attestation = attestationResponse.attestation;

// Now you can use messageBytes and attestation to call receiveMessage
```

#### V2 workflow example

```javascript theme={null}
// V2 gets message and attestation in a single call
const sourceDomainId = 0; // Ethereum mainnet
const transactionHash = "0x1234...";

// Single step: Get message, attestation, and decoded data
const response = await fetch(
  `https://iris-api.circle.com/v2/messages/${sourceDomainId}?transactionHash=${transactionHash}`,
);
const data = await response.json();

// All data available in single response
const message = data.messages[0].message;
const attestation = data.messages[0].attestation;
const decodedMessage = data.messages[0].decodedMessage;

// Now you can use message and attestation to call receiveMessage
// You can also access decoded fields without manual parsing
console.log(`Amount: ${decodedMessage.decodedMessageBody.amount}`);
console.log(`Recipient: ${decodedMessage.decodedMessageBody.mintRecipient}`);
```

### Endpoint migration mapping

| Legacy endpoint                                       | V2 replacement                                             | Migration notes                                        |
| ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| `GET /v1/attestations/{messageHash}`                  | `GET /v2/messages/{sourceDomainId}?transactionHash={hash}` | Combined into messages endpoint with enhanced response |
| `GET /v1/messages/{sourceDomainId}/{transactionHash}` | `GET /v2/messages/{sourceDomainId}?transactionHash={hash}` | Enhanced with decoded data and attestation             |
| `GET /v1/publicKeys`                                  | `GET /v2/publicKeys`                                       | Multi-version support, backward compatible             |

### New V2-only endpoints

V2 introduces additional endpoints for advanced features:

| Endpoint                                                 | Purpose                           | Use case                                               |
| -------------------------------------------------------- | --------------------------------- | ------------------------------------------------------ |
| `POST /v2/reattest/{nonce}`                              | Re-attest messages for edge cases | Handle expired Fast Transfer burns or finality changes |
| `GET /v2/fastBurn/USDC/allowance`                        | Monitor Fast Transfer allowance   | Check remaining Fast Transfer capacity in real-time    |
| `GET /v2/burn/USDC/fees/{sourceDomainId}/{destDomainId}` | Get current transfer fees         | Calculate fees before initiating transfers             |

### Message data changes

V2 message responses now include the decoded message data and attestation:

#### V1 messages response

```json theme={null}
{
  "messages": [
    {
      "attestation": "0xdc485fb2f9a8f68c871f4ca7386dee9086ff9d4387756990c9c4b9280338325252866861f9495dce3128cd524d525c44e8e7b731dedd3098a618dcc19c45be1e1c",
      "message": "0x00000000000000050000000300000000000194c2...",
      "eventNonce": "9682"
    }
  ]
}
```

#### V2 messages response

```json theme={null}
{
  "messages": [
    {
      "message": "0x00000000000000050000000300000000000194c2...",
      "eventNonce": "9682",
      "attestation": "0x6edd90f4a0ad0212fd9fbbd5058a25aa8ee10ce77e4fc143567bbe73fb6e164f384a3e14d350c8a4fc50b781177297e03c16b304e8d7656391df0f59a75a271f1b",
      "decodedMessage": {
        "sourceDomain": "7",
        "destinationDomain": "5",
        "nonce": "569",
        "sender": "0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350",
        "recipient": "0xb7317b4EFEa194a22bEB42506065D3772C2E95EF",
        "destinationCaller": "0xf2Edb1Ad445C6abb1260049AcDDCA9E84D7D8aaA",
        "messageBody": "0x00000000000000050000000300000000000194c2...",
        "decodedMessageBody": {
          "burnToken": "0x4Bc078D75390C0f5CCc3e7f59Ae2159557C5eb85",
          "mintRecipient": "0xb7317b4EFEa194a22bEB42506065D3772C2E95EF",
          "amount": "5000",
          "messageSender": "0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350"
        }
      },
      "cctpVersion": 2,
      "status": "complete"
    }
  ]
}
```

<Note>
  On Stellar, USDC precision and address encoding differ from other CCTP-supported
  blockchains. For inbound transfers, use
  [`CctpForwarder`](/cctp/references/stellar#use-cctpforwarder-for-stellar-recipients)
  so funds reach the correct recipient. See
  [CCTP on Stellar](/cctp/references/stellar).
</Note>


# Transfer USDC from Ethereum to Arc
Source: https://developers.circle.com/cctp/quickstarts/transfer-usdc-ethereum-to-arc

Build a script to transfer USDC between EVM blockchains using CCTP

This guide demonstrates how to transfer USDC from Ethereum Sepolia to Arc
testnet using CCTP. You use the [viem](https://viem.sh/) framework to interact
with [CCTP contracts](/cctp/references/contract-addresses) and the
[CCTP API](/api-reference/cctp/all/get-messages-v2) to retrieve attestations.

<Tip>
  **Use [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit) to
  simplify crosschain transfers with CCTP.**

  This quickstart shows how to transfer USDC from  to
  &#x20;using a manual CCTP integration. The example is for learning
  or for developers who need a manual integration.

  To streamline this, use Bridge Kit to transfer USDC in just a few lines of code.
</Tip>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)
* Prepared an EVM testnet wallet with the private key available
  * Added Arc testnet network to your wallet
    ([network details](https://docs.arc.io/arc/references/connect-to-arc#wallet-setup))
* Funded your wallet with the following testnet tokens:
  * Sepolia ETH (native token) from a
    [public faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia)
  * Sepolia USDC from the [Circle Faucet](https://faucet.circle.com)
  * Arc testnet USDC from the [Circle Faucet](https://faucet.circle.com) if you
    choose the direct mint path below, because the destination wallet must pay
    gas to call `receiveMessage`

## Step 1. Set up the project

### 1.1. Create the project and install dependencies

```shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir cctp-evm-transfer
cd cctp-evm-transfer
npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="tsx --env-file=.env index.ts"

# Install runtime dependencies
npm install viem

# Install dev dependencies
npm install --save-dev @types/node tsx typescript
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.3. Set environment variables

Open `.env` in your editor and add:

```text theme={null}
PRIVATE_KEY=YOUR_ETHEREUM_SEPOLIA_PRIVATE_KEY
```

* `PRIVATE_KEY` is the private key for the Ethereum Sepolia EOA that signs the
  source-chain approval and burn transactions. The direct-mint path also uses
  the same key to submit the destination mint on Arc.

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

The `npm run start` command loads variables from `.env` using Node.js native
env-file support.

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>

## Step 2: Configure the script

This section covers the necessary setup for the transfer script, including
defining keys and addresses, and configuring the wallet client for interacting
with the source and destination chains.

### 2.1. Define configuration constants

The script predefines the contract addresses, transfer amount, and maximum fee.
Update the `DESTINATION_ADDRESS` with your wallet address.

For simplicity, this quickstart uses the same EOA as the Ethereum Sepolia source
signer and the Arc recipient. In production, these can be different addresses.

```ts TypeScript theme={null}
// Authentication
const PRIVATE_KEY = process.env.PRIVATE_KEY;
const account = privateKeyToAccount(PRIVATE_KEY as `0x${string}`);

// Contract Addresses
const ETHEREUM_SEPOLIA_USDC = "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238";
const ETHEREUM_SEPOLIA_TOKEN_MESSENGER =
  "0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa";
const ARC_TESTNET_MESSAGE_TRANSMITTER =
  "0xe737e5cebeeba77efe34d4aa090756590b1ce275";

// Transfer Parameters
const DESTINATION_ADDRESS = account.address; // Address to receive minted tokens on destination chain
const AMOUNT = 1_000_000n; // 1 USDC (1 USDC = 1,000,000 subunits)
const maxFee = 500n; // 0.0005 USDC (500 subunits)

// Bytes32 Formatted Parameters
const DESTINATION_ADDRESS_BYTES32 = `0x000000000000000000000000${DESTINATION_ADDRESS.slice(
  2,
)}`; // Destination address in bytes32 format
const DESTINATION_CALLER_BYTES32 =
  "0x0000000000000000000000000000000000000000000000000000000000000000"; // Empty bytes32 allows any address to call MessageTransmitterV2.receiveMessage()

// Chain-specific Parameters
const ETHEREUM_SEPOLIA_DOMAIN = 0; // Source domain ID for Ethereum Sepolia
const ARC_TESTNET_DOMAIN = 26; // Destination domain ID for Arc testnet
```

### 2.2. Set up wallet clients

The wallet client configures the appropriate network settings using `viem`. The
direct-mint path below uses clients for both Ethereum Sepolia and Arc testnet.
The [Forwarding Service](/cctp/concepts/forwarding-service) path only needs the
source-chain client on Ethereum Sepolia.

```ts TypeScript theme={null}
// Set up the wallet clients
const sepoliaClient = createWalletClient({
  chain: sepolia,
  transport: http(),
  account,
});

const arcClient = createWalletClient({
  chain: arcTestnet,
  transport: http(),
  account,
});
```

## Step 3: Implement the transfer logic

The following sections outline the core transfer logic.

The path diverges at the source-chain burn transaction:

* **Direct mint** uses `depositForBurn`, then retrieves an attestation and calls
  `receiveMessage` on Arc.
* **Forwarding Service** uses `depositForBurnWithHook`, then lets Circle handle
  the destination-side mint on Arc.

<Tabs>
  <Tab title="Forwarding Service">
    ### 3.1. Get forwarding fees and calculate the burn amount

    Before you burn USDC with the Forwarding Service, query the CCTP fee endpoint
    with `forward=true`. The forwarding fee is dynamic, so fetch it immediately
    before the transfer. The returned `maxFee` must cover both the CCTP protocol fee
    and the forwarding fee.

    ```ts TypeScript theme={null}
    const FORWARDING_SERVICE_HOOK_DATA =
      "0x636374702d666f72776172640000000000000000000000000000000000000000" as `0x${string}`;

    async function getForwardingFees() {
      const response = await fetch(
        `https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/${ETHEREUM_SEPOLIA_DOMAIN}/${ARC_TESTNET_DOMAIN}?forward=true`,
        {
          method: "GET",
          headers: { "Content-Type": "application/json" },
        },
      );

      if (!response.ok) {
        throw new Error(`Failed to fetch fees: ${await response.text()}`);
      }

      return response.json();
    }

    async function calculateForwardingAmounts() {
      const fees = await getForwardingFees();
      const feeData = fees.find(
        (fee: { finalityThreshold: number }) => fee.finalityThreshold === 1000,
      );

      if (!feeData) {
        throw new Error("Fast-transfer forwarding fees not available");
      }

      const forwardFee = BigInt(feeData.forwardFee.med);
      const protocolFee =
        (AMOUNT * BigInt(Math.round(feeData.minimumFee * 100))) / 1_000_000n;
      const maxFee = forwardFee + protocolFee;
      const totalAmount = AMOUNT + maxFee;

      return { maxFee, totalAmount };
    }
    ```

    ### 3.2. Approve the total burn amount

    Approve the total amount you will burn on the source chain. For the forwarding
    path, that is the transfer amount plus the forwarding and protocol fees.

    ```ts TypeScript theme={null}
    async function approveUSDC(amount: bigint) {
      console.log("Approving USDC transfer...");
      const approveTx = await sepoliaClient.sendTransaction({
        to: ETHEREUM_SEPOLIA_USDC,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "approve",
              stateMutability: "nonpayable",
              inputs: [
                { name: "spender", type: "address" },
                { name: "amount", type: "uint256" },
              ],
              outputs: [{ name: "", type: "bool" }],
            },
          ],
          functionName: "approve",
          args: [ETHEREUM_SEPOLIA_TOKEN_MESSENGER, amount],
        }),
      });
      console.log(`USDC Approval Tx: ${approveTx}`);
    }
    ```

    ### 3.3. Burn USDC with the Forwarding Service hook

    Use `depositForBurnWithHook` on the source chain. The forwarding hook data tells
    Circle to handle the destination-side `receiveMessage` call on Arc.

    ```ts TypeScript theme={null}
    async function burnUSDCWithForwarding(totalAmount: bigint, maxFee: bigint) {
      console.log("Burning USDC on Ethereum Sepolia with Forwarding Service...");

      const burnTx = await sepoliaClient.sendTransaction({
        to: ETHEREUM_SEPOLIA_TOKEN_MESSENGER,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "depositForBurnWithHook",
              stateMutability: "nonpayable",
              inputs: [
                { name: "amount", type: "uint256" },
                { name: "destinationDomain", type: "uint32" },
                { name: "mintRecipient", type: "bytes32" },
                { name: "burnToken", type: "address" },
                { name: "destinationCaller", type: "bytes32" },
                { name: "maxFee", type: "uint256" },
                { name: "minFinalityThreshold", type: "uint32" },
                { name: "hookData", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "depositForBurnWithHook",
          args: [
            totalAmount,
            ARC_TESTNET_DOMAIN,
            DESTINATION_ADDRESS_BYTES32,
            ETHEREUM_SEPOLIA_USDC,
            DESTINATION_CALLER_BYTES32,
            maxFee,
            1000,
            FORWARDING_SERVICE_HOOK_DATA,
          ],
        }),
      });

      console.log(`Burn Tx: ${burnTx}`);
      return burnTx;
    }
    ```

    ### 3.4. Verify the forwarded mint

    After the burn is confirmed, poll the Iris API until it returns a
    `forwardTxHash`. That hash is the Arc destination mint transaction submitted by
    Circle. In the forwarding path, `forwardTxHash` is the completion signal for the
    destination-side mint. You do not need to retrieve an attestation and call
    `receiveMessage` yourself.

    ```ts TypeScript theme={null}
    async function waitForForwardedMint(transactionHash: string) {
      console.log("Waiting for Forwarding Service to mint on Arc...");

      while (true) {
        const response = await fetch(
          `https://iris-api-sandbox.circle.com/v2/messages/${ETHEREUM_SEPOLIA_DOMAIN}?transactionHash=${transactionHash}`,
          { method: "GET" },
        );

        if (!response.ok) {
          await new Promise((resolve) => setTimeout(resolve, 5000));
          continue;
        }

        const data = await response.json();
        const forwardTxHash = data?.messages?.[0]?.forwardTxHash;

        if (forwardTxHash) {
          console.log(`Forwarded Mint Tx: ${forwardTxHash}`);
          return forwardTxHash;
        }

        await new Promise((resolve) => setTimeout(resolve, 5000));
      }
    }
    ```
  </Tab>

  <Tab title="Direct mint">
    ### 3.1. Approve USDC

    Grant approval for the
    [`TokenMessengerV2` contract](/cctp/references/contract-addresses) deployed on
    Ethereum Sepolia to withdraw USDC from your wallet. This allows the contract to
    burn USDC when you initiate the transfer.

    ```ts TypeScript theme={null}
    async function approveUSDC() {
      console.log("Approving USDC transfer...");
      const approveTx = await sepoliaClient.sendTransaction({
        to: ETHEREUM_SEPOLIA_USDC,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "approve",
              stateMutability: "nonpayable",
              inputs: [
                { name: "spender", type: "address" },
                { name: "amount", type: "uint256" },
              ],
              outputs: [{ name: "", type: "bool" }],
            },
          ],
          functionName: "approve",
          args: [ETHEREUM_SEPOLIA_TOKEN_MESSENGER, 10_000_000n], // 10 USDC allowance
        }),
      });
      console.log(`USDC Approval Tx: ${approveTx}`);
    }
    ```

    ### 3.2. Burn USDC

    Call the `depositForBurn` function from the
    [`TokenMessengerV2` contract](/cctp/references/contract-interfaces#depositforburn)
    deployed on Ethereum Sepolia to burn USDC on that source chain. You specify the
    following parameters:

    * **Burn amount**: The amount of USDC to burn
    * **Destination domain**: The target blockchain for minting USDC (see
      [supported chains and domains](/cctp/concepts/supported-chains-and-domains))
    * **Mint recipient**: The wallet address that will receive the minted USDC
    * **Burn token**: The contract address of the USDC token being burned on the
      source chain
    * **Destination caller**: The address on the target chain to call
      `receiveMessage`
    * **Max fee**: The maximum [fee](/cctp/concepts/fees) allowed for the transfer
    * **Finality threshold**: Determines whether it's a
      [Fast Transfer](/cctp/concepts/finality-and-block-confirmations#fast-transfer-attestation-times)
      (1000 or less) or a
      [Standard Transfer](/cctp/concepts/finality-and-block-confirmations#standard-transfer-attestation-times)
      (2000 or more)

    ```ts TypeScript theme={null}
    async function burnUSDC() {
      console.log("Burning USDC on Ethereum Sepolia...");
      const burnTx = await sepoliaClient.sendTransaction({
        to: ETHEREUM_SEPOLIA_TOKEN_MESSENGER,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "depositForBurn",
              stateMutability: "nonpayable",
              inputs: [
                { name: "amount", type: "uint256" },
                { name: "destinationDomain", type: "uint32" },
                { name: "mintRecipient", type: "bytes32" },
                { name: "burnToken", type: "address" },
                { name: "destinationCaller", type: "bytes32" },
                { name: "maxFee", type: "uint256" },
                { name: "minFinalityThreshold", type: "uint32" },
              ],
              outputs: [],
            },
          ],
          functionName: "depositForBurn",
          args: [
            AMOUNT,
            ARC_TESTNET_DOMAIN,
            DESTINATION_ADDRESS_BYTES32,
            ETHEREUM_SEPOLIA_USDC,
            DESTINATION_CALLER_BYTES32,
            maxFee,
            1000, // minFinalityThreshold (1000 or less for Fast Transfer)
          ],
        }),
      });
      console.log(`Burn Tx: ${burnTx}`);
      return burnTx;
    }
    ```

    ### 3.3. Retrieve attestation

    Retrieve the attestation required to complete the CCTP transfer by calling
    Circle's attestation API.

    * Call Circle's [`GET /v2/messages`](/api-reference/cctp/all/get-messages-v2)
      API endpoint to retrieve the attestation.
    * Pass the `srcDomain` argument from the
      [CCTP domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers)
      for your source chain.
    * Pass `transactionHash` from the value returned by `sendTransaction` within the
      `burnUSDC` function above.

    ```ts TypeScript theme={null}
    async function retrieveAttestation(transactionHash: string) {
      console.log("Retrieving attestation...");
      const url = `https://iris-api-sandbox.circle.com/v2/messages/${ETHEREUM_SEPOLIA_DOMAIN}?transactionHash=${transactionHash}`;
      while (true) {
        try {
          const response = await fetch(url, { method: "GET" });

          if (!response.ok) {
            if (response.status !== 404) {
              const text = await response.text().catch(() => "");
              console.error(
                "Error fetching attestation:",
                `${response.status} ${response.statusText}${
                  text ? ` - ${text}` : ""
                }`,
              );
            }
            await new Promise((resolve) => setTimeout(resolve, 5000));
            continue;
          }

          const data = (await response.json()) as AttestationResponse;

          if (data?.messages?.[0]?.status === "complete") {
            console.log("Attestation retrieved successfully!");
            return data.messages[0];
          }
          console.log("Waiting for attestation...");
          await new Promise((resolve) => setTimeout(resolve, 5000));
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          console.error("Error fetching attestation:", message);
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }
    }
    ```

    ### 3.4. Mint USDC

    Call the
    [`receiveMessage` function](/cctp/references/contract-interfaces#receivemessage)
    from the [`MessageTransmitterV2` contract](/cctp/references/contract-addresses)
    deployed on the Arc testnet to mint USDC on that destination chain.

    * Pass the signed attestation and the message data as parameters.
    * The function processes the attestation and mints USDC to the specified Arc
      testnet wallet address.

    ```ts TypeScript theme={null}
    async function mintUSDC(attestation: AttestationMessage) {
      console.log("Minting USDC on Arc testnet...");
      const mintTx = await arcClient.sendTransaction({
        to: ARC_TESTNET_MESSAGE_TRANSMITTER,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "receiveMessage",
              stateMutability: "nonpayable",
              inputs: [
                { name: "message", type: "bytes" },
                { name: "attestation", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "receiveMessage",
          args: [
            attestation.message as `0x${string}`,
            attestation.attestation as `0x${string}`,
          ],
        }),
      });
      console.log(`Mint Tx: ${mintTx}`);
    }
    ```
  </Tab>
</Tabs>

## Step 4: Complete script

Create a `index.ts` file in your project directory and populate it with the
complete code below for the path you want to test.

<Tabs>
  <Tab title="Forwarding Service">
    ```ts index.ts expandable theme={null}
    import {
      createPublicClient,
      createWalletClient,
      http,
      encodeFunctionData,
      pad,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { sepolia } from "viem/chains";

    type FeeQuote = {
      finalityThreshold: number;
      minimumFee: number;
      forwardFee: { med: number };
    };

    const PRIVATE_KEY = process.env.PRIVATE_KEY;
    const account = privateKeyToAccount(PRIVATE_KEY as `0x${string}`);

    const ETHEREUM_SEPOLIA_USDC = "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238";
    const ETHEREUM_SEPOLIA_TOKEN_MESSENGER =
      "0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa";

    const DESTINATION_ADDRESS = account.address;
    const AMOUNT = 1_000_000n;
    const ETHEREUM_SEPOLIA_DOMAIN = 0;
    const ARC_TESTNET_DOMAIN = 26;
    const DESTINATION_ADDRESS_BYTES32 = pad(DESTINATION_ADDRESS, { size: 32 });
    const DESTINATION_CALLER_BYTES32 = pad("0x", { size: 32 });
    const FORWARDING_SERVICE_HOOK_DATA =
      "0x636374702d666f72776172640000000000000000000000000000000000000000" as `0x${string}`;

    const sepoliaClient = createWalletClient({
      chain: sepolia,
      transport: http(),
      account,
    });
    const sepoliaPublicClient = createPublicClient({
      chain: sepolia,
      transport: http(),
    });

    async function approveUSDC(amount: bigint) {
      console.log("Approving USDC transfer...");
      const approveTx = await sepoliaClient.sendTransaction({
        to: ETHEREUM_SEPOLIA_USDC,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "approve",
              stateMutability: "nonpayable",
              inputs: [
                { name: "spender", type: "address" },
                { name: "amount", type: "uint256" },
              ],
              outputs: [{ name: "", type: "bool" }],
            },
          ],
          functionName: "approve",
          args: [ETHEREUM_SEPOLIA_TOKEN_MESSENGER, amount],
        }),
      });
      console.log(`USDC Approval Tx: ${approveTx}`);
      await sepoliaPublicClient.waitForTransactionReceipt({ hash: approveTx });
    }

    async function getForwardingFeeQuote() {
      const response = await fetch(
        `https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/${ETHEREUM_SEPOLIA_DOMAIN}/${ARC_TESTNET_DOMAIN}?forward=true`,
        {
          method: "GET",
          headers: { "Content-Type": "application/json" },
        },
      );

      if (!response.ok) {
        throw new Error(`Failed to fetch fees: ${await response.text()}`);
      }

      const fees = (await response.json()) as FeeQuote[];
      const feeData = fees.find((fee) => fee.finalityThreshold === 1000);

      if (!feeData) {
        throw new Error("Fast-transfer forwarding fees not available");
      }

      return feeData;
    }

    async function calculateForwardingAmounts() {
      const feeData = await getForwardingFeeQuote();
      const forwardFee = BigInt(feeData.forwardFee.med);
      const protocolFee =
        (AMOUNT * BigInt(Math.round(feeData.minimumFee * 100))) / 1_000_000n;
      const maxFee = forwardFee + protocolFee;
      const totalAmount = AMOUNT + maxFee;

      console.log("Forward fee:", Number(forwardFee) / 1_000_000, "USDC");
      console.log("Protocol fee:", Number(protocolFee) / 1_000_000, "USDC");
      console.log("Max fee:", Number(maxFee) / 1_000_000, "USDC");
      console.log("Total to burn:", Number(totalAmount) / 1_000_000, "USDC");

      return { maxFee, totalAmount };
    }

    async function burnUSDCWithForwarding(totalAmount: bigint, maxFee: bigint) {
      console.log("Burning USDC on Ethereum Sepolia with Forwarding Service...");
      const burnTx = await sepoliaClient.sendTransaction({
        to: ETHEREUM_SEPOLIA_TOKEN_MESSENGER,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "depositForBurnWithHook",
              stateMutability: "nonpayable",
              inputs: [
                { name: "amount", type: "uint256" },
                { name: "destinationDomain", type: "uint32" },
                { name: "mintRecipient", type: "bytes32" },
                { name: "burnToken", type: "address" },
                { name: "destinationCaller", type: "bytes32" },
                { name: "maxFee", type: "uint256" },
                { name: "minFinalityThreshold", type: "uint32" },
                { name: "hookData", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "depositForBurnWithHook",
          args: [
            totalAmount,
            ARC_TESTNET_DOMAIN,
            DESTINATION_ADDRESS_BYTES32,
            ETHEREUM_SEPOLIA_USDC,
            DESTINATION_CALLER_BYTES32,
            maxFee,
            1000,
            FORWARDING_SERVICE_HOOK_DATA,
          ],
        }),
      });

      console.log(`Burn Tx: ${burnTx}`);
      return burnTx;
    }

    async function waitForForwardedMint(transactionHash: string) {
      console.log("Waiting for Forwarding Service to mint on Arc...");

      while (true) {
        const response = await fetch(
          `https://iris-api-sandbox.circle.com/v2/messages/${ETHEREUM_SEPOLIA_DOMAIN}?transactionHash=${transactionHash}`,
          { method: "GET" },
        );

        if (!response.ok) {
          await new Promise((resolve) => setTimeout(resolve, 5000));
          continue;
        }

        const data = await response.json();
        const forwardTxHash = data?.messages?.[0]?.forwardTxHash;

        if (forwardTxHash) {
          console.log(`Forwarded Mint Tx: ${forwardTxHash}`);
          return forwardTxHash;
        }

        await new Promise((resolve) => setTimeout(resolve, 5000));
      }
    }

    async function main() {
      console.log("Wallet address:", account.address);

      // [1] Quote forwarding fees and derive the total source-chain burn amount.
      const { maxFee, totalAmount } = await calculateForwardingAmounts();

      // [2] Approve the total burn amount, including forwarding and protocol fees.
      await approveUSDC(totalAmount);

      // [3] Burn on the source chain with the forwarding hook enabled.
      const burnTx = await burnUSDCWithForwarding(totalAmount, maxFee);

      // [4] Poll until Iris returns the destination mint transaction hash.
      await waitForForwardedMint(burnTx);
      console.log("USDC transfer completed with Forwarding Service.");
    }

    main().catch(console.error);
    ```
  </Tab>

  <Tab title="Direct mint">
    ```ts index.ts expandable theme={null}
    import {
      createPublicClient,
      createWalletClient,
      http,
      encodeFunctionData,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet, sepolia } from "viem/chains";

    interface AttestationMessage {
      message: string;
      attestation: string;
      status: string;
    }

    interface AttestationResponse {
      messages: AttestationMessage[];
    }

    // ============ Configuration Constants ============
    // Authentication
    const PRIVATE_KEY = process.env.PRIVATE_KEY;
    const account = privateKeyToAccount(PRIVATE_KEY as `0x${string}`);

    // Contract Addresses
    const ETHEREUM_SEPOLIA_USDC = "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238";
    const ETHEREUM_SEPOLIA_TOKEN_MESSENGER =
      "0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa";
    const ARC_TESTNET_MESSAGE_TRANSMITTER =
      "0xe737e5cebeeba77efe34d4aa090756590b1ce275";

    // Transfer Parameters
    const DESTINATION_ADDRESS = account.address; // Address to receive minted tokens on destination chain
    const AMOUNT = 1_000_000n; // 1 USDC (1 USDC = 1,000,000 subunits)
    const maxFee = 500n; // 0.0005 USDC (500 subunits)

    // Bytes32 Formatted Parameters
    const DESTINATION_ADDRESS_BYTES32 = `0x000000000000000000000000${DESTINATION_ADDRESS.slice(
      2,
    )}`; // Destination address in bytes32 format
    const DESTINATION_CALLER_BYTES32 =
      "0x0000000000000000000000000000000000000000000000000000000000000000"; // Empty bytes32 allows any address to call MessageTransmitterV2.receiveMessage()

    // Chain-specific Parameters
    const ETHEREUM_SEPOLIA_DOMAIN = 0; // Source domain ID for Ethereum Sepolia
    const ARC_TESTNET_DOMAIN = 26; // Destination domain ID for Arc testnet

    // Set up wallet clients
    const sepoliaClient = createWalletClient({
      chain: sepolia,
      transport: http(),
      account,
    });
    const sepoliaPublicClient = createPublicClient({
      chain: sepolia,
      transport: http(),
    });
    const arcClient = createWalletClient({
      chain: arcTestnet,
      transport: http(),
      account,
    });

    // ============ CCTP Flow Functions ============
    async function approveUSDC() {
      console.log("Approving USDC transfer...");
      const approveTx = await sepoliaClient.sendTransaction({
        to: ETHEREUM_SEPOLIA_USDC,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "approve",
              stateMutability: "nonpayable",
              inputs: [
                { name: "spender", type: "address" },
                { name: "amount", type: "uint256" },
              ],
              outputs: [{ name: "", type: "bool" }],
            },
          ],
          functionName: "approve",
          args: [ETHEREUM_SEPOLIA_TOKEN_MESSENGER, 10_000_000n], // 10 USDC allowance
        }),
      });
      console.log(`USDC Approval Tx: ${approveTx}`);
      await sepoliaPublicClient.waitForTransactionReceipt({ hash: approveTx });
    }

    async function burnUSDC() {
      console.log("Burning USDC on Ethereum Sepolia...");
      const burnTx = await sepoliaClient.sendTransaction({
        to: ETHEREUM_SEPOLIA_TOKEN_MESSENGER,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "depositForBurn",
              stateMutability: "nonpayable",
              inputs: [
                { name: "amount", type: "uint256" },
                { name: "destinationDomain", type: "uint32" },
                { name: "mintRecipient", type: "bytes32" },
                { name: "burnToken", type: "address" },
                { name: "destinationCaller", type: "bytes32" },
                { name: "maxFee", type: "uint256" },
                { name: "minFinalityThreshold", type: "uint32" },
              ],
              outputs: [],
            },
          ],
          functionName: "depositForBurn",
          args: [
            AMOUNT,
            ARC_TESTNET_DOMAIN,
            DESTINATION_ADDRESS_BYTES32 as `0x${string}`,
            ETHEREUM_SEPOLIA_USDC,
            DESTINATION_CALLER_BYTES32,
            maxFee,
            1000, // minFinalityThreshold (1000 or less for Fast Transfer)
          ],
        }),
      });
      console.log(`Burn Tx: ${burnTx}`);
      return burnTx;
    }

    async function retrieveAttestation(transactionHash: string) {
      console.log("Retrieving attestation...");
      const url = `https://iris-api-sandbox.circle.com/v2/messages/${ETHEREUM_SEPOLIA_DOMAIN}?transactionHash=${transactionHash}`;
      while (true) {
        try {
          const response = await fetch(url, { method: "GET" });

          if (!response.ok) {
            if (response.status !== 404) {
              const text = await response.text().catch(() => "");
              console.error(
                "Error fetching attestation:",
                `${response.status} ${response.statusText}${
                  text ? ` - ${text}` : ""
                }`,
              );
            }
            await new Promise((resolve) => setTimeout(resolve, 5000));
            continue;
          }

          const data = (await response.json()) as AttestationResponse;

          if (data?.messages?.[0]?.status === "complete") {
            console.log("Attestation retrieved successfully!");
            return data.messages[0];
          }
          console.log("Waiting for attestation...");
          await new Promise((resolve) => setTimeout(resolve, 5000));
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          console.error("Error fetching attestation:", message);
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }
    }

    async function mintUSDC(attestation: AttestationMessage) {
      console.log("Minting USDC on Arc testnet...");
      const mintTx = await arcClient.sendTransaction({
        to: ARC_TESTNET_MESSAGE_TRANSMITTER,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "receiveMessage",
              stateMutability: "nonpayable",
              inputs: [
                { name: "message", type: "bytes" },
                { name: "attestation", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "receiveMessage",
          args: [
            attestation.message as `0x${string}`,
            attestation.attestation as `0x${string}`,
          ],
        }),
      });
      console.log(`Mint Tx: ${mintTx}`);
    }

    // ============ Main Execution ============
    async function main() {
      await approveUSDC();
      const burnTx = await burnUSDC();
      const attestation = await retrieveAttestation(burnTx);
      await mintUSDC(attestation);
      console.log("USDC transfer completed.");
    }

    main().catch(console.error);
    ```
  </Tab>
</Tabs>

## Step 5: Test the script

Run the following command to execute the script:

```shell Shell theme={null}
npm run start
```

Once the script runs and the transfer is finalized, a confirmation receipt is
logged in the console.

<Note>
  **Rate limit:** The attestation service rate limit is 35 requests per second. If
  you exceed this limit, the service blocks all API requests for the next 5
  minutes and returns an HTTP 429 (Too Many Requests) response.
</Note>


# Transfer USDC from Solana to Arc
Source: https://developers.circle.com/cctp/quickstarts/transfer-usdc-solana-to-arc

Transfer USDC from Solana to an EVM blockchain using CCTP

This guide demonstrates how to transfer USDC from Solana Devnet to Arc Testnet
using CCTP. You use the [Solana Kit](https://github.com/anza-xyz/kit) library to
interact with [Solana CCTP programs](/cctp/references/solana-programs), and viem
to mint USDC on Arc Testnet.

<Tip>
  **Use [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit) to
  simplify crosschain transfers with CCTP.**

  This quickstart shows how to transfer USDC from  to
  &#x20;using a manual CCTP integration. The example is for learning
  or for developers who need a manual integration.

  To streamline this, use Bridge Kit to transfer USDC in just a few lines of code.
</Tip>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)
* Prepared a Solana wallet and have the private key array available
* Funded your Solana wallet with the following testnet tokens:
  * Solana Devnet SOL (native token) from a
    [public faucet](https://faucet.solana.com/)
  * Solana Devnet USDC from the [Circle Faucet](https://faucet.circle.com)
* Prepared an EVM testnet wallet with the private key available
  * Added Arc testnet network to your wallet
    ([network details](https://docs.arc.io/arc/references/connect-to-arc#wallet-setup))
* Funded your EVM wallet with Arc Testnet USDC from the
  [Circle Faucet](https://faucet.circle.com) if you choose the direct mint path
  below, because the destination wallet must pay gas to call `receiveMessage`

## Step 1. Set up the project

### 1.1. Create the project and install dependencies

```shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir cctp-solana-transfer
cd cctp-solana-transfer
npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="tsx --env-file=.env index.ts"

# Install runtime dependencies
npm install @solana/kit @solana-program/system @solana-program/token viem

# Install dev dependencies
npm install --save-dev @types/node tsx typescript
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.3. Set environment variables

Open `.env` in your editor and add:

```text theme={null}
SOLANA_PRIVATE_KEY=YOUR_SOLANA_PRIVATE_KEY_ARRAY
EVM_PRIVATE_KEY=YOUR_ARC_PRIVATE_KEY
```

* `SOLANA_PRIVATE_KEY` is the private key array for the Solana Devnet wallet
  that signs the source-chain burn transaction.
* `EVM_PRIVATE_KEY` is used to derive the Arc recipient address. The direct-mint
  path also uses this key to submit the destination mint on Arc.

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

The `npm run start` command loads variables from `.env` using Node.js native
env-file support.

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>

## Step 2: Configure the script

Define the configuration constants for interacting with Solana and Arc Testnet.

### 2.1. Setup chains and wallets

The script predefines the program addresses, transfer amount, and other
parameters:

```ts TypeScript expandable theme={null}
// Solana Configuration
const SOLANA_RPC = "https://api.devnet.solana.com";
const SOLANA_WS = "wss://api.devnet.solana.com";
const rpc = createSolanaRpc(SOLANA_RPC);
const rpcSubscriptions = createSolanaRpcSubscriptions(SOLANA_WS);
const solanaPrivateKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY!);
const solanaKeypair = await createKeyPairSignerFromBytes(
  Uint8Array.from(solanaPrivateKey),
);

// Solana CCTP Program Addresses (Devnet)
const TOKEN_MESSENGER_MINTER_PROGRAM = address(
  "CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe",
);
const MESSAGE_TRANSMITTER_PROGRAM = address(
  "CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC",
);
const USDC_MINT = address("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");
const ASSOCIATED_TOKEN_PROGRAM = address(
  "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
);

// Arc Testnet Configuration
const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY!;
const ethAccount = privateKeyToAccount(EVM_PRIVATE_KEY as `0x${string}`);
const ARC_MESSAGE_TRANSMITTER = "0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275";
const arcClient = createWalletClient({
  chain: arcTestnet,
  transport: http(),
  account: ethAccount,
});

// Transfer Parameters
const AMOUNT = 1_000_000n;
const DESTINATION_DOMAIN = 26;
const ARC_DESTINATION_ADDRESS = ethAccount.address;
const MAX_FEE = 500n;
```

## Step 3: Implement the transfer logic

The following sections outline the core transfer logic from Solana to Arc.

For simplicity, this quickstart uses the same Arc wallet as the recipient and,
in the direct-mint path, the wallet that submits `receiveMessage`. In
production, these can be different addresses.

In the two examples provided, the path diverges at the Solana burn instruction:

* **Direct mint** uses `deposit_for_burn`, then retrieves an attestation and
  calls `receiveMessage` on Arc.
* **Forwarding Service** uses `deposit_for_burn_with_hook`, then lets Circle
  handle the destination-side mint on Arc.

<Tabs>
  <Tab title="Forwarding Service">
    ### 3.1. Get forwarding fees and calculate the burn amount

    Before you burn USDC with the
    [Forwarding Service](/cctp/concepts/forwarding-service), query the CCTP fee
    endpoint with `forward=true`. The forwarding fee is dynamic, so fetch it
    immediately before the transfer. The returned `maxFee` must cover both the CCTP
    protocol fee and the forwarding fee.

    ```ts TypeScript theme={null}
    const FORWARDING_SERVICE_HOOK_DATA = Buffer.from(
      "636374702d666f72776172640000000000000000000000000000000000000000",
      "hex",
    );

    async function getForwardingFees() {
      const response = await fetch(
        "https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/5/26?forward=true",
        {
          method: "GET",
          headers: { "Content-Type": "application/json" },
        },
      );

      if (!response.ok) {
        throw new Error(`Failed to fetch fees: ${await response.text()}`);
      }

      return response.json();
    }

    async function calculateForwardingAmounts() {
      const fees = await getForwardingFees();
      const feeData = fees.find(
        (fee: { finalityThreshold: number }) => fee.finalityThreshold === 1000,
      );

      if (!feeData) {
        throw new Error("Fast-transfer forwarding fees not available");
      }

      const forwardFee = BigInt(feeData.forwardFee.med);
      const protocolFee =
        (AMOUNT * BigInt(Math.round(feeData.minimumFee * 100))) / 1_000_000n;
      const maxFee = forwardFee + protocolFee;
      const totalAmount = AMOUNT + maxFee;

      return { maxFee, totalAmount };
    }
    ```

    ### 3.2. Burn USDC with the Forwarding Service hook

    Use `deposit_for_burn_with_hook` on Solana. The forwarding hook data tells
    Circle to handle the destination-side `receiveMessage` call on Arc.

    ```ts TypeScript expandable theme={null}
    type BurnContext = {
      senderUsdcAccount: ReturnType<typeof address>;
      senderAuthorityPda: ReturnType<typeof address>;
      denylistPda: ReturnType<typeof address>;
      messageTransmitter: ReturnType<typeof address>;
      tokenMessenger: ReturnType<typeof address>;
      remoteTokenMessenger: ReturnType<typeof address>;
      tokenMinter: ReturnType<typeof address>;
      localToken: ReturnType<typeof address>;
      eventAuthority: ReturnType<typeof address>;
      messageTransmitterEventAuthority: ReturnType<typeof address>;
      messageSentEventAccount: Awaited<ReturnType<typeof generateKeyPairSigner>>;
      destAddressBytes32: Buffer;
    };

    async function getBurnContext(): Promise<BurnContext> {
      const addressEncoder = getAddressEncoder();
      const [senderUsdcAccount] = await getProgramDerivedAddress({
        programAddress: ASSOCIATED_TOKEN_PROGRAM,
        seeds: [
          addressEncoder.encode(solanaKeypair.address),
          addressEncoder.encode(TOKEN_PROGRAM_ADDRESS),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      const destAddressBytes32 = Buffer.concat([
        Buffer.alloc(12),
        Buffer.from(ARC_DESTINATION_ADDRESS.slice(2), "hex"),
      ]);

      const [senderAuthorityPda] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("sender_authority")],
      });
      const [denylistPda] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("denylist_account"),
          addressEncoder.encode(solanaKeypair.address),
        ],
      });
      const [messageTransmitter] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("message_transmitter")],
      });
      const [tokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_messenger")],
      });
      const [remoteTokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("remote_token_messenger"),
          new TextEncoder().encode(DESTINATION_DOMAIN.toString()),
        ],
      });
      const [tokenMinter] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_minter")],
      });
      const [localToken] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("local_token"),
          addressEncoder.encode(USDC_MINT),
        ],
      });
      const [eventAuthority] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });
      const [messageTransmitterEventAuthority] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });
      const messageSentEventAccount = await generateKeyPairSigner();

      return {
        senderUsdcAccount,
        senderAuthorityPda,
        denylistPda,
        messageTransmitter,
        tokenMessenger,
        remoteTokenMessenger,
        tokenMinter,
        localToken,
        eventAuthority,
        messageTransmitterEventAuthority,
        messageSentEventAccount,
        destAddressBytes32,
      };
    }

    async function burnUSDCWithForwarding() {
      console.log("Burning USDC on Solana with Forwarding Service...");

      const { maxFee, totalAmount } = await calculateForwardingAmounts();
      const burnContext = await getBurnContext();

      const amountBuffer = Buffer.alloc(8);
      amountBuffer.writeBigUInt64LE(totalAmount);
      const domainBuffer = Buffer.alloc(4);
      domainBuffer.writeUInt32LE(DESTINATION_DOMAIN);
      const maxFeeBuffer = Buffer.alloc(8);
      maxFeeBuffer.writeBigUInt64LE(maxFee);
      const finalityBuffer = Buffer.alloc(4);
      finalityBuffer.writeUInt32LE(1000);
      const hookLengthBuffer = Buffer.alloc(4);
      hookLengthBuffer.writeUInt32LE(FORWARDING_SERVICE_HOOK_DATA.length);

      const instructionData = new Uint8Array(
        Buffer.concat([
          Buffer.from([111, 245, 62, 131, 204, 108, 223, 155]),
          amountBuffer,
          domainBuffer,
          burnContext.destAddressBytes32,
          Buffer.alloc(32),
          maxFeeBuffer,
          finalityBuffer,
          hookLengthBuffer,
          FORWARDING_SERVICE_HOOK_DATA,
        ]),
      );

      const depositForBurnIx = {
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        accounts: [
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: burnContext.senderAuthorityPda, role: 0 },
          { address: burnContext.senderUsdcAccount, role: 1 },
          { address: burnContext.denylistPda, role: 0 },
          { address: burnContext.messageTransmitter, role: 1 },
          { address: burnContext.tokenMessenger, role: 0 },
          { address: burnContext.remoteTokenMessenger, role: 0 },
          { address: burnContext.tokenMinter, role: 0 },
          { address: burnContext.localToken, role: 1 },
          { address: USDC_MINT, role: 1 },
          {
            address: burnContext.messageSentEventAccount.address,
            role: 3,
            signer: burnContext.messageSentEventAccount,
          },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: TOKEN_PROGRAM_ADDRESS, role: 0 },
          { address: SYSTEM_PROGRAM_ADDRESS, role: 0 },
          { address: burnContext.eventAuthority, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: burnContext.messageTransmitterEventAuthority, role: 0 },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
        ],
        data: instructionData,
      };

      const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
      const transactionMessage = pipe(
        createTransactionMessage({ version: 0 }),
        (tx) => setTransactionMessageFeePayerSigner(solanaKeypair, tx),
        (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
        (tx) => appendTransactionMessageInstruction(depositForBurnIx, tx),
      );
      const signedTransaction =
        await signTransactionMessageWithSigners(transactionMessage);
      const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
        rpc,
        rpcSubscriptions,
      });

      await sendAndConfirmTransaction(signedTransaction as any, {
        commitment: "confirmed",
      });

      const signature = getSignatureFromTransaction(signedTransaction);
      console.log(`Burn transaction signature: ${signature}`);
      return signature;
    }
    ```

    ### 3.3. Verify the forwarded mint

    After the burn is confirmed, poll the Iris API until it returns a
    `forwardTxHash`. That hash is the Arc destination mint transaction submitted by
    Circle. In the forwarding path, `forwardTxHash` is the completion signal for the
    destination-side mint. You do not need to retrieve an attestation and call
    `receiveMessage` yourself.

    ```ts TypeScript theme={null}
    async function waitForForwardedMint(transactionSignature: string) {
      console.log("Waiting for Forwarding Service to mint on Arc...");

      while (true) {
        const response = await fetch(
          `https://iris-api-sandbox.circle.com/v2/messages/5?transactionHash=${transactionSignature}`,
          { method: "GET" },
        );

        if (!response.ok) {
          await new Promise((resolve) => setTimeout(resolve, 5000));
          continue;
        }

        const data = await response.json();
        const forwardTxHash = data?.messages?.[0]?.forwardTxHash;

        if (forwardTxHash) {
          console.log(`Forwarded Mint Tx: ${forwardTxHash}`);
          return forwardTxHash;
        }

        await new Promise((resolve) => setTimeout(resolve, 5000));
      }
    }
    ```
  </Tab>

  <Tab title="Direct mint">
    ### 3.1. Burn USDC on Solana

    Call the `depositForBurn` instruction from the `TokenMessengerMinterV2` program
    to burn USDC on Solana:

    ```ts TypeScript expandable theme={null}
    const DIRECT_MINT_DISCRIMINATOR = Buffer.from([
      215, 60, 61, 46, 114, 55, 128, 176,
    ]);

    async function burnUSDCOnSolana() {
      console.log("Burning USDC on Solana...");

      const addressEncoder = getAddressEncoder();

      // Get the sender's USDC token account (Associated Token Account PDA)
      const [senderUsdcAccount] = await getProgramDerivedAddress({
        programAddress: ASSOCIATED_TOKEN_PROGRAM,
        seeds: [
          addressEncoder.encode(solanaKeypair.address),
          addressEncoder.encode(TOKEN_PROGRAM_ADDRESS),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      const destAddressBytes32 = Buffer.concat([
        Buffer.alloc(12),
        Buffer.from(ARC_DESTINATION_ADDRESS.slice(2), "hex"),
      ]);

      // Derive PDAs (Program Derived Addresses)
      const [senderAuthorityPda] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("sender_authority")],
      });

      const [denylistPda] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("denylist_account"),
          addressEncoder.encode(solanaKeypair.address),
        ],
      });

      const [messageTransmitter] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("message_transmitter")],
      });

      const [tokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_messenger")],
      });

      // NOTE: Domain is converted to string for PDA derivation in V2
      const [remoteTokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("remote_token_messenger"),
          new TextEncoder().encode(DESTINATION_DOMAIN.toString()),
        ],
      });

      const [tokenMinter] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_minter")],
      });

      const [localToken] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("local_token"),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      // Derive event authority PDAs for Anchor CPI events
      const [eventAuthority] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });

      const [messageTransmitterEventAuthority] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });

      const messageSentEventAccount = await generateKeyPairSigner();

      const amountBuffer = Buffer.alloc(8);
      amountBuffer.writeBigUInt64LE(AMOUNT);

      const domainBuffer = Buffer.alloc(4);
      domainBuffer.writeUInt32LE(DESTINATION_DOMAIN);

      const maxFeeBuffer = Buffer.alloc(8);
      maxFeeBuffer.writeBigUInt64LE(MAX_FEE);

      const finalityBuffer = Buffer.alloc(4);
      finalityBuffer.writeUInt32LE(1000);

      const instructionData = new Uint8Array(
        Buffer.concat([
          DIRECT_MINT_DISCRIMINATOR,
          amountBuffer,
          domainBuffer,
          destAddressBytes32,
          Buffer.alloc(32),
          maxFeeBuffer,
          finalityBuffer,
        ]),
      );

      const depositForBurnIx = {
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        accounts: [
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: senderAuthorityPda, role: 0 },
          { address: senderUsdcAccount, role: 1 },
          { address: denylistPda, role: 0 },
          { address: messageTransmitter, role: 1 },
          { address: tokenMessenger, role: 0 },
          { address: remoteTokenMessenger, role: 0 },
          { address: tokenMinter, role: 0 },
          { address: localToken, role: 1 },
          { address: USDC_MINT, role: 1 },
          {
            address: messageSentEventAccount.address,
            role: 3,
            signer: messageSentEventAccount,
          },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: TOKEN_PROGRAM_ADDRESS, role: 0 },
          { address: SYSTEM_PROGRAM_ADDRESS, role: 0 },
          { address: eventAuthority, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: messageTransmitterEventAuthority, role: 0 },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
        ],
        data: instructionData,
      };

      const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
      const transactionMessage = pipe(
        createTransactionMessage({ version: 0 }),
        (tx) => setTransactionMessageFeePayerSigner(solanaKeypair, tx),
        (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
        (tx) => appendTransactionMessageInstruction(depositForBurnIx, tx),
      );

      const signedTransaction =
        await signTransactionMessageWithSigners(transactionMessage);
      const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
        rpc,
        rpcSubscriptions,
      });

      await sendAndConfirmTransaction(signedTransaction as any, {
        commitment: "confirmed",
      });

      const signature = getSignatureFromTransaction(signedTransaction);
      console.log(`Burn transaction signature: ${signature}`);

      return signature;
    }
    ```

    ### 3.2. Retrieve attestation

    Retrieve the attestation required to complete the CCTP transfer by calling
    Circle's attestation API:

    ```ts TypeScript theme={null}
    async function retrieveAttestation(transactionSignature: string) {
      console.log("Retrieving attestation...");
      const url = `https://iris-api-sandbox.circle.com/v2/messages/5?transactionHash=${transactionSignature}`;

      while (true) {
        try {
          const response = await fetch(url, { method: "GET" });

          if (!response.ok) {
            if (response.status !== 404) {
              const text = await response.text().catch(() => "");
              console.error(
                "Error fetching attestation:",
                `${response.status} ${response.statusText}${
                  text ? ` - ${text}` : ""
                }`,
              );
            }

            await new Promise((resolve) => setTimeout(resolve, 5000));
            continue;
          }

          const data = (await response.json()) as AttestationResponse;

          if (data?.messages?.[0]?.status === "complete") {
            console.log("Attestation retrieved successfully!");
            return data.messages[0];
          }

          console.log("Waiting for attestation...");
          await new Promise((resolve) => setTimeout(resolve, 5000));
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          console.error("Error fetching attestation:", message);
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }
    }
    ```

    ### 3.3. Mint USDC on Arc Testnet

    Call the `receiveMessage` function from the `MessageTransmitterV2` contract on
    Arc Testnet to mint USDC:

    ```ts TypeScript theme={null}
    async function mintUSDCOnArc(attestation: AttestationMessage) {
      console.log("Minting USDC on Arc testnet...");

      const mintTx = await arcClient.sendTransaction({
        to: ARC_MESSAGE_TRANSMITTER,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "receiveMessage",
              stateMutability: "nonpayable",
              inputs: [
                { name: "message", type: "bytes" },
                { name: "attestation", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "receiveMessage",
          args: [
            attestation.message as `0x${string}`,
            attestation.attestation as `0x${string}`,
          ],
        }),
      });

      console.log(`Mint transaction hash: ${mintTx}`);
    }
    ```
  </Tab>
</Tabs>

## Step 4: Complete script

Create a `index.ts` file in your project directory and populate it with the
complete code below for the path you want to test.

<Tabs>
  <Tab title="Forwarding Service">
    ```ts index.ts expandable theme={null}
    import {
      address,
      createKeyPairSignerFromBytes,
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      createTransactionMessage,
      generateKeyPairSigner,
      getAddressEncoder,
      getProgramDerivedAddress,
      getSignatureFromTransaction,
      pipe,
      sendAndConfirmTransactionFactory,
      setTransactionMessageFeePayerSigner,
      setTransactionMessageLifetimeUsingBlockhash,
      appendTransactionMessageInstruction,
      signTransactionMessageWithSigners,
    } from "@solana/kit";
    import { SYSTEM_PROGRAM_ADDRESS } from "@solana-program/system";
    import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
    import { privateKeyToAccount } from "viem/accounts";

    type FeeQuote = {
      finalityThreshold: number;
      minimumFee: number;
      forwardFee: { med: number };
    };

    type BurnContext = {
      senderUsdcAccount: ReturnType<typeof address>;
      senderAuthorityPda: ReturnType<typeof address>;
      denylistPda: ReturnType<typeof address>;
      messageTransmitter: ReturnType<typeof address>;
      tokenMessenger: ReturnType<typeof address>;
      remoteTokenMessenger: ReturnType<typeof address>;
      tokenMinter: ReturnType<typeof address>;
      localToken: ReturnType<typeof address>;
      eventAuthority: ReturnType<typeof address>;
      messageTransmitterEventAuthority: ReturnType<typeof address>;
      messageSentEventAccount: Awaited<ReturnType<typeof generateKeyPairSigner>>;
      destAddressBytes32: Buffer;
    };

    const SOLANA_RPC = "https://api.devnet.solana.com";
    const SOLANA_WS = "wss://api.devnet.solana.com";
    const rpc = createSolanaRpc(SOLANA_RPC);
    const rpcSubscriptions = createSolanaRpcSubscriptions(SOLANA_WS);
    const solanaPrivateKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY!);
    const solanaKeypair = await createKeyPairSignerFromBytes(
      Uint8Array.from(solanaPrivateKey),
    );

    const TOKEN_MESSENGER_MINTER_PROGRAM = address(
      "CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe",
    );
    const MESSAGE_TRANSMITTER_PROGRAM = address(
      "CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC",
    );
    const USDC_MINT = address("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");
    const ASSOCIATED_TOKEN_PROGRAM = address(
      "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
    );

    const ethAccount = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY! as `0x${string}`,
    );
    const AMOUNT = 1_000_000n;
    const DESTINATION_DOMAIN = 26;
    const ARC_DESTINATION_ADDRESS = ethAccount.address;
    const FORWARDING_SERVICE_HOOK_DATA = Buffer.from(
      "636374702d666f72776172640000000000000000000000000000000000000000",
      "hex",
    );
    const FORWARDING_DISCRIMINATOR = Buffer.from([
      111, 245, 62, 131, 204, 108, 223, 155,
    ]);

    async function getForwardingFeeQuote() {
      const response = await fetch(
        "https://iris-api-sandbox.circle.com/v2/burn/USDC/fees/5/26?forward=true",
        {
          method: "GET",
          headers: { "Content-Type": "application/json" },
        },
      );

      if (!response.ok) {
        throw new Error(`Failed to fetch fees: ${await response.text()}`);
      }

      const fees = (await response.json()) as FeeQuote[];
      const feeData = fees.find((fee) => fee.finalityThreshold === 1000);

      if (!feeData) {
        throw new Error("Fast-transfer forwarding fees not available");
      }

      return feeData;
    }

    async function calculateForwardingAmounts() {
      const feeData = await getForwardingFeeQuote();
      const forwardFee = BigInt(feeData.forwardFee.med);
      const protocolFee =
        (AMOUNT * BigInt(Math.round(feeData.minimumFee * 100))) / 1_000_000n;
      const maxFee = forwardFee + protocolFee;
      const totalAmount = AMOUNT + maxFee;

      console.log("Forward fee:", Number(forwardFee) / 1_000_000, "USDC");
      console.log("Protocol fee:", Number(protocolFee) / 1_000_000, "USDC");
      console.log("Max fee:", Number(maxFee) / 1_000_000, "USDC");
      console.log("Total to burn:", Number(totalAmount) / 1_000_000, "USDC");

      return { maxFee, totalAmount };
    }

    async function getBurnContext(): Promise<BurnContext> {
      const addressEncoder = getAddressEncoder();
      const [senderUsdcAccount] = await getProgramDerivedAddress({
        programAddress: ASSOCIATED_TOKEN_PROGRAM,
        seeds: [
          addressEncoder.encode(solanaKeypair.address),
          addressEncoder.encode(TOKEN_PROGRAM_ADDRESS),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      const destAddressBytes32 = Buffer.concat([
        Buffer.alloc(12),
        Buffer.from(ARC_DESTINATION_ADDRESS.slice(2), "hex"),
      ]);

      const [senderAuthorityPda] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("sender_authority")],
      });
      const [denylistPda] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("denylist_account"),
          addressEncoder.encode(solanaKeypair.address),
        ],
      });
      const [messageTransmitter] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("message_transmitter")],
      });
      const [tokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_messenger")],
      });
      const [remoteTokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("remote_token_messenger"),
          new TextEncoder().encode(DESTINATION_DOMAIN.toString()),
        ],
      });
      const [tokenMinter] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_minter")],
      });
      const [localToken] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("local_token"),
          addressEncoder.encode(USDC_MINT),
        ],
      });
      const [eventAuthority] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });
      const [messageTransmitterEventAuthority] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });
      const messageSentEventAccount = await generateKeyPairSigner();

      return {
        senderUsdcAccount,
        senderAuthorityPda,
        denylistPda,
        messageTransmitter,
        tokenMessenger,
        remoteTokenMessenger,
        tokenMinter,
        localToken,
        eventAuthority,
        messageTransmitterEventAuthority,
        messageSentEventAccount,
        destAddressBytes32,
      };
    }

    async function burnUSDCWithForwarding(totalAmount: bigint, maxFee: bigint) {
      console.log("Burning USDC on Solana with Forwarding Service...");
      const burnContext = await getBurnContext();

      const amountBuffer = Buffer.alloc(8);
      amountBuffer.writeBigUInt64LE(totalAmount);
      const domainBuffer = Buffer.alloc(4);
      domainBuffer.writeUInt32LE(DESTINATION_DOMAIN);
      const maxFeeBuffer = Buffer.alloc(8);
      maxFeeBuffer.writeBigUInt64LE(maxFee);
      const finalityBuffer = Buffer.alloc(4);
      finalityBuffer.writeUInt32LE(1000);
      const hookLengthBuffer = Buffer.alloc(4);
      hookLengthBuffer.writeUInt32LE(FORWARDING_SERVICE_HOOK_DATA.length);

      const instructionData = new Uint8Array(
        Buffer.concat([
          FORWARDING_DISCRIMINATOR,
          amountBuffer,
          domainBuffer,
          burnContext.destAddressBytes32,
          Buffer.alloc(32),
          maxFeeBuffer,
          finalityBuffer,
          hookLengthBuffer,
          FORWARDING_SERVICE_HOOK_DATA,
        ]),
      );

      const depositForBurnIx = {
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        accounts: [
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: burnContext.senderAuthorityPda, role: 0 },
          { address: burnContext.senderUsdcAccount, role: 1 },
          { address: burnContext.denylistPda, role: 0 },
          { address: burnContext.messageTransmitter, role: 1 },
          { address: burnContext.tokenMessenger, role: 0 },
          { address: burnContext.remoteTokenMessenger, role: 0 },
          { address: burnContext.tokenMinter, role: 0 },
          { address: burnContext.localToken, role: 1 },
          { address: USDC_MINT, role: 1 },
          {
            address: burnContext.messageSentEventAccount.address,
            role: 3,
            signer: burnContext.messageSentEventAccount,
          },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: TOKEN_PROGRAM_ADDRESS, role: 0 },
          { address: SYSTEM_PROGRAM_ADDRESS, role: 0 },
          { address: burnContext.eventAuthority, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: burnContext.messageTransmitterEventAuthority, role: 0 },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
        ],
        data: instructionData,
      };

      const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
      const transactionMessage = pipe(
        createTransactionMessage({ version: 0 }),
        (tx) => setTransactionMessageFeePayerSigner(solanaKeypair, tx),
        (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
        (tx) => appendTransactionMessageInstruction(depositForBurnIx, tx),
      );
      const signedTransaction =
        await signTransactionMessageWithSigners(transactionMessage);
      const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
        rpc,
        rpcSubscriptions,
      });

      await sendAndConfirmTransaction(signedTransaction as any, {
        commitment: "confirmed",
      });

      const signature = getSignatureFromTransaction(signedTransaction);
      console.log(`Burn transaction signature: ${signature}`);
      return signature;
    }

    async function waitForForwardedMint(transactionSignature: string) {
      console.log("Waiting for Forwarding Service to mint on Arc...");

      while (true) {
        const response = await fetch(
          `https://iris-api-sandbox.circle.com/v2/messages/5?transactionHash=${transactionSignature}`,
          { method: "GET" },
        );

        if (!response.ok) {
          await new Promise((resolve) => setTimeout(resolve, 5000));
          continue;
        }

        const data = await response.json();
        const forwardTxHash = data?.messages?.[0]?.forwardTxHash;

        if (forwardTxHash) {
          console.log(`Forwarded Mint Tx: ${forwardTxHash}`);
          return forwardTxHash;
        }

        await new Promise((resolve) => setTimeout(resolve, 5000));
      }
    }

    async function main() {
      console.log("Solana address:", solanaKeypair.address);
      console.log("Arc recipient:", ARC_DESTINATION_ADDRESS);

      // [1] Quote forwarding fees and derive the total source-chain burn amount.
      const { maxFee, totalAmount } = await calculateForwardingAmounts();

      // [2] Burn on Solana with the forwarding hook enabled.
      const burnSignature = await burnUSDCWithForwarding(totalAmount, maxFee);

      // [3] Poll until Iris returns the destination mint transaction hash.
      await waitForForwardedMint(burnSignature);
      console.log(
        "USDC transfer from Solana Devnet to Arc Testnet completed with Forwarding Service.",
      );
    }

    main().catch(console.error);
    ```
  </Tab>

  <Tab title="Direct mint">
    ```ts index.ts expandable theme={null}
    import {
      address,
      createKeyPairSignerFromBytes,
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      createTransactionMessage,
      generateKeyPairSigner,
      getAddressEncoder,
      getProgramDerivedAddress,
      getSignatureFromTransaction,
      pipe,
      sendAndConfirmTransactionFactory,
      setTransactionMessageFeePayerSigner,
      setTransactionMessageLifetimeUsingBlockhash,
      appendTransactionMessageInstruction,
      signTransactionMessageWithSigners,
    } from "@solana/kit";
    import { SYSTEM_PROGRAM_ADDRESS } from "@solana-program/system";
    import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
    import { createWalletClient, http, encodeFunctionData } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet } from "viem/chains";

    interface AttestationMessage {
      message: string;
      attestation: string;
      status: string;
    }

    interface AttestationResponse {
      messages: AttestationMessage[];
    }

    const SOLANA_RPC = "https://api.devnet.solana.com";
    const SOLANA_WS = "wss://api.devnet.solana.com";
    const rpc = createSolanaRpc(SOLANA_RPC);
    const rpcSubscriptions = createSolanaRpcSubscriptions(SOLANA_WS);
    const solanaPrivateKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY!);
    const solanaKeypair = await createKeyPairSignerFromBytes(
      Uint8Array.from(solanaPrivateKey),
    );

    // Solana CCTP Program Addresses (Devnet)
    const TOKEN_MESSENGER_MINTER_PROGRAM = address(
      "CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe",
    );
    const MESSAGE_TRANSMITTER_PROGRAM = address(
      "CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC",
    );
    const USDC_MINT = address("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");
    const ASSOCIATED_TOKEN_PROGRAM = address(
      "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
    );

    const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY!;
    const ethAccount = privateKeyToAccount(EVM_PRIVATE_KEY as `0x${string}`);
    const ARC_MESSAGE_TRANSMITTER = "0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275";
    const arcClient = createWalletClient({
      chain: arcTestnet,
      transport: http(),
      account: ethAccount,
    });

    const AMOUNT = 1_000_000n;
    const DESTINATION_DOMAIN = 26;
    const ARC_DESTINATION_ADDRESS = ethAccount.address;
    const MAX_FEE = 500n;
    const DIRECT_MINT_DISCRIMINATOR = Buffer.from([
      215, 60, 61, 46, 114, 55, 128, 176,
    ]);

    async function burnUSDCOnSolana() {
      console.log("Burning USDC on Solana...");

      const addressEncoder = getAddressEncoder();

      const [senderUsdcAccount] = await getProgramDerivedAddress({
        programAddress: ASSOCIATED_TOKEN_PROGRAM,
        seeds: [
          addressEncoder.encode(solanaKeypair.address),
          addressEncoder.encode(TOKEN_PROGRAM_ADDRESS),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      const destAddressBytes32 = Buffer.concat([
        Buffer.alloc(12),
        Buffer.from(ARC_DESTINATION_ADDRESS.slice(2), "hex"),
      ]);

      const [senderAuthorityPda] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("sender_authority")],
      });

      const [denylistPda] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("denylist_account"),
          addressEncoder.encode(solanaKeypair.address),
        ],
      });

      const [messageTransmitter] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("message_transmitter")],
      });

      const [tokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_messenger")],
      });

      const [remoteTokenMessenger] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("remote_token_messenger"),
          new TextEncoder().encode(DESTINATION_DOMAIN.toString()),
        ],
      });

      const [tokenMinter] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("token_minter")],
      });

      const [localToken] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [
          new TextEncoder().encode("local_token"),
          addressEncoder.encode(USDC_MINT),
        ],
      });

      const [eventAuthority] = await getProgramDerivedAddress({
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });

      const [messageTransmitterEventAuthority] = await getProgramDerivedAddress({
        programAddress: MESSAGE_TRANSMITTER_PROGRAM,
        seeds: [new TextEncoder().encode("__event_authority")],
      });

      const messageSentEventAccount = await generateKeyPairSigner();

      const amountBuffer = Buffer.alloc(8);
      amountBuffer.writeBigUInt64LE(AMOUNT);

      const domainBuffer = Buffer.alloc(4);
      domainBuffer.writeUInt32LE(DESTINATION_DOMAIN);

      const maxFeeBuffer = Buffer.alloc(8);
      maxFeeBuffer.writeBigUInt64LE(MAX_FEE);

      const finalityBuffer = Buffer.alloc(4);
      finalityBuffer.writeUInt32LE(1000);

      const instructionData = new Uint8Array(
        Buffer.concat([
          DIRECT_MINT_DISCRIMINATOR,
          amountBuffer,
          domainBuffer,
          destAddressBytes32,
          Buffer.alloc(32),
          maxFeeBuffer,
          finalityBuffer,
        ]),
      );

      const depositForBurnIx = {
        programAddress: TOKEN_MESSENGER_MINTER_PROGRAM,
        accounts: [
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: solanaKeypair.address, role: 3, signer: solanaKeypair },
          { address: senderAuthorityPda, role: 0 },
          { address: senderUsdcAccount, role: 1 },
          { address: denylistPda, role: 0 },
          { address: messageTransmitter, role: 1 },
          { address: tokenMessenger, role: 0 },
          { address: remoteTokenMessenger, role: 0 },
          { address: tokenMinter, role: 0 },
          { address: localToken, role: 1 },
          { address: USDC_MINT, role: 1 },
          {
            address: messageSentEventAccount.address,
            role: 3,
            signer: messageSentEventAccount,
          },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: TOKEN_PROGRAM_ADDRESS, role: 0 },
          { address: SYSTEM_PROGRAM_ADDRESS, role: 0 },
          { address: eventAuthority, role: 0 },
          { address: TOKEN_MESSENGER_MINTER_PROGRAM, role: 0 },
          { address: messageTransmitterEventAuthority, role: 0 },
          { address: MESSAGE_TRANSMITTER_PROGRAM, role: 0 },
        ],
        data: instructionData,
      };

      const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
      const transactionMessage = pipe(
        createTransactionMessage({ version: 0 }),
        (tx) => setTransactionMessageFeePayerSigner(solanaKeypair, tx),
        (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
        (tx) => appendTransactionMessageInstruction(depositForBurnIx, tx),
      );

      const signedTransaction =
        await signTransactionMessageWithSigners(transactionMessage);

      const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
        rpc,
        rpcSubscriptions,
      });

      await sendAndConfirmTransaction(signedTransaction as any, {
        commitment: "confirmed",
      });

      const signature = getSignatureFromTransaction(signedTransaction);
      console.log(`Burn transaction signature: ${signature}`);

      return signature;
    }

    async function retrieveAttestation(transactionSignature: string) {
      console.log("Retrieving attestation...");
      const url = `https://iris-api-sandbox.circle.com/v2/messages/5?transactionHash=${transactionSignature}`;

      while (true) {
        try {
          const response = await fetch(url, { method: "GET" });

          if (!response.ok) {
            if (response.status !== 404) {
              const text = await response.text().catch(() => "");
              console.error(
                "Error fetching attestation:",
                `${response.status} ${response.statusText}${
                  text ? ` - ${text}` : ""
                }`,
              );
            }

            await new Promise((resolve) => setTimeout(resolve, 5000));
            continue;
          }

          const data = (await response.json()) as AttestationResponse;

          if (data?.messages?.[0]?.status === "complete") {
            console.log("Attestation retrieved successfully!");
            return data.messages[0];
          }

          console.log("Waiting for attestation...");
          await new Promise((resolve) => setTimeout(resolve, 5000));
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          console.error("Error fetching attestation:", message);
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }
    }

    async function mintUSDCOnArc(attestation: AttestationMessage) {
      console.log("Minting USDC on Arc testnet...");

      const mintTx = await arcClient.sendTransaction({
        to: ARC_MESSAGE_TRANSMITTER,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "receiveMessage",
              stateMutability: "nonpayable",
              inputs: [
                { name: "message", type: "bytes" },
                { name: "attestation", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "receiveMessage",
          args: [
            attestation.message as `0x${string}`,
            attestation.attestation as `0x${string}`,
          ],
        }),
      });

      console.log(`Mint transaction hash: ${mintTx}`);
    }

    async function main() {
      // [1] Burn USDC on Solana Devnet.
      const burnSignature = await burnUSDCOnSolana();

      // [2] Poll until Iris returns a complete attestation.
      const attestation = await retrieveAttestation(burnSignature);

      // [3] Submit the destination-side mint on Arc Testnet.
      await mintUSDCOnArc(attestation);
      console.log("USDC transfer from Solana Devnet to Arc Testnet completed.");
    }

    main().catch(console.error);
    ```
  </Tab>
</Tabs>

## Step 5: Test the script

Run the following command to execute the script:

```shell Shell theme={null}
npm run start
```

Once the script runs and the transfer is finalized, a confirmation message is
logged in the console.

<Note>
  **Rate limit:** The attestation service rate limit is 35 requests per second. If
  you exceed this limit, the service blocks all API requests for the next 5
  minutes and returns an HTTP 429 (Too Many Requests) response.
</Note>


# Transfer USDC to and from Stellar
Source: https://developers.circle.com/cctp/quickstarts/transfer-usdc-stellar-arc

Build scripts to transfer USDC between Arc Testnet and Stellar Testnet using CCTP

Use CCTP to transfer USDC with Stellar Testnet as the source or destination.

<Note>
  On Stellar, USDC precision and address encoding differ from other CCTP-supported
  blockchains. Before you integrate beyond these examples, read
  [CCTP on Stellar](/cctp/references/stellar).
</Note>

Pick the tab that matches the direction of your transfer.

<Tabs>
  <Tab title="Stellar to Arc">
    This quickstart demonstrates how to transfer USDC from Stellar Testnet to Arc
    Testnet using CCTP. You use the
    [@stellar/stellar-sdk](https://github.com/stellar/js-stellar-sdk) library to
    interact with Stellar Soroban contracts, and [`viem`](https://viem.sh/) to mint
    USDC on Arc Testnet. When you finish, you will have executed a full
    burn-attest-mint flow.

    You should be comfortable using a terminal and Node.js. Familiarity with Stellar
    Soroban transactions and basic EVM usage helps you follow and adapt the script.
    Examples use Arc Testnet as the destination, but you can use any
    [supported blockchain](/cctp/concepts/supported-chains-and-domains).

    ## Prerequisites

    Before you begin this tutorial, ensure you have:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared an EVM wallet with the private key available for Arc Testnet
      * Added the Arc Testnet network to your wallet
        ([network details](https://docs.arc.io/arc/references/connect-to-arc#wallet-setup))
      * Funded your wallet with Arc Testnet USDC (for gas fees) from the
        [Circle Faucet](https://faucet.circle.com)
    * Prepared a Stellar Testnet wallet with the secret key (`S...`) available
      * Funded your Stellar wallet with testnet XLM from the
        [Stellar Friendbot](https://lab.stellar.org/account/fund) (for Soroban fees
        on Stellar Testnet)
      * Established a
        [USDC trustline](/stablecoins/quickstart-setup-usdc-trustline-stellar) on
        your Stellar account so you can hold the testnet USDC you burn
      * Funded your Stellar wallet with Stellar Testnet USDC from the
        [Circle Faucet](https://faucet.circle.com)

    <Tip>
      You can use [Stellar Lab](https://lab.stellar.org/) on Stellar Testnet to fund
      accounts and establish USDC trustlines.
    </Tip>

    ## Step 1: Set up the project

    This step shows you how to prepare your project and environment.

    ### 1.1. Set up your development environment

    Create a new directory and install the required dependencies:

    ```bash Shell theme={null}
    # Set up your directory and initialize a Node.js project
    mkdir cctp-stellar-to-arc
    cd cctp-stellar-to-arc
    npm init -y

    # Set up module type and start command
    npm pkg set type=module
    npm pkg set scripts.start="npx tsx --env-file=.env index.ts"

    # Install runtime dependencies
    npm install @stellar/stellar-sdk viem

    # Install dev dependencies
    npm install --save-dev typescript @types/node
    ```

    ### 1.2. Initialize and configure the project

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3. Configure environment variables

    Open .env in your editor and add:

    ```text theme={null}
    STELLAR_SECRET_KEY=YOUR_STELLAR_SECRET_KEY
    EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY
    ```

    * `STELLAR_SECRET_KEY` is the Stellar secret key `(S...)` used to sign Soroban
      transactions on Stellar Testnet.
    * `EVM_PRIVATE_KEY` is the private key for the EVM wallet you use on Arc
      Testnet.

    <Tip>
      Open `.env` in your editor rather than writing values with shell commands, and
      add `.env` to your `.gitignore`. This prevents credentials from leaking into
      your shell history or version control.
    </Tip>

    The `npm run start` command loads variables from `.env` using Node.js native
    env-file support.

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Configure the script

    Define contract addresses, amounts, and clients for Stellar Testnet and Arc
    Testnet.

    ### 2.1. Define configuration constants

    The script predefines the contract addresses, transfer amount, and maximum fee.

    ```ts TypeScript theme={null}
    import {
      Address,
      Contract,
      Keypair,
      nativeToScVal,
      rpc,
      TransactionBuilder,
      xdr,
    } from "@stellar/stellar-sdk";
    import {
      createPublicClient,
      createWalletClient,
      encodeFunctionData,
      http,
      pad,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet } from "viem/chains";

    interface AttestationMessage {
      message: string;
      attestation: string;
      status: string;
    }

    interface AttestationResponse {
      messages: AttestationMessage[];
    }

    // Contract Addresses
    const STELLAR_TOKEN_MESSENGER_MINTER =
      "CDNG7HXAPBWICI2E3AUBP3YZWZELJLYSB6F5CC7WLDTLTHVM74SLRTHP";
    const STELLAR_USDC = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA";
    const ARC_MESSAGE_TRANSMITTER = "0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275";

    // Transfer Parameters
    const AMOUNT = 10_000_000n; // 1 USDC (Stellar has 7 decimals)
    const MAX_FEE = 100_000n; // 0.01 USDC in Stellar subunits (7 decimals)

    // Chain-specific Parameters
    const STELLAR_DOMAIN = 27; // Source domain ID for Stellar Testnet
    const ARC_TESTNET_DOMAIN = 26; // Destination domain ID for Arc Testnet

    // Stellar Soroban Configuration
    const STELLAR_RPC_URL = "https://soroban-testnet.stellar.org";
    const STELLAR_NETWORK_PASSPHRASE = "Test SDF Network ; September 2015";

    // Authentication
    const stellarKeypair = Keypair.fromSecret(
      process.env.STELLAR_SECRET_KEY as string,
    );
    ```

    ### 2.2. Set up wallet clients

    The wallet client configures the appropriate network settings using `viem`. In
    this example, the script connects to Arc Testnet.

    ```ts TypeScript theme={null}
    const evmAccount = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );

    const arcWalletClient = createWalletClient({
      chain: arcTestnet,
      transport: http(),
      account: evmAccount,
    });

    const arcPublicClient = createPublicClient({
      chain: arcTestnet,
      transport: http(),
    });
    ```

    ### 2.3. Add helper function

    The `submitSorobanTx` helper builds, signs, submits, and confirms a Soroban
    contract transaction.

    ```ts TypeScript theme={null}
    async function submitSorobanTx(
      server: rpc.Server,
      contractId: string,
      method: string,
      args: xdr.ScVal[],
    ) {
      const account = await server.getAccount(stellarKeypair.publicKey());
      const contract = new Contract(contractId);

      const tx = new TransactionBuilder(account, {
        fee: "10000000",
        networkPassphrase: STELLAR_NETWORK_PASSPHRASE,
      })
        .addOperation(contract.call(method, ...args))
        .setTimeout(120)
        .build();

      const simulated = await server.simulateTransaction(tx);
      if (rpc.Api.isSimulationError(simulated)) {
        throw new Error(`Simulation failed: ${JSON.stringify(simulated)}`);
      }

      const prepared = rpc.assembleTransaction(tx, simulated).build();
      prepared.sign(stellarKeypair);

      const sendResult = await server.sendTransaction(prepared);
      if (sendResult.status === "ERROR") {
        throw new Error(`Send failed: ${JSON.stringify(sendResult)}`);
      }

      let getResult = await server.getTransaction(sendResult.hash);
      while (getResult.status === "NOT_FOUND") {
        await new Promise((resolve) => setTimeout(resolve, 2000));
        getResult = await server.getTransaction(sendResult.hash);
      }

      if (getResult.status !== "SUCCESS") {
        throw new Error(`Transaction failed: ${JSON.stringify(getResult)}`);
      }

      return sendResult.hash;
    }
    ```

    ## Step 3: Implement the transfer logic

    This step implements the core transfer logic: approve and burn on Stellar, poll
    for an attestation, then mint on Arc. A successful run prints transaction hashes
    and a completion message in the console.

    ### 3.1. Approve USDC on Stellar

    Approve the `TokenMessengerMinterV2` contract to spend your USDC. The
    `submitSorobanTx` helper is used to submit the approve call to the Stellar USDC
    contract.

    ```ts TypeScript theme={null}
    async function approveUSDC() {
      console.log("Approving USDC spend on Stellar...");
      const server = new rpc.Server(STELLAR_RPC_URL);
      const latestLedger = await server.getLatestLedger();
      const expirationLedger = latestLedger.sequence + 100_000;

      const approveHash = await submitSorobanTx(server, STELLAR_USDC, "approve", [
        new Address(stellarKeypair.publicKey()).toScVal(),
        new Address(STELLAR_TOKEN_MESSENGER_MINTER).toScVal(),
        nativeToScVal(AMOUNT, { type: "i128" }),
        nativeToScVal(expirationLedger, { type: "u32" }),
      ]);
      console.log(`Approve Tx: ${approveHash}`);
    }
    ```

    ### 3.2. Burn USDC on Stellar

    Call `deposit_for_burn` to burn USDC on Stellar. The `submitSorobanTx` helper is
    used to submit the burn call with the transfer parameters listed below:

    * **Burn amount**: The amount of USDC to burn (in Stellar subunits, 7 decimals)
    * **Destination domain**: The target blockchain for minting USDC (see
      [supported blockchains and domains](/cctp/concepts/supported-chains-and-domains))
    * **Mint recipient**: The wallet address that receives the minted USDC on Arc
    * **Burn token**: The contract address of the USDC token on Stellar
    * **Destination caller**: The address on the target blockchain that may call
      `receiveMessage`
    * **Max fee**: The maximum [fee](/cctp/concepts/fees) allowed for the transfer
      (in Stellar subunits, 7 decimals)
    * **Finality threshold**: Determines whether it's a
      [Fast Transfer](/cctp/concepts/finality-and-block-confirmations#fast-transfer-attestation-times)
      (1000 or less) or a
      [Standard Transfer](/cctp/concepts/finality-and-block-confirmations#standard-transfer-attestation-times)
      (2000 or more)

    ```ts TypeScript theme={null}
    async function burnUSDC() {
      console.log("Burning USDC on Stellar...");
      // Bytes32 Formatted Parameters
      const evmAddressBytes32 = pad(evmAccount.address);
      const mintRecipient = xdr.ScVal.scvBytes(
        Buffer.from(evmAddressBytes32.slice(2), "hex"),
      );
      const server = new rpc.Server(STELLAR_RPC_URL);

      const txHash = await submitSorobanTx(
        server,
        STELLAR_TOKEN_MESSENGER_MINTER,
        "deposit_for_burn",
        [
          new Address(stellarKeypair.publicKey()).toScVal(),
          nativeToScVal(AMOUNT, { type: "i128" }),
          nativeToScVal(ARC_TESTNET_DOMAIN, { type: "u32" }),
          mintRecipient,
          new Address(STELLAR_USDC).toScVal(),
          xdr.ScVal.scvBytes(Buffer.alloc(32)), // destination_caller
          nativeToScVal(MAX_FEE, { type: "i128" }),
          nativeToScVal(1000, { type: "u32" }), // Fast Transfer finality threshold
        ],
      );
      console.log(`Burn Tx: ${txHash}`);
      return txHash;
    }
    ```

    ### 3.3. Retrieve attestation

    Retrieve the attestation required to complete the CCTP transfer by calling
    Circle's attestation API.

    * Call Circle's [`GET /v2/messages`](/api-reference/cctp/all/get-messages-v2)
      API endpoint to retrieve the attestation.
    * Pass `STELLAR_DOMAIN` for the `sourceDomain` path parameter, using the
      [CCTP domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers)
      for Stellar Testnet (27).
    * Pass `transactionHash` from the value returned by `submitSorobanTx` within the
      `burnUSDC` function above.

    ```ts TypeScript theme={null}
    async function retrieveAttestation(transactionHash: string) {
      console.log("Retrieving attestation...");
      const url = `https://iris-api-sandbox.circle.com/v2/messages/${STELLAR_DOMAIN}?transactionHash=${transactionHash}`;
      while (true) {
        try {
          const response = await fetch(url, { method: "GET" });

          if (!response.ok) {
            if (response.status !== 404) {
              const text = await response.text().catch(() => "");
              console.error(
                "Error fetching attestation:",
                `${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`,
              );
            }
            await new Promise((resolve) => setTimeout(resolve, 5000));
            continue;
          }

          const data = (await response.json()) as AttestationResponse;

          if (data?.messages?.[0]?.status === "complete") {
            console.log("Attestation retrieved successfully!");
            return data.messages[0];
          }
          console.log("Waiting for attestation...");
          await new Promise((resolve) => setTimeout(resolve, 5000));
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          console.error("Error fetching attestation:", message);
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }
    }
    ```

    ### 3.4. Mint USDC on Arc

    Call the
    [`receiveMessage` function](/cctp/references/contract-interfaces#receivemessage)
    from the [`MessageTransmitterV2` contract](/cctp/references/contract-addresses)
    deployed on Arc Testnet to mint USDC on the destination blockchain.

    * Pass the signed attestation and the message bytes as parameters.
    * The contract verifies the attestation and mints USDC to the recipient encoded
      in the CCTP message.

    ```ts TypeScript theme={null}
    async function mintUSDCOnArc(attestation: AttestationMessage) {
      console.log("Minting USDC on Arc Testnet...");
      const hash = await arcWalletClient.sendTransaction({
        to: ARC_MESSAGE_TRANSMITTER as `0x${string}`,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "receiveMessage",
              stateMutability: "nonpayable",
              inputs: [
                { name: "message", type: "bytes" },
                { name: "attestation", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "receiveMessage",
          args: [
            attestation.message as `0x${string}`,
            attestation.attestation as `0x${string}`,
          ],
        }),
      });
      await arcPublicClient.waitForTransactionReceipt({ hash });
      console.log(`Mint Tx: ${hash}`);
    }
    ```

    ## Step 4: Full script

    Create an `index.ts` file in your project directory and paste the full script
    below so you can run the flow from one file.

    ```ts index.ts expandable theme={null}
    import {
      Address,
      Contract,
      Keypair,
      nativeToScVal,
      rpc,
      TransactionBuilder,
      xdr,
    } from "@stellar/stellar-sdk";
    import {
      createPublicClient,
      createWalletClient,
      encodeFunctionData,
      http,
      pad,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet } from "viem/chains";

    interface AttestationMessage {
      message: string;
      attestation: string;
      status: string;
    }

    interface AttestationResponse {
      messages: AttestationMessage[];
    }

    // ============ Configuration Constants ============
    // Contract Addresses
    const STELLAR_TOKEN_MESSENGER_MINTER =
      "CDNG7HXAPBWICI2E3AUBP3YZWZELJLYSB6F5CC7WLDTLTHVM74SLRTHP";
    const STELLAR_USDC = "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA";
    const ARC_MESSAGE_TRANSMITTER = "0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275";

    // Transfer Parameters
    const AMOUNT = 10_000_000n; // 1 USDC (Stellar has 7 decimals)
    const MAX_FEE = 100_000n; // 0.01 USDC in Stellar subunits (7 decimals)

    // Chain-specific Parameters
    const STELLAR_DOMAIN = 27; // Source domain ID for Stellar Testnet
    const ARC_TESTNET_DOMAIN = 26; // Destination domain ID for Arc Testnet

    // Stellar Soroban Configuration
    const STELLAR_RPC_URL = "https://soroban-testnet.stellar.org";
    const STELLAR_NETWORK_PASSPHRASE = "Test SDF Network ; September 2015";

    // Authentication
    const stellarKeypair = Keypair.fromSecret(
      process.env.STELLAR_SECRET_KEY as string,
    );

    // Set up wallet clients
    const evmAccount = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );
    const arcWalletClient = createWalletClient({
      chain: arcTestnet,
      transport: http(),
      account: evmAccount,
    });
    const arcPublicClient = createPublicClient({
      chain: arcTestnet,
      transport: http(),
    });

    async function submitSorobanTx(
      server: rpc.Server,
      contractId: string,
      method: string,
      args: xdr.ScVal[],
    ) {
      const account = await server.getAccount(stellarKeypair.publicKey());
      const contract = new Contract(contractId);

      const tx = new TransactionBuilder(account, {
        fee: "10000000",
        networkPassphrase: STELLAR_NETWORK_PASSPHRASE,
      })
        .addOperation(contract.call(method, ...args))
        .setTimeout(120)
        .build();

      const simulated = await server.simulateTransaction(tx);
      if (rpc.Api.isSimulationError(simulated)) {
        throw new Error(`Simulation failed: ${JSON.stringify(simulated)}`);
      }

      const prepared = rpc.assembleTransaction(tx, simulated).build();
      prepared.sign(stellarKeypair);

      const sendResult = await server.sendTransaction(prepared);
      if (sendResult.status === "ERROR") {
        throw new Error(`Send failed: ${JSON.stringify(sendResult)}`);
      }

      let getResult = await server.getTransaction(sendResult.hash);
      while (getResult.status === "NOT_FOUND") {
        await new Promise((resolve) => setTimeout(resolve, 2000));
        getResult = await server.getTransaction(sendResult.hash);
      }

      if (getResult.status !== "SUCCESS") {
        throw new Error(`Transaction failed: ${JSON.stringify(getResult)}`);
      }

      return sendResult.hash;
    }

    // ============ CCTP Flow Functions ============
    async function approveUSDC() {
      console.log("Approving USDC spend on Stellar...");
      const server = new rpc.Server(STELLAR_RPC_URL);
      const latestLedger = await server.getLatestLedger();
      const expirationLedger = latestLedger.sequence + 100_000;

      const approveHash = await submitSorobanTx(server, STELLAR_USDC, "approve", [
        new Address(stellarKeypair.publicKey()).toScVal(),
        new Address(STELLAR_TOKEN_MESSENGER_MINTER).toScVal(),
        nativeToScVal(AMOUNT, { type: "i128" }),
        nativeToScVal(expirationLedger, { type: "u32" }),
      ]);
      console.log(`Approve Tx: ${approveHash}`);
    }

    async function burnUSDC() {
      console.log("Burning USDC on Stellar...");
      // Bytes32 Formatted Parameters
      const evmAddressBytes32 = pad(evmAccount.address);
      const mintRecipient = xdr.ScVal.scvBytes(
        Buffer.from(evmAddressBytes32.slice(2), "hex"),
      );
      const server = new rpc.Server(STELLAR_RPC_URL);

      const txHash = await submitSorobanTx(
        server,
        STELLAR_TOKEN_MESSENGER_MINTER,
        "deposit_for_burn",
        [
          new Address(stellarKeypair.publicKey()).toScVal(),
          nativeToScVal(AMOUNT, { type: "i128" }),
          nativeToScVal(ARC_TESTNET_DOMAIN, { type: "u32" }),
          mintRecipient,
          new Address(STELLAR_USDC).toScVal(),
          xdr.ScVal.scvBytes(Buffer.alloc(32)), // destination_caller
          nativeToScVal(MAX_FEE, { type: "i128" }),
          nativeToScVal(1000, { type: "u32" }), // Fast Transfer finality threshold
        ],
      );
      console.log(`Burn Tx: ${txHash}`);
      return txHash;
    }

    async function retrieveAttestation(transactionHash: string) {
      console.log("Retrieving attestation...");
      const url = `https://iris-api-sandbox.circle.com/v2/messages/${STELLAR_DOMAIN}?transactionHash=${transactionHash}`;
      while (true) {
        try {
          const response = await fetch(url, { method: "GET" });

          if (!response.ok) {
            if (response.status !== 404) {
              const text = await response.text().catch(() => "");
              console.error(
                "Error fetching attestation:",
                `${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`,
              );
            }
            await new Promise((resolve) => setTimeout(resolve, 5000));
            continue;
          }

          const data = (await response.json()) as AttestationResponse;

          if (data?.messages?.[0]?.status === "complete") {
            console.log("Attestation retrieved successfully!");
            return data.messages[0];
          }
          console.log("Waiting for attestation...");
          await new Promise((resolve) => setTimeout(resolve, 5000));
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          console.error("Error fetching attestation:", message);
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }
    }

    async function mintUSDCOnArc(attestation: AttestationMessage) {
      console.log("Minting USDC on Arc Testnet...");
      const hash = await arcWalletClient.sendTransaction({
        to: ARC_MESSAGE_TRANSMITTER as `0x${string}`,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "receiveMessage",
              stateMutability: "nonpayable",
              inputs: [
                { name: "message", type: "bytes" },
                { name: "attestation", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "receiveMessage",
          args: [
            attestation.message as `0x${string}`,
            attestation.attestation as `0x${string}`,
          ],
        }),
      });
      await arcPublicClient.waitForTransactionReceipt({ hash });
      console.log(`Mint Tx: ${hash}`);
    }

    // ============ Main Execution ============
    async function main() {
      await approveUSDC();
      const burnTx = await burnUSDC();
      const attestation = await retrieveAttestation(burnTx);
      await mintUSDCOnArc(attestation);
      console.log("USDC transfer from Stellar to Arc completed!");
    }

    main().catch(console.error);
    ```

    ## Step 5: Test the script

    Run the following command to execute the script:

    ```shell Shell theme={null}
    npm run start
    ```

    When the transfer finishes, the console logs a completion message and the
    relevant transaction hashes. Successful output looks similar to the following:

    ```bash Shell theme={null}
    Approving USDC spend on Stellar...
    Approve Tx: <stellar-transaction-hash>
    Burning USDC on Stellar...
    Burn Tx: <stellar-transaction-hash>
    Retrieving attestation...
    Waiting for attestation...
    Waiting for attestation...
    Attestation retrieved successfully!
    Minting USDC on Arc Testnet...
    Mint Tx: 0x...
    USDC transfer from Stellar to Arc completed!
    ```

    Attestation polling can take several minutes depending on network conditions and
    the finality threshold you chose. The script retries every 5 seconds with no
    timeout, so if it appears to hang at `Waiting for attestation...`, allow at
    least five minutes before investigating.

    <Note>
      **Rate limit:** The attestation service rate limit is 35 requests per second. If
      you exceed this limit, the service blocks all API requests for the next 5
      minutes and returns an HTTP 429 (Too Many Requests) response.
    </Note>
  </Tab>

  <Tab title="Arc to Stellar">
    This quickstart demonstrates how to transfer USDC from Arc Testnet to Stellar
    Testnet using CCTP. You use the [viem](https://viem.sh/) library to burn USDC on
    Arc, and [`@stellar/stellar-sdk`](https://github.com/stellar/js-stellar-sdk) to
    mint and forward tokens on the Stellar CCTP Forwarder. When you finish, you will
    have executed a full burn-attest-mint flow.

    You should be comfortable using a terminal and Node.js. Familiarity with basic
    EVM usage and Stellar Soroban transactions helps you follow and adapt the
    script. Examples use Arc Testnet as the source, but you can use any
    [supported blockchain](/cctp/concepts/supported-chains-and-domains).

    <Warning>
      Always
      [use `CctpForwarder`](/cctp/references/stellar#use-cctpforwarder-for-stellar-recipients)
      when routing CCTP USDC to a Stellar address. Set both `mintRecipient` and
      `destinationCaller` to the `CctpForwarder`
      [contract address](/cctp/references/stellar-contracts).

      * If `destinationCaller` is wrong, the forwarder cannot complete the transfer.
      * If `mintRecipient` is set to a user account or muxed address, USDC is not sent
        to the forwarder.

      In either case, funds become permanently stuck and **cannot be recovered**.
    </Warning>

    ## Prerequisites

    Before you begin this tutorial, ensure you have:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared an EVM wallet with the private key available for Arc Testnet
      * Added the Arc Testnet network to your wallet
        ([network details](https://docs.arc.io/arc/references/connect-to-arc#wallet-setup))
      * Funded your wallet with Arc Testnet USDC (for gas fees and the transfer
        amount) from the [Circle Faucet](https://faucet.circle.com)
    * Prepared a Stellar Testnet wallet with the secret key (`S...`) available
      * Funded your Stellar wallet with testnet XLM from the
        [Stellar Friendbot](https://lab.stellar.org/account/fund) (for Soroban fees
        on Stellar Testnet)
    * If needed, identified the forward recipient Stellar `strkey` (`G...`, `C...`,
      or `M...`). For `G...` or `M...` recipients, established a
      [USDC trustline](/stablecoins/quickstart-setup-usdc-trustline-stellar) before
      receiving minted USDC

    <Tip>
      You can use [Stellar Lab](https://lab.stellar.org/) on Stellar Testnet to fund
      accounts and establish USDC trustlines.
    </Tip>

    ## Step 1: Set up the project

    This step shows you how to prepare your project and environment.

    ### 1.1. Set up your development environment

    Create a new directory and install the required dependencies:

    ```bash Shell theme={null}
    # Set up your directory and initialize a Node.js project
    mkdir cctp-arc-to-stellar
    cd cctp-arc-to-stellar
    npm init -y

    # Set up module type and start command
    npm pkg set type=module
    npm pkg set scripts.start="npx tsx --env-file=.env index.ts"

    # Install runtime dependencies
    npm install @stellar/stellar-sdk viem

    # Install dev dependencies
    npm install --save-dev typescript @types/node
    ```

    ### 1.2. Initialize and configure the project

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3. Configure environment variables

    Open `.env` in your editor and add:

    ```text theme={null}
    EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY
    STELLAR_SECRET_KEY=YOUR_STELLAR_SECRET_KEY
    # FORWARD_RECIPIENT=G_OR_C_OR_M_STELLAR_STRKEY
    ```

    * `EVM_PRIVATE_KEY` is the private key for the EVM wallet you use on Arc
      Testnet.
    * `STELLAR_SECRET_KEY` is the Stellar secret key `(S...)` used to sign Soroban
      transactions on Stellar Testnet.
    * `FORWARD_RECIPIENT` is required when the final recipient is a `G...` or `M...`
      address. When omitted, the script defaults to the public key derived from
      `STELLAR_SECRET_KEY`.

    <EnvFileTip />

    The `npm run start` command loads variables from `.env` using Node.js native
    env-file support.

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Configure the script

    This section covers the necessary setup for the transfer script, including
    defining keys and addresses, and configuring the wallet clients for interacting
    with Arc and Stellar.

    ### 2.1. Define configuration constants

    The script predefines the contract addresses, transfer amount, and other
    parameters.

    ```ts TypeScript theme={null}
    import {
      Contract,
      Keypair,
      StrKey,
      rpc,
      TransactionBuilder,
      xdr,
    } from "@stellar/stellar-sdk";
    import {
      createPublicClient,
      createWalletClient,
      encodeFunctionData,
      http,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet } from "viem/chains";

    interface AttestationMessage {
      message: string;
      attestation: string;
      status: string;
    }

    interface AttestationResponse {
      messages: AttestationMessage[];
    }

    // ============ Configuration Constants ============
    // Contract Addresses
    const ARC_USDC = "0x3600000000000000000000000000000000000000";
    const ARC_TOKEN_MESSENGER = "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA";
    const STELLAR_CCTP_FORWARDER =
      "CA66Q2WFBND6V4UEB7RD4SAXSVIWMD6RA4X3U32ELVFGXV5PJK4T4VSZ";

    // Transfer Parameters
    const AMOUNT = 1_000_000n; // 1 USDC (1 USDC = 1,000,000 subunits)
    const MAX_FEE = 500n; // 0.0005 USDC (500 subunits)

    // Chain-specific Parameters
    const ARC_TESTNET_DOMAIN = 26; // Source domain ID for Arc Testnet
    const STELLAR_DOMAIN = 27; // Destination domain ID for Stellar

    // Stellar Soroban Configuration
    const STELLAR_RPC_URL = "https://soroban-testnet.stellar.org";
    const STELLAR_NETWORK_PASSPHRASE = "Test SDF Network ; September 2015";
    ```

    ### 2.2. Set up wallet clients

    The wallet clients configure the appropriate network settings using `viem`. In
    this example, the script connects to Arc Testnet.

    ```ts TypeScript theme={null}
    const evmAccount = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );

    const arcWalletClient = createWalletClient({
      chain: arcTestnet,
      transport: http(),
      account: evmAccount,
    });

    const arcPublicClient = createPublicClient({
      chain: arcTestnet,
      transport: http(),
    });
    ```

    ### 2.3. Encode the CCTP Forwarder hook data

    When transferring to Stellar, the Arc burn encodes the forward recipient in the
    `hookData` field. The Stellar CCTP Forwarder contract is set as both the
    `mintRecipient` and `destinationCaller`.

    The hook data encodes the forward recipient in a specific binary format:

    ```text Byte layout theme={null}
      [32-byte header + forward recipient bytes]
      ├─ Bytes 0-23:  Zero padding (0x000...000)
      ├─ Bytes 24-27: Hook version (uint32, currently 0)
      ├─ Bytes 28-31: Forward recipient strkey length (uint32, byte length)
      └─ Bytes 32+:   Forward recipient strkey as UTF-8 bytes
    ```

    Example: For forward recipient "GABC...XYZ" (56 chars):

    * Zero padding: 0x000000000000000000000000000000000000000000000000
    * Hook version: 0x00000000
    * Length: 0x00000038 (56 in hex)
    * Forward recipient: "GABC...XYZ" encoded as UTF-8

    This encoding tells the CCTP Forwarder where to send tokens after minting.

    <Note>
      `G` and `M` strkey forward recipients need an established
      [USDC trustline](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#trustlines)
      before receiving funds. Transfers without a trustline fail.
    </Note>

    <Accordion title="How the CCTP Forwarder flow works">
      This path follows the
      [CCTP Forwarder](/cctp/references/stellar#use-cctpforwarder-for-stellar-recipients)
      pattern:

      1. **Burn with hook**: `depositForBurnWithHook` on the Arc
         [`TokenMessengerV2`](/cctp/references/contract-interfaces#depositforburnwithhook)
         contract. `mintRecipient` is the Stellar
         [CCTP Forwarder](/cctp/references/stellar-contracts#cctpforwarder), and
         `hookData` carries the forward recipient strkey.
      2. **Attest**: Circle's attestation service signs the burn event.
      3. **Mint and forward**: `mint_and_forward` on the Stellar CCTP Forwarder calls
         `receive_message` on `MessageTransmitter`, mints tokens, and forwards them
         per the hook data.

      <Note>
        The CCTP Forwarder flow is non-custodial. In one atomic Soroban transaction,
        `mint_and_forward` mints to `CctpForwarder` and pays `forwardRecipient` onchain.
        Circle does not take custody of the minted balance in between.
      </Note>
    </Accordion>

    ```ts TypeScript theme={null}
    // Convert a Stellar contract address (C...) to 0x-prefixed bytes32
    function contractStrkeyToBytes32(strkey: string): `0x${string}` {
      if (!StrKey.isValidContract(strkey)) {
        throw new Error(`Invalid contract strkey: ${strkey}`);
      }
      return `0x${Buffer.from(StrKey.decodeContract(strkey)).toString("hex")}`;
    }

    // Build hook data encoding the forward recipient
    function buildCctpForwarderHookData(
      forwardRecipientStrkey: string,
    ): `0x${string}` {
      const isValid =
        StrKey.isValidEd25519PublicKey(forwardRecipientStrkey) ||
        StrKey.isValidContract(forwardRecipientStrkey) ||
        StrKey.isValidMed25519PublicKey(forwardRecipientStrkey);
      if (!isValid) {
        throw new Error(
          `Invalid forward recipient: ${forwardRecipientStrkey} (expected G..., C..., or M... address)`,
        );
      }

      const recipientBytes = Buffer.from(forwardRecipientStrkey, "utf8");
      const hookData = Buffer.alloc(32 + recipientBytes.length);
      hookData.writeUInt32BE(0, 24); // hook version = 0
      hookData.writeUInt32BE(recipientBytes.length, 28); // recipient byte length
      recipientBytes.copy(hookData, 32); // recipient strkey as UTF-8
      return `0x${hookData.toString("hex")}`;
    }

    const stellarKeypair = Keypair.fromSecret(
      process.env.STELLAR_SECRET_KEY as string,
    );
    // Falls back to the Stellar public key derived from STELLAR_SECRET_KEY
    // when FORWARD_RECIPIENT is unset or empty.
    const forwardRecipient =
      process.env.FORWARD_RECIPIENT || stellarKeypair.publicKey();
    const hookData = buildCctpForwarderHookData(forwardRecipient);
    ```

    ## Step 3: Implement the transfer logic

    This step implements the core transfer logic: approve and burn on Arc, poll for
    an attestation, then mint and forward on Stellar. A successful run prints
    transaction hashes and a completion message in the console.

    ### 3.1. Approve USDC on Arc

    Grant approval for the
    [`TokenMessengerV2` contract](/cctp/references/contract-addresses) to withdraw
    USDC from your wallet. This allows the contract to burn USDC when you initiate
    the transfer.

    ```ts TypeScript theme={null}
    async function approveUSDC() {
      console.log("Approving USDC spend on Arc...");
      const approveTx = await arcWalletClient.sendTransaction({
        to: ARC_USDC as `0x${string}`,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "approve",
              stateMutability: "nonpayable",
              inputs: [
                { name: "spender", type: "address" },
                { name: "amount", type: "uint256" },
              ],
              outputs: [{ name: "", type: "bool" }],
            },
          ],
          functionName: "approve",
          args: [ARC_TOKEN_MESSENGER as `0x${string}`, AMOUNT],
        }),
      });
      await arcPublicClient.waitForTransactionReceipt({ hash: approveTx });
      console.log(`Approve Tx: ${approveTx}`);
    }
    ```

    ### 3.2. Burn USDC on Arc

    Call `depositForBurnWithHook` to burn USDC with the CCTP Forwarder hook data.
    You specify the following parameters:

    * **Burn amount**: The amount of USDC to burn (in Arc subunits, 6 decimals)
    * **Destination domain**: The target blockchain for minting USDC (see
      [supported blockchains and domains](/cctp/concepts/supported-chains-and-domains))
    * **Mint recipient**: The CCTP Forwarder contract address on Stellar (encoded as
      `bytes32`)
    * **Burn token**: The contract address of the USDC token being burned on Arc
    * **Destination caller**: The CCTP Forwarder contract address on Stellar
      (restricts who can call `receive_message`)
    * **Max fee**: The maximum [fee](/cctp/concepts/fees) allowed for the transfer
    * **Finality threshold**: Determines whether it's a
      [Fast Transfer](/cctp/concepts/finality-and-block-confirmations#fast-transfer-attestation-times)
      (1000 or less) or a
      [Standard Transfer](/cctp/concepts/finality-and-block-confirmations#standard-transfer-attestation-times)
      (2000 or more)
    * **Hook data**: Encodes the final Stellar recipient address for the CCTP
      Forwarder

    <Warning>
      Always
      [use `CctpForwarder`](/cctp/references/stellar#use-cctpforwarder-for-stellar-recipients)
      when routing CCTP USDC to a Stellar address. Set both `mintRecipient` and
      `destinationCaller` to the `CctpForwarder`
      [contract address](/cctp/references/stellar-contracts).

      * If `destinationCaller` is wrong, the forwarder cannot complete the transfer.
      * If `mintRecipient` is set to a user account or muxed address, USDC is not sent
        to the forwarder.

      In either case, funds become permanently stuck and **cannot be recovered**.
    </Warning>

    `mintRecipient` and `destinationCaller` must be the Stellar CCTP Forwarder
    contract address. `TokenMessengerMinter` assumes `mintRecipient` is a contract
    address, so this example validates `STELLAR_CCTP_FORWARDER` as a contract
    `strkey` and uses the final recipient only in `hookData`.

    ```ts TypeScript theme={null}
    async function burnUSDC() {
      console.log("Burning USDC on Arc (with hook)...");
      const cctpForwarderBytes32 = contractStrkeyToBytes32(STELLAR_CCTP_FORWARDER);
      const burnTx = await arcWalletClient.sendTransaction({
        to: ARC_TOKEN_MESSENGER as `0x${string}`,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "depositForBurnWithHook",
              stateMutability: "nonpayable",
              inputs: [
                { name: "amount", type: "uint256" },
                { name: "destinationDomain", type: "uint32" },
                { name: "mintRecipient", type: "bytes32" },
                { name: "burnToken", type: "address" },
                { name: "destinationCaller", type: "bytes32" },
                { name: "maxFee", type: "uint256" },
                { name: "minFinalityThreshold", type: "uint32" },
                { name: "hookData", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "depositForBurnWithHook",
          args: [
            AMOUNT,
            STELLAR_DOMAIN,
            cctpForwarderBytes32, // mintRecipient = Stellar CCTP Forwarder
            ARC_USDC as `0x${string}`,
            cctpForwarderBytes32, // destinationCaller = Stellar CCTP Forwarder
            MAX_FEE,
            2000, // Standard Transfer finality threshold
            hookData,
          ],
        }),
      });
      await arcPublicClient.waitForTransactionReceipt({ hash: burnTx });
      console.log(`Burn Tx: ${burnTx}`);
      return burnTx;
    }
    ```

    ### 3.3. Retrieve attestation

    Retrieve the attestation required to complete the CCTP transfer by calling
    Circle's attestation API.

    * Call Circle's [`GET /v2/messages`](/api-reference/cctp/all/get-messages-v2)
      API endpoint to retrieve the attestation.
    * Pass `ARC_TESTNET_DOMAIN` for the `sourceDomain` path parameter, using the
      [CCTP domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers)
      for Arc Testnet (26).
    * Pass `transactionHash` from the value returned by `burnUSDC` above.

    ```ts TypeScript theme={null}
    async function retrieveAttestation(transactionHash: string) {
      console.log("Retrieving attestation...");
      const url = `https://iris-api-sandbox.circle.com/v2/messages/${ARC_TESTNET_DOMAIN}?transactionHash=${transactionHash}`;
      while (true) {
        try {
          const response = await fetch(url, { method: "GET" });

          if (!response.ok) {
            if (response.status !== 404) {
              const text = await response.text().catch(() => "");
              console.error(
                "Error fetching attestation:",
                `${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`,
              );
            }
            await new Promise((resolve) => setTimeout(resolve, 5000));
            continue;
          }

          const data = (await response.json()) as AttestationResponse;

          if (data?.messages?.[0]?.status === "complete") {
            console.log("Attestation retrieved successfully!");
            return data.messages[0];
          }
          console.log("Waiting for attestation...");
          await new Promise((resolve) => setTimeout(resolve, 5000));
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          console.error("Error fetching attestation:", message);
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }
    }
    ```

    ### 3.4. Mint and forward USDC on Stellar

    The `submitSorobanTx` helper builds, signs, submits, and confirms a Soroban
    contract transaction.

    ```ts TypeScript theme={null}
    async function submitSorobanTx(
      server: rpc.Server,
      contractId: string,
      method: string,
      args: xdr.ScVal[],
    ) {
      const account = await server.getAccount(stellarKeypair.publicKey());
      const contract = new Contract(contractId);

      const tx = new TransactionBuilder(account, {
        fee: "10000000",
        networkPassphrase: STELLAR_NETWORK_PASSPHRASE,
      })
        .addOperation(contract.call(method, ...args))
        .setTimeout(120)
        .build();

      const simulated = await server.simulateTransaction(tx);
      if (rpc.Api.isSimulationError(simulated)) {
        throw new Error(`Simulation failed: ${JSON.stringify(simulated)}`);
      }

      const prepared = rpc.assembleTransaction(tx, simulated).build();
      prepared.sign(stellarKeypair);

      const sendResult = await server.sendTransaction(prepared);
      if (sendResult.status === "ERROR") {
        throw new Error(`Send failed: ${JSON.stringify(sendResult)}`);
      }

      let getResult = await server.getTransaction(sendResult.hash);
      while (getResult.status === "NOT_FOUND") {
        await new Promise((resolve) => setTimeout(resolve, 2000));
        getResult = await server.getTransaction(sendResult.hash);
      }

      if (getResult.status !== "SUCCESS") {
        throw new Error(`Transaction failed: ${JSON.stringify(getResult)}`);
      }

      return sendResult.hash;
    }
    ```

    Use the `submitSorobanTx` helper to call `mint_and_forward` on the Stellar CCTP
    Forwarder. This verifies the CCTP message and attestation, mints USDC through
    the `TokenMessengerMinter`, and forwards it to the recipient encoded in the hook
    data:

    ```ts TypeScript theme={null}
    async function mintAndForwardOnStellar(attestation: AttestationMessage) {
      console.log("Minting and forwarding USDC on Stellar...");
      const server = new rpc.Server(STELLAR_RPC_URL);

      const messageBytes = Buffer.from(
        attestation.message.replace("0x", ""),
        "hex",
      );
      const attestationBytes = Buffer.from(
        attestation.attestation.replace("0x", ""),
        "hex",
      );

      const txHash = await submitSorobanTx(
        server,
        STELLAR_CCTP_FORWARDER,
        "mint_and_forward",
        [xdr.ScVal.scvBytes(messageBytes), xdr.ScVal.scvBytes(attestationBytes)],
      );

      console.log(`mint_and_forward Tx: ${txHash}`);
    }
    ```

    ## Step 4: Full script

    Create an `index.ts` file in your project directory and paste the full script
    below so you can run the flow from one file.

    ```ts index.ts expandable theme={null}
    import {
      Contract,
      Keypair,
      StrKey,
      rpc,
      TransactionBuilder,
      xdr,
    } from "@stellar/stellar-sdk";
    import {
      createPublicClient,
      createWalletClient,
      encodeFunctionData,
      http,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet } from "viem/chains";

    interface AttestationMessage {
      message: string;
      attestation: string;
      status: string;
    }

    interface AttestationResponse {
      messages: AttestationMessage[];
    }

    // ============ Configuration Constants ============
    // Contract Addresses
    const ARC_USDC = "0x3600000000000000000000000000000000000000";
    const ARC_TOKEN_MESSENGER = "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA";
    const STELLAR_CCTP_FORWARDER =
      "CA66Q2WFBND6V4UEB7RD4SAXSVIWMD6RA4X3U32ELVFGXV5PJK4T4VSZ";

    // Transfer Parameters
    const AMOUNT = 1_000_000n; // 1 USDC (1 USDC = 1,000,000 subunits)
    const MAX_FEE = 500n; // 0.0005 USDC (500 subunits)

    // Chain-specific Parameters
    const ARC_TESTNET_DOMAIN = 26; // Source domain ID for Arc Testnet
    const STELLAR_DOMAIN = 27; // Destination domain ID for Stellar

    // Stellar Soroban Configuration
    const STELLAR_RPC_URL = "https://soroban-testnet.stellar.org";
    const STELLAR_NETWORK_PASSPHRASE = "Test SDF Network ; September 2015";

    // Set up wallet clients
    const evmAccount = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );
    const arcWalletClient = createWalletClient({
      chain: arcTestnet,
      transport: http(),
      account: evmAccount,
    });
    const arcPublicClient = createPublicClient({
      chain: arcTestnet,
      transport: http(),
    });

    // Hook Data — encodes the forward recipient for the CCTP Forwarder contract
    function contractStrkeyToBytes32(strkey: string): `0x${string}` {
      if (!StrKey.isValidContract(strkey)) {
        throw new Error(`Invalid contract strkey: ${strkey}`);
      }
      return `0x${Buffer.from(StrKey.decodeContract(strkey)).toString("hex")}`;
    }
    function buildCctpForwarderHookData(
      forwardRecipientStrkey: string,
    ): `0x${string}` {
      const isValid =
        StrKey.isValidEd25519PublicKey(forwardRecipientStrkey) ||
        StrKey.isValidContract(forwardRecipientStrkey) ||
        StrKey.isValidMed25519PublicKey(forwardRecipientStrkey);
      if (!isValid) {
        throw new Error(
          `Invalid forward recipient: ${forwardRecipientStrkey} (expected G..., C..., or M... address)`,
        );
      }
      const recipientBytes = Buffer.from(forwardRecipientStrkey, "utf8");
      const hookData = Buffer.alloc(32 + recipientBytes.length);
      hookData.writeUInt32BE(0, 24);
      hookData.writeUInt32BE(recipientBytes.length, 28);
      recipientBytes.copy(hookData, 32);
      return `0x${hookData.toString("hex")}`;
    }
    const stellarKeypair = Keypair.fromSecret(
      process.env.STELLAR_SECRET_KEY as string,
    );
    // Falls back to the Stellar public key derived from STELLAR_SECRET_KEY
    // when FORWARD_RECIPIENT is unset or empty.
    const forwardRecipient =
      process.env.FORWARD_RECIPIENT || stellarKeypair.publicKey();
    const hookData = buildCctpForwarderHookData(forwardRecipient);

    // ============ CCTP Flow Functions ============
    async function approveUSDC() {
      console.log("Approving USDC spend on Arc...");
      const approveTx = await arcWalletClient.sendTransaction({
        to: ARC_USDC as `0x${string}`,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "approve",
              stateMutability: "nonpayable",
              inputs: [
                { name: "spender", type: "address" },
                { name: "amount", type: "uint256" },
              ],
              outputs: [{ name: "", type: "bool" }],
            },
          ],
          functionName: "approve",
          args: [ARC_TOKEN_MESSENGER as `0x${string}`, AMOUNT],
        }),
      });
      await arcPublicClient.waitForTransactionReceipt({ hash: approveTx });
      console.log(`Approve Tx: ${approveTx}`);
    }

    async function burnUSDC() {
      console.log("Burning USDC on Arc (with hook)...");
      const cctpForwarderBytes32 = contractStrkeyToBytes32(STELLAR_CCTP_FORWARDER);
      const burnTx = await arcWalletClient.sendTransaction({
        to: ARC_TOKEN_MESSENGER as `0x${string}`,
        data: encodeFunctionData({
          abi: [
            {
              type: "function",
              name: "depositForBurnWithHook",
              stateMutability: "nonpayable",
              inputs: [
                { name: "amount", type: "uint256" },
                { name: "destinationDomain", type: "uint32" },
                { name: "mintRecipient", type: "bytes32" },
                { name: "burnToken", type: "address" },
                { name: "destinationCaller", type: "bytes32" },
                { name: "maxFee", type: "uint256" },
                { name: "minFinalityThreshold", type: "uint32" },
                { name: "hookData", type: "bytes" },
              ],
              outputs: [],
            },
          ],
          functionName: "depositForBurnWithHook",
          args: [
            AMOUNT,
            STELLAR_DOMAIN,
            cctpForwarderBytes32, // mintRecipient = Stellar CCTP Forwarder
            ARC_USDC as `0x${string}`,
            cctpForwarderBytes32, // destinationCaller = Stellar CCTP Forwarder
            MAX_FEE,
            2000, // Standard Transfer finality threshold
            hookData,
          ],
        }),
      });
      await arcPublicClient.waitForTransactionReceipt({ hash: burnTx });
      console.log(`Burn Tx: ${burnTx}`);
      return burnTx;
    }

    async function retrieveAttestation(transactionHash: string) {
      console.log("Retrieving attestation...");
      const url = `https://iris-api-sandbox.circle.com/v2/messages/${ARC_TESTNET_DOMAIN}?transactionHash=${transactionHash}`;
      while (true) {
        try {
          const response = await fetch(url, { method: "GET" });

          if (!response.ok) {
            if (response.status !== 404) {
              const text = await response.text().catch(() => "");
              console.error(
                "Error fetching attestation:",
                `${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`,
              );
            }
            await new Promise((resolve) => setTimeout(resolve, 5000));
            continue;
          }

          const data = (await response.json()) as AttestationResponse;

          if (data?.messages?.[0]?.status === "complete") {
            console.log("Attestation retrieved successfully!");
            return data.messages[0];
          }
          console.log("Waiting for attestation...");
          await new Promise((resolve) => setTimeout(resolve, 5000));
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          console.error("Error fetching attestation:", message);
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }
    }

    async function submitSorobanTx(
      server: rpc.Server,
      contractId: string,
      method: string,
      args: xdr.ScVal[],
    ) {
      const account = await server.getAccount(stellarKeypair.publicKey());
      const contract = new Contract(contractId);

      const tx = new TransactionBuilder(account, {
        fee: "10000000",
        networkPassphrase: STELLAR_NETWORK_PASSPHRASE,
      })
        .addOperation(contract.call(method, ...args))
        .setTimeout(120)
        .build();

      const simulated = await server.simulateTransaction(tx);
      if (rpc.Api.isSimulationError(simulated)) {
        throw new Error(`Simulation failed: ${JSON.stringify(simulated)}`);
      }

      const prepared = rpc.assembleTransaction(tx, simulated).build();
      prepared.sign(stellarKeypair);

      const sendResult = await server.sendTransaction(prepared);
      if (sendResult.status === "ERROR") {
        throw new Error(`Send failed: ${JSON.stringify(sendResult)}`);
      }

      let getResult = await server.getTransaction(sendResult.hash);
      while (getResult.status === "NOT_FOUND") {
        await new Promise((resolve) => setTimeout(resolve, 2000));
        getResult = await server.getTransaction(sendResult.hash);
      }

      if (getResult.status !== "SUCCESS") {
        throw new Error(`Transaction failed: ${JSON.stringify(getResult)}`);
      }

      return sendResult.hash;
    }

    async function mintAndForwardOnStellar(attestation: AttestationMessage) {
      console.log("Minting and forwarding USDC on Stellar...");
      const server = new rpc.Server(STELLAR_RPC_URL);

      const messageBytes = Buffer.from(
        attestation.message.replace("0x", ""),
        "hex",
      );
      const attestationBytes = Buffer.from(
        attestation.attestation.replace("0x", ""),
        "hex",
      );

      const txHash = await submitSorobanTx(
        server,
        STELLAR_CCTP_FORWARDER,
        "mint_and_forward",
        [xdr.ScVal.scvBytes(messageBytes), xdr.ScVal.scvBytes(attestationBytes)],
      );

      console.log(`mint_and_forward Tx: ${txHash}`);
    }

    // ============ Main Execution ============
    async function main() {
      await approveUSDC();
      const burnTx = await burnUSDC();
      const attestation = await retrieveAttestation(burnTx);
      await mintAndForwardOnStellar(attestation);
      console.log("USDC transfer from Arc to Stellar completed!");
    }

    main().catch(console.error);
    ```

    ## Step 5: Test the script

    Run the following command to execute the script:

    ```shell Shell theme={null}
    npm run start
    ```

    When the transfer finishes, the console logs a completion message and the
    relevant transaction hashes. Successful output looks similar to the following:

    ```bash Shell theme={null}
    Approving USDC spend on Arc...
    Approve Tx: 0x65d6504333ac76cf952975dad29d4a31d8de28c59d7c97ee8ac5d0c360c0e70c
    Burning USDC on Arc (with hook)...
    Burn Tx: 0x73e1eb9224ca5778be763b4e8afc11cfa63e7ae3caa8b2748ce73f4f3d07181a
    Retrieving attestation...
    Waiting for attestation...
    Attestation retrieved successfully!
    Minting and forwarding USDC on Stellar...
    mint_and_forward Tx: <stellar-transaction-hash>
    USDC transfer from Arc to Stellar completed!
    ```

    Attestation polling can take several minutes depending on network conditions and
    the finality threshold you chose. The script retries every 5 seconds with no
    timeout, so if it appears to hang at `Waiting for attestation...`, allow at
    least five minutes before investigating.

    <Note>
      **Rate limit:** The attestation service rate limit is 35 requests per second. If
      you exceed this limit, the service blocks all API requests for the next 5
      minutes and returns an HTTP 429 (Too Many Requests) response.
    </Note>
  </Tab>
</Tabs>


# Attestation Verification
Source: https://developers.circle.com/cctp/references/attestation-verification

Technical reference for verifying CCTP attestation signatures

When you retrieve an attestation from Circle's Attestation Service, you can
optionally verify the attestation signature before using it to mint USDC on the
destination blockchain. This page explains how the verification process works
and when you might want to use it.

## How verification works

The verification process uses cryptographic signature recovery to confirm that
Circle's Attestation Service signed the message. It involves the following
steps:

<Steps>
  <Step title="Retrieve the public key">
    Fetch Circle's current public key from the
    [`GET /v2/publicKeys`](/api-reference/cctp/all/get-public-keys-v2) endpoint.
  </Step>

  <Step title="Hash the message">
    Create a `keccak256` hash of the message bytes.
  </Step>

  <Step title="Parse the attestation">
    Split the 65-byte attestation into its `r`, `s`, and `v` components (ECDSA
    signature format).
  </Step>

  <Step title="Recover the signer">
    Use the signature and message hash to recover the public key that signed the
    message.
  </Step>

  <Step title="Compare addresses">
    Convert both the recovered public key and Circle's public key to Ethereum
    addresses and compare them.
  </Step>
</Steps>

If the addresses match, the attestation was signed by Circle's Attestation
Service and is valid.

## When to verify attestations

Attestation verification is optional because the CCTP contracts on the
destination blockchain perform their own verification when you call
`receiveMessage`. However, you might want to verify attestations before
submitting the mint transaction if:

* **Your application requires an additional layer of security**: Verifying
  before minting provides defense-in-depth by catching invalid attestations at
  the application layer.

* **You want to detect invalid attestations before paying gas fees**: If an
  attestation is invalid, the mint transaction fails and you lose the gas fees.
  Pre-verification lets you catch this before submitting the transaction.

* **You're building a relayer service that batches multiple attestations**:
  Relayers can verify each attestation in a batch before submitting, preventing
  a single invalid attestation from affecting the entire batch.

## Verification code example

The following examples show how to verify an attestation signature using Viem or
Ethers:

<CodeGroup>
  ```ts Viem theme={null}
  import { keccak256, hexToBytes, recoverAddress, bytesToHex } from "viem";

  interface PublicKey {
    publicKey: `0x${string}`;
    cctpVersion: number;
  }

  interface AttestationData {
    message: string;
    attestation: string;
  }

  function publicKeyToAddress(publicKey: `0x${string}`): `0x${string}` {
    // Remove '0x04' prefix (uncompressed public key marker)
    const publicKeyWithoutPrefix = `0x${publicKey.slice(4)}` as `0x${string}`;
    const hash = keccak256(hexToBytes(publicKeyWithoutPrefix));
    // Take last 20 bytes (40 hex chars) as address
    return `0x${hash.slice(-40)}`;
  }

  async function getPublicKeys() {
    const response = await fetch(
      "https://iris-api-sandbox.circle.com/v2/publicKeys",
    );
    const data = await response.json();
    return data.publicKeys
      .filter((key: PublicKey) => key.cctpVersion === 2)
      .map((key: PublicKey) => key.publicKey);
  }

  async function verifyAttestation(
    attestationData: AttestationData,
    publicKeys: `0x${string}`[],
  ) {
    try {
      const messageHash = keccak256(attestationData.message as `0x${string}`);
      const attestationBytes = hexToBytes(
        attestationData.attestation as `0x${string}`,
      );
      const signatureLength = 65;
      const numSignatures = attestationBytes.length / signatureLength;

      if (attestationBytes.length % signatureLength !== 0) {
        throw new Error(`Invalid attestation length: ${attestationBytes.length}`);
      }

      let validSignatures = 0;

      for (let i = 0; i < numSignatures; i++) {
        const start = i * signatureLength;
        const signature = attestationBytes.slice(start, start + signatureLength);

        const recoveredAddress = await recoverAddress({
          hash: messageHash,
          signature: bytesToHex(signature),
        });

        const isValid = publicKeys.some(
          (publicKey) =>
            publicKeyToAddress(publicKey).toLowerCase() ===
            recoveredAddress.toLowerCase(),
        );

        if (isValid) validSignatures++;
      }

      const threshold = Math.ceil(publicKeys.length / 2);
      console.log(
        `Valid signatures: ${validSignatures}/${numSignatures}, threshold: ${threshold}`,
      );

      return validSignatures >= threshold;
    } catch (error) {
      console.error(
        "Error verifying attestation:",
        error instanceof Error ? error.message : String(error),
      );
      return false;
    }
  }

  const attestationData: AttestationData = {
    message: "0x000000010000001a00000015...", // Full message hex from API
    attestation: "0x3c5951abd82a83369d603ebaf9...", // Full attestation hex from API
  };

  // Example usage
  const publicKeys = await getPublicKeys();
  const isValid = await verifyAttestation(attestationData, publicKeys);
  ```

  ```ts Ethers.js theme={null}
  import { ethers } from "ethers";

  interface PublicKey {
    publicKey: string;
    cctpVersion: number;
  }

  interface AttestationData {
    message: string;
    attestation: string;
  }

  async function getPublicKeys() {
    const response = await fetch(
      "https://iris-api-sandbox.circle.com/v2/publicKeys",
    );
    const data = await response.json();

    // Get all public keys for CCTP V2
    const v2Keys = data.publicKeys
      .filter((key: PublicKey) => key.cctpVersion === 2)
      .map((key: PublicKey) => key.publicKey);

    if (v2Keys.length === 0) {
      throw new Error("CCTP V2 public key not found");
    }

    return v2Keys;
  }

  function verifyAttestation(
    attestationData: AttestationData,
    publicKeys: string[],
  ) {
    try {
      const messageHash = ethers.keccak256(attestationData.message);
      const attestationBytes = ethers.getBytes(attestationData.attestation);

      // V2 attestation has multiple 65-byte signatures
      const signatureLength = 65;
      const numSignatures = attestationBytes.length / signatureLength;

      if (attestationBytes.length % signatureLength !== 0) {
        throw new Error(`Invalid attestation length: ${attestationBytes.length}`);
      }

      let validSignatures = 0;

      // Verify each signature
      for (let i = 0; i < numSignatures; i++) {
        const start = i * signatureLength;
        const sigBytes = attestationBytes.slice(start, start + signatureLength);

        const r = ethers.hexlify(sigBytes.slice(0, 32));
        const s = ethers.hexlify(sigBytes.slice(32, 64));
        const v = sigBytes[64];

        const signature = { r, s, v };
        const recoveredAddress = ethers.recoverAddress(messageHash, signature);

        // Check if recovered address matches any V2 public key
        const isValid = publicKeys.some(
          (publicKey) =>
            ethers.computeAddress(publicKey).toLowerCase() ===
            recoveredAddress.toLowerCase(),
        );

        if (isValid) validSignatures++;
      }

      const threshold = Math.ceil(publicKeys.length / 2);
      console.log(
        `Valid signatures: ${validSignatures}/${numSignatures}, threshold: ${threshold}`,
      );

      return validSignatures >= threshold;
    } catch (error) {
      console.error("Error verifying attestation:", (error as Error).message);
      return false;
    }
  }

  // Use attestation data from the API
  const attestationData: AttestationData = {
    message: "0x000000010000001a00000015...", // Full message hex from API
    attestation: "0x3c5951abd82a83369d603ebaf9...", // Full attestation hex from API
  };

  // Example usage
  const publicKeys = await getPublicKeys();
  const isValid = verifyAttestation(attestationData, publicKeys);
  ```
</CodeGroup>


# Contract Addresses
Source: https://developers.circle.com/cctp/references/contract-addresses

CCTP smart contract addresses for EVM-compatible blockchains

This page lists the deployed contract addresses for CCTP on all
[supported EVM-compatible blockchains](/cctp/concepts/supported-chains-and-domains).
For contract interfaces and method signatures, see
[Contract Interfaces](/cctp/references/contract-interfaces).

Full contract source code is
[available on GitHub](https://github.com/circlefin/evm-cctp-contracts).

For non-EVM blockchain contract addresses, see:

* [Solana Programs](/cctp/references/solana-programs)
* [Stellar Contracts](/cctp/references/stellar-contracts)
* [Starknet Contracts](/cctp/references/starknet-contracts)

## Mainnet contract addresses

### TokenMessengerV2

| Blockchain      | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                      |
| --------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum**    | 0                                                                        | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://etherscan.io/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                      |
| **Avalanche**   | 1                                                                        | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://snowtrace.io/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                      |
| **OP Mainnet**  | 2                                                                        | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://optimistic.etherscan.io/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)           |
| **Arbitrum**    | 3                                                                        | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://arbiscan.io/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                       |
| **Base**        | 6                                                                        | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://basescan.org/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                      |
| **Polygon PoS** | 7                                                                        | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://polygonscan.com/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                   |
| **Unichain**    | 10                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://uniscan.xyz/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                       |
| **Linea**       | 11                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://lineascan.build/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                   |
| **Codex**       | 12                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://explorer.codex.xyz/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                |
| **Sonic**       | 13                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://sonicscan.org/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                     |
| **World Chain** | 14                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://worldscan.org/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                     |
| **Monad**       | 15                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://monadvision.com/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                   |
| **Sei**         | 16                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://seiscan.io/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                        |
| **XDC**         | 18                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://xdcscan.com/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                       |
| **HyperEVM**    | 19                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://hyperscan.com/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                     |
| **Ink**         | 21                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://explorer.inkonchain.com/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)           |
| **Plume**       | 22                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://explorer.plume.org/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)                |
| **EDGE**        | 28                                                                       | [`0x98706A006bc632Df31CAdFCBD43F38887ce2ca5c`](https://pro.edgex.exchange/en-US/explorer/address/0x98706A006bc632Df31CAdFCBD43F38887ce2ca5c) |
| **Injective**   | 29                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://blockscout.injective.network/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)      |
| **Morph**       | 30                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://explorer.morph.network/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)            |
| **Pharos**      | 31                                                                       | [`0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d`](https://pharos.socialscan.io/address/0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d)              |

### MessageTransmitterV2

| Blockchain      | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                      |
| --------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum**    | 0                                                                        | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://etherscan.io/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                      |
| **Avalanche**   | 1                                                                        | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://snowtrace.io/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                      |
| **OP Mainnet**  | 2                                                                        | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://optimistic.etherscan.io/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)           |
| **Arbitrum**    | 3                                                                        | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://arbiscan.io/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                       |
| **Base**        | 6                                                                        | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://basescan.org/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                      |
| **Polygon PoS** | 7                                                                        | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://polygonscan.com/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                   |
| **Unichain**    | 10                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://uniscan.xyz/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                       |
| **Linea**       | 11                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://lineascan.build/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                   |
| **Codex**       | 12                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://explorer.codex.xyz/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                |
| **Sonic**       | 13                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://sonicscan.org/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                     |
| **World Chain** | 14                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://worldscan.org/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                     |
| **Monad**       | 15                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://monadvision.com/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                   |
| **Sei**         | 16                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://seiscan.io/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                        |
| **XDC**         | 18                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://xdcscan.com/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                       |
| **HyperEVM**    | 19                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://hyperscan.com/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                     |
| **Ink**         | 21                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://explorer.inkonchain.com/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)           |
| **Plume**       | 22                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://explorer.plume.org/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)                |
| **EDGE**        | 28                                                                       | [`0x5b61381Fc9e58E70EfC13a4A97516997019198ee`](https://pro.edgex.exchange/en-US/explorer/address/0x5b61381Fc9e58E70EfC13a4A97516997019198ee) |
| **Injective**   | 29                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://blockscout.injective.network/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)      |
| **Morph**       | 30                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://explorer.morph.network/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)            |
| **Pharos**      | 31                                                                       | [`0x81D40F21F12A8F0E3252Bccb954D722d4c464B64`](https://pharos.socialscan.io/address/0x81D40F21F12A8F0E3252Bccb954D722d4c464B64)              |

### TokenMinterV2

| Blockchain      | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                      |
| --------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum**    | 0                                                                        | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://etherscan.io/address/0xfd78EE919681417d192449715b2594ab58f5D002)                      |
| **Avalanche**   | 1                                                                        | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://snowtrace.io/address/0xfd78EE919681417d192449715b2594ab58f5D002)                      |
| **OP Mainnet**  | 2                                                                        | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://optimistic.etherscan.io/address/0xfd78EE919681417d192449715b2594ab58f5D002)           |
| **Arbitrum**    | 3                                                                        | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://arbiscan.io/address/0xfd78EE919681417d192449715b2594ab58f5D002)                       |
| **Base**        | 6                                                                        | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://basescan.org/address/0xfd78EE919681417d192449715b2594ab58f5D002)                      |
| **Polygon PoS** | 7                                                                        | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://polygonscan.com/address/0xfd78EE919681417d192449715b2594ab58f5D002)                   |
| **Unichain**    | 10                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://uniscan.xyz/address/0xfd78EE919681417d192449715b2594ab58f5D002)                       |
| **Linea**       | 11                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://lineascan.build/address/0xfd78EE919681417d192449715b2594ab58f5D002)                   |
| **Codex**       | 12                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://explorer.codex.xyz/address/0xfd78EE919681417d192449715b2594ab58f5D002)                |
| **Sonic**       | 13                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://sonicscan.org/address/0xfd78EE919681417d192449715b2594ab58f5D002)                     |
| **World Chain** | 14                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://worldscan.org/address/0xfd78EE919681417d192449715b2594ab58f5D002)                     |
| **Monad**       | 15                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://monadvision.com/address/0xfd78EE919681417d192449715b2594ab58f5D002)                   |
| **Sei**         | 16                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://seiscan.io/address/0xfd78EE919681417d192449715b2594ab58f5D002)                        |
| **XDC**         | 18                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://xdcscan.com/address/0xfd78EE919681417d192449715b2594ab58f5D002)                       |
| **HyperEVM**    | 19                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://hyperscan.com/address/0xfd78EE919681417d192449715b2594ab58f5D002)                     |
| **Ink**         | 21                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://explorer.inkonchain.com/address/0xfd78EE919681417d192449715b2594ab58f5D002)           |
| **Plume**       | 22                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://explorer.plume.org/address/0xfd78EE919681417d192449715b2594ab58f5D002)                |
| **EDGE**        | 28                                                                       | [`0x338Dfd607855BeEc17f33e539Ac2479853cC8384`](https://pro.edgex.exchange/en-US/explorer/address/0x338Dfd607855BeEc17f33e539Ac2479853cC8384) |
| **Injective**   | 29                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://blockscout.injective.network/address/0xfd78EE919681417d192449715b2594ab58f5D002)      |
| **Morph**       | 30                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://explorer.morph.network/address/0xfd78EE919681417d192449715b2594ab58f5D002)            |
| **Pharos**      | 31                                                                       | [`0xfd78EE919681417d192449715b2594ab58f5D002`](https://pharos.socialscan.io/address/0xfd78EE919681417d192449715b2594ab58f5D002)              |

### MessageV2

| Blockchain      | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                      |
| --------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum**    | 0                                                                        | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://etherscan.io/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                      |
| **Avalanche**   | 1                                                                        | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://snowtrace.io/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                      |
| **OP Mainnet**  | 2                                                                        | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://optimistic.etherscan.io/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)           |
| **Arbitrum**    | 3                                                                        | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://arbiscan.io/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                       |
| **Base**        | 6                                                                        | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://basescan.org/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                      |
| **Polygon PoS** | 7                                                                        | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://polygonscan.com/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                   |
| **Unichain**    | 10                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://uniscan.xyz/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                       |
| **Linea**       | 11                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://lineascan.build/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                   |
| **Codex**       | 12                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://explorer.codex.xyz/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                |
| **Sonic**       | 13                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://sonicscan.org/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                     |
| **World Chain** | 14                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://worldscan.org/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                     |
| **Monad**       | 15                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://monadvision.com/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                   |
| **Sei**         | 16                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://seiscan.io/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                        |
| **XDC**         | 18                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://xdcscan.com/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                       |
| **HyperEVM**    | 19                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://hyperscan.com/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                     |
| **Ink**         | 21                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://explorer.inkonchain.com/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)           |
| **Plume**       | 22                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://explorer.plume.org/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)                |
| **EDGE**        | 28                                                                       | [`0x88ba38dbB2117879E500c11A0772e2B84Be000B3`](https://pro.edgex.exchange/en-US/explorer/address/0x88ba38dbB2117879E500c11A0772e2B84Be000B3) |
| **Injective**   | 29                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://blockscout.injective.network/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)      |
| **Morph**       | 30                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://explorer.morph.network/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)            |
| **Pharos**      | 31                                                                       | [`0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78`](https://pharos.socialscan.io/address/0xec546b6B005471ECf012e5aF77FBeC07e0FD8f78)              |

## Testnet contract addresses

### TokenMessengerV2

| Blockchain              | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum Sepolia**    | 0                                                                        | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://sepolia.etherscan.io/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                 |
| **Avalanche Fuji**      | 1                                                                        | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://testnet.snowtrace.io/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                 |
| **OP Sepolia**          | 2                                                                        | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://sepolia-optimism.etherscan.io/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)        |
| **Arbitrum Sepolia**    | 3                                                                        | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://sepolia.arbiscan.io/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                  |
| **Base Sepolia**        | 6                                                                        | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://base-sepolia.blockscout.com/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)          |
| **Polygon PoS Amoy**    | 7                                                                        | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://amoy.polygonscan.com/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                 |
| **Unichain Sepolia**    | 10                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://unichain-sepolia.blockscout.com/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)      |
| **Linea Sepolia**       | 11                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://sepolia.lineascan.build/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)              |
| **Codex Testnet**       | 12                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://explorer.codex-stg.xyz/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)               |
| **Sonic Testnet**       | 13                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://blaze.soniclabs.com/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                  |
| **World Chain Sepolia** | 14                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://sepolia.worldscan.org/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                |
| **Monad Testnet**       | 15                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://testnet.monadexplorer.com/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)            |
| **Sei Testnet**         | 16                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://testnet.seiscan.io/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                   |
| **XDC Apothem**         | 18                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://testnet.xdcscan.com/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                  |
| **HyperEVM Testnet**    | 19                                                                       | `0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`                                                                                                    |
| **Ink Testnet**         | 21                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://explorer-sepolia.inkonchain.com/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)      |
| **Plume Testnet**       | 22                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://testnet-explorer.plume.org/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)           |
| **Arc Testnet**         | 26                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://testnet.arcscan.app/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)                  |
| **EDGE Testnet**        | 28                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://edge-testnet.explorer.alchemy.com/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)    |
| **Injective Testnet**   | 29                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://testnet.blockscout.injective.network/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA) |
| **Morph Hoodi Testnet** | 30                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://explorer-hoodi.morph.network/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)         |
| **Pharos Testnet**      | 31                                                                       | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://pharos-testnet.socialscan.io/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA)         |

### MessageTransmitterV2

| Blockchain              | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum Sepolia**    | 0                                                                        | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://sepolia.etherscan.io/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                 |
| **Avalanche Fuji**      | 1                                                                        | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://testnet.snowtrace.io/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                 |
| **OP Sepolia**          | 2                                                                        | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://sepolia-optimism.etherscan.io/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)        |
| **Arbitrum Sepolia**    | 3                                                                        | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://sepolia.arbiscan.io/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                  |
| **Base Sepolia**        | 6                                                                        | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://base-sepolia.blockscout.com/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)          |
| **Polygon PoS Amoy**    | 7                                                                        | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://amoy.polygonscan.com/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                 |
| **Unichain Sepolia**    | 10                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://unichain-sepolia.blockscout.com/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)      |
| **Linea Sepolia**       | 11                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://sepolia.lineascan.build/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)              |
| **Codex Testnet**       | 12                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://explorer.codex-stg.xyz/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)               |
| **Sonic Testnet**       | 13                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://blaze.soniclabs.com/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                  |
| **World Chain Sepolia** | 14                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://sepolia.worldscan.org/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                |
| **Monad Testnet**       | 15                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://testnet.monadexplorer.com/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)            |
| **Sei Testnet**         | 16                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://testnet.seiscan.io/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                   |
| **XDC Apothem**         | 18                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://testnet.xdcscan.com/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                  |
| **HyperEVM Testnet**    | 19                                                                       | `0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`                                                                                                    |
| **Ink Testnet**         | 21                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://explorer-sepolia.inkonchain.com/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)      |
| **Plume Testnet**       | 22                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://testnet-explorer.plume.org/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)           |
| **Arc Testnet**         | 26                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://testnet.arcscan.app/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)                  |
| **EDGE Testnet**        | 28                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://edge-testnet.explorer.alchemy.com/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)    |
| **Injective Testnet**   | 29                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://testnet.blockscout.injective.network/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275) |
| **Morph Hoodi Testnet** | 30                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://explorer-hoodi.morph.network/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)         |
| **Pharos Testnet**      | 31                                                                       | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://pharos-testnet.socialscan.io/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275)         |

### TokenMinterV2

| Blockchain              | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum Sepolia**    | 0                                                                        | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://sepolia.etherscan.io/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                 |
| **Avalanche Fuji**      | 1                                                                        | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://testnet.snowtrace.io/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                 |
| **OP Sepolia**          | 2                                                                        | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://sepolia-optimism.etherscan.io/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)        |
| **Arbitrum Sepolia**    | 3                                                                        | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://sepolia.arbiscan.io/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                  |
| **Base Sepolia**        | 6                                                                        | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://base-sepolia.blockscout.com/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)          |
| **Polygon PoS Amoy**    | 7                                                                        | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://amoy.polygonscan.com/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                 |
| **Unichain Sepolia**    | 10                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://unichain-sepolia.blockscout.com/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)      |
| **Linea Sepolia**       | 11                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://sepolia.lineascan.build/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)              |
| **Codex Testnet**       | 12                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://explorer.codex-stg.xyz/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)               |
| **Sonic Testnet**       | 13                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://blaze.soniclabs.com/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                  |
| **World Chain Sepolia** | 14                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://sepolia.worldscan.org/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                |
| **Monad Testnet**       | 15                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://testnet.monadexplorer.com/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)            |
| **Sei Testnet**         | 16                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://testnet.seiscan.io/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                   |
| **XDC Apothem**         | 18                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://testnet.xdcscan.com/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                  |
| **HyperEVM Testnet**    | 19                                                                       | `0xb43db544E2c27092c107639Ad201b3dEfAbcF192`                                                                                                    |
| **Ink Testnet**         | 21                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://explorer-sepolia.inkonchain.com/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)      |
| **Plume Testnet**       | 22                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://testnet-explorer.plume.org/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)           |
| **Arc Testnet**         | 26                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://testnet.arcscan.app/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)                  |
| **EDGE Testnet**        | 28                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://edge-testnet.explorer.alchemy.com/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)    |
| **Injective Testnet**   | 29                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://testnet.blockscout.injective.network/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192) |
| **Morph Hoodi Testnet** | 30                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://explorer-hoodi.morph.network/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)         |
| **Pharos Testnet**      | 31                                                                       | [`0xb43db544E2c27092c107639Ad201b3dEfAbcF192`](https://pharos-testnet.socialscan.io/address/0xb43db544E2c27092c107639Ad201b3dEfAbcF192)         |

### MessageV2

| Blockchain              | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum Sepolia**    | 0                                                                        | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://sepolia.etherscan.io/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                 |
| **Avalanche Fuji**      | 1                                                                        | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://testnet.snowtrace.io/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                 |
| **OP Sepolia**          | 2                                                                        | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://sepolia-optimism.etherscan.io/address/0xbaC0179bB358A8936169a63408C8481D582390C4)        |
| **Arbitrum Sepolia**    | 3                                                                        | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://sepolia.arbiscan.io/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                  |
| **Base Sepolia**        | 6                                                                        | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://base-sepolia.blockscout.com/address/0xbaC0179bB358A8936169a63408C8481D582390C4)          |
| **Polygon PoS Amoy**    | 7                                                                        | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://amoy.polygonscan.com/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                 |
| **Unichain Sepolia**    | 10                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://unichain-sepolia.blockscout.com/address/0xbaC0179bB358A8936169a63408C8481D582390C4)      |
| **Linea Sepolia**       | 11                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://sepolia.lineascan.build/address/0xbaC0179bB358A8936169a63408C8481D582390C4)              |
| **Codex Testnet**       | 12                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://explorer.codex-stg.xyz/address/0xbaC0179bB358A8936169a63408C8481D582390C4)               |
| **Sonic Testnet**       | 13                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://blaze.soniclabs.com/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                  |
| **World Chain Sepolia** | 14                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://sepolia.worldscan.org/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                |
| **Monad Testnet**       | 15                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://testnet.monadexplorer.com/address/0xbaC0179bB358A8936169a63408C8481D582390C4)            |
| **Sei Testnet**         | 16                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://testnet.seiscan.io/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                   |
| **XDC Apothem**         | 18                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://testnet.xdcscan.com/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                  |
| **HyperEVM Testnet**    | 19                                                                       | `0xbaC0179bB358A8936169a63408C8481D582390C4`                                                                                                    |
| **Ink Testnet**         | 21                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://explorer-sepolia.inkonchain.com/address/0xbaC0179bB358A8936169a63408C8481D582390C4)      |
| **Plume Testnet**       | 22                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://testnet-explorer.plume.org/address/0xbaC0179bB358A8936169a63408C8481D582390C4)           |
| **Arc Testnet**         | 26                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://testnet.arcscan.app/address/0xbaC0179bB358A8936169a63408C8481D582390C4)                  |
| **EDGE Testnet**        | 28                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://edge-testnet.explorer.alchemy.com/address/0xbaC0179bB358A8936169a63408C8481D582390C4)    |
| **Injective Testnet**   | 29                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://testnet.blockscout.injective.network/address/0xbaC0179bB358A8936169a63408C8481D582390C4) |
| **Morph Hoodi Testnet** | 30                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://explorer-hoodi.morph.network/address/0xbaC0179bB358A8936169a63408C8481D582390C4)         |
| **Pharos Testnet**      | 31                                                                       | [`0xbaC0179bB358A8936169a63408C8481D582390C4`](https://pharos-testnet.socialscan.io/address/0xbaC0179bB358A8936169a63408C8481D582390C4)         |


# EVM Contract Interfaces
Source: https://developers.circle.com/cctp/references/contract-interfaces

Public methods and events for CCTP smart contracts on EVM-compatible blockchains

This page documents the public methods and events exposed by CCTP smart
contracts on EVM-compatible blockchains.

## Contract responsibilities

* **TokenMessengerV2**: Entrypoint for crosschain USDC transfer. Routes messages
  to burn USDC on a source blockchain and mint USDC on a destination blockchain.
* **MessageTransmitterV2**: Generic message passing. Sends all messages on the
  source blockchain and receives all messages on the destination blockchain.
* **TokenMinterV2**: Responsible for minting and burning USDC. Contains
  blockchain-specific settings used by burners and minters.
* **MessageV2**: Provides helper functions for crosschain transfers, such as
  `bytes32ToAddress` and `addressToBytes32`, which are commonly used when
  bridging between EVM and non-EVM blockchains.

<Note>
  **Gas optimization tip:** If you're writing your own integration, it's more
  gas-efficient to
  [include address conversion logic directly in your contract](https://github.com/circlefin/evm-cctp-contracts/blob/5f1901a9791b18204e8556bb53fb0dfcb05a832a/src/messages/Message.sol#L146)
  rather than calling an external contract.
</Note>

Full contract source code is
[available on GitHub](https://github.com/circlefin/evm-cctp-contracts).

## TokenMessengerV2

### depositForBurn

Deposits and burns tokens from sender to be minted on destination domain. Minted
tokens will be transferred to `mintRecipient`.

<Note>
  **Note:** There is a \$10 million limit on the amount of USDC that can be burned
  in a single CCTP transaction. If the amount exceeds this limit, the transaction
  will revert. If you need to transfer more than this limit, break up your
  transfers into multiple transactions.

  For Fast Transfers, you should always
  [check the remaining allowance](/api-reference/cctp/all/get-fast-burn-usdc-allowance)
  before initiating a transfer to ensure there is enough to complete your
  transfer.
</Note>

**Parameters**

| Field                  | Type      | Description                                                                                                                               |
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`               | `uint256` | Amount of tokens to deposit and burn                                                                                                      |
| `destinationDomain`    | `uint32`  | Destination [domain ID](/cctp/concepts/supported-chains-and-domains#domain-identifiers) to send the message to                            |
| `mintRecipient`        | `bytes32` | Address of mint recipient on destination domain (must be converted to 32 byte array, that is, prefix with zeros if needed)                |
| `burnToken`            | `address` | Address of contract to burn deposited tokens on local domain                                                                              |
| `destinationCaller`    | `bytes32` | Address as `bytes32` which can call `receiveMessage` on destination domain. If set to `bytes32(0)`, any address can call `receiveMessage` |
| `maxFee`               | `uint256` | Maximum [fee](/cctp/concepts/fees) paid for transfer, specified in units of `burnToken`                                                   |
| `minFinalityThreshold` | `uint32`  | Minimum [finality threshold](/cctp/concepts/finality-and-block-confirmations) at which burn will be attested                              |

**Example**

```solidity Solidity theme={null}
// Burn 100 USDC on Ethereum for minting on Avalanche
uint256 amount = 100 * 10**6; // 100 USDC
uint32 destinationDomain = 1; // Avalanche
bytes32 mintRecipient = bytes32(uint256(uint160(recipientAddress)));
address burnToken = 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48; // USDC on Ethereum
bytes32 destinationCaller = bytes32(0); // Anyone can call receiveMessage
uint256 maxFee = 1000; // 0.001 USDC max fee
uint32 minFinalityThreshold = 1000; // Fast Transfer

tokenMessenger.depositForBurn(
  amount,
  destinationDomain,
  mintRecipient,
  burnToken,
  destinationCaller,
  maxFee,
  minFinalityThreshold
);
```

### depositForBurnWithHook

Deposits and burns tokens from sender to be minted on destination domain, and
emits a crosschain message with additional hook data appended. In addition to
the standard `depositForBurn` parameters, `depositForBurnWithHook` accepts a
dynamic-length `hookData` parameter, allowing you to include additional metadata
that can trigger custom logic on the destination blockchain.

<Note>
  **Note:** There is a \$10 million limit on the amount of USDC that can be burned
  in a single CCTP transaction. If the amount exceeds this limit, the transaction
  will revert. If you need to transfer more than this limit, break up your
  transfers into multiple transactions.

  For Fast Transfers, you should always
  [check the remaining allowance](/api-reference/cctp/all/get-fast-burn-usdc-allowance)
  before initiating a transfer to ensure there is enough to complete your
  transfer.
</Note>

**Parameters**

| Field                  | Type      | Description                                                                                                                               |
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`               | `uint256` | Amount of tokens to burn                                                                                                                  |
| `destinationDomain`    | `uint32`  | Destination domain to send the message to                                                                                                 |
| `mintRecipient`        | `bytes32` | Address of mint recipient on destination domain (must be converted to 32 byte array, that is, prefix with zeros if needed)                |
| `burnToken`            | `address` | Address of contract to burn deposited tokens on local domain                                                                              |
| `destinationCaller`    | `bytes32` | Address as `bytes32` which can call `receiveMessage` on destination domain. If set to `bytes32(0)`, any address can call `receiveMessage` |
| `maxFee`               | `uint256` | Maximum fee paid for transfer, specified in units of `burnToken`                                                                          |
| `minFinalityThreshold` | `uint32`  | Minimum finality threshold at which burn will be attested                                                                                 |
| `hookData`             | `bytes`   | Additional metadata attached to the attested message, used to trigger custom logic on the destination blockchain                          |

### getMinFeeAmount

Calculates and returns the minimum fee required for a given amount in a Standard
Transfer. If the minimum fee (per unit of `burnToken`) is non-zero, the
specified `maxFee` must be at least the returned minimum fee. Otherwise, the
burn will revert onchain.

**Parameters**

| Field    | Type      | Description                                                                                     |
| -------- | --------- | ----------------------------------------------------------------------------------------------- |
| `amount` | `uint256` | The amount used to compute the minimum fee. Must be greater than `1` if standard fee is applied |

### handleReceiveFinalizedMessage

Handles incoming message received by the local MessageTransmitter. For a burn
message, mints the associated token to the requested recipient on the local
domain. Validates the function sender is the local MessageTransmitter, and the
remote sender is a registered remote TokenMessenger for `remoteDomain`.

This method is called for messages where `finalityThresholdExecuted` ≥ 2000
(Standard Transfer).

**Parameters**

| Field                       | Type                     | Description                                                    |
| --------------------------- | ------------------------ | -------------------------------------------------------------- |
| `remoteDomain`              | `uint32`                 | The domain where the message originated from                   |
| `sender`                    | `bytes32`                | The sender of the message (remote TokenMessenger)              |
| `finalityThresholdExecuted` | `uint32`                 | Specifies the level of finality Circle signed the message with |
| `messageBody`               | `bytes` (dynamic length) | The message body bytes                                         |

### handleReceiveUnfinalizedMessage

Handles incoming message received by the local MessageTransmitter. For a burn
message, mints the associated token to the requested recipient on the local
domain. Similar to `handleReceiveFinalizedMessage`, but is called for messages
which are not finalized (`finalityThresholdExecuted` \< 2000) such as Fast
Transfers.

Unlike `handleReceiveFinalizedMessage`, `handleReceiveUnfinalizedMessage`
processes messages with:

* **`expirationBlock`**: If `expirationBlock` ≤ `blockNumber` on the destination
  domain, the message will revert and must be re-signed without the expiration
  block.
* **`feeExecuted`**: If nonzero, the `feeExecuted` amount is minted to the
  `feeRecipient`.

**Parameters**

| Field                       | Type                     | Description                                                                                  |
| --------------------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
| `remoteDomain`              | `uint32`                 | The domain where the message originated from                                                 |
| `sender`                    | `bytes32`                | The sender of the message (remote TokenMessenger)                                            |
| `finalityThresholdExecuted` | `uint32`                 | Specifies the level of finality Circle signed the message with                               |
| `messageBody`               | `bytes` (dynamic length) | The message body bytes (see [Message format](/cctp/references/technical-guide#message-body)) |

## MessageTransmitterV2

### `receiveMessage`

Receives message on destination blockchain by passing message and attestation.
Emits `MessageReceived` event. Messages with a given nonce can only be broadcast
successfully once for a pair of domains. The message body of a valid message is
passed to the specified recipient for further processing.

**Parameters**

| Field         | Type    | Description                                                                           |
| ------------- | ------- | ------------------------------------------------------------------------------------- |
| `message`     | `bytes` | Encoded message (see [Message format](/cctp/references/technical-guide#message-body)) |
| `attestation` | `bytes` | Signed attestation received from Circle's attestation service                         |

**Example**

```solidity Solidity theme={null}
// Mint USDC on destination chain
bytes memory message = attestationData.message;
bytes memory attestation = attestationData.attestation;

messageTransmitter.receiveMessage(message, attestation);
```

### `sendMessage`

Sends a message to the recipient on the destination domain. Emits a
`MessageSent` event which will be attested by Circle's attestation service.

**Parameters**

| Field                  | Type      | Description                                                                                                                                                                                |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `destinationDomain`    | `uint32`  | Destination domain ID to send the message to                                                                                                                                               |
| `recipient`            | `bytes32` | Address of recipient on destination domain                                                                                                                                                 |
| `destinationCaller`    | `bytes32` | Address as `bytes32` which can call `receiveMessage` on destination domain. If set to `bytes32(0)`, any address can call `receiveMessage`                                                  |
| `minFinalityThreshold` | `uint32`  | Minimum finality threshold requested. A value greater than 2000 is interpreted as 2000 (finalized). Thresholds: 1000 for Fast Transfer (confirmed), 2000 for Standard Transfer (finalized) |
| `messageBody`          | `bytes`   | application-specific message to be handled by recipient                                                                                                                                    |

## Events

### DepositForBurn

Emitted when USDC is burned on the source blockchain.

**Parameters**

| Field                       | Type      | Indexed | Description                                                 |
| --------------------------- | --------- | ------- | ----------------------------------------------------------- |
| `nonce`                     | `uint64`  | Yes     | Unique message identifier                                   |
| `burnToken`                 | `address` | Yes     | Address of token burned                                     |
| `amount`                    | `uint256` | No      | Burn amount                                                 |
| `depositor`                 | `address` | Yes     | Address of depositor                                        |
| `mintRecipient`             | `bytes32` | No      | Mint recipient address on destination domain                |
| `destinationDomain`         | `uint32`  | No      | Destination domain identifier                               |
| `destinationTokenMessenger` | `bytes32` | No      | Address of TokenMessenger contract on destination domain    |
| `destinationCaller`         | `bytes32` | No      | Authorized caller of `receiveMessage` on destination domain |
| `maxFee`                    | `uint256` | No      | Maximum fee for the transfer                                |
| `minFinalityThreshold`      | `uint32`  | No      | Minimum finality threshold at which burn will be attested   |

### MessageSent

Emitted when a message is sent from the source blockchain.

**Parameters**

| Field     | Type    | Indexed | Description          |
| --------- | ------- | ------- | -------------------- |
| `message` | `bytes` | No      | Raw bytes of message |

### MessageReceived

Emitted when a message is received on the destination blockchain.

**Parameters**

| Field          | Type      | Indexed | Description                                |
| -------------- | --------- | ------- | ------------------------------------------ |
| `caller`       | `address` | Yes     | Address that called `receiveMessage`       |
| `sourceDomain` | `uint32`  | Yes     | Source domain identifier                   |
| `nonce`        | `uint64`  | Yes     | Unique message identifier                  |
| `sender`       | `bytes32` | No      | Address of message sender on source domain |
| `messageBody`  | `bytes`   | No      | Message body                               |

### MintAndWithdraw

Emitted when USDC is minted on the destination blockchain.

**Parameters**

| Field           | Type      | Indexed | Description                   |
| --------------- | --------- | ------- | ----------------------------- |
| `mintRecipient` | `address` | Yes     | Address receiving minted USDC |
| `amount`        | `uint256` | No      | Amount minted                 |
| `mintToken`     | `address` | Yes     | Address of token minted       |


# CoreDepositWallet Contract Interface
Source: https://developers.circle.com/cctp/references/coredepositwallet-contract-interface



The `CoreDepositWallet` contract on HyperEVM allows you to deposit USDC from
HyperEVM to HyperCore. This topic describes the contract interface and the
available deposit functions.

<Warning>
  To move USDC from HyperEVM to HyperCore, always call one of the
  `CoreDepositWallet` deposit functions (`deposit`, `depositFor`, or
  `depositWithAuth`). Only USDC is supported.

  Sending USDC or any tokens directly to the `CoreDepositWallet` contract address
  doesn't trigger a deposit on HyperCore. The funds are permanently stuck.
</Warning>

## Deposit functions

The `CoreDepositWallet` provides three entry points for depositing USDC from
HyperEVM into HyperCore. All deposits credit a user's balance on HyperCore, on
either the perps or spot DEX.

### `deposit` function

The `deposit` function transfers USDC from the caller's address and credits the
same address on HyperCore, after the caller has approved the `CoreDepositWallet`
to spend their tokens.

**Signature:**

```solidity theme={null}
deposit(uint256 amount, uint32 destinationDex);
```

**Parameters:**

| Parameter        | Value                                                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `amount`         | The USDC amount being deposited from HyperEVM to HyperCore                                                                      |
| `destinationDex` | The HyperCore destination `dex` index. Accepted values are:<br />- `0` → default perps DEX<br />- `type(uint32).max` → spot DEX |

**Token pull:** Uses `transferFrom(msg.sender, address(this), amount)` →
requires prior ERC-20 approve from the `msg.sender` to the core deposit wallet.

**Who is credited:** The `msg.sender` of the transaction on HyperEVM is credited
on HyperCore.

**Examples:**

ERC-20 Approval:

```shell theme={null}
# approve the CoreDepositWallet to spend 100 USDC from the sender
cast send <USDC_ADDRESS> "approve(address,uint256)" <CORE_DEPOSIT_WALLET_ADDRESS> 100000000 \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC_URL
```

Depositing to the perps DEX:

```shell theme={null}
# Deposit 100 USDC to the perps DEX (destinationDex = 0)
cast send <CORE_DEPOSIT_WALLET_ADDRESS> "deposit(uint256,uint32)" 100000000 0 \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC_URL
```

Depositing to the spot DEX:

```shell theme={null}
# Deposit 100 USDC to the spot DEX (destinationDex = uint32.max)
cast send <CORE_DEPOSIT_WALLET_ADDRESS> "deposit(uint256,uint32)" 100000000 4294967295 \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC_URL
```

<Note>
  **Note:** If the destination DEX value is not supported (spot or perps), the
  deposit is credited to the sender's spot balance.
</Note>

### `depositFor` function

The `depositFor` function transfers USDC from the caller but credits a specified
recipient address on HyperCore. This allows deposits on behalf of another user.

**Signature:**

```solidity theme={null}
depositFor(address recipient, uint256 amount, uint32 destinationId);
```

**Parameters:**

| Parameter       | Value                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `recipient`     | The recipient address on HyperCore                                                                                              |
| `amount`        | The USDC amount being deposited from HyperEVM to HyperCore                                                                      |
| `destinationId` | The HyperCore destination `dex` index. Accepted values are:<br />- `0` → default perps DEX<br />- `type(uint32).max` → spot DEX |

**Token pull:** Uses `transferFrom(msg.sender, address(this), amount)` →
requires prior ERC-20 approve from the `msg.sender` to the core deposit wallet.

**Who is credited:** The recipient address passed to the function is credited on
HyperCore.

**Examples:**

ERC-20 Approval:

```shell theme={null}
# approve the CoreDepositWallet to spend 100 USDC from the sender
cast send <USDC_ADDRESS> "approve(address,uint256)" <CORE_DEPOSIT_WALLET_ADDRESS> 100000000 \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC_URL
```

Depositing to the perps DEX:

```shell theme={null}
# Deposit 100 USDC to the perps DEX (destinationDex = 0)
cast send <CORE_DEPOSIT_WALLET_ADDRESS> "depositFor(address,uint256,uint32)" <RECIPIENT_ADDRESS> 100000000 0 \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC_URL
```

Depositing to the spot DEX:

```shell theme={null}
# Deposit 100 USDC to the spot DEX (destinationDex = uint32.max)
cast send <CORE_DEPOSIT_WALLET_ADDRESS> "depositFor(address,uint256,uint32)" <RECIPIENT_ADDRESS> 100000000 4294967295 \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC_URL
```

<Note>
  **Note:** If the destination DEX value is not supported (spot or perps), the
  deposit is credited to the recipient's spot balance.
</Note>

### `depositWithAuth` function

The `depositWithAuth` function allows depositing USDC using a pre-signed
ERC-3009 authorization. This enables a deposit where the token transfer is
authorized offchain and executed onchain without requiring a prior approve call.

**Signature:**

```solidity theme={null}
depositWithAuth(uint256 amount, uint256 authValidAfter, uint256 authValidBefore, bytes32 authNonce, uint8 v, bytes32 r, bytes32 s, uint32 destinationDex);
```

**Parameters:**

* `amount`: The USDC amount being deposited from HyperEVM to HyperCore
* `authValidAfter`, `authValidBefore`, `authNonce`, `v`, `r`, `s`:
  EIP-3009-style authorization fields for `receiveWithAuthorization`
* `destinationDex`: The HyperCore destination `dex` index. Accepted values are:
  * `0` → default perps DEX
  * `type(uint32).max` → spot DEX

**Token pull:** Calls `token.receiveWithAuthorization(...)`, no prior approve
needed.

**Who is credited:** The `msg.sender` which has to match the `from` address from
the `receiveWithAuthorization` is credited on HyperCore.

**receiveWithAuthorization details:**

* **ERC:** ERC-3009
* **Function Signature:** `ReceiveWithAuthorization`
* **Parameters:**

| Parameter     | Value                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------- |
| `from`        | The payer's address (`authorizer`) has to match the `msg.sender` of the `depositWithAuth` function |
| `to`          | The `CoreDepositWallet` address (payee)                                                            |
| `value`       | The auth amount                                                                                    |
| `validAfter`  | The time after which this is valid (Unix time)                                                     |
| `validBefore` | The time before which this is valid (Unix time)                                                    |
| `nonce`       | Unique nonce                                                                                       |
| `v`           | v of the signature                                                                                 |
| `r`           | r of the signature                                                                                 |
| `s`           | s of the signature                                                                                 |

**Example:**

The example below illustrates how to generate an ERC-3009 authorization:

```javascript theme={null}
#!/usr/bin/env node

const ethers = require("ethers");
const PRIVATE_KEY = process.env.PRIVATE_KEY;
const wallet = new ethers.Wallet(PRIVATE_KEY);
const provider = new ethers.JsonRpcProvider(
  process.env.RPC_URL || "https://rpc.hyperliquid-testnet.xyz/evm",
);

const usdcAddress = "<USDC_CONTRACT_ADDRESS>";
const coreDepositWallet = "<CORE_DEPOSIT_WALLET_ADDRESS>";

const EIP712_PREFIX = "0x1901";

const amount = ethers.parseUnits("100", 6); // 100 USDC
const nonce = ethers.hexlify(ethers.randomBytes(32));
const validAfter = 0;
const validBefore = Math.floor(Date.now() / 1000) + 3600; // valid for 1 hour

// Minimal ABI for DOMAIN_SEPARATOR
const USDC_ABI = [
  {
    inputs: [],
    name: "DOMAIN_SEPARATOR",
    outputs: [{ internalType: "bytes32", name: "", type: "bytes32" }],
    stateMutability: "view",
    type: "function",
  },
];

async function getDomainSeparator(usdc) {
  try {
    return await usdc.DOMAIN_SEPARATOR();
  } catch {
    const domain = {
      name: "USD Coin",
      version: "2",
      chainId: await provider.getNetwork().then((n) => n.chainId),
      verifyingContract: await usdc.getAddress(),
    };
    return ethers.TypedDataEncoder.hashDomain(domain);
  }
}

async function main() {
  const usdc = new ethers.Contract(usdcAddress, USDC_ABI, provider);
  const domainSeparator = await getDomainSeparator(usdc);

  const structHash = ethers.keccak256(
    ethers.AbiCoder.defaultAbiCoder().encode(
      [
        "bytes32",
        "address",
        "address",
        "uint256",
        "uint256",
        "uint256",
        "bytes32",
      ],
      [
        ethers.keccak256(
          ethers.toUtf8Bytes(
            "ReceiveWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)",
          ),
        ),
        wallet.address,
        coreDepositWallet,
        amount,
        validAfter,
        validBefore,
        nonce,
      ],
    ),
  );

  const digest = ethers.keccak256(
    ethers.concat([EIP712_PREFIX, domainSeparator, structHash]),
  );
  const signer = new ethers.SigningKey(PRIVATE_KEY);
  const sig = signer.sign(digest);

  console.log("Authorization parameters:");
  console.log({
    amount: amount.toString(),
    validAfter,
    validBefore,
    nonce,
    v: sig.v,
    r: sig.r,
    s: sig.s,
  });
}

main().catch(console.error);
```

The example below illustrates how to call the `depositWithAuth` function with
the authorization data:

```shell theme={null}
cast send <CORE_DEPOSIT_WALLET_ADDRESS> \
  "depositWithAuth(uint256,uint256,uint256,bytes32,uint8,bytes32,bytes32,uint32)" \
  <AMOUNT> 0 1735660000 0x<NONCE> <V> 0x<R> 0x<S> <DEST_DEX_ID> \
  --private-key $PRIVATE_KEY \
  --rpc-url $RPC_URL
```

<Note>
  **Note:** If the destination DEX value is not supported (spot or `perp`), the
  deposit is credited to the `authorizer's` spot balance.
</Note>


# HyperCore CCTP-Enablement Contract Addresses
Source: https://developers.circle.com/cctp/references/hypercore-contract-addresses



CCTP has additional contracts beyond the standard protocol to enable transfers
to HyperCore. The following sections describe the functions and addresses of
these contracts.

* **`CctpExtension`**: (Arbitrum only) Responsible for transferring USDC from
  Arbitrum to HyperCore.
* **`CctpForwarder`**: (HyperEVM only) Responsible for forwarding USDC from
  HyperEVM to HyperCore in a CCTP transfer from any non-HyperEVM domain.
* **`CoreDepositWallet`**: (HyperEVM only) Responsible for
  [depositing USDC into HyperCore](/cctp/references/coredepositwallet-contract-interface).

This page contains the contract addresses for the HyperCore CCTP-enablement
contracts. For the contract addresses for core CCTP contracts, see
[EVM Contracts and Interfaces](/cctp/evm-smart-contracts),
[Solana Contracts and Interfaces](/cctp/solana-programs), and
[Starknet Contracts and Interfaces](/cctp/starknet-contracts).

## Mainnet contract addresses

### CctpExtension: Mainnet

| Chain        | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                                                                                                |
| ------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Arbitrum** | 3                                                                 | [`0xA95d9c1F655341597C94393fDdc30cf3c08E4fcE`](https://arbiscan.io/address/0xA95d9c1F655341597C94393fDdc30cf3c08E4fcE) |

### CctpForwarder: Mainnet

| Chain        | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                                                                                                    |
| ------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **HyperEVM** | 19                                                                | [`0xb21D281DEdb17AE5B501F6AA8256fe38C4e45757`](https://hyperevmscan.io/address/0xb21D281DEdb17AE5B501F6AA8256fe38C4e45757) |

### CoreDepositWallet: Mainnet

| Chain        | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                                                                                                    |
| ------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **HyperEVM** | 19                                                                | [`0x6B9E773128f453f5c2C60935Ee2DE2CBc5390A24`](https://hyperevmscan.io/address/0x6B9E773128f453f5c2C60935Ee2DE2CBc5390A24) |

## Testnet contract addresses

### CctpExtension: Testnet

| Chain                | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                                                                                                        |
| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Arbitrum Sepolia** | 3                                                                 | [`0x8E4e3d0E95C1bEC4F3eC7F69aa48473E0Ab6eB8D`](https://sepolia.arbiscan.io/address/0x8E4e3d0E95C1bEC4F3eC7F69aa48473E0Ab6eB8D) |

### CctpForwarder: Testnet

| Chain                | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                      |
| -------------------- | ----------------------------------------------------------------- | -------------------------------------------- |
| **HyperEVM Testnet** | 19                                                                | `0x02e39ECb8368b41bF68FF99ff351aC9864e5E2a2` |

### CoreDepositWallet: Testnet

| Chain                | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                      |
| -------------------- | ----------------------------------------------------------------- | -------------------------------------------- |
| **HyperEVM Testnet** | 19                                                                | `0x0B80659a4076E9E93C7DbE0f10675A16a3e5C206` |


# CCTP Solana Programs and Interfaces
Source: https://developers.circle.com/cctp/references/solana-programs

Programs for CCTP support on the Solana blockchain

## Overview

Solana CCTP programs are written in Rust and leverage the Anchor framework. The
Solana CCTP protocol implementation is split into two programs:
`MessageTransmitterV2` and `TokenMessengerMinterV2`. `TokenMessengerMinterV2`
encapsulates the capabilities of both `TokenMessengerV2` and `TokenMinterV2`
contracts on EVM chains. To ensure alignment with EVM contracts' logic and
state, and to facilitate upgrades and maintenance, the code and state of Solana
programs reflect the EVM counterparts as closely as possible.

### Mainnet program addresses

| Program                  | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                                                                                                   |
| :----------------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| `MessageTransmitterV2`   | 5                                                                 | [`CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC`](https://solscan.io/account/CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC) |
| `TokenMessengerMinterV2` | 5                                                                 | [`CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe`](https://solscan.io/account/CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe) |

### Devnet program addresses

| Program                  | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                                                                                                                  |
| :----------------------- | :---------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `MessageTransmitterV2`   | 5                                                                 | [`CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC`](https://solscan.io/account/CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC?cluster=devnet) |
| `TokenMessengerMinterV2` | 5                                                                 | [`CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe`](https://solscan.io/account/CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe?cluster=devnet) |

The Solana CCTP source code is
[available on GitHub](https://github.com/circlefin/solana-cctp-contracts/). The
interface below serves as a reference for permissionless messaging functions
exposed by the programs.

## CCTP interface

The interface below serves as a reference for permissionless messaging functions
exposed by the `TokenMessengerMinter` and `MessageTransmitter` programs. The
full IDLs can be found onchain using a block explorer.
[`MessageTransmitterV2` IDL](https://explorer.solana.com/address/CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe/anchor-program)
and
[`TokenMessengerMinterV2` IDL](https://explorer.solana.com/address/CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC/anchor-program).

*See the instruction rust files or quick-start for PDA information.*

### TokenMessengerMinterV2

#### [`depositForBurn`](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/v2/token-messenger-minter-v2/src/token_messenger_v2/instructions/deposit_for_burn.rs)

Deposits and burns tokens from sender to be minted on destination domain. Minted
tokens will be transferred to `mintRecipient`.

**Parameters**

| Field                  | Type     | Description                                                                                                                                                                                                                                                                     |
| :--------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `amount`               | `u64`    | Amount of tokens to deposit and burn.                                                                                                                                                                                                                                           |
| `destinationDomain`    | `u32`    | Destination domain identifier.                                                                                                                                                                                                                                                  |
| `mintRecipient`        | `Pubkey` | Public Key of token account mint recipient on destination domain. *Address should be the 32 byte version of the hex address in base58. See Additional Notes on `mintRecipient` section for more information.*                                                                   |
| `destinationCaller`    | `Pubkey` | Address which can call `receiveMessage` on destination domain. If set to `PublicKey.default`, any address can call `receiveMessage` *Address should be the 32 byte version of the hex address in base58. See Additional Notes on `mintRecipient` section for more information.* |
| `maxFee`               | `u64`    | Max fee paid for the transfer, specified in units of the burn token.                                                                                                                                                                                                            |
| `minFinalityThreshold` | `u32`    | Minimum finality threshold at which burn will be attested                                                                                                                                                                                                                       |

<Note>
  **Fees**

  A fee may be charged for standard USDC transfers. Fees for standard transfers
  are set to 0, but are subject to change. See
  [CCTP Fees](/cctp/technical-guide#cctp-fees) for more information.

  **MessageSent event storage**

  To ensure persistent and reliable message storage, MessageSent events are stored
  in accounts. MessageSent event accounts are generated client-side, passed into
  the instruction call, and assigned to have the `MessageTransmitterV2` program as
  the owner. See the
  [Quickstart Guide](/cctp/transfer-usdc-on-testnet-from-ethereum-to-avalanche)
  for how to generate this account and pass it to the instruction call.

  Message nonces are generated offchain, meaning the source messages cannot be
  identified from the attestation. Due to this, there is a 5 day window after
  sending a message that callers must wait before `reclaim_event_account` can be
  called. This is to ensure that the message has been fully processed by Circle's
  offchain services.
</Note>

#### [depositForBurnWithHook](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/v2/token-messenger-minter-v2/src/token_messenger_v2/instructions/deposit_for_burn_with_hook.rs)

Deposits and burns tokens from sender to be minted on destination domain, and
emits a crosschain message with additional hook data appended. In addition to
the standard `deposit_for_burn` parameters, `deposit_for_burn_with_hook` accepts
a dynamic-length `hookData` parameter, allowing the caller to include additional
metadata to the attested message, which can be used to trigger custom logic on
the destination chain.

**Parameters**

| Field                  | Type      | Description                                                                                                                                                                                                                                                                     |
| :--------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `amount`               | `u64`     | Amount of tokens to deposit and burn.                                                                                                                                                                                                                                           |
| `destinationDomain`    | `u32`     | Destination domain identifier.                                                                                                                                                                                                                                                  |
| `mintRecipient`        | `Pubkey`  | Public Key of token account mint recipient on destination domain. *Address should be the 32 byte version of the hex address in base58. See Additional Notes on `mintRecipient` section for more information.*                                                                   |
| `destinationCaller`    | `Pubkey`  | Address which can call `receiveMessage` on destination domain. If set to `PublicKey.default`, any address can call `receiveMessage` *Address should be the 32 byte version of the hex address in base58. See Additional Notes on `mintRecipient` section for more information.* |
| `maxFee`               | `u64`     | Max fee paid for fast burn, specified in units of the burn token.                                                                                                                                                                                                               |
| `minFinalityThreshold` | `u32`     | Minimum finality threshold at which burn will be attested                                                                                                                                                                                                                       |
| `hookData`             | `Vec<u8>` | Additional metadata attached to the attested message, which can be used to trigger custom logic on the destination chain                                                                                                                                                        |

#### [handleReceiveFinalizedMessage](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/v2/token-messenger-minter-v2/src/token_messenger_v2/instructions/handle_receive_finalized_message.rs)

Handles incoming message received by the local MessageTransmitter, and takes the
appropriate action. For a burn message, mints the associated token to the
requested recipient on the local domain. Validates the function sender is the
local MessageTransmitter, and the remote sender is a registered remote
TokenMessenger for `remoteDomain`.

Additionally, reads the `feeExecuted` parameter from the BurnMessage. If
nonzero, the `feeExecuted` amount is minted to the `feeRecipient`.

**Parameters**

| Field                       | Type                       | Description                                                  |
| --------------------------- | -------------------------- | ------------------------------------------------------------ |
| `remoteDomain`              | `u32`                      | The domain where the message originated from                 |
| `sender`                    | `Pubkey`                   | The sender of the message (remote TokenMessenger)            |
| `finalityThresholdExecuted` | `u32`                      | Specifies the level of finality Iris signed the message with |
| `messageBody`               | `Vec<u8>` (dynamic length) | The message body bytes                                       |

#### [handleReceiveUnfinalizedMessage](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/v2/token-messenger-minter-v2/src/token_messenger_v2/instructions/handle_receive_unfinalized_message.rs)

Handles incoming message received by the local MessageTransmitter, and takes the
appropriate action. For a burn message, mints the associated token to the
requested recipient on the local domain. Validates the function sender is the
local MessageTransmitter, and the remote sender is a registered remote
TokenMessenger for `remoteDomain`.

Similar to `handleReceiveFinalizedMessage`, but is called for messages which are
not finalized (`finalityThresholdExecuted` \< 2000).

Unlike `handleReceiveFinalizedMessage`, `handleReceiveUnfinalizedMessage` has
the following `messageBody` parameter:

* **`expirationBlock`**. If `expirationBlock` ≤ `blockNumber` on the destination
  domain, the message will revert and must be re-signed without the expiration
  block.

**Parameters**

| Field                       | Type                       | Description                                                                       |
| --------------------------- | -------------------------- | --------------------------------------------------------------------------------- |
| `remoteDomain`              | `u32`                      | The domain where the message originated from                                      |
| `sender`                    | `Pubkey`                   | The sender of the message (remote TokenMessenger)                                 |
| `finalityThresholdExecuted` | `u32`                      | Specifies the level of finality Iris signed the message with                      |
| `messageBody`               | `Vec<u8>` (dynamic length) | The message body bytes (see [Message format](/cctp/technical-guide#message-body)) |

### MessageTransmitterV2

#### [`receiveMessage`](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/v2/message-transmitter-v2/src/instructions/receive_message.rs)

Messages with a given nonce can only be broadcast successfully once for a pair
of domains. The message body of a valid message is passed to the specified
recipient for further processing.

**Parameters**

| Field         | Type      | Description                    |
| :------------ | :-------- | :----------------------------- |
| `message`     | `Vec<u8>` | Message bytes.                 |
| `attestation` | `Vec<u8>` | Signed attestation of message. |

**Remaining Accounts**

If the `receiveMessage` instruction is being called with a deposit for burn
message that will be received by the `TokenMessengerMinterV2`, additional
`remainingAccounts` are required so they can be passed with the CPI to
`TokenMessengerMinter#handle_receive_finalized_message` or
`TokenMessengerMinter#handle_receive_unfinalized_message`:

| Account Name                    | PDA Seeds                                             | PDA ProgramId        | `isSigner`? | `isWritable`? | Description                                                                                                                                                               |
| :------------------------------ | :---------------------------------------------------- | :------------------- | :---------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `token_messenger`               | `["token_messenger"]`                                 | tokenMessengerMinter | false       | false         | TokenMessenger Program Account                                                                                                                                            |
| `remote_token_messenger`        | `["remote_token_messenger", sourceDomainId]`          | tokenMessengerMinter | false       | false         | Remote token messenger account where the remote token messenger address is stored for the given source domain id                                                          |
| `token_minter`                  | `["token_minter"]`                                    | tokenMessengerMinter | false       | true          | TokenMinter Program Account                                                                                                                                               |
| `local_token`                   | `["local_token", localTokenMint.publicKey]`           | tokenMessengerMinter | false       | true          | Local token account where the information for the local token (for example, USDCSOL) being minted is stored                                                               |
| `token_pair`                    | `["token_pair", sourceDomainId, sourceTokenInBase58]` | tokenMessengerMinter | false       | false         | Token pair account where the info for the local and remote tokens are stored. `sourceTokenInBase58` is the remote token that was burned and converted into base58 format. |
| `user_token_account`            | N/A                                                   | N/A                  | false       | true          | User token account that will receive the minted tokens. This address **must** match the `mintRecipient` from the source chain `depositForBurn` call.                      |
| `custody_token_account`         | `["custody", localTokenMint.publicKey]`               | tokenMessengerMinter | false       | true          | Custody account that holds the pre-minted USDCSOL that can be minted for CCTP usage.                                                                                      |
| `SPL.token_program_id`          | N/A                                                   | N/A                  | false       | false         | The native SPL token program ID.                                                                                                                                          |
| `token_program_event_authority` | `["__event_authority"]`                               | tokenMessengerMinter | false       | false         | Event authority account for the TokenMessengerMinter program. Needed to emit Anchor CPI events.                                                                           |
| `program`                       | N/A                                                   | N/A                  | false       | false         | Program id for the TokenMessengerMinter program.                                                                                                                          |

#### [`sendMessage`](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/v2/message-transmitter-v2/src/instructions/send_message.rs)

Sends a message to the destination domain and recipient. Stores message in a
`MessageSent` account which will be attested by Circle's attestation service.

**Parameters**

| Field               | Type      | Description                                           |
| :------------------ | :-------- | :---------------------------------------------------- |
| `destinationDomain` | `u32`     | Destination domain identifier.                        |
| `recipient`         | `Pubkey`  | Address to handle message body on destination domain. |
| `messageBody`       | `Vec<u8>` | App-specific message to be handled by recipient.      |

## Additional Notes

These notes are applicable to all CCTP versions.

### Mint Recipient for Solana as Destination Chain Transfers

When calling `depositForBurn` on a non-Solana chain with Solana as the
destination, the `mintRecipient` should be a **hex encoded USDC token account
address**. The token account\* must exist at the time `receiveMessage` is called
on Solana\* or else this instruction will revert. An example of converting an
address from Base58 to hex taken from the Solana quickstart tutorial in
TypeScript can be seen below:

```typescript TypeScript theme={null}
import { bs58 } from "@coral-xyz/anchor/dist/cjs/utils/bytes";
import { hexlify } from "ethers";

const solanaAddressToHex = (solanaAddress: string): string =>
  hexlify(bs58.decode(solanaAddress));
```

### Mint Recipient for Solana as Source Chain Transfers

When specifying the `mintRecipient` for Solana `deposit_for_burn` instruction
calls, the address must be given as the 32 byte version of the hex address in
base58 format. An example taken from the Solana quickstart tutorial in
TypeScript can be seen below:

```typescript TypeScript theme={null}
import { getBytes } from "ethers";
import { PublicKey } from "@solana/web3.js";

const evmAddressToBytes32 = (address: string): string =>
  `0x000000000000000000000000${address.replace("0x", "")}`;

const evmAddressToBase58PublicKey = (addressHex: string): PublicKey =>
  new PublicKey(getBytes(evmAddressToBytes32(addressHex)));
```

### Program Events

Program events like
[DepositForBurn](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/events.rs#L35-L45)
,
[MintAndWithdraw](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/events.rs#L47-L52)
, and
[MessageReceived](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/events.rs#L47-L52)
are emitted as Anchor CPI events. This means a self-CPI is made into the program
with the serialized event as instruction data so it is persisted in the
transaction and can be fetched later on as needed. More information can be seen
in the
[Anchor implementation PR](https://github.com/coral-xyz/anchor/pull/2438), and
an example of reading CPI events can be seen in the
[`solana-cctp-contracts` repository](https://github.com/circlefin/solana-cctp-contracts/blob/master/tests/utils.ts#L62-L111).

[MessageSent](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/events.rs#L49-L55)
events are different, as they are stored in accounts. See the
[MessageSent Event Storage section](#depositforburn) for more info.


# CCTP Starknet Contracts and Interfaces
Source: https://developers.circle.com/cctp/references/starknet-contracts

Contracts for CCTP support on the Starknet blockchain

## Overview

Starknet CCTP contracts are written in Cairo and run on a non-EVM zk-rollup.
Transactions executed on Starknet are batched and proven using STARK proofs,
which are then posted to Ethereum L1. This design allows Starknet to inherit
Ethereum's security while offering higher throughput and lower fees.

To align with Starknet's architecture while keeping parity with EVM chains, CCTP
uses two contracts:

* `TokenMessengerMinterV2`: consolidates the responsibilities of
  `TokenMessengerV2` (burn + send) and `TokenMinterV2` (receive + mint).
* `MessageTransmitterV2`: provides the messaging layer that emits or receives
  attested messages and delivers them to `TokenMessengerMinterV2`.

This mirrors how other non-EVM deployments (for example, Solana) combine
messenger and minter logic while preserving behavior with the EVM equivalents.

## Mainnet contract addresses

| Contract                 | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                                                                                                                                                    |
| :----------------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TokenMessengerMinterV2` | 25                                                                | [`0x07d421B9cA8aA32DF259965cDA8ACb93F7599F69209A41872AE84638B2A20F2a`](https://voyager.online/contract/0x07d421B9cA8aA32DF259965cDA8ACb93F7599F69209A41872AE84638B2A20F2a) |
| `MessageTransmitterV2`   | 25                                                                | [`0x02EBB5777B6dD8B26ea11D68Fdf1D2c85cD2099335328Be845a28c77A8AEf183`](https://voyager.online/contract/0x02EBB5777B6dD8B26ea11D68Fdf1D2c85cD2099335328Be845a28c77A8AEf183) |

## Testnet contract addresses

| Contract                 | [Domain](/cctp/cctp-supported-blockchains#cctp-supported-domains) | Address                                                                                                                                                                            |
| :----------------------- | :---------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TokenMessengerMinterV2` | 25                                                                | [`0x04bDdE1E09a4B09a2F95d893D94a967b7717eB85A3f6dEcA8c080Ee01fBc3370`](https://sepolia.voyager.online/contract/0x04bDdE1E09a4B09a2F95d893D94a967b7717eB85A3f6dEcA8c080Ee01fBc3370) |
| `MessageTransmitterV2`   | 25                                                                | [`0x04db7926C64f1f32a840F3Fa95cB551f3801a3600Bae87aF87807A54DCE12Fe8`](https://sepolia.voyager.online/contract/0x04db7926C64f1f32a840F3Fa95cB551f3801a3600Bae87aF87807A54DCE12Fe8) |

## CCTP interface

* `TokenMessengerMinterV2`: initiates crosschain burns and mints tokens upon
  attested message receipt.
* `MessageTransmitterV2`: emits messages, verifies attestations, and routes
  verified messages to the recipient contract.

### TokenMessengerMinterV2 interface

The `TokenMessengerMinterV2` contract consolidates the roles of both
`TokenMessengerV2` and `TokenMinterV2` found on EVM chains. It handles USDC
burns, message emission, and token minting once crosschain messages are attested
by Circle's Iris service.

| Function                             | Description                                                              | Notes                                     |
| :----------------------------------- | :----------------------------------------------------------------------- | :---------------------------------------- |
| `deposit_for_burn`                   | Burns USDC and emits a crosschain message for minting on another domain. | Standard CCTP transfer initiation.        |
| `deposit_for_burn_with_hook`         | Same as `deposit_for_burn`, but attaches custom metadata (`hook_data`).  | Used for programmable transfers.          |
| `handle_receive_finalized_message`   | Mints USDC upon receiving a fully finalized message.                     | Called by `MessageTransmitterV2`.         |
| `handle_receive_unfinalized_message` | Processes partially finalized (“Fast Burn”) messages.                    | Enables faster crosschain transfers.      |
| `message_body_version`               | Returns supported message format version.                                | Used for compatibility checks.            |
| `local_message_transmitter`          | Returns the linked `MessageTransmitterV2` address.                       | Must match configured domain transmitter. |

### MessageTransmitterV2 interface

The `MessageTransmitterV2` contract provides the core messaging layer for CCTP
on Starknet. It is responsible for emitting, receiving, and validating
crosschain messages, enforcing attestation rules, and ensuring message
uniqueness.

| Function                    | Description                                                                      | Notes                                                                                              |
| :-------------------------- | :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
| `send_message`              | Sends a crosschain message with specified domain, recipient, and message body.   | Core function for outgoing CCTP messages.                                                          |
| `receive_message`           | Validates a message and its attestation; delivers message body to the recipient. | Called by an offchain forwarding service with an attestation from Circle to complete the transfer. |
| `get_max_message_body_size` | Returns the maximum allowed message size.                                        | Used by offchain components for validation.                                                        |
| `is_nonce_used`             | Checks if a message nonce has been processed already.                            | Prevents message replay.                                                                           |
| `get_local_domain`          | Returns this contract's domain ID.                                               | Expected to be 25 for Starknet.                                                                    |
| `get_version`               | Returns protocol version supported by this transmitter.                          | Used by Iris attestation service.                                                                  |


# CCTP on Stellar
Source: https://developers.circle.com/cctp/references/stellar

Learn how to send funds to Stellar addresses and how CCTP handles Stellar USDC.

CCTP on Stellar has two behaviors you must account for when integrating: a
32-byte address format that does not distinguish accounts from contracts, and a
seven-decimal USDC precision that differs from other CCTP supported blockchains.
See [CCTP Stellar Contracts and Interfaces](/cctp/references/stellar-contracts)
for the contract addresses and interfaces.

<Warning>
  Always
  [use `CctpForwarder`](/cctp/references/stellar#use-cctpforwarder-for-stellar-recipients)
  when routing CCTP USDC to a Stellar address. Set both `mintRecipient` and
  `destinationCaller` to the `CctpForwarder`
  [contract address](/cctp/references/stellar-contracts).

  * If `destinationCaller` is wrong, the forwarder cannot complete the transfer.
  * If `mintRecipient` is set to a user account or muxed address, USDC is not sent
    to the forwarder.

  In either case, funds become permanently stuck and **cannot be recovered**.
</Warning>

## Stellar address types

On Stellar, addresses are `strkey` strings composed of a type identifier and a
32-byte payload. The type identifier determines the account type: user accounts
(`G`) carry an Ed25519 public key, contracts (`C`) carry a contract ID hash.
Muxed accounts (`M`) are a type of `G` account that additionally embeds a
numeric identifier alongside the Ed25519 public key (see Stellar's
[muxed accounts documentation](https://developers.stellar.org/docs/build/guides/transactions/pooled-accounts-muxed-accounts-memos#muxed-accounts)).

CCTP messages store only the raw 32-byte payload without the type identifier, so
the protocol cannot distinguish between address types and assumes the
`mintRecipient` is always a contract. Use `CctpForwarder` when transferring to
Stellar to ensure funds are forwarded to the intended recipient.

## Use `CctpForwarder` for Stellar recipients

`CctpForwarder` is a publicly callable onchain contract that receives minted
USDC on Stellar and atomically forwards it to `forwardRecipient`. Encode
`forwardRecipient` in hook data as a Stellar `strkey`. The prefix `G`, `M`, or
`C` identifies the recipient address type.

<Warning>
  On the source burn, both `mintRecipient` and `destinationCaller` must be set to
  the `CctpForwarder` [contract address](/cctp/references/stellar-contracts).

  * If `destinationCaller` is wrong, the forwarder cannot complete the transfer.
  * If `mintRecipient` is set to a user account or muxed address, USDC is not sent
    to the forwarder.

  In either case, funds become permanently stuck and **cannot be recovered**.
</Warning>

### How it works

Call `mint_and_forward` on `CctpForwarder` through the Stellar Soroban client
for your language. Pass the raw CCTP message and attestation bytes.

The following shows the onchain contract interface. It is not a TypeScript or
JavaScript function you call directly. Your Soroban client builds an
`invokeHostFunction` operation from these arguments.

```text theme={null}
mint_and_forward(message: Bytes, attestation: Bytes)
```

For TypeScript,
[`@stellar/stellar-sdk`](https://github.com/stellar/js-stellar-sdk) documents
how to encode arguments and how to simulate, sign, and submit transactions
against [Stellar RPC](https://developers.stellar.org/docs/data/rpc).

Inside `mint_and_forward`, `CctpForwarder` does the following:

1. Validates the message.
2. Extracts `forwardRecipient` from hook data.
3. Calls `receive_message` on `MessageTransmitter`, which mints USDC to
   `CctpForwarder`.
4. Transfers the minted USDC to `forwardRecipient`.
5. Runs atomically. Any failure reverts the invocation.

<Note>
  The `CctpForwarder` flow is non-custodial. The mint and the payout to
  `forwardRecipient` both run onchain in that single Soroban invocation. Circle
  does not take custody of the minted balance in between.
</Note>

### Hook format

The hook data begins with the reserved magic bytes, followed by versioning and
payload fields. On Stellar, bytes 28 onward carry the length of
`forwardRecipient`, the `forwardRecipient` `strkey`, and any optional trailing
bytes for integrator use.

| Bytes          | Type      | Data                                                |
| -------------- | --------- | --------------------------------------------------- |
| 0-23           | `bytes24` | Magic. Circle-reserved bytes; use all zero bytes    |
| 24-27          | `uint32`  | Version; set to `0`                                 |
| 28-31          | `uint32`  | `L`: length of `forwardRecipient` in bytes          |
| `32..(32+L-1)` | `bytes`   | `forwardRecipient` as a `strkey`                    |
| `(32+L)..`     | `bytes`   | Optional integrator-defined payload; omit if unused |

#### Building forwarder hook data (example)

The following helper functions validate Stellar contract `strkey` inputs and
build the `hookData` payload for an EVM `depositForBurnWithHook` call:

```ts TypeScript theme={null}
import { StrKey } from "@stellar/stellar-sdk";

/**
 * Validates that the input is a Stellar contract address (C…) and decodes it
 * to a 0x-prefixed bytes32 hex string suitable for EVM contract calls.
 *
 * @param strkey - Stellar contract address (C…)
 * @returns 0x-prefixed 64-character hex string
 * @throws If the input is not a valid contract address
 */
function contractStrkeyToBytes32(strkey: string): `0x${string}` {
  if (!StrKey.isValidContract(strkey)) {
    throw new Error(`Invalid contract strkey: ${strkey}`);
  }
  return `0x${Buffer.from(StrKey.decodeContract(strkey)).toString("hex")}`;
}

/**
 * Builds the hookData buffer for a CCTP Forwarder burn message.
 *
 * Hook data layout:
 *   bytes  0–23: reserved (zeroed)
 *   bytes 24–27: hook data version (u32 BE, currently 0)
 *   bytes 28–31: forward_recipient byte length (u32 BE)
 *   bytes 32+  : forward_recipient (UTF-8 encoded Stellar strkey)
 *
 * @param forwardRecipientStrkey - Stellar strkey of the final token recipient (C…, G…, or M…)
 * @returns Hook data as a 0x-prefixed hex string
 */
function buildCctpForwarderHookData(
  forwardRecipientStrkey: string,
): `0x${string}` {
  const isValid =
    StrKey.isValidEd25519PublicKey(forwardRecipientStrkey) ||
    StrKey.isValidContract(forwardRecipientStrkey) ||
    StrKey.isValidMed25519PublicKey(forwardRecipientStrkey);
  if (!isValid) {
    throw new Error(
      `Invalid forward recipient: ${forwardRecipientStrkey} (expected G..., C..., or M... address)`,
    );
  }

  const recipientBytes = Buffer.from(forwardRecipientStrkey, "utf8");
  const hookData = Buffer.alloc(32 + recipientBytes.length);
  hookData.writeUInt32BE(0, 24); // hook version = 0
  hookData.writeUInt32BE(recipientBytes.length, 28); // recipient byte length
  recipientBytes.copy(hookData, 32); // recipient strkey as UTF-8
  return `0x${hookData.toString("hex")}`;
}

interface DepositForBurnWithHookParams {
  amount: bigint;
  destinationDomain: number;
  mintRecipient: `0x${string}`;
  burnToken: `0x${string}`;
  destinationCaller: `0x${string}`;
  maxFee: bigint;
  minFinalityThreshold: number;
  hookData: `0x${string}`;
}

/**
 * Prepares all arguments for an EVM `depositForBurnWithHook` call targeting
 * Stellar via the CCTP Forwarder. Converts Stellar strkeys to 0x-prefixed
 * bytes32 hex strings and encodes the hook data.
 *
 * @param amount - Token amount to burn (in EVM token decimals)
 * @param cctpForwarderStrkey - Stellar strkey of the CCTP Forwarder contract (C…), used as mintRecipient and destinationCaller
 * @param burnToken - EVM address of the token to burn
 * @param maxFee - Maximum fee for the burn
 * @param minFinalityThreshold - Minimum finality threshold (1000 = fast, 2000 = standard)
 * @param forwardRecipientStrkey - Stellar strkey of the final token recipient (C…, G…, or M…), encoded in hookData
 */
function prepareEvmDepositForBurnWithHookToStellar(
  amount: bigint,
  cctpForwarderStrkey: string,
  burnToken: `0x${string}`,
  maxFee: bigint,
  minFinalityThreshold: number,
  forwardRecipientStrkey: string,
): DepositForBurnWithHookParams {
  const cctpForwarderHex = contractStrkeyToBytes32(cctpForwarderStrkey);
  const hookData = buildCctpForwarderHookData(forwardRecipientStrkey);

  return {
    amount,
    destinationDomain: 27,
    mintRecipient: cctpForwarderHex,
    burnToken,
    destinationCaller: cctpForwarderHex,
    maxFee,
    minFinalityThreshold,
    hookData,
  };
}
```

## Stellar addresses in CCTP messages and API responses

[Stellar addresses](#stellar-address-types) are `strkey` strings. CCTP message
fields store only 32-byte address payloads. They omit the `strkey` encoding,
including the `G`, `M`, or `C` type marker, so the raw bytes in the message do
not say whether the address is an account or a contract. `mintRecipient` is
always assumed to be a contract address. You must
[use `CctpForwarder`](#use-cctpforwarder-for-stellar-recipients) to make
transfers to Stellar.

### CCTP message fields

The following tables describe each address field in the CCTP message, explain
how Stellar uses it during a mint (inbound) or burn (outbound), and indicate
whether you need to design around the address type. For the full message layout,
see the [CCTP Technical Guide](/cctp/references/technical-guide#message-format).

#### Inbound transfers to Stellar destination

| Field               | Operation                                                                   | Must design around address type?                                                                                              |
| ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `sender`            | Validate against the source domain `TokenMessenger` mapping.                | No                                                                                                                            |
| `recipient`         | Select the Stellar contract that handles the destination `receive_message`. | No, always a contract (`C`)                                                                                                   |
| `destinationCaller` | Restrict who may call `receive_message` (`require_auth` compares bytes).    | No, compare raw bytes                                                                                                         |
| `burnToken`         | Map the burned token identifier to Stellar USDC.                            | No, known asset contract                                                                                                      |
| `messageSender`     | Not used operationally on Stellar.                                          | No                                                                                                                            |
| `mintRecipient`     | Mint USDC to this 32-byte destination on Stellar.                           | Yes, always assumed to be a contract; [use `CctpForwarder` for Stellar recipients](#use-cctpforwarder-for-stellar-recipients) |

#### Outbound transfers from Stellar source

| Field               | Operation                                                                                 | Must design around address type? |
| ------------------- | ----------------------------------------------------------------------------------------- | -------------------------------- |
| `sender`            | 32 byte address payload of the Stellar `TokenMessengerMinterV2` used to perform the burn. | No                               |
| `burnToken`         | Identify the Stellar USDC contract that is burned.                                        | No                               |
| `mintRecipient`     | Encode the recipient on the destination blockchain.                                       | No                               |
| `messageSender`     | Record caller context (not used operationally on Stellar).                                | No                               |
| `destinationCaller` | Encode which address may call receive on the destination blockchain.                      | No                               |
| `recipient`         | Encode the handler contract on the destination blockchain.                                | No                               |

### Null address fields in API responses

When a CCTP message involves Stellar, the
[Get messages](/api-reference/cctp/all/get-messages-v2) endpoint returns all
address fields in `decodedMessage` and `decodedMessageBody` as `null` because
the API cannot distinguish a 32-byte Stellar account from a contract. To read
those addresses, parse the raw hex in the `message` field directly.

The following example shows an Ethereum-to-Stellar transfer response with
typical `null` address fields:

```json JSON theme={null}
{
  "messages": [
    {
      "message": "0x...",
      "eventNonce": "0",
      "attestation": "0x...",
      "cctpVersion": 2,
      "status": "complete",
      "decodedMessage": {
        "sourceDomain": "0",
        "destinationDomain": "27",
        "nonce": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "sender": null,
        "recipient": null,
        "destinationCaller": null,
        "minFinalityThreshold": "1000",
        "finalityThresholdExecuted": "2000",
        "messageBody": "0x...",
        "decodedMessageBody": {
          "burnToken": null,
          "mintRecipient": null,
          "amount": "1000000",
          "messageSender": null,
          "maxFee": "0",
          "feeExecuted": "0",
          "expirationBlock": "0",
          "hookData": null
        }
      }
    }
  ]
}
```

## USDC precision for CCTP and Stellar

Stellar represents USDC in seven-decimal subunits while other CCTP-supported
blockchains use six. How CCTP handles that difference depends on whether Stellar
is the source or destination blockchain. Regardless of direction, the `amount`
field in a CCTP message is always in six-decimal subunits.

<Note>
  Stellar wallets and SDKs often display seven fractional digits. Use six-decimal
  subunits in `amount` when handling CCTP messages offchain.
</Note>

### Stellar as the source

When Stellar is the source blockchain, the burn debits only through the sixth
decimal digit of the user's balance. Anything in the seventh decimal place stays
in the user's account.

1. A user bridges **0.1234567 USDC** from Stellar to the destination blockchain.
2. Stellar burns **0.1234560 USDC**.
3. **0.0000007 USDC** stays in the user's Stellar account.
4. The CCTP message `amount` is **123456** (six-decimal subunits).
5. The destination blockchain mints **0.123456 USDC** to the recipient.

### Stellar as the destination

When Stellar is the destination blockchain, the mint converts the six-decimal
message `amount` into seven by scaling the integer by 10 (for example, `123456`
becomes `1234560` seven-decimal subunits).

1. A user bridges **0.123456 USDC** from the source blockchain to Stellar.
2. The CCTP message `amount` is **123456** (six-decimal subunits).
3. Stellar mints **0.1234560 USDC** to the recipient.


# CCTP Stellar Contracts and Interfaces
Source: https://developers.circle.com/cctp/references/stellar-contracts

Contracts for CCTP support on the Stellar network

## Overview

Stellar CCTP contracts run on Soroban, Stellar's smart contracts platform. CCTP
message fields use 32-byte address encodings. CCTP treats `mintRecipient` as a
contract address. If the recipient is a Stellar user or
[muxed](https://developers.stellar.org/docs/build/guides/transactions/pooled-accounts-muxed-accounts-memos#muxed-accounts)
account instead, hook data can carry a `forwardRecipient` `strkey` so the
forwarder can send funds to that address.

To align with Stellar address encoding while keeping parity with EVM and other
non-EVM blockchains, CCTP uses three contracts:

* `TokenMessengerMinter`: consolidates the responsibilities of
  `TokenMessengerV2` (burn + send) and `TokenMinterV2` (receive + mint). On
  mint, `mintRecipient` is treated as a contract address and hooks supply the
  `forwardRecipient` when needed.
* `MessageTransmitter`: provides the messaging layer that emits or receives
  attested messages and delivers them to `TokenMessengerMinter` (including
  `receive_message` for forwarder flows).
* `CctpForwarder`: receives minted USDC and forwards it to `forwardRecipient` in
  hook data.

## Mainnet contract addresses

| Contract               | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                                                |
| :--------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TokenMessengerMinter` | 27                                                                       | [`CAE2G5Z77UP7GYPYGFOWFGW7C7J6I4YP2AFGSADRKQY62SYUFLPNFTXL`](https://stellar.expert/explorer/public/contract/CAE2G5Z77UP7GYPYGFOWFGW7C7J6I4YP2AFGSADRKQY62SYUFLPNFTXL) |
| `MessageTransmitter`   | 27                                                                       | [`CACMENFFJPJMSDAJQLX4R7K3SFZIW2LJSE3R2UMLGSWHFHS353FVXAZV`](https://stellar.expert/explorer/public/contract/CACMENFFJPJMSDAJQLX4R7K3SFZIW2LJSE3R2UMLGSWHFHS353FVXAZV) |
| `CctpForwarder`        | 27                                                                       | [`CBZL2IH7F6BIDAA3WBNXYKIXSATJGMSW7K5P5MJ6STX5RXN47TZJDF5T`](https://stellar.expert/explorer/public/contract/CBZL2IH7F6BIDAA3WBNXYKIXSATJGMSW7K5P5MJ6STX5RXN47TZJDF5T) |

## Testnet contract addresses

| Contract               | [Domain](/cctp/concepts/supported-chains-and-domains#domain-identifiers) | Address                                                                                                                                                                 |
| :--------------------- | :----------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TokenMessengerMinter` | 27                                                                       | [`CDNG7HXAPBWICI2E3AUBP3YZWZELJLYSB6F5CC7WLDTLTHVM74SLRTHP`](https://stellar.expert/explorer/testnet/contract/CDNG7HXAPBWICI2E3AUBP3YZWZELJLYSB6F5CC7WLDTLTHVM74SLRTHP) |
| `MessageTransmitter`   | 27                                                                       | [`CBJ6MTCKKZG73PMDZCJMSFRD7DQEMI4FKDH7CGDSV4W6FHCRBCQAVVJY`](https://stellar.expert/explorer/testnet/contract/CBJ6MTCKKZG73PMDZCJMSFRD7DQEMI4FKDH7CGDSV4W6FHCRBCQAVVJY) |
| `CctpForwarder`        | 27                                                                       | [`CA66Q2WFBND6V4UEB7RD4SAXSVIWMD6RA4X3U32ELVFGXV5PJK4T4VSZ`](https://stellar.expert/explorer/testnet/contract/CA66Q2WFBND6V4UEB7RD4SAXSVIWMD6RA4X3U32ELVFGXV5PJK4T4VSZ) |

## CCTP interface

* `TokenMessengerMinter`: initiates crosschain burns and mints tokens upon
  attested message receipt.
* `MessageTransmitter`: emits messages, verifies attestations, and routes
  verified messages to the recipient contract.
* `CctpForwarder`: completes mint and forward in one transaction when hook data
  supplies a `forwardRecipient` `strkey`.

### TokenMessengerMinter interface

The `TokenMessengerMinter` contract consolidates the roles of both
`TokenMessengerV2` and `TokenMinterV2` found on EVM chains. It handles USDC
burns, message emission, and token minting once crosschain messages are attested
by Circle's Iris service. On Stellar it assumes `mintRecipient` is a contract.
Account recipients use `CctpForwarder` and hook-qualified `forwardRecipient`
bytes.

| Function                             | Description                                                              | Notes                                                   |
| :----------------------------------- | :----------------------------------------------------------------------- | :------------------------------------------------------ |
| `deposit_for_burn`                   | Burns USDC and emits a crosschain message for minting on another domain. | Standard CCTP transfer initiation.                      |
| `deposit_for_burn_with_hook`         | Same as `deposit_for_burn`, but attaches custom metadata (`hook_data`).  | Used for programmable transfers and Stellar forwarding. |
| `handle_receive_finalized_message`   | Mints USDC upon receiving a fully finalized message.                     | Called by `MessageTransmitter`.                         |
| `handle_receive_unfinalized_message` | Processes partially finalized ("Fast Burn") messages.                    | Enables faster crosschain transfers.                    |
| `message_body_version`               | Returns supported message format version.                                | Used for compatibility checks.                          |
| `local_message_transmitter`          | Returns the linked `MessageTransmitter` address.                         | Must match configured domain transmitter.               |

### MessageTransmitter interface

The `MessageTransmitter` contract provides the core messaging layer for CCTP on
Stellar. It is responsible for emitting, receiving, and validating crosschain
messages, enforcing attestation rules, and ensuring message uniqueness.

| Function                    | Description                                                                      | Notes                                                                                                                   |
| :-------------------------- | :------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
| `send_message`              | Sends a crosschain message with specified domain, recipient, and message body.   | Core function for outgoing CCTP messages.                                                                               |
| `receive_message`           | Validates a message and its attestation; delivers message body to the recipient. | Called by an offchain forwarding service (or by `CctpForwarder` in the forwarder flow) with an attestation from Circle. |
| `get_max_message_body_size` | Returns the maximum allowed message size.                                        | Used by offchain components for validation.                                                                             |
| `is_nonce_used`             | Checks if a message nonce has been processed already.                            | Prevents message replay.                                                                                                |
| `get_local_domain`          | Returns this contract's domain ID.                                               | Expected to be 27 for Stellar.                                                                                          |
| `get_version`               | Returns protocol version supported by this transmitter.                          | Used by Iris attestation service.                                                                                       |

### CctpForwarder interface

The `CctpForwarder` contract calls `receive_message` on `MessageTransmitter`,
takes the mint, and transfers USDC to `forwardRecipient` parsed from
`hook_data`. See [Hook format](/cctp/references/stellar#hook-format) for
details.

| Function                                               | Description                                                                                                                             | Notes                        |
| :----------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- |
| `mint_and_forward(message: Bytes, attestation: Bytes)` | Verifies message and attestation. Runs `receive_message` so USDC mints to `CctpForwarder`. Sends USDC to `forwardRecipient` from hooks. | Atomic, any failure reverts. |

<Note>
  The `CctpForwarder` flow is non-custodial. `mint_and_forward` mints to this
  contract and pays `forwardRecipient` in one atomic Soroban invocation. Circle
  does not take custody of the minted balance in between.
</Note>


# CCTP Technical Guide
Source: https://developers.circle.com/cctp/references/technical-guide

Technical explainer for CCTP

## Message passing

Cross-Chain Transfer Protocol (CCTP) uses generalized message passing to
facilitate the native burning and minting of USDC across supported blockchains,
also known as
[domains](/cctp/cctp-supported-blockchains#cctp-supported-domains). Message
passing is a three-step process:

1. An onchain component on the source domain emits a message.
2. Circle's offchain attestation service signs the message.
3. The onchain component at the destination domain receives the message, and
   forwards the message body to the specified recipient.

Onchain components serve the same purpose across all domains, but their
implementations differ between EVM-compatible and non-EVM domains. Moreover,
there are both implementation and naming differences between CCTP V2 and
previous versions due to the addition of Fast Transfer and other improvements.

### For EVM chains

The relationship between CCTP's onchain components and Circle's offchain
Attestation Service is illustrated below for a burn-and-mint of USDC between
EVM-compatible domains:

<Frame>
  <img />
</Frame>

On EVM domains, the onchain component for crosschain burning and minting is
called **TokenMessengerV2**, which is built on top of **MessageTransmitterV2**,
an onchain component for generalized message passing.

In the diagram, a token depositor calls the
[TokenMessengerV2#depositForBurn](https://github.com/circlefin/evm-cctp-contracts/blob/63ab1f0ac06ce0793c0bbfbb8d09816bc211386d/src/v2/TokenMessengerV2.sol#L158)
function to deposit a native token (such as USDC), which delegates to the
TokenMinterV2 contract to burn the token. The **TokenMessengerV2** contract then
sends a message via the
[MessageTransmitterV2#sendMessage](https://github.com/circlefin/evm-cctp-contracts/blob/63ab1f0ac06ce0793c0bbfbb8d09816bc211386d/src/v2/MessageTransmitterV2.sol#L143)
function. After
[sufficient block confirmations](/cctp/required-block-confirmations), Circle's
offchain attestation service, Iris, signs the message. An API consumer must
query this attestation and submits it onchain to the destination domain's
[MessageTransmitterV2#receiveMessage](https://github.com/circlefin/evm-cctp-contracts/blob/63ab1f0ac06ce0793c0bbfbb8d09816bc211386d/src/v2/MessageTransmitterV2.sol#L206)
function.

To send an arbitrary message, directly call
[MessageTransmitterV2#sendMessage](https://github.com/circlefin/evm-cctp-contracts/blob/63ab1f0ac06ce0793c0bbfbb8d09816bc211386d/src/v2/MessageTransmitterV2.sol#L143).
The message recipient must implement the following methods to handle messages
based on their finality threshold:

* Implement
  [IMessageHandlerV2#handleReceiveFinalizedMessage](https://github.com/circlefin/evm-cctp-contracts/blob/63ab1f0ac06ce0793c0bbfbb8d09816bc211386d/src/interfaces/v2/IMessageHandlerV2.sol#L35)
  to receive messages with `finalityThresholdExecuted` ≥ 2000.
* Implement
  [IMessageHandlerV2#handleReceiveUnfinalizedMessage](https://github.com/circlefin/evm-cctp-contracts/blob/63ab1f0ac06ce0793c0bbfbb8d09816bc211386d/src/interfaces/v2/IMessageHandlerV2.sol#L51)
  to receive messages with `finalityThresholdExecuted` \< 2000.

This distinction allows the recipient to control the level of finality it
requires before accepting a message.

### For non-EVM chains

CCTP is also available on several non-EVM blockchains where USDC is natively
issued, extending crosschain capabilities to the broader ecosystem.

<Note>
  On Stellar, USDC precision and address encoding differ from other CCTP-supported
  blockchains. For inbound transfers, use
  [`CctpForwarder`](/cctp/references/stellar#use-cctpforwarder-for-stellar-recipients)
  so funds reach the correct recipient. See
  [CCTP on Stellar](/cctp/references/stellar).
</Note>

## Message format

### Message header

The top-level message header format is standard for all messages passing through
CCTP.

| Field                       | Offset | Solidity Type | Length (bytes) | Description                                                                                                                   |
| --------------------------- | ------ | ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `version`                   | 0      | `uint32`      | 4              | Version identifier - use 1 for CCTP                                                                                           |
| `sourceDomain`              | 4      | `uint32`      | 4              | Source domain ID                                                                                                              |
| `destinationDomain`         | 8      | `uint32`      | 4              | Destination domain ID                                                                                                         |
| `nonce`                     | 12     | `bytes32`     | 32             | Unique message nonce (see [CCTP V2 Nonces](#cctp-v2-nonces))                                                                  |
| `sender`                    | 44     | `bytes32`     | 32             | Address of MessageTransmitterV2 caller on source domain                                                                       |
| `recipient`                 | 76     | `bytes32`     | 32             | Address to handle message body on destination domain                                                                          |
| `destinationCaller`         | 108    | `bytes32`     | 32             | Address permitted to call MessageTransmitterV2 on destination domain, or bytes32(0) if message can be received by any address |
| `minFinalityThreshold`      | 140    | `uint32`      | 4              | Minimum finality threshold before allowed to attest (see [CCTP V2 Finality Thresholds](#cctp-v2-finality-thresholds))         |
| `finalityThresholdExecuted` | 144    | `uint32`      | 4              | Actual finality threshold executed from source chain (see [CCTP V2 Finality Thresholds](#cctp-v2-finality-thresholds))        |
| `messageBody`               | 148    | `bytes`       | dynamic        | App-specific message to be handled by recipient                                                                               |

#### Nonces

A CCTP nonce is a unique identifier for a message that can only be used once on
the destination domain. Circle assigns CCTP nonces offchain. The nonce for each
message in a transaction can be queried through the
[`GET /v2/messages`](/api-reference/cctp/all/get-messages-v2) endpoint, using
the transaction hash as a query parameter.

<Note>
  **Why `bytes32` type for addresses**

  CCTP is built to support EVM chains, which use 20 byte addresses, and non-EVM
  chains, many of which use 32 byte addresses. Circle provides a
  [`Message.sol` library](https://github.com/circlefin/evm-cctp-contracts/blob/40111601620071988e94e39274c8f48d6f406d6d/src/messages/Message.sol#L145-L157)
  as a reference implementation for converting between address and `bytes32` in
  Solidity.
</Note>

### Message body

The message format includes a dynamically sized `messageBody` field, used for
application-specific messages. For example, `TokenMessengerV2` defines a
[BurnMessageV2](https://github.com/circlefin/evm-cctp-contracts/blob/master/src/messages/v2/BurnMessageV2.sol)
with data related to crosschain transfers.

| Field             | Offset | Solidity Type | Length (bytes) | Description                                                                                                                                                                                                                                                                                            |
| ----------------- | ------ | ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `version`         | 0      | `uint32`      | 4              | Version identifier - use 1 for CCTP                                                                                                                                                                                                                                                                    |
| `burnToken`       | 4      | `bytes32`     | 32             | Address of burned token on source domain                                                                                                                                                                                                                                                               |
| `mintRecipient`   | 36     | `bytes32`     | 32             | Address to receive minted tokens on destination domain                                                                                                                                                                                                                                                 |
| `amount`          | 68     | `uint256`     | 32             | Amount of burned tokens                                                                                                                                                                                                                                                                                |
| `messageSender`   | 100    | `bytes32`     | 32             | Address of caller of `depositForBurn` (or `depositForBurnWithCaller`) on source domain                                                                                                                                                                                                                 |
| `maxFee`          | 132    | `uint256`     | 32             | Maximum fee to pay on the destination domain, specified in units of `burnToken`                                                                                                                                                                                                                        |
| `feeExecuted`     | 164    | `uint256`     | 32             | Actual fee charged on the destination domain, specified in units of `burnToken` (capped by `maxFee`)                                                                                                                                                                                                   |
| `expirationBlock` | 196    | `uint256`     | 32             | An expiration block 24 hours in the future is encoded in the message before signing by attestation service, and is respected on the destination chain. If the burn expires, it must be re-signed. Expiration acts as a safety mechanism against problems with finalization, such as a stuck sequencer. |
| `hookData`        | 228    | `bytes`       | dynamic        | Arbitrary data to be included in the `depositForBurn` on source domain and to be executed on destination domain                                                                                                                                                                                        |

<Note>
  **`expirationBlock` on ARB-stack blockchains**

  For ARB-stack destination blockchains (Arbitrum, EDGE, and Plume), the
  `expirationBlock` is an Ethereum (L1) block number, not the L2 block number.
  ARB-stack blockchains track blocks internally using the parent blockchain
  (Ethereum). When validating expiration for these blockchains, compare the
  `expirationBlock` value against the current Ethereum block number, not the L2
  block number.
</Note>

## API hosts and endpoints

CCTP provides a set of API hosts and endpoints to manage messages, attestations,
and transaction details for your crosschain USDC transfers.

### API service hosts

| Environment | URL                                   |
| :---------- | :------------------------------------ |
| **Testnet** | `https://iris-api-sandbox.circle.com` |
| **Mainnet** | `https://iris-api.circle.com`         |

<Note>
  **API Service Rate Limit**

  The CCTP API service rate limit is 35 requests per second. If you exceed 35
  requests per second, the service blocks all API requests for the next 5 minutes
  and returns an HTTP 429 response.
</Note>

### API endpoints

CCTP endpoints enable advanced capabilities such as fetching attestations for
**Standard Transfer** or **Fast Transfer** burn events, verifying public keys
across versions, accessing transaction details, querying fast transfer
allowances and fees, and initiating re-attestation processes. Below is an
overview of the CCTP public endpoints. Click on any endpoint for its API
reference.

| Endpoint                                                                                  | Description                                                                                                         | Use Case                                                                                       |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [`GET /v2/publicKeys`](/api-reference/cctp/all/get-public-keys-v2)                        | Returns public keys for validating attestations across all supported CCTP versions.                                 | Retrieve public keys to verify attestation authenticity for crosschain transactions.           |
| [`GET /v2/messages`](/api-reference/cctp/all/get-messages-v2)                             | Retrieves messages and attestations for a given transaction or nonce, supporting messages for all CCTP versions.    | Fetch attestation status and transaction details.                                              |
| [`POST /v2/reattest`](/api-reference/cctp/all/reattest-message)                           | Re-attests a <Tooltip>soft finality</Tooltip> V2 message to achieve finality or revive expired Fast Transfer burns. | Handle edge cases requiring updated attestations or finalize transactions with stricter rules. |
| [`GET /v2/fastBurn/USDC/allowance`](/api-reference/cctp/all/get-fast-burn-usdc-allowance) | Retrieves the current USDC Fast Transfer allowance remaining.                                                       | Monitor available allowance for Fast Transfer burns in real-time.                              |
| [`GET /v2/burn/USDC/fees`](/api-reference/cctp/all/get-burn-usdc-fees)                    | Returns the fees for USDC transfers between specified source and destination domains.                               | Calculate transaction costs before initiating a Fast or Standard Transfer.                     |

<Note>
  **Deprecated endpoint**

  The endpoint `/v2/fastBurn/USDC/fees` is deprecated. Use
  [`/v2/burn/USDC/fees`](/api-reference/cctp/all/get-burn-usdc-fees) instead to
  retrieve both Fast and Standard Transfer fees.

  **Note:** This deprecation does **not** affect
  [`/v2/fastBurn/USDC/allowance`](/api-reference/cctp/all/get-fast-burn-usdc-allowance)
  (see preceding table), which remains active and valid.
</Note>

## Finality thresholds

CCTP has the concept of a finality threshold, which is a chain-agnostic
representation of the confirmation level required before an attestation is
issued. This allows integrators to specify how many confirmations are needed
based on their risk tolerance or use case.

In CCTP, each message specifies a `minFinalityThreshold`. This threshold
indicates the minimum level of confirmation required for Circle's attestation
service (Iris) to attest to the message. Iris will not attest to a message at a
confirmation level below the specified minimum threshold. This allows
applications to enforce a desired level of finality before acting on an
attestation on the destination chain.

### Defined finality thresholds

CCTP V2 defines the following finality thresholds:

| Finality Threshold | Value |
| ------------------ | ----- |
| **Confirmed**      | 1000  |
| **Finalized**      | 2000  |

### Messages and finality

* Messages with a `minFinalityThreshold` of **1000** or lower are considered
  **Fast** messages. These messages are eligible for fast attestation at the
  *confirmed* level by Iris.
* Messages with a `minFinalityThreshold` of **2000** are considered **Standard**
  messages. These messages are attested to at the *finalized* level by Iris.

<Note>
  Only two finality thresholds are supported. Any `minFinalityThreshold` value
  below **1000** is treated as **1000**, and any value above **1000** is treated
  as **2000**.
</Note>

## Fees

For information about CCTP transfer fees, including fee tables by blockchain,
the `maxFee` parameter, and Standard Transfer fee switch support, see
[CCTP Fees](/cctp/concepts/fees).

## Hooks

Hooks in CCTP V2 are metadata that can be attached to a burn message, allowing
integrators to execute custom logic at the destination chain. Hook execution is
left entirely to the integrator, offering maximum flexibility and enabling
broader crosschain compatibility without altering the core CCTP protocol.

### Design overview

CCTP does not implement hook execution in the core protocol. Instead, hooks are
treated as opaque metadata passed along with the burn message. This design
allows integrators to define and control how hooks are processed on the
destination chain, based on their own infrastructure and trust model.

### Key benefits

* **Maximum flexibility for integrators**
  * Determine execution timing: pre-mint or post-mint
  * Implement custom recovery or error-handling strategies if hook execution
    fails
  * Choose any execution environment (EVM or non-EVM); even non-EVM chains can
    support Hooks as data passed into a function call.

* **Improved Compliance and Security Separation**
  * **Compliance**: By delegating hook execution to the integrator, the protocol
    maintains a clear boundary between CCTP's core message-passing capabilities
    and application-specific logic. This modular approach helps integrators meet
    their own compliance requirements with greater flexibility.
  * **Security**: By keeping hook execution outside the core protocol, CCTP
    maintains a smaller and more focused security surface, while allowing
    integrators to manage their own execution environments independently.

## Security audit

The CCTP smart contracts have been independently audited by two third-party
security firms:

* CCTP was audited by
  [ChainSecurity (PDF)](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/PDFs/ChainSecurity_Circle_CCTP_V2_audit%20\(1\).pdf)
  and
  [OtterSec (PDF)](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/PDFs/public_evm_cctp_audit_final%20\(2\).pdf)
* CCTP (with Standard Transfer fee switch) was audited by
  [ChainSecurity (PDF)](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/CCTP/ChainSecurity_Circle_CCTP_audit_2025-07.pdf)


# Cross-Chain Transfer Protocol V1
Source: https://developers.circle.com/cctp/v1

Move USDC securely across blockchains and simplify user experience

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

## Overview

**Cross-Chain Transfer Protocol V1** is a permissionless onchain utility that
facilitates USDC transfers securely between blockchain networks via native
burning and minting. Circle created CCTP to improve capital efficiency and
minimize trust requirements when using USDC across blockchain networks. CCTP V1
enables developers to build multichain applications that allow users to perform
1:1 transfers of USDC securely across blockchains.

<Note>
  **Note:** CCTP V1 only supports **Standard Transfer**, constrained by
  blockchain finality on the source blockchain. Later [CCTP](/cctp) versions
  support **Fast Transfer** and **Hooks**, in addition to also supporting
  **Standard Transfer**.
</Note>

## Understanding the Problem

Blockchain networks often operate in siloed environments and cannot natively
communicate with one another. While some ecosystems, such as Cosmos, use
built-in protocols like the Inter-Blockchain Communication (IBC) protocol to
enable data transmission between their appchains, direct communication between
isolated networks, such as Ethereum and Avalanche, remains infeasible.

Traditional bridges exist to address this limitation by enabling the transfer of
digital assets, such as USDC, across blockchains. However, these bridges come
with significant drawbacks. Two common methods, lock-and-mint bridging and
liquidity pool bridging, require locking USDC liquidity in third-party smart
contracts. This approach reduces capital efficiency and introduces additional
trust assumptions.

## Design Approach

As a low-level primitive, CCTP V1 can be embedded within any app or wallet -
even existing bridges - to enhance and simplify the user experience for
cross-chain use cases. With USDC circulating across a large number of blockchain
networks, CCTP V1 can connect and unify liquidity across disparate ecosystems
where it's supported.

CCTP V1 is built on generalized message passing and designed for composability,
enabling a wide range of use cases. Developers can extend its functionality
beyond just moving USDC between blockchains. For example, you can create a flow
where USDC is sent across chains and automatically deposited into a DeFi lending
pool after the transfer, allowing it to generate yield in an automated manner.
This experience can be designed to feel like a seamless, single transaction for
the end user.

## How CCTP V1 works

**Standard Transfer** is the default method in CCTP V1 for transferring USDC
across blockchains, which involves burning USDC on the source chain and minting
it on the destination chain. It relies on transaction finality on the source
chain and uses Circle's Attestation Service to enable standard-finality
(<Tooltip>hard
finality</Tooltip>) transfers. The process includes the following steps:

1. **Initiation**. A user accesses an app powered by CCTP V1 and initiates a
   Standard Transfer of USDC, specifying the recipient's wallet address on the
   destination chain.
2. **Burn Event**. The app facilitates a burn of the specified USDC amount on
   the source blockchain.
3. **Attestation**. Circle's Attestation Service observes the burn event and,
   after observing hard finality on the source chain, issues a signed
   attestation. Hard finality ensures the burn is irreversible (about 13 to 19
   minutes for Ethereum and L2 chains.)
4. **Mint Event**. The app retrieves the signed attestation from Circle and uses
   it to mint USDC on the destination chain.
5. **Completion**. The recipient wallet address receives the newly minted USDC
   on the destination blockchain, completing the transfer.

**Standard Transfer** prioritizes reliability and security, making it suitable
for scenarios where finality wait times are acceptable.

## Use Cases

CCTP V1 enables developers to build novel cross-chain apps that integrate
functionalities like trading, lending, payments, NFTs, and gaming, while
simplifying the user experience. Below are some practical examples of how you
can leverage CCTP V1 in your applications, either directly or indirectly by
routing USDC behind the scenes:

### Cross-chain rebalancing

Market makers, fillers/solvers, exchanges, and bridges can use CCTP V1 to manage
liquidity more efficiently. By securely rebalancing USDC holdings across
blockchains, you can reduce operational costs, meet demand, and take advantage
of market opportunities with minimal latency.

### Cross-chain swaps

With CCTP V1, users can quickly swap between digital assets on different
blockchains by routing through USDC. Users can also swap for USDC and
automatically trigger subsequent actions on the destination chain, enabling
seamless cross-chain transactions.

### Cross-chain purchases

Automate cross-chain purchases with CCTP V1. For example, a user can use USDC on
one chain to purchase an NFT on a decentralized exchange on another chain and
list it for sale on an NFT marketplace. When the transaction is initiated, CCTP
V1 routes USDC across chains to buy the NFT and opens the listing on the
marketplace—all in one streamlined flow.

### Simplify cross-chain complexities

Simplify the cross-chain experience by using USDC as collateral on one chain to
open a borrowing position on a lending protocol on another chain. With CCTP V1,
USDC can move quickly between blockchains, allowing users to onboard to new
applications without switching wallets or managing multi-chain complexities.


# CCTP Aptos Packages and Interfaces V1
Source: https://developers.circle.com/cctp/v1/aptos-packages

Packages for CCTP V1 support on the Aptos blockchain

<Warning>
  **This is CCTP V1 version. For the latest version, see [CCTP](/cctp)**.
</Warning>

## Overview

The CCTP V1 Aptos smart contract implementation is written in
[Move](https://aptos.dev/en/build/smart-contracts). The Aptos CCTP V1
implementation is split into two packages: `MessageTransmitter` and
`TokenMessengerMinter`. `TokenMessengerMinter` encapsulates the functionality of
both `TokenMessenger` and `TokenMinter` contracts on EVM chains. To ensure
alignment with EVM contracts logic and state, and to facilitate future upgrades
and maintenance, the code and state of the Aptos packages reflect the EVM
counterparts as closely as possible.

The key difference with Aptos packages from EVM and other CCTP V1
implementations is the receive message flow. Since the Move language uses static
dispatch and requires all dependencies to be available at compile time, the
`MessageTransmitter` `receive_message` function cannot call into the receiver
package (e.g. `TokenMessengerMinter` for USDC transfers). The workaround for
this limitation is that callers of `message_transmitter::receive_message` must
also atomically (in the same transaction or
[move script](https://aptos.dev/en/build/smart-contracts/scripts)) call into the
receiver package's `handle_receive_message` function with a Receipt object
returned from `receive_message`, and then pass a `Receipt` object back into the
`message_transmitter::complete_receive_message` function to complete the message
and destroy the `Receipt` object. Please see the interface and examples below
for more information on this flow.

Below are the known package IDs and object IDs on Aptos testnet and mainnet.

### Testnet

#### Package IDs

| Package              | [Domain](/cctp/v1/supported-domains) | Address                                                              |
| :------------------- | :----------------------------------- | :------------------------------------------------------------------- |
| MessageTransmitter   | 9                                    | `0x081e86cebf457a0c6004f35bd648a2794698f52e0dde09a48619dcd3d4cc23d9` |
| TokenMessengerMinter | 9                                    | `0x5f9b937419dda90aa06c1836b7847f65bbbe3f1217567758dc2488be31a477b9` |

#### Object IDs

| Object               | Object ID                                                            |
| :------------------- | :------------------------------------------------------------------- |
| MessageTransmitter   | `0xcbb70e4f5d89b4a37e850c22d7c994e32c31e9cf693e9633784e482e9a879e0c` |
| TokenMessengerMinter | `0x1fbf4458a00a842a4774f441fac7a41f2da0488dd93a43880e76d58789144e17` |
| Stablecoin           | `0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832` |

CCTP V1 and Stablcoin use a shared package `AptosExtensions` deployed at
`0xb75a74c6f8fddb93fdc00194e2295d8d5c3f6a721e79a2b86884394dcc554f8f`

### Mainnet

#### Package IDs

| Package              | [Domain](/cctp/v1/supported-domains) | Address                                                              |
| :------------------- | :----------------------------------- | :------------------------------------------------------------------- |
| MessageTransmitter   | 9                                    | `0x177e17751820e4b4371873ca8c30279be63bdea63b88ed0f2239c2eea10f1772` |
| TokenMessengerMinter | 9                                    | `0x9bce6734f7b63e835108e3bd8c36743d4709fe435f44791918801d0989640a9d` |

#### Object IDs

| Object               | Object ID                                                            |
| :------------------- | :------------------------------------------------------------------- |
| MessageTransmitter   | `0x45bf7f71e44750f2b2a7a1fea21fc44b4a83ba5d68ab10c7a3935f6d8cbdbc75` |
| TokenMessengerMinter | `0x9e6702a472080ea3caaf6ba9dfaa6effad2290a9ba9adaacd5af5c618e42782d` |
| Stablecoin           | `0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b` |

The shared package `AptosExtensions` is deployed at
`0x98bce69c31ee2cf91ac50a3f38db7b422e3df7cdde9fe672ee1d03538a6aeae0`

## Interface

The Aptos CCTP V1 source code is
[available on GitHub](https://github.com/circlefin/aptos-cctp/).

The interface below serves as a reference for permissionless messaging functions
exposed by the programs.

### TokenMessengerMinter

#### [deposit\_for\_burn](https://github.com/circlefin/aptos-cctp/blob/master/packages/token_messenger_minter/sources/token_messenger/token_messenger.move#L123)

Burns passed in `FungibleAsset` from sender to be minted on the destination
domain. Minted tokens will be transferred to `mint_recipient` on the destination
chain. The `mint_recipient` can be an account address or a store address. The
`deposit_for_burn` interface and functionality is very similar to the EVM
implementation. The asset parameter is the key difference due to how passing
tokens around on Aptos works. The asset parameter is Aptos Fungible Asset type,
defining information of the token to deposit and burn.

Nonce reserved for the message is returned, but it is not required to do
anything with this return value, they are returned for convenience.

**Parameters**

| Field               | Type            | Description                                                                                                                                                                                                                                                                                                                         |
| :------------------ | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| caller              | `Signer`        | Signer executing the transaction                                                                                                                                                                                                                                                                                                    |
| asset               | `FungibleAsset` | Asset to be burned.                                                                                                                                                                                                                                                                                                                 |
| destination\_domain | `u32`           | Destination domain identifier.                                                                                                                                                                                                                                                                                                      |
| mint\_recipient     | `address`       | Address of mint recipient on destination domain. Can be an account address or [store address](https://aptos.dev/en/build/smart-contracts/fungible-asset#managing-stores-advanced). *Note: If destination is a non-Move chain,* `mint_recipient` *address should be converted to hex and passed in using the @0x123 address format.* |

#### [deposit\_for\_burn\_with\_caller](https://github.com/circlefin/aptos-cctp/blob/master/packages/token_messenger_minter/sources/token_messenger/token_messenger.move#L147)

The same as deposit\_for\_burn, but with an additional parameter:
`destination_caller`. This parameter specifies which address has permission to
call `receiveMessage` on the destination domain for the message.

**Parameters**

| Field               | Type            | Description                                                                                                                                                                                                                                                                                                                         |
| :------------------ | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| caller              | `Signer`        | Signer executing the transaction                                                                                                                                                                                                                                                                                                    |
| asset               | `FungibleAsset` | Asset to be burned.                                                                                                                                                                                                                                                                                                                 |
| destination\_domain | `u32`           | Destination domain identifier.                                                                                                                                                                                                                                                                                                      |
| mint\_recipient     | `address`       | Address of mint recipient on destination domain. Can be an account address or [store address](https://aptos.dev/en/build/smart-contracts/fungible-asset#managing-stores-advanced). *Note: If destination is a non-Move chain,* `mint_recipient` *address should be converted to hex and passed in using the @0x123 address format.* |
| destination\_caller | `address`       | Address of caller on destination chain.                                                                                                                                                                                                                                                                                             |

<Note>
  **Destination Caller Notes**

  If the `destination_caller` does not represent a valid address, then it will not
  be possible to broadcast the message on the destination domain. This is an
  advanced feature, and the standard `deposit_for_burn` should be preferred for
  use cases where a specific destination caller is not required.

  *Note: If destination is a non-Move chain,* `destination_caller` *address should
  be converted to hex and passed in using the @0x123 address format.*
</Note>

#### [replace\_deposit\_for\_burn\_with](https://github.com/circlefin/aptos-cctp/blob/master/packages/token_messenger_minter/sources/token_messenger/token_messenger.move#L171)

Replace a BurnMessage to change the mint recipient and/or destination caller.
Allows the sender of a previous BurnMessage (created by `deposit_for_burn` or
`deposit_for_burn_with_caller`) to send a new BurnMessage to replace the
original.

**Remarks:**

* Only the sender of the original `deposit_for_burn` transaction has access to
  call `replace_deposit_for_burn`
* The new `BurnMessage` will reuse the amount and burn token of the original,
  without requiring a new `FA` deposit.
* The resulting mint will supersede the original mint, as long as the original
  mint has not confirmed yet onchain.
* A valid attestation is required before calling this function.
* This is useful in situations where the user specified an incorrect address and
  has no way to safely mint the previously burned USDC.

**Parameters**

| Field                    | Type              | Description                                                                                                                                                                                      |
| :----------------------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| caller                   | `Signer`          | Signer executing the transaction                                                                                                                                                                 |
| original\_message        | `vector<u8>`      | Original message bytes (to replace).                                                                                                                                                             |
| original\_attestation    | `vector<u8>`      | Original attestation                                                                                                                                                                             |
| new\_destination\_caller | `Option<address>` | The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller, indicating that any destination caller is valid. |
| new\_mint\_recipient     | `Option<address>` | The new mint recipient, which may be the same as the original mint recipient, or different.                                                                                                      |

#### [handle\_receive\_message](https://github.com/circlefin/aptos-cctp/blob/master/packages/token_messenger_minter/sources/token_messenger/token_messenger.move#241)

Handles an incoming message that has already been verified by
`message_transmitter`, and mints USDC to the recipient for valid messages. This
function can only be called with a mutable reference to a `Receipt` object,
which can only be created via a call with a valid message to the
`message_transmitter::receive_message` function. In this function
`MessageTransmitter::complete_receive_message` is called with the `Receipt` to
emit the `MessageReceived` event to complete the message and destroy Receipt.

This should be called in a single transaction after calling
`message_transmitter::receive_message`. EOAs can execute these functions in a
single
[Move script](https://github.com/circlefin/aptos-cctp/blob/master/packages/token_messenger_minter/scripts/handle_receive_message.move#L5).
See the Examples section for the entire flow of receiving a message.

**Parameters**

| Field   | Type      | Description                                                      |
| :------ | :-------- | :--------------------------------------------------------------- |
| receipt | `Receipt` | Receipt struct returned by `message_transmitter:receive_message` |

### MessageTransmitter

#### [receive\_message](https://github.com/circlefin/aptos-cctp/blob/master/packages/message_transmitter/sources/message_transmitter.move#L287)

Receives a message emitted from a source chain. Messages with a given `nonce`
can only be received once for a (sourceDomain, destinationDomain) pair.

This function returns a `Receipt` struct
([Hot Potato](https://medium.com/@borispovod/move-hot-potato-pattern-bbc48a48d93c))
after validating the attestation and marking the nonce as used. In order to
destroy the `Receipt` and complete the message, in a single transaction,
`handle_receive_message()` must be called with the `Receipt` in the receiver
package. EOAs can execute these functions in a single
[Move script](https://github.com/circlefin/aptos-cctp/blob/master/packages/token_messenger_minter/scripts/handle_receive_message.move#L5).

Returns a `Receipt` object that must be handled by the intended receiving
package, and completed via a `complete_receive_message` call before the
transaction ends. See the
[Examples](/cctp/v1/transfer-usdc-on-testnet-from-aptos-to-base) section for
more information on receiving USDC transfers.

**Parameters**

| Field          | Type         | Description                      |
| :------------- | :----------- | :------------------------------- |
| caller         | `Signer`     | Signer executing the transaction |
| message\_bytes | `vector<u8>` | Message bytes                    |
| attestation    | `vector<u8>` | Attestation                      |

#### [complete\_receive\_message](https://github.com/circlefin/aptos-cctp/blob/master/packages/message_transmitter/sources/message_transmitter.move#L330)

Completes the message by emitting a `MessageReceived` event for a receipt and
destroying the receipt.

**Parameters**

| Field   | Type      | Description                                |
| :------ | :-------- | :----------------------------------------- |
| caller  | `Signer`  | Signer for the `receipt.recipient` address |
| receipt | `Receipt` | Receipt struct to be destroyed             |

#### [send\_message](https://github.com/circlefin/aptos-cctp/blob/master/packages/message_transmitter/sources/message_transmitter.move#L169)

Sends a message to the destination domain and recipient. Nonce reserved for the
message is returned, but it is not required to do anything with this struct, it
is returned for convenience.

**Remarks:**

* For USDC transfers, this function is called directly by the
  `TokenMessengerMinter` package in `deposit_for_burn()`.

**Parameters**

| Field               | Type         | Description                                                                                                                                                    |
| :------------------ | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| caller              | `Signer`     | Signer for executing the transaction                                                                                                                           |
| destination\_domain | `u32`        | Destination domain identifier.                                                                                                                                 |
| recipient           | `address`    | Recipient address. *Note: If destination is a non-Move chain,* `recipient` *address should be converted to hex and passed in using the @0x123 address format.* |
| message\_body       | `vector<u8>` | Message to be sent to destination chain                                                                                                                        |

#### [send\_message\_with\_caller](https://github.com/circlefin/aptos-cctp/blob/master/packages/message_transmitter/sources/message_transmitter.move#L198)

This is the same as send\_message, except the `receive_message` call on the
destination domain must be called by `destination_caller`.

**Parameters**

| Field               | Type         | Description                                                                                                                                                    |
| :------------------ | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| caller              | `Signer`     | Signer for executing the transaction                                                                                                                           |
| destination\_domain | `u32`        | Destination domain identifier.                                                                                                                                 |
| recipient           | `address`    | Recipient address. *Note: If destination is a non-Move chain,* `recipient` *address should be converted to hex and passed in using the @0x123 address format.* |
| destination\_caller | `address`    | Address of caller on destination chain.                                                                                                                        |
| message\_body       | `vector<u8>` | Message to be sent to destination chain                                                                                                                        |

<Note>
  **Destination Caller Notes**

  If the `destination_caller` does not represent a valid address, then it will not
  be possible to broadcast the message on the destination domain. This is an
  advanced feature, and the standard `deposit_for_burn` should be preferred for
  use cases where a specific destination caller is not required.

  *Note: If destination is a non-Move chain,* `destination_caller` *address should
  be converted to hex and passed in using the @0x123 address format.*
</Note>

#### [replace\_message](https://github.com/circlefin/aptos-cctp/blob/master/packages/message_transmitter/sources/message_transmitter.move#L229)

Replace a message with a new message body and/or destination caller. The
originalAttestation must be a valid attestation of originalMessage, produced by
Circle's attestation service.

**Remarks:**

* Only the sender of the original deposit\_for\_burn transaction has access to
  call `replace_message`

**Parameters**

| Field                    | Type                 | Description                                                                                                                                                                                      |
| :----------------------- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| caller                   | `Signer`             | Signer executing the transaction                                                                                                                                                                 |
| original\_message        | `vector<u8>`         | Original message bytes (to replace).                                                                                                                                                             |
| original\_attestation    | `vector<u8>`         | Original attestation                                                                                                                                                                             |
| new\_message\_body       | `Option<vector<u8>>` | New message body                                                                                                                                                                                 |
| new\_destination\_caller | `Option<address>`    | The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller, indicating that any destination caller is valid. |

## Additional Notes

### Using Move Scripts

Pre-compiled scripts for executing `deposit_for_burn` and
`handle_receive_message` are available in the
[repo](https://github.com/circlefin/aptos-cctp/tree/master/typescript/example/precompiled-move-scripts)
for testnet and mainnet. Alternatively, the scripts can be compiled from the
source code. The documentation can be found on the official Aptos
[website](https://aptos.dev/en/build/smart-contracts/scripts/compiling-scripts).

### Mint Recipient Addresses for Aptos as Source Chain

Outgoing mint recipient addresses from Aptos are passed as Aptos address types
and can be treated the same as a `bytes32` mint recipient parameter on EVM
implementations.

### Mint Recipient Addresses for Aptos as Destination Chain

Aptos mint recipient addresses from other chains should be treated the same as a
hex `bytes32` parameter.


# CCTP API Hosts and Endpoints V1
Source: https://developers.circle.com/cctp/v1/cctp-apis

API hosts and endpoints for CCTP V1

<Warning>
  **This is CCTP V1 version. For the latest version, see [CCTP](/cctp)**.
</Warning>

CCTP V1 provides a set of API hosts and endpoints to manage messages,
attestations, and transaction details for your cross-chain USDC transfers.

## CCTP V1 API Service Hosts

| Environment | URL                                   |
| :---------- | :------------------------------------ |
| **Testnet** | `https://iris-api-sandbox.circle.com` |
| **Mainnet** | `https://iris-api.circle.com`         |

## CCTP V1 API Endpoints

CCTP V1 endpoints allow you to fetch attestations for **Standard Transfer** burn
events, verify public keys, and access transaction details. Below is an overview
of the CCTP V1 public endpoints. Click on any endpoint for its API reference.

| Endpoint                                                                                      | Description                                                                 | Use Case                                                                                                                   |
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [`GET /v1/attestations/{messageHash}`](/api-reference/cctp/all/get-attestation)               | Retrieves the signed attestation for a USDC burn event on the source chain. | Certifying the burn of USDC post <Tooltip>hard finality</Tooltip>. Used as a signal to mint USDC on the destination chain. |
| [`GET /v1/publicKeys`](/api-reference/cctp/all/get-public-keys)                               | Fetches Circle's active public keys for verifying attestation signatures.   | Validating the authenticity of Circle's signed attestations.                                                               |
| [`GET /v1/messages/{sourceDomainId}/{transactionHash}`](/api-reference/cctp/all/get-messages) | Provides transaction details for burn events or associated messages.        | Accessing detailed information about CCTP V1 transactions.                                                                 |

<Note>
  **API Service Rate Limit**

  The CCTP V1 API service rate limit is 35 requests per second. If you exceed 35
  requests per second, the service blocks all API requests for the next 5 minutes
  and returns an HTTP 429 response.
</Note>


# CCTP Supported Blockchains V1
Source: https://developers.circle.com/cctp/v1/cctp-supported-blockchains



<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

CCTP V1 is available on the following blockchains where USDC is natively issued,
providing **Standard Transfer** functionality.

**Mainnet:**

* Aptos
* Arbitrum
* Avalanche
* Base
* Ethereum
* Noble
* OP Mainnet
* Polygon PoS
* Solana
* Sui
* Unichain

**Testnet:**

* Aptos Testnet
* Arbitrum Sepolia
* Avalanche Fuji
* Base Sepolia
* Ethereum Sepolia
* Noble Testnet
* OP Sepolia
* Polygon PoS Amoy
* Solana Devnet
* Sui Testnet
* Unichain Sepolia


# CCTP EVM Contracts and Interfaces V1
Source: https://developers.circle.com/cctp/v1/evm-smart-contracts

CCTP V1 smart contracts for EVM-compatible blockchains

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see
  [CCTP](/cctp)**.
</Warning>

## Contract responsibilities

* **TokenMessenger**: Entrypoint for cross-chain USDC transfer. Routes messages
  to burn USDC on a source chain, and mint USDC on a destination chain.
* **MessageTransmitter**: Generic message passing. Sends all messages on the
  source chain, and receives all messages on the destination chain.
* **TokenMinter**: Responsible for minting and burning USDC. Contains
  chain-specific settings used by burners and minters.
* **Message**: Provides helper functions for cross-chain transfers, such as
  `bytes32ToAddress` and `addressToBytes32`, which are commonly used when
  bridging between EVM and non-EVM chains. These conversions are simple: prepend
  12 zero bytes to an EVM address, or strip them to convert back.

<Note>
  **Note:** If you're writing your own integration, it's more gas-efficient to
  [include this logic directly in your
  contract](https://github.com/circlefin/evm-cctp-contracts/blob/5f1901a9791b18204e8556bb53fb0dfcb05a832a/src/messages/Message.sol#L146)
  rather than calling an external one.
</Note>

Full contract source code is
[available on GitHub](https://github.com/circlefin/evm-cctp-contracts).

## Mainnet contract addresses

### TokenMessenger: Mainnet

| Chain           | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                            |
| --------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum**    | 0                                    | [`0xBd3fa81B58Ba92a82136038B25aDec7066af3155`](https://etherscan.io/address/0xbd3fa81b58ba92a82136038b25adec7066af3155)            |
| **Avalanche**   | 1                                    | [`0x6B25532e1060CE10cc3B0A99e5683b91BFDe6982`](https://snowtrace.io/address/0x6b25532e1060ce10cc3b0a99e5683b91bfde6982)            |
| **OP Mainnet**  | 2                                    | [`0x2B4069517957735bE00ceE0fadAE88a26365528f`](https://optimistic.etherscan.io/address/0x2B4069517957735bE00ceE0fadAE88a26365528f) |
| **Arbitrum**    | 3                                    | [`0x19330d10D9Cc8751218eaf51E8885D058642E08A`](https://arbiscan.io/address/0x19330d10D9Cc8751218eaf51E8885D058642E08A)             |
| **Base**        | 6                                    | [`0x1682Ae6375C4E4A97e4B583BC394c861A46D8962`](https://basescan.org/address/0x1682Ae6375C4E4A97e4B583BC394c861A46D8962)            |
| **Polygon PoS** | 7                                    | [`0x9daF8c91AEFAE50b9c0E69629D3F6Ca40cA3B3FE`](https://polygonscan.com/address/0x9daf8c91aefae50b9c0e69629d3f6ca40ca3b3fe)         |
| **Unichain**    | 10                                   | [`0x4e744b28E787c3aD0e810eD65A24461D4ac5a762`](https://uniscan.xyz/address/0x4e744b28E787c3aD0e810eD65A24461D4ac5a762)             |

### MessageTransmitter: Mainnet

| Chain           | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                            |
| --------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum**    | 0                                    | [`0x0a992d191DEeC32aFe36203Ad87D7d289a738F81`](https://etherscan.io/address/0x0a992d191deec32afe36203ad87d7d289a738f81)            |
| **Avalanche**   | 1                                    | [`0x8186359aF5F57FbB40c6b14A588d2A59C0C29880`](https://snowtrace.io/address/0x8186359af5f57fbb40c6b14a588d2a59c0c29880)            |
| **OP Mainnet**  | 2                                    | [`0x4D41f22c5a0e5c74090899E5a8Fb597a8842b3e8`](https://optimistic.etherscan.io/address/0x4d41f22c5a0e5c74090899e5a8fb597a8842b3e8) |
| **Arbitrum**    | 3                                    | [`0xC30362313FBBA5cf9163F0bb16a0e01f01A896ca`](https://arbiscan.io/address/0xC30362313FBBA5cf9163F0bb16a0e01f01A896ca)             |
| **Base**        | 6                                    | [`0xAD09780d193884d503182aD4588450C416D6F9D4`](https://basescan.org/address/0xAD09780d193884d503182aD4588450C416D6F9D4)            |
| **Polygon PoS** | 7                                    | [`0xF3be9355363857F3e001be68856A2f96b4C39Ba9`](https://polygonscan.com/address/0xF3be9355363857F3e001be68856A2f96b4C39Ba9)         |
| **Unichain**    | 10                                   | [`0x353bE9E2E38AB1D19104534e4edC21c643Df86f4`](https://uniscan.xyz/address/0x353bE9E2E38AB1D19104534e4edC21c643Df86f4)             |

### TokenMinter: Mainnet

| Chain           | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                            |
| --------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum**    | 0                                    | [`0xc4922d64a24675E16e1586e3e3Aa56C06fABe907`](https://etherscan.io/address/0xc4922d64a24675e16e1586e3e3aa56c06fabe907)            |
| **Avalanche**   | 1                                    | [`0x420F5035fd5dC62a167E7e7f08B604335aE272b8`](https://snowtrace.io/address/0x420f5035fd5dc62a167e7e7f08b604335ae272b8)            |
| **OP Mainnet**  | 2                                    | [`0x33E76C5C31cb928dc6FE6487AB3b2C0769B1A1e3`](https://optimistic.etherscan.io/address/0x33E76C5C31cb928dc6FE6487AB3b2C0769B1A1e3) |
| **Arbitrum**    | 3                                    | [`0xE7Ed1fa7f45D05C508232aa32649D89b73b8bA48`](https://arbiscan.io/address/0xE7Ed1fa7f45D05C508232aa32649D89b73b8bA48)             |
| **Base**        | 6                                    | [`0xe45B133ddc64bE80252b0e9c75A8E74EF280eEd6`](https://basescan.org/address/0xe45B133ddc64bE80252b0e9c75A8E74EF280eEd6)            |
| **Polygon PoS** | 7                                    | [`0x10f7835F827D6Cf035115E10c50A853d7FB2D2EC`](https://polygonscan.com/address/0x10f7835f827d6cf035115e10c50a853d7fb2d2ec)         |
| **Unichain**    | 10                                   | [`0x726bFEF3cBb3f8AF7d8CB141E78F86Ae43C34163`](https://uniscan.xyz/address/0x726bFEF3cBb3f8AF7d8CB141E78F86Ae43C34163)             |

### Message: Mainnet

| Chain           | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                            |
| --------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Ethereum**    | 0                                    | [`0xB2f38107A18f8599331677C14374Fd3A952fb2c8`](https://etherscan.io/address/0xb2f38107a18f8599331677c14374fd3a952fb2c8)            |
| **Avalanche**   | 1                                    | [`0x21F337db7A718F23e061262470Af8c1Fd01232D1`](https://snowtrace.io/address/0x21f337db7a718f23e061262470af8c1fd01232d1)            |
| **OP Mainnet**  | 2                                    | [`0xDB2831EaF163be1B564d437A97372deB0046C70D`](https://optimistic.etherscan.io/address/0xdb2831eaf163be1b564d437a97372deb0046c70d) |
| **Arbitrum**    | 3                                    | [`0xE189BDCFbceCEC917b937247666a44ED959D81e4`](https://arbiscan.io/address/0xe189bdcfbcecec917b937247666a44ed959d81e4)             |
| **Base**        | 6                                    | [`0x827ae40E55C4355049ab91e441b6e269e4091441`](https://basescan.org/address/0x827ae40E55C4355049ab91e441b6e269e4091441)            |
| **Polygon PoS** | 7                                    | [`0x02d9fa3e7f870E5FAA7Ca6c112031E0ddC5E646C`](https://polygonscan.com/address/0x02d9fa3e7f870E5FAA7Ca6c112031E0ddC5E646C)         |
| **Unichain**    | 10                                   | [`0x395b1be6E432033B676e3e36B2c2121a1f952622`](https://uniscan.xyz/address/0x395b1be6E432033B676e3e36B2c2121a1f952622)             |

## Testnet contract addresses

### TokenMessenger: Testnet

| Chain                | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                                    |
| -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Ethereum Sepolia** | 0                                    | [`0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5`](https://sepolia.etherscan.io/address/0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5)            |
| **Avalanche Fuji**   | 1                                    | [`0xeb08f243E5d3FCFF26A9E38Ae5520A669f4019d0`](https://testnet.snowtrace.io/address/0xeb08f243e5d3fcff26a9e38ae5520a669f4019d0)            |
| **OP Sepolia**       | 2                                    | [`0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5`](https://sepolia-optimism.etherscan.io/address/0x9f3b8679c73c2fef8b59b4f3444d4e156fb70aa5)   |
| **Arbitrum Sepolia** | 3                                    | [`0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5`](https://sepolia.arbiscan.io/address/0x9f3b8679c73c2fef8b59b4f3444d4e156fb70aa5)             |
| **Base Sepolia**     | 6                                    | [`0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5`](https://base-sepolia.blockscout.com/address/0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5)     |
| **Polygon PoS Amoy** | 7                                    | [`0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5`](https://amoy.polygonscan.com/address/0x9f3b8679c73c2fef8b59b4f3444d4e156fb70aa5)            |
| **Unichain Sepolia** | 10                                   | [`0x8ed94B8dAd2Dc5453862ea5e316A8e71AAed9782`](https://unichain-sepolia.blockscout.com/address/0x8ed94B8dAd2Dc5453862ea5e316A8e71AAed9782) |

### MessageTransmitter: Testnet

| Chain                | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                                    |
| -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Ethereum Sepolia** | 0                                    | [`0x7865fAfC2db2093669d92c0F33AeEF291086BEFD`](https://sepolia.etherscan.io/address/0x7865fAfC2db2093669d92c0F33AeEF291086BEFD)            |
| **Avalanche Fuji**   | 1                                    | [`0xa9fB1b3009DCb79E2fe346c16a604B8Fa8aE0a79`](https://testnet.snowtrace.io/address/0xa9fb1b3009dcb79e2fe346c16a604b8fa8ae0a79)            |
| **OP Sepolia**       | 2                                    | [`0x7865fAfC2db2093669d92c0F33AeEF291086BEFD`](https://sepolia-optimism.etherscan.io/address/0x7865fAfC2db2093669d92c0F33AeEF291086BEFD)   |
| **Arbitrum Sepolia** | 3                                    | [`0xaCF1ceeF35caAc005e15888dDb8A3515C41B4872`](https://sepolia.arbiscan.io/address/0xacf1ceef35caac005e15888ddb8a3515c41b4872)             |
| **Base Sepolia**     | 6                                    | [`0x7865fAfC2db2093669d92c0F33AeEF291086BEFD`](https://base-sepolia.blockscout.com/address/0x7865fAfC2db2093669d92c0F33AeEF291086BEFD)     |
| **Polygon PoS Amoy** | 7                                    | [`0x7865fAfC2db2093669d92c0F33AeEF291086BEFD`](https://amoy.polygonscan.com/address/0x7865fafc2db2093669d92c0f33aeef291086befd)            |
| **Unichain Sepolia** | 10                                   | [`0xbc498c326533d675cf571B90A2Ced265ACb7d086`](https://unichain-sepolia.blockscout.com/address/0xbc498c326533d675cf571B90A2Ced265ACb7d086) |

### TokenMinter: Testnet

| Chain                | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                                    |
| -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Ethereum Sepolia** | 0                                    | [`0xE997d7d2F6E065a9A93Fa2175E878Fb9081F1f0A`](https://sepolia.etherscan.io/address/0xe997d7d2f6e065a9a93fa2175e878fb9081f1f0a)            |
| **Avalanche Fuji**   | 1                                    | [`0x4ED8867f9947A5fe140C9dC1c6f207F3489F501E`](https://testnet.snowtrace.io/address/0x4ed8867f9947a5fe140c9dc1c6f207f3489f501e)            |
| **OP Sepolia**       | 2                                    | [`0xE997d7d2F6E065a9A93Fa2175E878Fb9081F1f0A`](https://sepolia-optimism.etherscan.io/address/0xe997d7d2f6e065a9a93fa2175e878fb9081f1f0a)   |
| **Arbitrum Sepolia** | 3                                    | [`0xE997d7d2F6E065a9A93Fa2175E878Fb9081F1f0A`](https://sepolia.arbiscan.io/address/0xe997d7d2f6e065a9a93fa2175e878fb9081f1f0a)             |
| **Base Sepolia**     | 6                                    | [`0xE997d7d2F6E065a9A93Fa2175E878Fb9081F1f0A`](https://base-sepolia.blockscout.com/address/0xE997d7d2F6E065a9A93Fa2175E878Fb9081F1f0A)     |
| **Polygon PoS Amoy** | 7                                    | [`0xE997d7d2F6E065a9A93Fa2175E878Fb9081F1f0A`](https://amoy.polygonscan.com/address/0xe997d7d2f6e065a9a93fa2175e878fb9081f1f0a)            |
| **Unichain Sepolia** | 10                                   | [`0x7348358C94519Da790DB38638d8c23669d343Bc6`](https://unichain-sepolia.blockscout.com/address/0x7348358C94519Da790DB38638d8c23669d343Bc6) |

### Message: Testnet

| Chain                | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                                    |
| -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Ethereum Sepolia** | 0                                    | [`0x80537e4e8bAb73D21096baa3a8c813b45CA0b7c9`](https://sepolia.etherscan.io/address/0x80537e4e8bAb73D21096baa3a8c813b45CA0b7c9)            |
| **Avalanche Fuji**   | 1                                    | [`0xeAf1DB5E3eb86FEbD8080368a956622b62Dcb78f`](https://testnet.snowtrace.io/address/0xeaf1db5e3eb86febd8080368a956622b62dcb78f)            |
| **OP Sepolia**       | 2                                    | [`0xffbeA106ce4A3CdAfcC82BAebeD78C81814e32Ed`](https://sepolia-optimism.etherscan.io/address/0xffbeA106ce4A3CdAfcC82BAebeD78C81814e32Ed)   |
| **Arbitrum Sepolia** | 3                                    | [`0x70fAB9868cd54E12C7d87196424d6E0ca21be534`](https://sepolia.arbiscan.io/address/0x70fAB9868cd54E12C7d87196424d6E0ca21be534)             |
| **Base Sepolia**     | 6                                    | [`0x8E52a9e76148185536F0f0779749Cc895E5f70dC`](https://base-sepolia.blockscout.com/address/0x8E52a9e76148185536F0f0779749Cc895E5f70dC)     |
| **Polygon PoS Amoy** | 7                                    | [`0x8E52a9e76148185536F0f0779749Cc895E5f70dC`](https://amoy.polygonscan.com/address/0x8E52a9e76148185536F0f0779749Cc895E5f70dC)            |
| **Unichain Sepolia** | 10                                   | [`0x1Fae490d95dDcFFD70728AF5024C524ed303a2e3`](https://unichain-sepolia.blockscout.com/address/0x1Fae490d95dDcFFD70728AF5024C524ed303a2e3) |

## CCTP V1 Interface

This section provides the **CCTP V1 Smart Contract Interface** exposed by **CCTP
V1**, outlining the available functions, and their parameters.

The interface below serves as a reference for permissionless messaging functions
exposed by the **TokenMessenger** and **MessageTransmitter** functions. The full
ABIs are
[available on GitHub](https://github.com/circlefin/evm-cctp-contracts/tree/adb2a382b09ea574f4d18d8af5b6706e8ed9b8f2/docs/abis/cctp).

### TokenMessenger

#### depositForBurn

Deposits and burns tokens from sender to be minted on destination domain. Minted
tokens will be transferred to `mintRecipient`.

**Parameters**

| Field               | Type      | Description                                                  |
| ------------------- | --------- | ------------------------------------------------------------ |
| `amount`            | `uint256` | Amount of tokens to deposit and burn                         |
| `destinationDomain` | `uint32`  | Destination domain identifier                                |
| `mintRecipient`     | `bytes32` | Address of mint recipient on destination domain              |
| `burnToken`         | `address` | Address of contract to burn deposited tokens on local domain |

#### depositForBurnWithCaller

Same as `depositForBurn` but with an additional parameter, `destinationCaller`.
This parameter specifies which address has permission to call `receiveMessage`
on the destination domain for the message.

**Parameters**

| Field               | Type      | Description                                                  |
| ------------------- | --------- | ------------------------------------------------------------ |
| `amount`            | `uint256` | Amount of tokens to deposit and burn                         |
| `destinationDomain` | `uint32`  | Destination domain identifier                                |
| `mintRecipient`     | `bytes32` | Address of mint recipient on destination domain              |
| `burnToken`         | `address` | Address of contract to burn deposited tokens on local domain |
| `destinationCaller` | `bytes32` | Address of caller on the destination domain                  |

#### replaceDepositForBurn

Replace a `BurnMessage` to change the mint recipient and/or destination caller.
Allows the sender of a previous `BurnMessage` (created by `depositForBurn` or
`depositForBurnWithCaller`) to send a new `BurnMessage` to replace the original.
The new `BurnMessage` will reuse the amount and burn token of the original,
without requiring a new deposit.

This is useful in situations where the user specified an incorrect address and
has no way to safely mint the previously burned USDC.

<Note>
  The sender of the original `depositForBurn` has access to call
  `replaceDepositForBurn`. The resulting mint will supersede the original mint,
  as long as the original mint has not confirmed yet onchain. When using a
  third-party app/bridge that integrates with CCTP V1 to burn and mint USDC, it
  is the choice of the app/bridge if and when to replace messages on behalf of
  users. When sending USDC to smart contracts, be aware of the functionality
  that those contracts have and their respective trust model.
</Note>

**Parameters**

| Field                  | Type             | Description                                                                                                                                                                                     |
| ---------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `originalMessage`      | `bytes calldata` | Original message bytes (to replace)                                                                                                                                                             |
| `originalAttestation`  | `bytes calldata` | Original attestation bytes                                                                                                                                                                      |
| `newDestinationCaller` | `bytes32`        | The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller, indicating that any destination caller is valid |
| `newMintRecipient`     | `bytes32`        | The new mint recipient, which may be the same as the original mint recipient, or different                                                                                                      |

### MessageTransmitter

#### receiveMessage

Messages with a given nonce can only be broadcast successfully once for a pair
of domains. The message body of a valid message is passed to the specified
recipient for further processing.

**Parameters**

| Field         | Type             | Description                   |
| ------------- | ---------------- | ----------------------------- |
| `message`     | `bytes calldata` | Message bytes                 |
| `attestation` | `bytes calldata` | Signed attestation of message |

#### sendMessage

Sends a message to the destination domain and recipient. Emits a `MessageSent`
event which will be attested by Circle's attestation service (Iris).

**Parameters**

| Field               | Type             | Description                                          |
| ------------------- | ---------------- | ---------------------------------------------------- |
| `destinationDomain` | `uint32`         | Destination domain identifier                        |
| `recipient`         | `bytes32`        | Address to handle message body on destination domain |
| `messageBody`       | `bytes calldata` | App-specific message to be handled by recipient      |

#### sendMessageWithCaller

Same as `sendMessage` but with an additional parameter, `destinationCaller`.
This parameter specifies which address has permission to call `receiveMessage`
on the destination domain for the message.

**Parameters**

| Field               | Type             | Description                                        |
| ------------------- | ---------------- | -------------------------------------------------- |
| `destinationDomain` | `uint32`         | Destination domain identifier                      |
| `recipient`         | `bytes32`        | Address of message recipient on destination domain |
| `destinationCaller` | `bytes32`        | Address of caller on the destination domain        |
| `messageBody`       | `bytes calldata` | App-specific message to be handled by recipient    |

#### replaceMessage

Replace a message with a new message body and/or destination caller. The
`originalAttestation` must be a valid attestation of `originalMessage`, produced
by Circle's attestation service (Iris).

**Parameters**

| Field                  | Type             | Description                                                                                                                                                                                                  |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `originalMessage`      | `bytes calldata` | Original message to replace                                                                                                                                                                                  |
| `originalAttestation`  | `bytes calldata` | Attestation of `originalMessage`                                                                                                                                                                             |
| `newMessageBody`       | `bytes calldata` | New message body of replaced message                                                                                                                                                                         |
| `newDestinationCaller` | `bytes32`        | The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller (bytes32(0), indicating that any destination caller is valid) |


# CCTP Message Passing V1
Source: https://developers.circle.com/cctp/v1/generic-message-passing

CCTP V1 architecture on EVM and non-EVM domains

<Warning>
  **This is CCTP V1 version. For the latest version, see [CCTP](/cctp)**.
</Warning>

Cross-Chain Transfer Protocol V1 uses generalized message passing to facilitate
the native burning and minting of USDC across supported blockchains, also known
as [domains](/cctp/v1/supported-domains). Message passing is a three-step
process:

1. An onchain component on the source domain emits a message.
2. Circle's offchain attestation service signs the message.
3. The onchain component at the destination domain receives the message, and
   forwards the message body to the specified recipient.

## Architecture

Onchain components on all domains have the same purpose, but implementation
differs between EVM-compatible and non-EVM domains.

### CCTP V1 on EVM Domains

The relationship between CCTP V1's onchain components and Circle's offchain
Attestation Service is illustrated below for a burn-and-mint of USDC between
EVM-compatible domains:

<Frame>
  <img />
</Frame>

On EVM domains, the onchain component for cross-chain burning and minting is
called **TokenMessenger**, which is built on top of **MessageTransmitter**, an
onchain component for generalized message passing.

In the diagram above, a token depositor calls the
[TokenMessenger#depositForBurn](https://github.com/circlefin/evm-cctp-contracts/blob/adb2a382b09ea574f4d18d8af5b6706e8ed9b8f2/src/TokenMessenger.sol#L169)
function to deposit a native token (such as USDC), which delegates to the
**TokenMinter** contract to burn the token. The **TokenMessenger** contract then
sends a message via the
[MessageTransmitter#sendMessage](https://github.com/circlefin/evm-cctp-contracts/blob/adb2a382b09ea574f4d18d8af5b6706e8ed9b8f2/src/MessageTransmitter.sol#L108)
function. After
[sufficient block confirmations](/cctp/v1/required-block-confirmations),
Circle's offchain attestation service, Iris, signs the message. An API consumer
queries this attestation and submits it onchain to the destination domain's
[MessageTransmitter#receiveMessage](https://github.com/circlefin/evm-cctp-contracts/blob/adb2a382b09ea574f4d18d8af5b6706e8ed9b8f2/src/MessageTransmitter.sol#L250)
function. For more details, see
[Quickstart: Cross-chain USDC transfer](/cctp/v1/transfer-usdc-on-testnet-from-ethereum-to-avalanche).

To send an arbitrary message, directly call
[MessageTransmitter#sendMessage](https://github.com/circlefin/evm-cctp-contracts/blob/adb2a382b09ea574f4d18d8af5b6706e8ed9b8f2/src/MessageTransmitter.sol#L108).
Note that the message recipient must implement
[IMessageHandler#handleReceiveMessage](https://github.com/circlefin/evm-cctp-contracts/blob/master/src/interfaces/IMessageHandler.sol#L31C14-L31C34).

<Note>
  **Note:**

  In CCTP V1, it is not possible to perform a burn-and-mint operation for USDC and
  include arbitrary data in the same message. You must include arbitrary data in a
  separate message. In later CCTP versions, you can burn-and-mint while including
  data in the same message via Hooks.
</Note>

### CCTP V1 on Non-EVM Domains

#### Noble

Noble is a Cosmos application-specific blockchain (or "appchain") that provides
native asset issuance for the Cosmos ecosystem. USDC is natively issued on Noble
and can be transferred via the Inter-Blockchain Communication (IBC) protocol to
other supported appchains in Cosmos, or via CCTP V1 to any supported domain (for
example, Ethereum).

Note that there are key differences between Cosmos appchains like Noble and
EVM-compatible blockchains. Unlike on EVM domains where CCTP V1 is a set of
smart contracts, CCTP V1 on Noble is a Cosmos SDK module, which is deployed by
Noble governance and built into the Noble blockchain. Cosmos appchains can use
IBC to build composable flows with CCTP V1 on Noble. Refer to the
[Noble documentation](/cctp/v1/noble-cosmos-module) for more details.

#### Solana

Solana is a layer-1 blockchain where USDC is natively issued as an SPL-token.
CCTP V1 is deployed to Solana as two Anchor programs: **MessageTransmitter** and
**TokenMessengerMinter**. Developers can compose programs on top of CCTP V1
programs through CPI's (Cross-Program Invocations). Arbitrary messages can be
sent directly by calling `MessageTransmitter#send_message` just as described in
the EVM section above. Refer to the
[Solana documentation](/cctp/v1/solana-programs) for more details.

#### Sui

Sui is another layer-1 blockchain where USDC is natively issued as a
[`Coin` implementation](https://docs.sui.io/guides/developer/coin). CCTP V1 is
deployed to Sui as two programs: **MessageTransmitter** and
**TokenMessengerMinter**. Arbitrary messages can be sent by directly calling
`message_transmitter::send_message` similar to the EVM section above. Refer to
the [Sui documentation](/cctp/v1/sui-packages) for more details.

#### Aptos

Aptos is another layer-1 blockchain where USDC is natively issued as a
[`FA` implementation](https://aptos.dev/en/build/smart-contracts/fungible-asset).
CCTP V1 is deployed to Aptos as two programs: **MessageTransmitter** and
**TokenMessengerMinter**. Arbitrary messages can be sent by directly calling
`message_transmitter::send_message` similar to the EVM section above. Refer to
the [Aptos documentation](/cctp/v1/aptos-packages) for more details.


# CCTP Limits V1
Source: https://developers.circle.com/cctp/v1/limits

Limits for CCTP V1 burning and minting

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

## Minter Allowance

The USDC smart contract (or module) on each blockchain specifies a limit for how
much USDC can be minted before the limit needs to be increased by the master
minter, Circle. This limit is called the "minter allowance" and it is
individually set for each authorized minter, such as CCTP V1.

Minter allowance is decremented each time the authorized minter mints, by the
amount of USDC that is minted. A transaction attempting to mint in excess of the
minter allowance will fail, but may succeed on a subsequent retry after the
minter allowance is reset. Minter allowance can be queried from the USDC
contract on EVM-compatible chains using the public
[minterAllowance](https://github.com/centrehq/centre-tokens/blob/0d3cab14ebd133a83fc834dbd48d0468bdf0b391/contracts/v1/FiatTokenV1.sol#L153)
function. For CCTP V1 on Noble, minter allowance can be queried via the
[fiattokenfactory module minters API](https://github.com/circlefin/noble-fiattokenfactory/blob/33b30a6cf87eba20874df84fa93dd100f71ed512/proto/fiattokenfactory/query.proto#L49-L52).

## Per-Message Burn Limit

CCTP V1 defines per-message burn limits. This value is configurable by Circle.
This limit prevents the situation where a user burns an amount of USDC on a
source chain that could never be minted on a destination chain without
increasing minter allowance thresholds. Per-message burn limits can be queried
on the TokenMinter contract on EVM-compatible chains, using the public
[burnLimitsPerMessage](https://github.com/circlefin/evm-cctp-contracts/blob/master/src/roles/TokenController.sol#L69)
mapping. For CCTP V1 on Noble, the per-message burn limit can be queried via the
[cctp module per\_message\_burn\_limits API](https://github.com/circlefin/noble-fiattokenfactory/blob/master/proto/fiattokenfactory/query.proto#L49-L52).


# CCTP Message Format V1
Source: https://developers.circle.com/cctp/v1/message-format

Format arbitrary and application-specific messages using CCTP V1

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

## CCTP V1 Message Header

The top-level message header format is standard for all messages passing through
CCTP V1.

| Field               | Offset | Solidity Type | Length (bytes) | Description                                                                                                                 |
| ------------------- | ------ | ------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `version`           | 0      | uint32        | 4              | Version identifier - use 0 for CCTP V1                                                                                      |
| `sourceDomain`      | 4      | uint32        | 4              | Source domain ID                                                                                                            |
| `destinationDomain` | 8      | uint32        | 4              | Destination domain ID                                                                                                       |
| `nonce`             | 12     | uint64        | 8              | Unique message nonce (see [Sequential Nonces](#sequential-nonces))                                                          |
| `sender`            | 20     | bytes32       | 32             | Address of MessageTransmitter caller on source domain                                                                       |
| `recipient`         | 52     | bytes32       | 32             | Address to handle message body on destination domain                                                                        |
| `destinationCaller` | 84     | bytes32       | 32             | Address permitted to call MessageTransmitter on destination domain, or bytes32(0) if message can be received by any address |
| `messageBody`       | 116    | bytes         | dynamic        | Application-specific message to be handled by recipient                                                                     |

### Sequential Nonces

A message nonce is a unique identifier for a message that can only be used once
on the destination domain. In CCTP V1, message nonces are implemented using
**Sequential Nonces**, where the next available nonce on a source domain is an
integer. On the destination domain, messages can be received in any order, and
used nonces are stored as a hash of the source domain and nonce integer value.

<Note>
  **Why we use `bytes32` type for addresses**

  CCTP V1 is built to support EVM chains, which use 20 byte addresses, and non-EVM
  chains, many of which use 32 byte addresses. We provide a
  [Message.sol library](https://github.com/circlefin/evm-cctp-contracts/blob/40111601620071988e94e39274c8f48d6f406d6d/src/messages/Message.sol#L145-L157)
  as a reference implementation for converting between address and `bytes32` in
  Solidity.
</Note>

## CCTP V1 Message Body

The message format includes a dynamically sized `messageBody` field, used for
application-specific messages. For example, TokenMessenger defines a
[BurnMessage](https://github.com/circlefin/evm-cctp-contracts/blob/master/src/messages/BurnMessage.sol)
with data related to cross-chain transfers.

| Field           | Offset | Solidity Type | Length (bytes) | Description                                                                            |
| --------------- | ------ | ------------- | -------------- | -------------------------------------------------------------------------------------- |
| `version`       | 0      | uint32        | 4              | Version identifier (0, for CCTP V1)                                                    |
| `burnToken`     | 4      | bytes32       | 32             | Address of burned token on source domain                                               |
| `mintRecipient` | 36     | bytes32       | 32             | Address to receive minted tokens on destination domain                                 |
| `amount`        | 68     | uint256       | 32             | Amount of burned tokens                                                                |
| `messageSender` | 100    | bytes32       | 32             | Address of caller of `depositForBurn` (or `depositForBurnWithCaller`) on source domain |


# CCTP Noble Cosmos Module V1
Source: https://developers.circle.com/cctp/v1/noble-cosmos-module

Cosmos SDK Module for CCTP V1 support on Noble

<Warning>
  **This is CCTP (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

## Overview

Noble is a Cosmos application-specific blockchain (or "appchain") that provides
native asset issuance for the Cosmos ecosystem. USDC is natively issued on Noble
and can be transferred via the Inter-Blockchain Communication Protocol (IBC) to
other supported appchains in Cosmos, or via CCTP V1 to any supported domain (for
example, Ethereum).

Note that there are key differences between Cosmos appchains like Noble and
EVM-compatible blockchains. Unlike on EVM chains where CCTP V1 is a set of smart
contracts, CCTP V1 on Noble is a Cosmos SDK module, which is deployed by Noble
governance and built into the Noble blockchain. Cosmos appchains can use IBC to
build composable flows with CCTP V1 on Noble.

## Testnet and Mainnet Module Address

| Chain | [Domain](/cctp/v1/supported-domains) | Address                                      |
| :---- | :----------------------------------- | :------------------------------------------- |
| Noble | 4                                    | noble12l2w4ugfz4m6dd73yysz477jszqnfughxvkss5 |

CCTP V1 on Noble source code is
[available on GitHub](https://github.com/circlefin/noble-cctp). The full message
spec is defined at
[noble-cctp/x/cctp/spec/02\_messages.md](https://github.com/circlefin/noble-cctp/blob/dc81b3e0d566d195c869a213519fcecd38b020a5/x/cctp/spec/02_messages.md).
The interface below serves as a reference for permissionless messaging functions
exposed by the module.

## Module Interface

### depositForBurn

**Message**: `MsgDepositForBurn`

Broadcast a transaction that deposits for burn to a provided domain.

**Arguments**:

* `Amount` - The burn amount
* `DestinationDomain` - Domain of destination chain
* `MintRecipient` - address receiving minted tokens on destination chain as a 32
  length byte array
* `BurnToken` - The burn token address on source domain

### depositForBurnWithCaller

**Message**:`MsgDepositForBurnWithCaller`

Broadcast a transaction that deposits for burn with caller to a provided domain.

This message wraps `MsgDepositForBurn`. It adds one extra argument,
`destinationCaller`.

**Arguments**:

* `Amount` - The burn amount
* `DestinationDomain` - Domain of destination chain
* `MintRecipient` - address receiving minted tokens on destination chain as a 32
  length byte array
* `BurnToken` - The burn token address on source domain
* `DestinationCaller` - authorized caller as 32 length byte array of
  receiveMessage() on destination domain

### replaceDepositForBurn

**Message**: `MsgReplaceDepositForBurn`

Broadcast a transaction that replaces a deposit for burn message. Replace the
mint recipient and/or\
destination caller.

Allows the sender of a previous BurnMessage (created by depositForBurn or
depositForBurnWithCaller)\
to send a new BurnMessage to replace the original. The new BurnMessage will
reuse the amount and\
burn token of the original without requiring a new deposit.

**Arguments**:

* `OriginalMessage`- original message bytes to replace
* `OriginalAttestation`- attestation bytes of `OriginalMessage`
* `NewDestinationCaller` - the new destination caller, which may be the\
  same as the original destination caller, a new destination caller, or an
  empty\
  destination caller, indicating that any destination caller is valid.
* `NewMintRecipient` - the new mint recipient. May be the same as the\
  original mint recipient, or different.

### receiveMessage

**Message**: `MsgReceiveMessage`

Broadcast a transaction that receives a provided message from another domain.
After validation, it performs a mint.

**Arguments**:

* `message` [Message Format](/cctp/v1/message-format)
* `attestation` - Concatenated 65-byte signature(s) of `message`, in increasing
  order\
  of the attester address recovered from signatures.

### sendMessage

**Message**:`MsgSendMessage`

Broadcast a transaction that sends a message to a provided domain.

**Arguments**:

* `DestinationDomain` - Domain of destination chain
* `Recipient` - Address of message recipient on destination chain
* `MessageBody` - Raw bytes content of message

### sendMessageWithCaller

**Message**:`MsgSendMessageWithCaller`

Broadcast a transaction that sends a message with a caller to a provided domain.

Specifying a Destination caller requires that only the specified caller can call
`receiveMessage()` on destination domain.

This message wraps `SendMessage` It adds one extra argument,
`DestinationCaller`.

**Arguments**:

* `DestinationDomain` - Domain of destination chain
* `Recipient` - Address of message recipient on destination chain
* `MessageBody` - Raw bytes content of message
* `DestinationCaller` - caller on the destination domain, as 32 length byte
  array

### replaceMessage

**Message**: `MsgReplaceMessage`

Broadcast a transaction that replaces a provided message. Replace the message
body and/or destination caller.

**Arguments**:

* `OriginalMessage` - original message bytes to replace
* `OriginalAttestation` - attestation bytes of `OriginalMessage`
* `NewMessageBody` - new message body of replaced message
* `NewDestinationCaller` - the new destination caller, which may be the same as
  the original destination caller, a new destination caller, or an empty
  destination caller, indicating that any destination caller is valid.


# CCTP Block Confirmations V1
Source: https://developers.circle.com/cctp/v1/required-block-confirmations

Block confirmation requirements for attestations by chain

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

Before signing an attestation for a source chain event, Circle waits for a
specified number of onchain block confirmations to achieve
<Tooltip>hard finality</Tooltip>.

The table below shows the average time required for an attestation to become
available after a message is emitted onchain.

<Note>**Note:** These values are subject to change.</Note>

## CCTP V1 Attestation Times

| Source Chain    | Number of Blocks  | Average Time         |
| --------------- | ----------------- | -------------------- |
| **Ethereum**    | \~65\*            | \~13 to 19 minutes\* |
| **Avalanche**   | 1                 | \~8 seconds          |
| **OP Mainnet**  | \~65 ETH blocks\* | \~13 to 19 minutes\* |
| **Arbitrum**    | \~65 ETH blocks\* | \~13 to 19 minutes\* |
| **Noble**       | 1                 | \~20 seconds         |
| **Base**        | \~65 ETH blocks\* | \~13 to 19 minutes\* |
| **Polygon PoS** | \~33              | \~75 to 120 seconds  |
| **Solana**      | 32                | \~25 seconds         |
| **Sui**         | 1                 | \~8 seconds          |
| **Aptos**       | 1                 | \~8 seconds          |
| **Unichain**    | \~65 ETH blocks\* | \~13 to 19 minutes\* |

<Note>
  **Block confirmations for L2s to Ethereum**

  Layer 2 (L2) blockchains publish transaction data in batches to Ethereum L1, and
  the frequency of these posts varies by chain. Some submit batches every few
  minutes, while others are less frequent. After a batch is posted, Circle waits
  for the Ethereum L1 block containing the batch to finalize, which typically
  happens after \~65 blocks, or 13 to 19 minutes, before issuing an attestation.
</Note>


# CCTP Solana Programs and Interfaces V1
Source: https://developers.circle.com/cctp/v1/solana-programs

Programs for CCTP V1 support on the Solana blockchain

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see
  [CCTP](/cctp)**.
</Warning>

## Overview

Solana CCTP V1 programs are written in Rust and leverage the Anchor framework.
The Solana CCTP V1 protocol implementation is split into two programs:
`MessageTransmitter` and `TokenMessengerMinter`. `TokenMessengerMinter`
encapsulates the functionality of both `TokenMessenger` and `TokenMinter`
contracts on EVM chains. To ensure alignment with EVM contracts' logic and
state, and to facilitate future upgrades and maintenance, the code and state of
Solana programs reflect the EVM counterparts as closely as possible.

### Mainnet Program Addresses

| Program              | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                   |
| :------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| MessageTransmitter   | 5                                    | [`CCTPmbSD7gX1bxKPAmg77w8oFzNFpaQiQUWD43TKaecd`](https://solscan.io/account/CCTPmbSD7gX1bxKPAmg77w8oFzNFpaQiQUWD43TKaecd) |
| TokenMessengerMinter | 5                                    | [`CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3`](https://solscan.io/account/CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3) |

### Devnet Program Addresses

| Program              | [Domain](/cctp/v1/supported-domains) | Address                                                                                                                                  |
| :------------------- | :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| MessageTransmitter   | 5                                    | [`CCTPmbSD7gX1bxKPAmg77w8oFzNFpaQiQUWD43TKaecd`](https://solscan.io/account/CCTPmbSD7gX1bxKPAmg77w8oFzNFpaQiQUWD43TKaecd?cluster=devnet) |
| TokenMessengerMinter | 5                                    | [`CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3`](https://solscan.io/account/CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3?cluster=devnet) |

The Solana CCTP V1 source code is
[available on GitHub](https://github.com/circlefin/solana-cctp-contracts/). The
interface below serves as a reference for permissionless messaging functions
exposed by the programs.

## CCTP V1 Interface

The interface below serves as a reference for permissionless messaging functions
exposed by the `TokenMessengerMinter` and `MessageTransmitter` programs. The
full IDLs can be found onchain using a block explorer.
[MessageTransmitter IDL](https://explorer.solana.com/address/CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3/anchor-program)
and
[TokenMessengerMinter IDL](https://explorer.solana.com/address/CCTPmbSD7gX1bxKPAmg77w8oFzNFpaQiQUWD43TKaecd/anchor-program).

*Please see the instruction rust files or quick-start for PDA information.*

### TokenMessengerMinter

### [depositForBurn](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/instructions/deposit_for_burn.rs)

Deposits and burns tokens from sender to be minted on destination domain. Minted
tokens will be transferred to `mintRecipient`.

**Parameters**

| Field             | Type   | Description                                                                                                                                                                                                   |
| :---------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| amount            | u64    | Amount of tokens to deposit and burn.                                                                                                                                                                         |
| destinationDomain | u32    | Destination domain identifier.                                                                                                                                                                                |
| mintRecipient     | Pubkey | Public Key of token account mint recipient on destination domain. *Address should be the 32 byte version of the hex address in base58. See Additional Notes on `mintRecipient` section for more information.* |

<Note>
  **MessageSent event storage**

  To ensure persistent and reliable message storage, MessageSent events are stored
  in accounts. MessageSent event accounts are generated client-side, passed into
  the instruction call, and assigned to have the `MessageTransmitter` program as
  the owner. Please see the
  [Quickstart Guide](/cctp/v1/transfer-usdc-on-testnet-from-ethereum-to-avalanche)
  for how to generate this account and pass it to the instruction call.

  For `depositForBurn` messages, this costs `~0.00295104 SOL` in rent. *This rent
  is paid by the
  [`event_rent_payer`](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/instructions/send_message.rs#L16C9-L16C25)
  account which can be the user or subsidized by a calling program or integrator.*

  Once an attestation is available and the message has been received on the
  destination chain, the event account can be closed and have the SOL reclaimed to
  the `event_rent_payer` account. This is done by calling the
  [`reclaim_event_account`](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/instructions/reclaim_event_account.rs)
  instruction. This can only be called by the `event_rent_payer` account from when
  the message was sent.

  Details on the message format can be found on the
  [Message Format page](/cctp/v1/message-format).
</Note>

### [depositForBurnWithCaller](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/instructions/deposit_for_burn_with_caller.rs)

The same as `depositForBurn` but with an additional parameter,
`destinationCaller`. This parameter specifies which address has permission to
call `receiveMessage` on the destination domain for the message.

**Parameters**

| Field             | Type   | Description                                                                                                                                                                                                   |
| :---------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| amount            | u64    | Amount of tokens to deposit and burn.                                                                                                                                                                         |
| destinationDomain | u32    | Destination domain identifier.                                                                                                                                                                                |
| mintRecipient     | Pubkey | Public Key of mint recipient on destination domain. *Address should be converted to base58.* See \[Mint Recipient for Solana as Source Chain Transfers]\(Mint Recipient for Solana as Source Chain Transfers) |
| destinationCaller | Pubkey | Public Key of caller on destination domain. *Address should be converted to base58.*                                                                                                                          |

### [replaceDepositForBurn](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/instructions/replace_deposit_for_burn.rs)

Replace a `BurnMessage` to change the mint recipient and/or destination caller.
Allows the sender of a previous `BurnMessage` (created by `depositForBurn` or
`depositForBurnWithCaller`) to send a new `BurnMessage` to replace the original.
The new `BurnMessage` will reuse the amount and burn token of the original,
without requiring a new deposit.

This is useful in situations where the user specified an incorrect address and
has no way to safely mint the previously burned USDC.

<Note>
  **Note on replaceDepositForBurn**

  Only the owner account of the original depositForBurn has access to call
  replaceDepositForBurn. The resulting mint will supersede the original mint, as
  long as the original mint has not confirmed yet onchain. When using a
  third-party app/bridge that integrates with CCTP V1 to burn and mint USDC, it is
  the choice of the app/bridge if and when to replace messages on behalf of users.
  When sending USDC to smart contracts, be aware of the functionality that those
  contracts have and their respective trust model.
</Note>

**Parameters**

| Field                | Type     | Description                                                                                                                                                                                                                               |
| :------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| originalMessage      | Vec\<u8> | Original message bytes (to replace).                                                                                                                                                                                                      |
| originalAttestation  | Vec\<u8> | Original attestation bytes.                                                                                                                                                                                                               |
| newDestinationCaller | Pubkey   | The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller, indicating that any destination caller is valid. *Address should be converted to base58.* |
| newMintRecipient     | Pubkey   | The new mint recipient, which may be the same as the original mint recipient, or different. *Address should be converted to base58.*                                                                                                      |

### MessageTransmitter

### [receiveMessage](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/instructions/receive_message.rs)

Messages with a given nonce can only be broadcast successfully once for a pair
of domains. The message body of a valid message is passed to the specified
recipient for further processing.

**Parameters**

| Field       | Type     | Description                    |
| :---------- | :------- | :----------------------------- |
| message     | Vec\<u8> | Message bytes.                 |
| attestation | Vec\<u8> | Signed attestation of message. |

**Remaining Accounts**

If the `receiveMessage` instruction is being called with a deposit for burn
message that will be received by the `TokenMessengerMinter`, additional
`remainingAccounts` are required so they can be passed with the CPI to
`TokenMessengerMinter#handleReceiveMessage`:

| Account Name                    | PDA Seeds                                             | PDA ProgramId        | isSigner? | isWritable? | Description                                                                                                                                                           |
| :------------------------------ | :---------------------------------------------------- | :------------------- | :-------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token_messenger`               | `["token_messenger"]`                                 | tokenMessengerMinter | false     | false       | TokenMessenger Program Account                                                                                                                                        |
| `remote_token_messenger`        | `["remote_token_messenger", sourceDomainId]`          | tokenMessengerMinter | false     | false       | Remote token messenger account where the remote token messenger address is stored for the given source domain id                                                      |
| `token_minter`                  | `["token_minter"]`                                    | tokenMessengerMinter | false     | true        | TokenMinter Program Account                                                                                                                                           |
| `local_token`                   | `["local_token", localTokenMint.publicKey]`           | tokenMessengerMinter | false     | true        | Local token account where the information for the local token (e.g. USDCSOL) being minted is stored                                                                   |
| `token_pair`                    | `["token_pair", sourceDomainId, sourceTokenInBase58]` | tokenMessengerMinter | false     | false       | Token pair account where the info for the local and remote tokens are stored. `sourceTokenInBase58` is the remote token that was burned converted into base58 format. |
| `user_token_account`            | N/A                                                   | N/A                  | false     | true        | User token account that will receive the minted tokens. This address **must** match the mintRecipient from the source chain depositForBurn call.                      |
| `custody_token_account`         | `["custody", localTokenMint.publicKey]`               | tokenMessengerMinter | false     | true        | Custody account that holds the pre-minted USDCSOL that can be minted for CCTP V1 usage.                                                                               |
| `SPL.token_program_id`          | N/A                                                   | N/A                  | false     | false       | The native SPL token program ID.                                                                                                                                      |
| `token_program_event_authority` | `["__event_authority"]`                               | tokenMessengerMinter | false     | false       | Event authority account for the TokenMessengerMinter program. Needed to emit Anchor CPI events.                                                                       |
| `program`                       | N/A                                                   | N/A                  | false     | false       | Program id for the TokenMessengerMinter program.                                                                                                                      |

### [sendMessage](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/instructions/send_message.rs)

Sends a message to the destination domain and recipient. Emits a `MessageSent`
event which will be attested by Circle's attestation service.

**Parameters**

| Field             | Type     | Description                                              |
| :---------------- | :------- | :------------------------------------------------------- |
| destinationDomain | u32      | Destination domain identifier.                           |
| recipient         | Pubkey   | Address to handle message body on destination domain.    |
| messageBody       | Vec\<u8> | Application-specific message to be handled by recipient. |

### [sendMessageWithCaller](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/instructions/send_message_with_caller.rs)

Same as `sendMessage` but with an additional parameter, `destinationCaller`.
This parameter specifies which address has permission to call `receiveMessage`
on the destination domain for the message.

**Parameters**

| Field             | Type     | Description                                                                           |
| :---------------- | :------- | :------------------------------------------------------------------------------------ |
| destinationDomain | u32      | Destination domain identifier.                                                        |
| recipient         | Pubkey   | Address of message recipient on destination domain.                                   |
| destinationCaller | Pubkey   | Address of caller on the destination domain. *Address should be converted to base58.* |
| messageBody       | Vec\<u8> | Application-specific message to be handled by recipient.                              |

### [replaceMessage](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/instructions/replace_message.rs)

Replace a message with a new message body and/or destination caller. The
`originalAttestation` must be a valid attestation of `originalMessage`, produced
by Circle's attestation service.

**Parameters**

| Field                | Type     | Description                                                                                                                                                                                                                                                                   |
| :------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| originalMessage      | Vec\<u8> | Original message to replace.                                                                                                                                                                                                                                                  |
| originalAttestation  | Vec\<u8> | Attestation of originalMessage.                                                                                                                                                                                                                                               |
| newMessageBody       | Vec\<u8> | New message body of replaced message.                                                                                                                                                                                                                                         |
| newDestinationCaller | Pubkey   | The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller (bytes32(0) or `PublicKey.default`, indicating that any destination caller is valid). *Address should be converted to base58.* |

### [reclaimEventAccount](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/instructions/reclaim_event_account.rs)

Closes the given event account and reclaims the paid rent in SOL back to the
`event_rent_payer` account. This instruction can only be called by the
`event_rent_payer` account that paid the rent when the message was sent.

**Parameters**

| Field       | Type     | Description                                                                                                                                                            |
| :---------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| attestation | Vec\<u8> | Valid attestation for the message stored in the account. This is required to ensure the attestation service has processed and stored the message before it is deleted. |

<Warning>
  **Warning**

  Once this instruction is executed for a message account, the message can no
  longer be read onchain. We recommend not calling this instruction until the
  message has been received on the destination chain. If the message is lost
  before receiving the message, it can be fetched from the attestation service
  using the [messages endpoint](/api-reference/cctp/all/get-messages).
</Warning>

## Additional Notes

### Mint Recipient for Solana as Destination Chain Transfers

When calling `depositForBurn` on a non-Solana chain with Solana as the
destination, the `mintRecipient` should be a **hex encoded USDC token account
address**. The token account\* must exist at the time `receiveMessage` is called
on Solana\* or else this instruction will revert. An example of converting an
address from Base58 to hex taken from the Solana quickstart tutorial in
TypeScript can be seen below:

```typescript TypeScript theme={null}
import { bs58 } from "@coral-xyz/anchor/dist/cjs/utils/bytes";
import { hexlify } from "ethers";

const solanaAddressToHex = (solanaAddress: string): string =>
  hexlify(bs58.decode(solanaAddress));
```

### Mint Recipient for Solana as Source Chain Transfers

When specifying the `mintRecipient` for Solana `deposit_for_burn` instruction
calls, the address must be given as the 32 byte version of the hex address in
base58 format. An example taken from the Solana quickstart tutorial in
TypeScript can be seen below:

```typescript TypeScript theme={null}
import { getBytes } from "ethers";
import { PublicKey } from "@solana/web3.js";

const evmAddressToBytes32 = (address: string): string =>
  `0x000000000000000000000000${address.replace("0x", "")}`;

const evmAddressToBase58PublicKey = (addressHex: string): PublicKey =>
  new PublicKey(getBytes(evmAddressToBytes32(addressHex)));
```

### Program Events

Program events like
[DepositForBurn](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/events.rs#L35-L45)
,
[MintAndWithdraw](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/events.rs#L47-L52)
, and
[MessageReceived](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/token-messenger-minter/src/token_messenger/events.rs#L47-L52)
are emitted as Anchor CPI events. This means a self-CPI is made into the program
with the serialized event as instruction data so it is persisted in the
transaction and can be fetched later on as needed. More information can be seen
in the
[Anchor implementation PR](https://github.com/coral-xyz/anchor/pull/2438), and
an example of reading CPI events can be seen in the
[solana-cctp-contracts repository](https://github.com/circlefin/solana-cctp-contracts/blob/master/tests/utils.ts#L62-L111).

[MessageSent](https://github.com/circlefin/solana-cctp-contracts/blob/master/programs/message-transmitter/src/events.rs#L49-L55)
events are different, as they are stored in accounts. Please see the
[MessageSent Event Storage section](#depositforburn) for more info.


# CCTP Sui Packages and Interfaces V1
Source: https://developers.circle.com/cctp/v1/sui-packages

Packages for CCTP V1 support on the Sui blockchain

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

## Overview

The CCTP V1 Sui smart contract implementation is written in
[Move](https://sui.io/move). The Sui CCTP V1 implementation is split into two
packages: `MessageTransmitter` and `TokenMessengerMinter`.
`TokenMessengerMinter` encapsulates the functionality of both `TokenMessenger`
and `TokenMinter` contracts on EVM chains. To ensure alignment with EVM
contracts logic and state, and to facilitate future upgrades and maintenance,
the code and state of the Sui packages reflect the EVM counterparts as closely
as possible.

There are a few key differences with Sui packages from EVM and other CCTP V1
implementations:

### Receive Message Flow

Since the Move language does not have interfaces, the
`message_transmitter::receive_message()` function cannot call directly into the
receiver package (e.g. `TokenMessenger` for USDC transfers). The workaround for
this limitation is that callers of `receive_message()` must also atomically (in
the same
[Programmable Transaction Block (PTB)](https://docs.sui.io/concepts/transactions/prog-txn-blocks))
call into the receiver package's `handle_receive_message()` function with a
`Receipt` struct, call `stamp_receipt()` with the `StampReceiptTicket` struct
returned from `handle_receive_message()`, and then pass the `StampedReceipt`
back into the `message_transmitter::complete_receive_message()` function to
complete the message and destroy the `Receipt` object. This flow ensures
atomicity and guarantees message receipt by the receiver packages. Please see
the interface and examples below for more information on this flow.

### Interacting with TokenMessengerMinter from other Packages

On Sui, when a package is upgraded, the new version is deployed with a new
package ID. This means if another package is directly calling a version-gated
function, when the package is upgraded, the dependent packages must also be
upgraded. To address this, all CCTP V1 functions that are intended to be called
from a dependent package follow a `Ticket` struct pattern. In this pattern, the
dependent package can call non version-gated `create_ticket()` functions with
the intended function parameters, including an `Auth` struct (used to uniquely
identify the package), and receive back a `Ticket` struct. This struct can then
be returned from the dependent package and used in a PTB to call the intended
CCTP V1 function. This allows integrators to securely integrate with CCTP V1
functions from their packages, and only have to update PTBs when CCTP V1
packages are upgraded rather than having to upgrade their packages as well. For
more information, see the functions below with the `_with_package_auth` suffix.

### Testnet

#### Package IDs

| Package              | [Domain](/cctp/v1/supported-domains) | Address                                                              |
| :------------------- | :----------------------------------- | :------------------------------------------------------------------- |
| MessageTransmitter   | 8                                    | `0x4931e06dce648b3931f890035bd196920770e913e43e45990b383f6486fdd0a5` |
| TokenMessengerMinter | 8                                    | `0x31cc14d80c175ae39777c0238f20594c6d4869cfab199f40b69f3319956b8beb` |

#### Shared Object IDs

| Object                    | Object ID                                                            |
| :------------------------ | :------------------------------------------------------------------- |
| MessageTransmitterState   | `0x98234bd0fa9ac12cc0a20a144a22e36d6a32f7e0a97baaeaf9c76cdc6d122d2e` |
| TokenMessengerMinterState | `0x5252abd1137094ed1db3e0d75bc36abcd287aee4bc310f8e047727ef5682e7c2` |
| USDC Treasury Object      | `0x7170137d4a6431bf83351ac025baf462909bffe2877d87716374fb42b9629ebe` |

Branch with testnet
[Automated Address Management](https://docs.sui.io/concepts/sui-move-concepts/packages/automated-address-management):
[github.com/circlefin/sui-cctp/tree/testnet](https://github.com/circlefin/sui-cctp/tree/testnet).

### Mainnet

#### Package IDs

| Package              | [Domain](/cctp/v1/supported-domains) | Address                                                              |
| :------------------- | :----------------------------------- | :------------------------------------------------------------------- |
| MessageTransmitter   | 8                                    | `0x08d87d37ba49e785dde270a83f8e979605b03dc552b5548f26fdf2f49bf7ed1b` |
| TokenMessengerMinter | 8                                    | `0x2aa6c5d56376c371f88a6cc42e852824994993cb9bab8d3e6450cbe3cb32b94e` |

#### Shared Object IDs

| Object                    | Object ID                                                            |
| :------------------------ | :------------------------------------------------------------------- |
| MessageTransmitterState   | `0xf68268c3d9b1df3215f2439400c1c4ea08ac4ef4bb7d6f3ca6a2a239e17510af` |
| TokenMessengerMinterState | `0x45993eecc0382f37419864992c12faee2238f5cfe22b98ad3bf455baf65c8a2f` |
| USDC Treasury Object      | `0x57d6725e7a8b49a7b2a612f6bd66ab5f39fc95332ca48be421c3229d514a6de7` |

Branch with mainnet
[Automated Address Management](https://docs.sui.io/concepts/sui-move-concepts/packages/automated-address-management):
[github.com/circlefin/sui-cctp/tree/mainnet](https://github.com/circlefin/sui-cctp/tree/mainnet).

## Interface

The Sui CCTP V1 source code is
[available on GitHub](https://github.com/circlefin/sui-cctp/).

The interface below serves as a reference for permissionless messaging functions
exposed by the programs.

### TokenMessengerMinter

#### [deposit\_for\_burn](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L106)

Burns passed in tokens from sender to be minted on destination domain. Minted
tokens will be transferred to `mint_recipient` on the destination chain. The
`deposit_for_burn` interface and functionality is very similar to the EVM
implementation. The coins parameter is the key difference due to how passing
tokens around on Sui works. `message_transmitter_state`, `deny_list`, and
`treasury` parameters are all shared objects.

**Remarks:**

* Intended to be called directly by EOA (rather than a dependent package). The
  initiating EOA will be the "owner" (e.g. message sender) of the message and
  have the ability to call `replace_deposit_for_burn()` to update the
  `mint_recipient` or `destination_caller`. If the calling EOA is not trusted by
  the mint recipient or destination caller,
  `deposit_for_burn_with_package_auth()` should be called instead with the
  integrating package owning the message.
* The generic type T is the coin's one-time witness
  ([OTW](https://docs.sui.io/concepts/sui-move-concepts/one-time-witness)) type
  for the specific coin type to be burned.
* `BurnMessage` and `Message` structs are returned, but it is not required to do
  anything with these structs; they are returned for convenience.

**Parameters**

| Field                       | Type                           | Description                                                                                                                                                                                       |
| :-------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| coins                       | `Coin<T>`                      | Coin of type T to be burned. Full amount in coins will be burned.                                                                                                                                 |
| destination\_domain         | `u32`                          | Destination domain identifier.                                                                                                                                                                    |
| mint\_recipient             | `address`                      | Address of mint recipient on destination domain. *Note: If destination is a non-Move chain,* `mint_recipient` *address should be converted to hex and passed in using the @0x123 address format.* |
| state                       | `&State`                       | Shared State object for the `TokenMessengerMinter` package.                                                                                                                                       |
| message\_transmitter\_state | `&mut MessageTransmitterState` | Shared State object for the `MessageTransmitter` package.                                                                                                                                         |
| deny\_list                  | `&DenyList`                    | DenyList shared object for the stablecoin token T. Constant address: `0x403`                                                                                                                      |
| treasury                    | `&mut Treasury<T>`             | Treasury shared object for the stablecoin token T.                                                                                                                                                |
| ctx                         | `&TxContext`                   | `TxContext` for the transaction.                                                                                                                                                                  |

#### [deposit\_for\_burn\_with\_package\_auth](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L143)

Same as `deposit_for_burn()`, but intended to be called with an `Auth` struct
from a dependent package. The calling package will be the "owner" (e.g.
message\_sender) of the message and have the ability to call
`replace_deposit_for_burn_with_package_auth()` to update the mint recipient or
destination caller. This would be similar to a wrapper contract on EVM chains
calling into `TokenMessenger` and being the message sender. Direct callers
(where EOAs are trusted and should be the owner) should use `deposit_for_burn()`
instead.

**Remarks:**

* This function uses a `DepositForBurnTicket` struct for parameters so that the
  calling package can call `create_deposit_for_burn_ticket()` (not
  version-gated) from their package with parameters, and call
  `deposit_for_burn_with_package_auth()` (version-gated) from a PTB so packages
  don't have to be updated during CCTP V1 package upgrades.
* `DepositForBurnTicket` also requires an `Auth` parameter. This is required to
  securely assign a sender address associated with the calling contract to the
  message. Any struct that implements the drop trait can be used as an
  authenticator, but it is recommended to use a dedicated `Auth` struct. Calling
  contracts should be careful to not expose these structs to the public or else
  messages from their package could be replaced. An example can be found in
  `TokenMessengerMinter`
  [on GitHub](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move).
* The returned structs - `BurnMessage` and `Message` both have the copy ability.
  There is also no guarantee of execution ordering, so your package could create
  5 DepositForBurnTickets in one transaction and they could be executed in any
  order depending on the PTB. Integrating packages should account for both of
  these scenarios.

**Parameters**

| Field                       | Type                            | Description                                                                    |
| :-------------------------- | :------------------------------ | :----------------------------------------------------------------------------- |
| deposit\_for\_burn\_ticket  | `DepositForBurnTicket<T, Auth>` | Struct containing parameters and authenticator struct.                         |
| state                       | `&State`                        | Shared `State` object for the `TokenMessengerMinter` package.                  |
| message\_transmitter\_state | `&mut MessageTransmitterState`  | Shared `State` object for the `MessageTransmitter` package.                    |
| deny\_list                  | `&DenyList`                     | DenyList shared object for the stablecoin token `T`. Constant address: `0x403` |
| treasury                    | `&mut Treasury<T>`              | Treasury shared object for the stablecoin token `T`.                           |
| ctx                         | `&TxContext`                    | `TxContext` for the transaction.                                               |

#### [deposit\_for\_burn\_with\_caller](https://github.com/circlefin/sui-cctp/blob/649ed8a06840271ddc1ad66bb215d51be8265c31/packages/token_messenger_minter/sources/deposit_for_burn.move#L177)

Same as `deposit_for_burn` but with an additional parameter,
`destination_caller`. This parameter specifies which address has permission to
call `receive_message` on the destination domain for the message.

**Remarks:**

* Intended to be called directly by EOA (rather than a dependent package). The
  initiating EOA will be the "owner" (e.g. message sender) of the message and
  have the ability to call `replace_deposit_for_burn()` to update the
  `mint_recipient` or `destination_caller`. If the calling EOA is not trusted by
  the mint recipient or destination caller,
  `deposit_for_burn_with_caller_with_package_auth()` should be called instead
  with the integrating package owning the message.

<Note>
  **Destination Caller Notes**

  If the `destination_caller` does not represent a valid address, then it will not
  be possible to broadcast the message on the destination domain. This is an
  advanced feature, and the standard `deposit_for_burn` should be preferred for
  use cases where a specific destination caller is not required.

  *Note: If destination is a non-Move chain,* `destination_caller` *address should
  be converted to hex and passed in using the @0x123 address format.*
</Note>

**Parameters**

| Field                       | Type                           | Description                                                                                                                                                                                      |
| :-------------------------- | :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| coins                       | `Coin<T>`                      | Coin of type T to be burned. Full amount in coins will be burned.                                                                                                                                |
| destination\_domain         | `u32`                          | Destination domain identifier.                                                                                                                                                                   |
| mint\_recipient             | `address`                      | Address of mint recipient on destination domain *Note: If destination is a non-Move chain,* `mint_recipient` *address should be converted to hex and passed in using the @0x123 address format.* |
| destination\_caller         | `address`                      | Address of caller on destination chain.                                                                                                                                                          |
| state                       | `&State`                       | Shared `State` object for the `TokenMessengerMinter` package.                                                                                                                                    |
| message\_transmitter\_state | `&mut MessageTransmitterState` | Shared `State` object for the `MessageTransmitter` package.                                                                                                                                      |
| deny\_list                  | `&DenyList`                    | DenyList shared object for the stablecoin token T. Constant address: `0x403`                                                                                                                     |
| treasury                    | `&mut Treasury<T>`             | Treasury shared object for the stablecoin token T.                                                                                                                                               |
| ctx                         | `&TxContext`                   | `TxContext` for the transaction.                                                                                                                                                                 |

#### [deposit\_for\_burn\_with\_caller\_with\_package\_auth](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L212)

The same as `deposit_for_burn_with_caller()`, but intended to be called with an
`Auth` struct from a dependent package. The calling package will be the "owner"
(e.g. message\_sender) of the message and have the ability to call
`replace_deposit_for_burn_with_package_auth()` to update the `mint_recipient` or
`destination_caller`. This would be similar to a wrapper contract on EVM chains
calling into `TokenMessenger` and being the message sender. Direct callers
(where EOAs are trusted and should be the owner) should use
`deposit_for_burn_with_caller()` instead.

**Remarks:**

* This function uses a `DepositForBurnWithCallerTicket` struct for parameters so
  that the calling package can call
  `create_deposit_for_burn_with_caller_ticket()` (not version-gated) from their
  package, and call `deposit_for_burn_with_caller_with_package_auth()`
  (version-gated) from a PTB so dependent packages don't have to be updated
  during upgrades.
* `DepositForBurnWithCallerTicket` also requires an `Auth` parameter. This is
  required to securely assign a sender address associated with the calling
  contract to the message. Any struct that implements the drop trait can be used
  as an authenticator, but it is recommended to use a dedicated struct. Calling
  contracts should be careful to not expose these structs to the public or else
  messages from their package could be replaced. An example can be found in
  `TokenMessengerMinter`
  [on GitHub](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move).

<Note>
  **Destination Caller Notes**

  If the `destination_caller` does not represent a valid address, then it will not
  be possible to broadcast the message on the destination domain. This is an
  advanced feature, and the standard `deposit_for_burn` should be preferred for
  use cases where a specific destination caller is not required.

  *Note: If destination is a non-Move chain,* `destination_caller` *address should
  be converted to hex and passed in using the @0x123 address format.*
</Note>

**Parameters**

| Field                                    | Type                                      | Description                                                                  |
| :--------------------------------------- | :---------------------------------------- | :--------------------------------------------------------------------------- |
| deposit\_for\_burn\_with\_caller\_ticket | `DepositForBurnWithCallerTicket<T, Auth>` | Struct containing parameters and authenticator struct.                       |
| state                                    | `&State`                                  | Shared `State` object for the `TokenMessengerMinter` package.                |
| message\_transmitter\_state              | `&mut MessageTransmitterState`            | Shared `State` object for the `MessageTransmitter` package.                  |
| deny\_list                               | `&DenyList`                               | DenyList shared object for the stablecoin token T. Constant address: `0x403` |
| treasury                                 | `&mut Treasury<T>`                        | Treasury shared object for the stablecoin token T.                           |
| ctx                                      | `&TxContext`                              | `TxContext` for the transaction.                                             |

#### [replace\_deposit\_for\_burn](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L259)

Replace a `BurnMessage` to change the mint recipient and/or destination caller.
Allows the sender of a previous `BurnMessage` (created by `deposit_for_burn` or
`deposit_for_burn_with_caller`) to send a new `BurnMessage` to replace the
original.

**Remarks:**

* The new `BurnMessage` will reuse the amount and burn token of the original,
  without requiring a new `Coin<T>` deposit.
* The resulting mint will supersede the original mint, as long as the original
  mint has not confirmed yet onchain.
* A valid attestation is required before calling this function.
* This is useful in situations where the user specified an incorrect address and
  has no way to safely mint the previously burned USDC.

**Parameters**

| Field                       | Type                           | Description                                                                                                                                                                                      |
| :-------------------------- | :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| original\_message           | `vector<u8>`                   | Original message bytes (to replace).                                                                                                                                                             |
| original\_attestation       | `vector<u8>`                   | Original attestation bytes.                                                                                                                                                                      |
| new\_destination\_caller    | `Option<address>`              | The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller, indicating that any destination caller is valid. |
| new\_mint\_recipient        | `Option<address>`              | The new mint recipient, which may be the same as the original mint recipient, or different.                                                                                                      |
| state                       | `&State`                       | Shared State object for the `TokenMessengerMinter` package.                                                                                                                                      |
| message\_transmitter\_state | `&mut MessageTransmitterState` | Shared State object for the `MessageTransmitter` package.                                                                                                                                        |
| ctx                         | `&TxContext`                   | `TxContext` for the transaction.                                                                                                                                                                 |

#### [replace\_deposit\_for\_burn\_with\_package\_auth](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L282)

Same as `replace_deposit_for_burn()`, but intended to be called when
`deposit_for_burn_with_package_auth()` or
`deposit_for_burn_with_caller_with_package_auth()` was called for the original
message where the calling package is the message sender.

**Remarks:**

* This function uses a `ReplaceDepositForBurnTicket` struct for parameters so
  that the calling package can call `create_replace_deposit_for_burn_ticket()`
  (not version-gated) from their package with parameters, and call
  `deposit_for_burn_with_package_auth()` (version-gated) from a PTB so packages
  don't have to be updated during CCTP V1 package upgrades.

**Parameters**

| Field                               | Type                                | Description                                                 |
| :---------------------------------- | :---------------------------------- | :---------------------------------------------------------- |
| replace\_deposit\_for\_burn\_ticket | `ReplaceDepositForBurnTicket<Auth>` | Struct containing parameters and authenticator struct.      |
| state                               | `&State`                            | Shared State object for the `TokenMessengerMinter` package. |
| message\_transmitter\_state         | `&mut MessageTransmitterState`      | Shared State object for the `MessageTransmitter` package.   |
| ctx                                 | `&TxContext`                        | `TxContext` for the transaction.                            |

#### [handle\_receive\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/handle_receive_message.move#L131)

Handles an incoming message from `MessageTransmitter`, and mints USDC to the
recipient for valid messages. This function can only be called with a mutable
reference to a `Receipt` object, which can only be created via a call with a
valid message to the `message_transmitter::receive_message()` function.

`state`, `mt_state`, `deny_list`, and `treasury` parameters are all shared
objects.

**Remarks:**

* Returns a `StampReceiptTicketWithBurnMessage` struct that can be deconstructed
  in a dependent package (or in a PTB) via
  `deconstruct_stamp_receipt_ticket_with_burn_message()`. This struct is
  returned so that dependent packages can associate the `BurnMessage` and
  `StampReceiptTicket` together from a PTB call and guarantee that
  `stamp_receipt()` was called.
* This must be called in a single PTB after calling `receive_message()` and
  before calling `complete_receive_message()`. See the
  [Examples](/cctp/v1/transfer-usdc-on-testnet-from-sui-to-ethereum) page for
  the entire flow of receiving a message.

**Parameters**

| Field      | Type               | Description                                                                  |
| :--------- | :----------------- | :--------------------------------------------------------------------------- |
| receipt    | `Receipt`          | Original message bytes (to replace).                                         |
| state      | `&State`           | Shared State object for the `TokenMessengerMinter` package.                  |
| deny\_list | `&DenyList`        | DenyList shared object for the stablecoin token T. Constant address: `0x403` |
| treasury   | `&mut Treasury<T>` | Treasury shared object for the stablecoin token T.                           |
| ctx        | `&TxContext`       | `TxContext` for the transaction.                                             |

### MessageTransmitter

#### [receive\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/receive_message.move#L113)

Receives a message emitted from a source chain. Messages with a given nonce can
only be received once for a (`sourceDomain`, `destinationDomain`) pair.

**Remarks:**

* This function returns a `Receipt`
  [Hot Potato](https://medium.com/@borispovod/move-hot-potato-pattern-bbc48a48d93c)
  struct after validating the attestation and marking the nonce as used.
* In order to destroy the `Receipt` and complete the message, in a single PTB,
  `stamp_receipt()` must be called with the `Receipt` and an `Auth` struct (see
  [message\_transmitter\_authenticator](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L212)
  for an example of this), and then `complete_receive_message()` must be called
  with the `StampedReceipt` to emit the `MessageReceived` event and complete the
  message.
* The receipt/stamp pattern is used to enforce atomicity and ensure the intended
  receiver contract is called.
* Intended to be called directly from an EOA when a package `destination_caller`
  is not specified on the message. Please use
  `receive_message_with_package_auth()` if a package `destination_caller` is
  specified.

**Parameters**

| Field       | Type         | Description                                                 |
| :---------- | :----------- | :---------------------------------------------------------- |
| message     | `vector<u8>` | Message bytes.                                              |
| attestation | `vector<u8>` | Signed attestation of message.                              |
| state       | `&mut State` | Shared State object for the `TokenMessengerMinter` package. |
| ctx         | `&TxContext` | `TxContext` for the transaction.                            |

#### [receive\_message\_with\_package\_auth](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/receive_message.move#L146)

Same as `receive_message()`, except intended to be used by a dependent package
when a package is specified as `destination_caller` (rather than an EOA).

**Remarks:**

* This function is version-gated and should be called from a PTB to prevent
  breaking changes when an upgrade occurs.
* This function uses a `ReceiveMessageTicket` for parameters so that the calling
  package can call `create_receive_message_ticket()` (not version-gated) from
  their package with parameters, and call `receive_message_with_package_auth()`
  (version-gated) from a PTB so packages don't have to be upgraded during CCTP
  V1 package upgrades.
* `ReceiveMessageTicket` also requires an `Auth` parameter. This is required
  whenever a package is assigned as a `destination_caller`. `destination_caller`
  address should be set to the `Auth` identifier returned from the
  `auth_caller_identifier()` function with the package's `Auth` struct. Any
  struct that implements the drop trait can be used as an authenticator, but it
  is recommended to use a dedicated `Auth` struct. Calling contracts should be
  careful to not expose these structs to the public or else messages intended
  for their package could be received by others. An example can be found in
  `TokenMessengerMinter`
  [on GitHub](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move).

**Parameters**

| Field                    | Type                         | Description                                                                         |
| :----------------------- | :--------------------------- | :---------------------------------------------------------------------------------- |
| receive\_message\_ticket | `ReceiveMessageTicket<Auth>` | A `Ticket` struct containing the message, attestation, and an authenticator struct. |
| state                    | `&mut State`                 | Shared State object for the `TokenMessengerMinter` package.                         |
| ctx                      | `&TxContext`                 | `TxContext` for the transaction.                                                    |

#### [stamp\_receipt](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/receive_message.move#L164)

Stamps a `Receipt` struct after verifying the intended package acknowledged the
message (through the `Auth` struct) by returning a `StampedReceipt` struct that
can be used to complete the message via `complete_receive_message()`.

**Remarks:**

* This function is version-gated and should be called from a PTB to prevent
  breaking changes in dependent packages when a CCTP V1 upgrade occurs.
* `create_stamp_receipt_ticket()` is safe to be called directly from a package
  (not version-gated), and it's returned `Ticket` struct can be passed into
  `stamp_receipt()` in a PTB.

<Note>
  **Auth Parameter Notes**

  This is required for the `MessageTransmitter` module to approve a `Receipt`
  prior to its deletion. Any struct that implements the drop trait can be used as
  an authenticator, but it is recommended to use a dedicated `Auth` struct.
  Calling contracts should be careful to not expose these `Auth` structs to the
  public to avoid messages being wrongly stamped. An example implementation exists
  in the `token_messenger_minter::message_transmitter_authenticator` module.
</Note>

**Parameters**

| Field                  | Type                       | Description                                                                                      |
| :--------------------- | :------------------------- | :----------------------------------------------------------------------------------------------- |
| stamp\_receipt\_ticket | `StampReceiptTicket<Auth>` | `Ticket` struct created by `create_stamp_receipt_ticket()` with the `Receipt` and `Auth` struct. |
| state                  | `&mut State`               | Shared State object for the `TokenMessengerMinter` package.                                      |
| ctx                    | `&TxContext`               | `TxContext` for the transaction.                                                                 |

#### [complete\_receive\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/receive_message.move#L178)

Completes the message by emitting a `MessageReceived` event for a stamped
receipt and destroying the receipt. Cannot be called without a `StampedReceipt`
(returned from `stamp_receipt()`).

**Parameters**

| Field            | Type             | Description                                                 |
| :--------------- | :--------------- | :---------------------------------------------------------- |
| stamped\_receipt | `StampedReceipt` | A stamped receipt returned from a `stamp_receipt()` call.   |
| state            | `&State`         | Shared State object for the `TokenMessengerMinter` package. |

#### [send\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/send_message.move#L66)

Sends a message to the destination domain and recipient. The created `Message`
struct is returned, but it is not required to do anything with this struct, it
is returned for convenience.

**Remarks:**

* This function uses a `SendMessageTicket` for parameters so that the calling
  package can call `create_send_message_ticket()` (not version-gated) from their
  package with parameters, and call `send_message()` (version-gated) from a PTB
  so packages don't have to be updated during CCTP V1 package upgrades.
* For USDC transfers, this function is called directly by the
  `TokenMessengerMinter` package in `deposit_for_burn()`.
* `SendMessageTicket` also requires an `Auth` parameter. This is required in
  order to assign a `sender` to the message. Any struct that implements the drop
  trait can be used as an authenticator, but it is recommended to use a
  dedicated `Auth` struct. Calling contracts should be careful to not expose
  these objects to the public or else their messages could be replaced. An
  example can be found in `TokenMessengerMinter`
  [on GitHub](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move).
* The returned struct (`Message`) has the copy ability. There is also no
  guarantee of execution ordering, so your package could create 5
  `SendMessageTickets` in one transaction and they could be executed in any
  order depending on the PTB. Integrating packages should account for both of
  these scenarios.

**Parameters**

| Field                 | Type                      | Description                                                                                                 |
| :-------------------- | :------------------------ | :---------------------------------------------------------------------------------------------------------- |
| send\_message\_ticket | `SendMessageTicket<Auth>` | A struct containing the necessary information to send a message created via `create_send_message_ticket()`. |
| state                 | `&mut State`              | Shared State object for the `TokenMessengerMinter` package.                                                 |

### [send\_message\_with\_caller](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/send_message.move#L85)

Same as `send_message()` but with an additional parameter, `destination_caller`.
This parameter specifies which address has permission to call
`receive_message()` on the destination domain for the message.

**Parameters**

| Field                               | Type                                | Description                                                                                                             |
| :---------------------------------- | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
| send\_message\_with\_caller\_ticket | `SendMessageWithCallerTicket<Auth>` | A struct containing the necessary information to send a message created via `create_send_message_with_caller_ticket()`. |
| state                               | `&mut State`                        | Shared `State` object for the `TokenMessengerMinter` package.                                                           |

### [replace\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/send_message.move#L115https://github.com/circlefin/sui-cctp-private/blob/master/packages/message_transmitter/sources/send_message.move#L146)

Replace a message with a new message body and/or destination caller. The
`original_attestation` must be a valid attestation of `original_message`,
produced by Circle's attestation service.

**Remarks:**

* The sender package of the replaced message must be the same as the caller of
  the original message. This is identified using the `Auth` generic parameter.
  See [stamp\_receipt](#stamp_receipt) for more info on `Auth` structs.

**Parameters**

| Field                    | Type                         | Description                                                                                                    |
| :----------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------- |
| replace\_message\_ticket | `ReplaceMessageTicket<Auth>` | A struct containing the necessary information to send a message created via `create_replace_message_ticket()`. |
| state                    | `&mut State`                 | Shared `State` object for the `TokenMessengerMinter` package.                                                  |

## Additional Notes

### Destination Callers for Sui as Destination Chain

Destination caller is a message field that specifies which address has
permission to call `receive_message()` on the destination domain for the given
message. On Sui this can either be an EOA (use `receive_message()`) or an `Auth`
struct address for a package (use `receive_message_with_package_auth()`). Using
a package destination caller allows integrators to run any atomic action in the
same transaction that the message is received in.

In order to determine the address to use for the destination caller field for
Sui destination messages, please call
`message_transmitter::auth::auth_caller_identifier()` with your `Auth` struct
type.

<Note>
  In order to use a package destination caller with Sui destination messages,
  integrators must create an `Auth` struct in their own package. Any struct that
  implements the drop trait can be used as an authenticator, but it is recommended
  to use a dedicated `Auth` struct. Integrators should be careful to not expose
  these structs to the public or else messages with their package as destination
  caller could be received by others. An example can be found in
  `TokenMessengerMinter`
  [on GitHub](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move).
</Note>

### Mint Recipient Addresses for Sui as Source Chain

Outgoing mint recipient addresses from Sui are passed as Sui address types and
can be treated the same as a `bytes32` mint recipient parameter on EVM
implementations.

### Mint Recipient Addresses for Sui as Destination Chain

Sui mint recipient addresses from other chains should be treated the same as a
hex `bytes32` parameter.

### CCTP V1 Package Upgrades and Versioning

CCTP V1 packages on Sui are upgradable. Public functions like
`deposit_for_burn()`, `receive_message()`, etc. are version-gated. This means if
the CCTP V1 packages are upgraded, the old versions of these functions will no
longer be callable. Because of this, we do not recommend calling these functions
directly from packages, and instead recommend calling the create ticket
functions (not version-gated) directly from dependent packages, returning the
created `Ticket` from your package, and then calling the main public function
(e.g. `deposit_for_burn()` or `receive_message()`) from a PTB. By using the
create ticket functions, dependent packages can securely set the parameters and
`Auth` struct for the function call from within the package, and only have to
update PTBs when CCTP V1 packages are upgraded.

### Integrating with CCTP V1 Sui from other Packages

Integrating with the CCTP V1 Sui packages from other packages is different from
non-Sui implementations. Rather than directly wrapping the CCTP-Sui packages
like one would in Solidity, on Sui packages should interact with CCTP V1
packages in a more composable way. Third party packages should follow the
`Ticket` pattern with a dedicated and private `Auth` struct as described below.

#### Private Auth Structs

`Auth` structs are used throughout the CCTP V1 packages in functions intended to
be called from other dependent packages. The `auth_caller_identifier()` function
is used to uniquely identify other packages by hashing the full object type of
the type passed in. Any struct that implements the drop trait can be used as an
authenticator, but it is recommended to use a dedicated auth struct. Calling
contracts should be careful to not expose these structs to the public or else
messages from their package could be forged. An example can be found in
`TokenMessengerMinter`
[on GitHub](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move).

#### Ticket Pattern

The `Ticket` pattern is a pattern used in CCTP-Sui that enables the
composability of CCTP V1 with third-party packages. The pattern enables a
third-party integrator (package) to create a `Ticket` ("hot potato") for a
designated operation directly in their package without having to upgrade their
packages with future CCTP V1 upgrades. Only PTBs would need to be updated.

`Ticket` structs contain parameters for specific interactions with CCTP V1
packages. They can only be created from and consumed by the CCTP V1 packages in
a specific interaction, and do not have drop or store abilities, so must be used
in the PTB where they are created. They also contain an `Auth` field that should
only be created by the third-party package. The calling PTB should handle the
`Ticket` by calling the relevant CCTP V1 package, which will recognize the
third-party integrator as the action initiator.

The following public functions (designed for third-party integrators, EOAs
should use the entry versions) are implemented following the `Ticket` pattern.
Each of them creates or consumes their own specific `Ticket` type:

**`message_transmitter`:**

* `receive_message_with_package_auth()`
* `stamp_receipt()`

**`token_messenger_minter`:**

* `deposit_for_burn_with_package_auth()`
* `deposit_for_burn_with_caller_with_package_auth()`
* `replace_deposit_for_burn_with_package_auth()`

For example, a typical workflow in a PTB to replace a deposit by an integrator
would be:

1. The integrating package calls `create_replace_deposit_for_burn_ticket()` with
   an `Auth` struct it defined, and returns this ticket.
2. The PTB calls `deposit_for_burn_with_caller_with_package_auth()` with the
   ticket on behalf of the integrator.
3. `token_messenger_minter` will validate if the type hash of `Auth` matches the
   original sender in the burn message.

#### PTB Function Call Ordering

Due to the composability of Sui and PTBs, along with the `Ticket` pattern, there
is no guarantee of ordering of calls within PTBs. The `Ticket` pattern
introduces behaviors similar to asynchronous functions in ordinary programming
contexts: when an integrator creates a ticket and returns it to the PTB, it is
signaling an intention to execute the logic function, and the properties of the
Move type system carry the guarantee that the function will indeed be eventually
executed before the end of the transaction. However, no guarantee is given
regarding the relative order of execution: the PTB is free to consume the
tickets in any order it sees fit. While this has no security implications on the
internal coherence of CCTP V1 itself, integrators should carefully evaluate
whether their own logic is somehow dependent on a specific order of execution of
the CCTP V1 functions.

For example, a PTB could create 5 `DepositForBurnTicket` structs and execute
them in any order. Similarly on the Sui destination side, 5 messages could be
received in `MessageTransmitter`, and then received (and thus the USDC minted)
in `TokenMessengerMinter` in a completely different order. If any pre or post
actions are taken in third party packages, these could also come in an
unexpected ordering, so this scenario should be handled accordingly in third
party packages.

#### Ticket Pattern Examples

An example of this with receiving `deposit_for_burn()` messages on Sui can be
seen below.

This example assumes the `destination_caller` for the message is set to the auth
address for your package's `Auth` struct.

```javascript JavaScript theme={null}
// Prepare the ReceiveMessageTicket by calling create_receive_message_ticket() from within your package.
let receive_msg_ticket = your_package::prepare_receive_message_ticket(message, attestation);
// Receive the message on MessageTransmitter.
let receipt = message_transmitter::receive_message_with_package_auth(receive_msg_ticket, ...);
// Pass the Receipt into TokenMessengerMinter to mint the USDC.
let ticket_with_burn_message = token_messenger_minter::handle_receive_message(receipt, ...);
// In your package you can call deconstruct_stamp_receipt_ticket_with_burn_message to deconstruct the ticket
// and burn_message and securely take some action with the burn_message (e.g. swap some tokens, send them somewhere, etc.)
let stamp_receipt_ticket = your_package::take_some_action(ticket_with_burn_message, ...);
// Stamp the receipt
let stamped_receipt = message_transmitter::stamp_receipt(stamp_receipt_ticket);
// Complete the message and destroy the StampedReceipt
message_transmitter::complete_receive_message(stamped_receipt);
```

A similar example can be seen on the `deposit_for_burn()` side:

```javascript JavaScript theme={null}
// Prepare the DepositForBurnWithCallerTicket by calling create_deposit_for_burn_with_caller_with_package_auth
// directly from your package with the input parameters and your Auth struct. Integrators can also take other
// actions here as needed.
let deposit_for_burn_ticket = your_package::prepare_deposit_for_burn_ticket(coins, ...);
// Call deposit for burn and burn the USDC
let (burn_message, message) = token_messenger_minter::deposit_for_burn_with_caller_with_package_auth(
  deposit_for_burn_ticket,
  ...
);
// Optionally, take some other action in your package based on the output message.
// Note that BurnMessage and Message have the copy ability so the possibility of them being copied should be
// handled in third party packages if post-actions are needed.
your_package::post_deposit_for_burn(burn_message, message, ...);
```


# CCTP Chain Domains V1
Source: https://developers.circle.com/cctp/v1/supported-domains

Mapping of supported CCTP V1 domains

<Warning>
  **This is CCTP V1 version. For the latest version, see [CCTP](/cctp)**.
</Warning>

A **domain** is a Circle-issued identifier for a blockchain where CCTP V1
contracts are deployed. Domains do not map to any existing public chain ID.

## CCTP V1 Domains

| Domain | Name        |
| :----- | :---------- |
| 0      | Ethereum    |
| 1      | Avalanche   |
| 2      | OP          |
| 3      | Arbitrum    |
| 4      | Noble       |
| 5      | Solana      |
| 6      | Base        |
| 7      | Polygon PoS |
| 8      | Sui         |
| 9      | Aptos       |
| 10     | Unichain    |


# Transfer USDC on devnet between Solana and other chains using CCTP V1
Source: https://developers.circle.com/cctp/v1/transfer-testnet-usdc-between-solana-devnet

Explore this tutorial for transferring USDC between Solana devnet and other testnets via CCTP V1

<Warning>
  **This is CCTP V1 version. For the latest version, see [CCTP](/cctp)**.
</Warning>

To get started with CCTP V1 on Solana devnet, follow the
[example scripts](https://github.com/circlefin/solana-cctp-contracts/tree/master/examples).
The examples use [Solana web3.js](https://www.npmjs.com/package/@solana/web3.js)
and [Anchor](https://www.npmjs.com/package/@project-serum/anchor) to transfer
USDC to and from an account on Solana devnet and an address on an external
blockchain.

As a security measure, these scripts should only be used for devnet testing. You
should not reuse private keys across devnet and mainnet.


# Transfer USDC on testnet between Aptos and Base using CCTP V1
Source: https://developers.circle.com/cctp/v1/transfer-usdc-on-testnet-from-aptos-to-base

Explore this tutorial for transferring USDC between Aptos testnet and Base Sepolia Testnet via CCTP V1

<Warning>
  **This is CCTP V1 version. For the latest version, see [CCTP](/cctp)**.
</Warning>

To get started with CCTP V1 on Aptos testnet, follow the example scripts
provided
[on GitHub](https://github.com/circlefin/aptos-cctp/tree/master/typescript/example).
The examples use the
[Aptos SDK](https://www.npmjs.com/package/@aptos-labs/ts-sdk), to transfer USDC
to and from an address on Aptos testnet and an address on an external
blockchain.

<Warning>
  **Do not reuse keys** As a security measure, these scripts should only be used
  on a testnet for testing purposes. It is not recommended to reuse private keys
  across mainnet and testnet.
</Warning>

Summary of calling `deposit_for_burn()` (full runnable script can be found in
the aptos-cctp repository):

```ts theme={null}
// Aptos Testnet Stablecoin object
const BURN_TOKEN =
  "0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832";

const aptosClient = new Aptos(new AptosConfig({ network: Network.TESTNET }));
const userAccount = Account.fromPrivateKey({
  privateKey: new Ed25519PrivateKey(APTOS_PRIVATE_KEY),
});

// Create a transaction with deposit for burn script
const buffer = readFileSync(
  "typescript/example/precompiled-move-scripts/testnet/deposit_for_burn.mv",
);
const bytecode = Uint8Array.from(buffer);
const amount = new U64(1);
const destinationDomain = new U32(6);
const burnToken = AccountAddress.from(BURN_TOKEN);
const mintRecipient = AccountAddress.from(evmSigner.address);
const functionArguments: Array<any> = [
  amount,
  destinationDomain,
  mintRecipient,
  burnToken,
];
const transaction = await aptosClient.transaction.build.simple({
  sender: userAccount.accountAddress,
  data: {
    bytecode,
    functionArguments,
  },
});
const pendingTxn = await aptosClient.signAndSubmitTransaction({
  signer: userAccount,
  transaction,
});
const depositForBurnTx = await aptosClient.waitForTransaction({
  transactionHash: pendingTxn.hash,
});
console.log(
  `Deposit for burn transaction completed successfully: https://explorer.aptoslabs.com/txn/${depositForBurnTx.hash}`,
);

// Fetch the event data from the transaction
const messageSentEvent = (
  depositForBurnTx as UserTransactionResponse
).events.find(
  (e: any) =>
    e.type ===
    `${MESSAGE_TRANSMITTER_PACKAGE_ID}::message_transmitter::MessageSent`,
);
```

Summary of calling `receive_message()` (full runnable script can be found in the
aptos-cctp repository):

```ts theme={null}
const bytecode = Uint8Array.from(
  fs.readFileSync(
    "typescript/example/precompiled-move-scripts/testnet/handle_receive_message.mv",
  ),
);
const functionArguments: Array<any> = [
  MoveVector.U8(messageBytes as Buffer),
  MoveVector.U8(attestationSignature),
];
const transaction = await aptosClient.transaction.build.simple({
  sender: userAccount.accountAddress,
  data: {
    bytecode,
    functionArguments,
  },
});
const pendingTxn = await aptosClient.signAndSubmitTransaction({
  signer: userAccount,
  transaction,
});
const receiveMessageTx = await aptosClient.waitForTransaction({
  transactionHash: pendingTxn.hash,
});
console.log(
  `Receive message transaction completed successfully: https://explorer.aptoslabs.com/txn/${receiveMessageTx.hash}`,
);
```


# Transfer USDC on testnet from Ethereum to Avalanche using CCTP V1
Source: https://developers.circle.com/cctp/v1/transfer-usdc-on-testnet-from-ethereum-to-avalanche

Explore this script to transfer USDC on testnet between two EVM-compatible chains via CCTP V1

<Warning>
  **This is CCTP V1 version. For the latest version, see [CCTP](/cctp)**.
</Warning>

This guide demonstrates how to use the [viem](https://viem.sh/) framework and
the [CCTP V1 API](/cctp/v1/cctp-apis) in a simple script that enables a user to
transfer USDC from a wallet address on the **Ethereum Sepolia testnet** to
another wallet address on the **Avalanche Fuji testnet**.

To get started with CCTP V1, follow the example script provided
[on GitHub](https://github.com/circlefin/evm-cctp-contracts/blob/d1c24577fb627b08483dc42e4d8a37a810b369f7/docs/index.js).
The example uses
[web3.js](https://web3js.readthedocs.io/en/v1.8.1/getting-started.html) to
transfer USDC from a wallet address on Ethereum Sepolia testnet to another
wallet address on Avalanche Fuji testnet.

The script has five steps:

1. In this first step, you initiate a transfer of USDC from one blockchain to
   another, and specify the recipient wallet address on the destination chain.
   This step approves the Ethereum Sepolia **TokenMessenger** contract to
   withdraw USDC from the provided Ethereum Sepolia wallet address.

```javascript JavaScript theme={null}
const approveTx = await usdcEthContract.methods
  .approve(ETH_TOKEN_MESSENGER_CONTRACT_ADDRESS, amount)
  .send({ gas: approveTxGas });
```

2. In this second step, you facilitate a burn of the specified amount of USDC on
   the source chain. This step executes the `depositForBurn` function on the
   Ethereum Sepolia **TokenMessenger** contract deployed on
   [Sepolia testnet](https://sepolia.etherscan.io/address/0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5).

```javascript JavaScript theme={null}
const burnTx = await ethTokenMessengerContract.methods
  .depositForBurn(
    amount,
    AVAX_DESTINATION_DOMAIN,
    destinationAddressInBytes32,
    USDC_ETH_CONTRACT_ADDRESS,
  )
  .send();
```

3. In this third step, you make sure you have the correct message and hash it.
   This step extracts `messageBytes` emitted by the **MessageSent** event from
   `depositForBurn` transaction logs and hashes the retrieved `messageBytes`
   using the **keccak256** hashing algorithm.

```javascript JavaScript theme={null}
const transactionReceipt = await web3.eth.getTransactionReceipt(
  burnTx.transactionHash,
);
const eventTopic = web3.utils.keccak256("MessageSent(bytes)");
const log = transactionReceipt.logs.find((l) => l.topics[0] === eventTopic);
const messageBytes = web3.eth.abi.decodeParameters(["bytes"], log.data)[0];
const messageHash = web3.utils.keccak256(messageBytes);
```

4. In this fourth step, you request the attestation from Circle, which provides
   authorization to mint the specified amount of USDC on the destination chain.
   This step polls the attestation service to acquire the signature using the
   `messageHash` from the previous step.

<Note>
  **Rate Limit**

  The attestation service rate limit is 35 requests per second. If you exceed 35
  requests per second, the service blocks all API requests for the next 5 minutes
  and returns an HTTP 429 response.
</Note>

```javascript JavaScript theme={null}
let attestationResponse = { status: "pending" };
while (attestationResponse.status != "complete") {
  const response = await fetch(
    `https://iris-api-sandbox.circle.com/attestations/${messageHash}`,
  );
  attestationResponse = await response.json();
  await new Promise((r) => setTimeout(r, 2000));
}
```

5. In this final step, you enable USDC to be minted on the destination chain.
   This step calls the `receiveMessage` function on the Avalanche Fuji
   **MessageTransmitter** contract to receive USDC at the Avalanche Fuji wallet
   address.

```javascript JavaScript theme={null}
const receiveTx = await avaxMessageTransmitterContract.receiveMessage(
  receivingMessageBytes,
  signature,
);
```

You have successfully transferred USDC between two EVM-compatible chains using
CCTP V1 end-to-end.


# Transfer USDC on testnet between Noble and Ethereum using CCTP V1
Source: https://developers.circle.com/cctp/v1/transfer-usdc-on-testnet-from-noble-to-ethereum

Explore this tutorial for transferring USDC on testnet between Noble via CCTP V1 and Ethereum

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

To transfer USDC between Noble testnet and Ethereum Sepolia, follow the
tutorials provided
[on GitHub](https://github.com/circlefin/noble-cctp/tree/master/examples).
Specifically, follow the instructions for the
[DepositForBurn script](https://github.com/circlefin/noble-cctp/blob/master/examples/depositForBurn.ts)
to test transferring USDC from Noble testnet to Ethereum Sepolia, and the
instructions for the
[ReceiveMessage script](https://github.com/circlefin/noble-cctp/blob/master/examples/receiveMessage.ts)
to transfer USDC from Ethereum Sepolia to Noble testnet.

As a security measure, these scripts should only be used for testnet testing. It
is not recommended to reuse private keys across mainnet and testnet.

<Note>
  **Note:**

  This tutorial relies on the Strangelove Ventures
  [Noble CCTP V1 relayer](https://github.com/strangelove-ventures/noble-cctp-relayer),
  which is a service that automatically calls `receiveMessage()` for messages
  transmitted to and from Noble domains. To avoid relying on this relayer, you can
  submit this `receiveMessage()` transaction directly. (If you do not want your
  transaction relayed automatically, you can specify a `destinationCaller` via
  `depositForBurnWithCaller()`.)
</Note>


# Transfer USDC on testnet between Sui and Ethereum using CCTP V1
Source: https://developers.circle.com/cctp/v1/transfer-usdc-on-testnet-from-sui-to-ethereum

Explore this tutorial for transferring USDC between Sui testnet and Ethereum Sepolia Testnet via CCTP V1

<Warning>
  **This is CCTP V1 (Legacy) version. For the latest version, see [CCTP](/cctp)**.
</Warning>

To get started with CCTP V1 on Sui testnet, follow the example scripts provided
[on GitHub](https://github.com/circlefin/sui-cctp/tree/master/scripts/sui-scripts).
The
[README](https://github.com/circlefin/sui-cctp?tab=readme-ov-file#run-localnet-example-scripts)
contains instructions for running the scripts. The examples use the
[Sui SDK](https://www.npmjs.com/package/@mysten/sui), to transfer USDC to and
from an address on Sui testnet and an address on an external blockchain.

<Warning>
  **Do not reuse keys** As a security measure, these scripts should only be used
  on a testnet for testing purposes. It is not recommended to reuse private keys
  across mainnet and testnet.
</Warning>

Summary of calling `deposit_for_burn()` (full runnable script can be found in
the sui-cctp repository):

```javascript JavaScript theme={null}
// Create DepositForBurn tx
const depositForBurnTx = new Transaction();

// Split USDC to send in depositForBurn call
const ownedCoins = await client.getAllCoins({owner: signer.toSuiAddress()})
const usdcStruct = ownedCoins.data.find(c => c.coinType.includes(usdcId));
if (!usdcStruct || Number(usdcStruct.balance) < USDC_AMOUNT) {
  throw new Error("Insufficient tokens in wallet to initiate transfer.");
}

const [coin] = depositForBurnTx.splitCoins(
  usdcStruct.coinObjectId,
  [USDC_AMOUNT]
);

// Create the deposit_for_burn move call
depositForBurnTx.moveCall({
  target: `${tokenMessengerMinterId}::deposit_for_burn::deposit_for_burn`,
  arguments: [
    depositForBurnTx.object(coin), // Coin<USDC>
    depositForBurnTx.pure.u32(DESTINATION_DOMAIN), // destination_domain
    depositForBurnTx.pure.address(evmUserAddress), // mint_recipient
    depositForBurnTx.object(tokenMessengerMinterStateId), // token_messenger_minter state
    depositForBurnTx.object(messageTransmitterStateId), // message_transmitter state
    depositForBurnTx.object("0x403"), // deny_list id, fixed address
    depositForBurnTx.object(treasuryId) // treasury object Treasury<USDC>
  ],
  typeArguments: [`${usdcId}::usdc::USDC`],
});

// Broadcast the transaction
console.log("Broadcasting sui deposit_for_burn tx...");
const depositForBurnOutput = await executeTransactionHelper({
  client: client,
  signer: signer,
  transaction: depositForBurnTx,
});
assert(!depositForBurnOutput.errors);
console.log(`deposit_for_burn transaction successful: 0x${depositForBurnOutput.digest} \n`);

// Get USDC balance changes (optional)
const suiUsdcBalanceChange = depositForBurnOutput.balanceChanges?.find(b => b.coinType.includes(usdcId))
const balances = await client.getAllBalances({ owner: signer.toSuiAddress() });
const usdcBalance = balances.find(b => b.coinType.includes(usdcId))?.totalBalance;

// Get the message emitted from the tx
const messageRaw: Uint8Array = (depositForBurnOutput.events?.find((event) =>
  event.type.includes("send_message::MessageSent")
)?.parsedJson as any).message;
const messageBuffer = Buffer.from(messageRaw);
const messageHex = `0x${messageBuffer.toString("hex")}`;
const messageHash = web3.utils.keccak256(messageHex);
console.log(`Message hash: ${messageHash}`);
```

Summary of calling `receive_message()` (full runnable script can be found in the
sui-cctp repository):

```javascript JavaScript theme={null}
// Create receiveMessage transaction
const receiveMessageTx = new Transaction();

// Add receive_message move call to MessageTransmitter
const [receipt] = receiveMessageTx.moveCall({
  target: `${messageTransmitterId}::receive_message::receive_message`,
  arguments: [
    receiveMessageTx.pure.vector(
      "u8",
      Buffer.from(evmBurnTx.message.replace("0x", ""), "hex"),
    ), // message as byte array
    receiveMessageTx.pure.vector(
      "u8",
      Buffer.from(attestation.replace("0x", ""), "hex"),
    ), // attestation as byte array
    receiveMessageTx.object(messageTransmitterStateId), // message_transmitter state
  ],
});

// Add handle_receive_message call to TokenMessengerMinter with Receipt from receive_message call
const [stampReceiptTicketWithBurnMessage] = receiveMessageTx.moveCall({
  target: `${tokenMessengerMinterId}::handle_receive_message::handle_receive_message`,
  arguments: [
    receipt, // Receipt object returned from receive_message call
    receiveMessageTx.object(tokenMessengerMinterStateId), // token_messenger_minter state
    receiveMessageTx.object("0x403"), // deny list, fixed address
    receiveMessageTx.object(treasuryId), // usdc treasury object Treasury<T>
  ],
  typeArguments: [`${usdcId}::usdc::USDC`],
});

// Add deconstruct_stamp_receipt_ticket_with_burn_message call
const [stampReceiptTicket] = receiveMessageTx.moveCall({
  target: `${tokenMessengerMinterId}::handle_receive_message::deconstruct_stamp_receipt_ticket_with_burn_message`,
  arguments: [stampReceiptTicketWithBurnMessage],
});

// Add stamp_receipt call
const [stampedReceipt] = receiveMessageTx.moveCall({
  target: `${messageTransmitterId}::receive_message::stamp_receipt`,
  arguments: [
    stampReceiptTicket, // Receipt ticket returned from deconstruct_stamp_receipt_ticket_with_burn_message call
    receiveMessageTx.object(messageTransmitterStateId), // message_transmitter state
  ],
  typeArguments: [
    `${tokenMessengerMinterId}::message_transmitter_authenticator::MessageTransmitterAuthenticator`,
  ],
});

// Add complete_receive_message call to MessageTransmitter with StampedReceipt from stamp_receipt call.
// Receipt and StampedReceipt are Hot Potatoes so they must be destroyed for the
// transaction to succeed.
receiveMessageTx.moveCall({
  target: `${messageTransmitterId}::receive_message::complete_receive_message`,
  arguments: [
    stampedReceipt, // Stamped receipt object returned from handle_receive_message call
    receiveMessageTx.object(messageTransmitterStateId), // message_transmitter state
  ],
});

// Broadcast the transaction
console.log("Broadcasting Sui receive_message tx...");
const receiveMessageOutput = await executeTransactionHelper({
  client: client,
  signer: signer,
  transaction: receiveMessageTx,
});
```


# Circle Mint
Source: https://developers.circle.com/circle-mint

Mint and redeem USDC and EURC directly from Circle.

<Note>
  Circle Mint is for institutional customers minting USDC or EURC. It is
  typically used by exchanges, institutional traders, wallet providers, banks,
  and consumer-app companies. [Contact
  Circle](https://www.circle.com/mint-contact) to learn more.
</Note>

Circle Mint lets you mint (convert fiat to stablecoins) and redeem (convert
stablecoins back to fiat) [USDC](/stablecoins/what-is-usdc) and EURC directly
from Circle, the sole issuer of both stablecoins. Every token redeems 1:1 for
its backing fiat currency: U.S. dollars for USDC, euros for EURC.

Manage your account through the [Mint Console](https://app.circle.com/) or the
Circle Mint API. Deposit fiat from a linked bank account, convert it to USDC or
EURC, and send stablecoins to blockchain wallets globally. To start integrating,
[set up your account and API key](/circle-mint/quickstarts/getting-started).

## What you can do

<CardGroup>
  <Card title="Mint and redeem stablecoins" icon="coins" href="/circle-mint/quickstarts/mint-and-redeem">
    Convert fiat to USDC or EURC and redeem stablecoins back to fiat through
    your Circle Mint account.
  </Card>

  <Card title="Transfer onchain" icon="arrow-right-arrow-left" href="/circle-mint/howtos/transfer-on-chain">
    Send and receive USDC and EURC on supported blockchains.
  </Card>

  <Card title="Accept stablecoin payments" icon="money-bill-wave" href="/circle-mint/receive-stablecoin-payin">
    Use Circle's Payment APIs to accept USDC deposits from your customers.
  </Card>

  <Card title="Exchange currencies" icon="rotate" href="/circle-mint/exchange-local-currency-usdc">
    Convert between local currencies and USDC using cross-currency APIs.
  </Card>
</CardGroup>


# Additional APIs
Source: https://developers.circle.com/circle-mint/additional-apis

Circle Mint customers can access extra APIs to use USDC in their apps.

Circle Mint customers can access extra APIs to use USDC in their apps.

<Note>
  These APIs cost extra. Your use case might need more support from Circle.
  Contact your Circle representative or
  [sales@circle.com](mailto:sales@circle.com) for more information.
</Note>

## Move money onchain

Use the Crypto Deposits and Crypto Payouts APIs to manage your Mint account.
These APIs let you build custom software that performs Circle Mint actions.

* Accept stablecoin payins: Take USDC and EURC on
  [supported blockchains](/circle-mint/references/supported-chains-and-currencies#crypto-deposits-api-and-crypto-payouts-api)
  through payment intents.
* Make stablecoin payouts: Send fast, low-cost onchain payouts to customers,
  vendors, and suppliers.

### Stablecoin payins

With the Crypto Deposits API, you take USDC and EURC through onchain transfers
into your Mint wallet using payment intents. For details, see
[How Stablecoin Payins and Payouts Work](/circle-mint/how-stablecoin-payins-and-payouts-work).

Read the quickstart to
[receive a stablecoin payin](/circle-mint/receive-stablecoin-payin).

### Stablecoin payouts

The Crypto Payouts API sends payouts to customers, vendors, or suppliers on
supported blockchains.

You can fund payouts in USDC with your Circle Mint account. Your account can
receive deposits from traditional and blockchain payment rails.

Read the quickstart to
[send stablecoin payouts](/circle-mint/send-stablecoin-payout).

## Currency exchange

The Currency Exchange API lets you swap local currency for USDC and USDC for
EURC.

[Read the quickstart guide on the Cross-Currency API](/circle-mint/exchange-local-currency-usdc).

## Credit API

The Credit API provides programmatic access to Circle Mint's credit products:
Settlement Advance and Line of Credit. You can initiate draws, track transfer
status, manage fees, and process repayments through a dedicated set of endpoints
under `/v1/credit/`.

* **Settlement Advance**: Reserve funds, upload wire proof, and receive
  disbursement after Treasury approval.
* **Line of Credit**: Request draws with auto-approval and repay outstanding
  balances using USDC from your Circle Mint wallet.

[Read the Credit API overview](/circle-mint/credit-api/overview).


# API Logs
Source: https://developers.circle.com/circle-mint/api-logs

View API log entries in the Developer Tab to review transactions and debug any errors.

*[API Logs](https://app-sandbox.circle.com/developer/logs) are transaction logs
that enable you to view your API transaction history and debug API errors with
no setup required. They show the most accurate representation of what Circle
received and sent. When you send an API request, Circle stores it along with its
associated response. On the API logs page, you can view these API logs for seven
days after the request is sent and filter them to find the specific request you
are looking for. You can use the API logs to debug API errors without having to
log out of your system.*

* To access the logs, go to [Circle Sandbox](https://app-sandbox.circle.com) or
  [Circle Mint](https://app.circle.com) and click the **Developer Tab > Logs**.

## API Log Data Elements

For each API request and response, Circle stores the following information,
which you can retrieve and review in the Developer tab.

| Field         | Description                                                                                                             |
| :------------ | :---------------------------------------------------------------------------------------------------------------------- |
| HTTP Status   | HTTP Status code for each request such as 200 or 400.                                                                   |
| Path          | The path excludes the base URL.                                                                                         |
| Request ID    | The `X-Request-Id` in the header provided in the request or is generated plus by Circle and returned in the response.   |
| User Agent    | The User-Agent field in the request header. It is common that the HTTP library used will provide this field by default. |
| Idempotency   | Idempotency Key sent in the request body. This is only found in POST requests.                                          |
| Origin        | Includes the protocol (HTTP/HTTPS), the domain or IP address, and the port number if applicable.                        |
| Time          | Timestamp of when the request was received.                                                                             |
| Request Body  | The full request body.                                                                                                  |
| Response Body | The full response body.                                                                                                 |

<Frame>
  <img />
</Frame>

## API Log Filtering

To filter your search, use the search fields and popup menus at the top of the
Circle Sandbox or Circle Mint page.

<Frame>
  <img />
</Frame>

| Filter Name | Description                                                                                                    |
| :---------- | :------------------------------------------------------------------------------------------------------------- |
| Search      | Filter by request ID, resource ID, or idempotency key ID.                                                      |
| Date Range  | Filter results by date range.                                                                                  |
| Status      | Filter results by `succeeded` and/or `failed`. Succeeded includes all 2## and failed includes all 4## and 5##. |
| Method      | Filter results by HTTP Method. Supports `POST`, `PUT`, `PATCH`, `DELETE`, and/or `GET`.                        |
| Path        | Filter results by the URL path such as `/payments`.                                                            |

## Data Redaction

Due to the sensitivity of some data provided to Circle, including financial
payment methods and PII data, some values will be redacted from the request and
response payloads. Values that are redacted are replaced with the value
`“[redacted].”` If you need access to this sensitive data, reach out to your
Circle customer success manager.


# CAMT.053 Daily Statements for Reconciliation
Source: https://developers.circle.com/circle-mint/camt053-statements

Integrate ISO 20022 CAMT.053 daily statement XML from Circle Mint for treasury and reconciliation workflows.

[ISO 20022](https://www.iso20022.org/) CAMT.053 is a standard bank-to-customer
statement format used for treasury reconciliation. Circle Mint generates one
CAMT.053.001.13 XML file per calendar day (UTC), covering all USDC and EURC
activity on your account. You
[retrieve the file](/circle-mint/camt053-statements#retrieve-the-report) through
the Circle Mint API and parse it to reconcile balances, match transactions, and
integrate with your treasury systems.

## Availability and SLA

* **Coverage**: Each report covers the prior calendar day from 00:00 through
  24:00 UTC.
* **When it is ready**: The report is committed to be available by 06:00 UTC the
  next day. Typically, it is ready around 02:00 UTC.
* **One file, multiple currencies**: USDC and EURC statements are delivered in a
  single XML file as separate `Stmt` blocks.

<Tip>
  Subscribe to the [Circle status page](https://status.circle.com/) to receive
  updates on CAMT.053 outages.
</Tip>

## Retrieve the report

Retrieve the CAMT.053 report by first calling
[Request a report](/api-reference/circle-mint/account/request-report) with
`reportType: camt053` and `date` in `YYYY-MM-DD` format (the UTC calendar date
the statement covers), then use the returned `id` with one of the following
endpoints:

* [Get report by ID](/api-reference/circle-mint/account/get-report-by-id):
  Returns JSON with a `data` object that includes `downloadUrl` and `expiresAt`.
  Download the XML from `downloadUrl` before the time indicated by `expiresAt`.
* [Get report content](/api-reference/circle-mint/account/get-report-content):
  Returns the raw XML as `application/xml`. The response uses a
  `Content-Disposition` attachment filename such as
  `camt053_YYYY-MM-DD_report.xml`.

## Read and reconcile the report

The report follows the ISO 20022 CAMT.053.001.13 structure. The sections below
cover the key elements you need for reconciliation.

### File format at a glance

The report uses ISO 20022 CAMT.053.001.13 XML structure. See the
[ISO 20022 message definitions catalog](https://www.iso20022.org/iso-20022-message-definitions)
for official message definitions.

* The file uses namespace `urn:iso:std:iso:20022:tech:xsd:camt.053.001.13`.
* The root is `Document` → `BkToCstmrStmt` → one or more `Stmt` elements.
* Each `Stmt` is one account and currency.
* Inside a statement you will see opening and closing balances and `Ntry`
  (entry) elements. There is one `Ntry` per movement that affects the balance.

### Balances

Each `Stmt` includes opening and closing balances for the report date:

* `OPBD`: Opening booked balance for the report date.
* `CLBD`: Closing booked balance for the report date.

Each balance has an amount with `Ccy` (currency), `CdtDbtInd` (credit or debit
side of the balance), and a timestamp. For reconciliation, a common check is:
opening balance plus the sum of entries (respecting credit and debit) aligns
with closing balance for that statement.

### Currency vs token

Standard ISO 20022 fields follow ISO 4217. They use three-letter currency codes
on `Amt` and related standard elements:

* `USD` for USDC transactions (for example `<Amt Ccy="USD">`).
* `EUR` for EURC transactions (for example `<Amt Ccy="EUR">`).

The full token identifier (`USDC` or `EURC`) is preserved on each transaction
line. At the transaction level it follows the path `Ntry` → `NtryDtls` →
`TxDtls` → `SplmtryData` → [`CircleTxn`](#circle-transaction-details-circletxn)
→ `Token`.

Use both when you need to match fiat-style accounting codes and token
identifiers.

### Transaction entries (`<Ntry>`)

Each `Ntry` is one transaction line. Important children include:

* `Amt`: Amount and ISO currency on the amount (`USD` or `EUR`).
* `CdtDbtInd`: `CRDT` (credit) or `DBIT` (debit).
* `Sts`: Booking status in `Cd`, such as:
  * `BOOK`: Booked
  * `PDNG`: Pending
  * `RJCT`: Rejected
  * `FAIL`: Failed
* `BookgDt`: Booking time in `DtTm`, UTC (ISO 8601).
* `BkTxCd`: Circle's label for the transaction type, found under `Prtry` / `Cd`.
  New labels can appear over time. Unmapped types may show as `UNKNOWN`.

### Circle transaction details (`CircleTxn`)

Circle adds detail under `Ntry` → `NtryDtls` → `TxDtls` → `SplmtryData` where
`PlcAndNm` is `CircleTransactionData`. Inside the envelope, `CircleTxn` uses
namespace `urn:circle:camt053:transaction`.

The following child elements may appear on a transaction line. This list is not
exhaustive — your parser should tolerate additional elements and fields that are
omitted.

* `TransactionId`: Identifier for the movement.
* `JobId`: Related job identifier.
* `Token`: Full token identifier (`USDC` or `EURC`).
* `CustomReferenceId`: Customer-provided reference when supplied.
* `ExternalReferenceId`: EFT-style reference when supplied (for example `IMAD`
  or `UETR`).
* `Blockchain`: Blockchain identifier when the movement is onchain.
* `TransactionHash`: Onchain transaction hash when present.
* `Source`: Originating party or address when populated.
* `SourceType`: Type of source (for example fiat account or blockchain address)
  when populated.
* `Destination`: Receiving party or address when populated.
* `DestinationType`: Type of destination when populated.
* `CustomerId`: Customer association when present.

Use these fields to tie a line back to APIs, onchain activity, or internal
references.

## Example truncated statement

The example below shows the header, one statement with opening and closing
balances, and one entry (abbreviated). It is only for orientation. Your real
files can contain many entries and a second statement for the other currency.

```xml Example CAMT.053 fragment theme={null}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.13">
  <BkToCstmrStmt>
    <GrpHdr>
      <MsgId>CAMT053_0455_20251006</MsgId>
      <CreDtTm>2025-10-07T14:30:45Z</CreDtTm>
      <MsgRcpt>
        <Id>
          <OrgId>
            <Othr>
              <Id>e0549c6e-c80e-4e5f-95ee-c66f7d1be455</Id>
              <SchmeNm>
                <Prtry>EntityId</Prtry>
              </SchmeNm>
            </Othr>
          </OrgId>
        </Id>
      </MsgRcpt>
    </GrpHdr>
    <Stmt>
      <Id>0455_1000123456_USD_20251006</Id>
      <Acct>
        <Id>
          <Othr>
            <Id>1000123456</Id>
          </Othr>
        </Id>
        <Ccy>USD</Ccy>
      </Acct>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>OPBD</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="USD">1750000.00</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Dt>
          <DtTm>2025-10-06T00:00:00Z</DtTm>
        </Dt>
      </Bal>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>CLBD</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="USD">1775000.00</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Dt>
          <DtTm>2025-10-06T23:59:59Z</DtTm>
        </Dt>
      </Bal>
      <Ntry>
        <Amt Ccy="USD">25000.00</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Sts>
          <Cd>BOOK</Cd>
        </Sts>
        <BookgDt>
          <DtTm>2025-10-06T08:15:23Z</DtTm>
        </BookgDt>
        <BkTxCd>
          <Prtry>
            <Cd>Mint</Cd>
          </Prtry>
        </BkTxCd>
        <NtryDtls>
          <TxDtls>
            <LclInstrm>
              <Prtry>wire</Prtry>
            </LclInstrm>
            <SplmtryData>
              <PlcAndNm>CircleTransactionData</PlcAndNm>
              <Envlp>
                <CircleTxn xmlns="urn:circle:camt053:transaction">
                  <TransactionId>550e8400-e29b-41d4-a716-446655440000</TransactionId>
                  <JobId>660e9511-f3ac-52e5-b827-557766551111</JobId>
                  <Token>USDC</Token>
                </CircleTxn>
              </Envlp>
            </SplmtryData>
          </TxDtls>
        </NtryDtls>
      </Ntry>
    </Stmt>
  </BkToCstmrStmt>
</Document>
```


# API Resource Data Models
Source: https://developers.circle.com/circle-mint/circle-api-resources

Discover the many resources used by Circle APIs to enable payouts, payments, and transfers.

Circle APIs are a set of functions and procedures that allow you to use USDC for
payments, payouts, and transfers. Circle's APIs are built around several
resources that represent payments, payouts, transfers, and their associated
objects.

## Primary resources

### Payout object

A `payout` object represents a payout to a customer, vendor, or supplier.

#### Example

```json JSON theme={null}
{
  "id": "df3b8e5f-9579-4c1f-9fa9-deac7f4be55c",
  "sourceWalletId": "1000038499",
  "destination": {
    "id": "4d260293-d17c-4309-a8da-fa7850f95c10",
    "type": "address_book",
  },
  "amount": {
    "amount": "10.0",
    "currency": "USD"
  },
  "fees": {
    "amount": 3.0,
    "currency": "USD"
  },
  "status": "complete",
  "errorCode": "insufficient_funds",
  "riskEvaluation": {
    "decision": "denied",
    "reason": "3000"
  },
  "return": { ... },
  "createDate": "2020-12-24T11:19:20.561Z",
  "updateDate": "2020-12-24T12:01:00.523Z",

}
```

#### Attributes

***

**`id`** *string* A `UUID` for the payout.

***

**`sourceWalletId`** *string* The identifier of the source wallet used to fund a
payout.

***

**`destination`** *object* The
[Destination object](#source-and-destination-objects) the payout is being made
to.

***

**`amount`** *object* A [Money object](#money-object) representing the total
amount that is paid to the destination.

***

**`toAmount`** *object* A [Money object](#money-object) representing the amount
that is paid to the destination currency. Only included for stablecoin payouts.

***

**`fees`** *object* A [Money object](#money-object) representing fees associated
with this payment.

***

**`status`** *string* Status of the payout. `pending` indicates that the payout
is in process; `complete` indicates it finished successfully; `failed` indicates
it failed.

***

**`externalRef`** *string* External network identifier which will be present
once provided from the applicable network.

***

**`errorCode`** *string* Indicates the failure reason of a payout. Only present
for payouts in failed state. Possible values are `insufficient_funds`,
`transaction_denied`, `transaction_failed`, and `transaction_returned`.

***

**`riskEvaluation`** *object* An object with two attributes, `decision` and
`reason`.

***

**`return`** *object* A Return object if the payout was returned.

***

**`createDate`** *string* ISO-8601 UTC date/time format.

***

**`updateDate`** *string* ISO-8601 UTC date/time format.

### Transfer object

A `transfer` object represents a transfer of funds from a Circle wallet to a
blockchain address, from a blockchain address to a Circle wallet, or between two
Circle wallets.

#### Example

```json JSON theme={null}
{
  "id": "0d46b642-3a5f-4071-a747-4053b7df2f99",
  "source": {
    "type": "blockchain",
    "chain": "ETH",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F"
  },
  "destination": {
    "type": "wallet",
    "id": "12345"
  },
  "amount": {
    "amount": "3.14",
    "currency": "USD"
  },
  "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63",
  "status": "pending",
  "riskEvaluation": {
    "decision": "approved",
    "reason": "1234"
  },
  "createDate": "2020-04-10T02:29:53.888Z"
}
```

#### Attributes

***

**`id`** *string* A `UUID` for the transfer.

***

**`source`** *object* A [Source object](#source-and-destination-objects)
representing the source of the transfer.

***

**`destination`** *object* A
[Destination object](#source-and-destination-objects) representing the
destination of the transfer.

***

**`amount`** *object* A [Money object](#money-object) representing the amount
transferred between source and destination.

***

**`transactionHash`** *string* A hash that uniquely identifies an onchain
transaction. This is only available when either `source` or `destination` are of
type `blockchain`.

***

**`status`** *string* Status of the transfer. Status `pending` indicates that
the transfer is in the process of running; `complete` indicates it finished
successfully; `failed` indicates it failed.

***

**`createDate`** *string* ISO-8601 UTC date/time format.

***

## Nested resources

The following are resources that are commonly used in other objects.

### Source and destination objects

Payments, payouts, and transfers reference `source` and `destination` objects,
which as the names suggest, tell you where the funds are coming from and where
they're going.

Sources and destinations can have the following types:

* `wire` for wire payments and payouts
* `blockchain` for transfers to/from blockchain addresses
* `wallet` for transfers to/from a Circle `wallet`

```json JSON theme={null}
// "blockchain"
// A "chain" and "address" together represent the blockchain location.
{
  "type": "blockchain",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "chain": "ETH"
}

// "wallet"
// The "id" is the id of the Circle wallet.
{
  "type": "wallet",
  "id": "12345"
}
```

### Money object

Monetary amounts across Circle APIs are represented as `money` objects, which
consist of an `amount` and a `currency`. Two currencies are supported, `USD` and
`EUR`, with the amount represented as a string containing the whole units and
two decimals. In the example below, the amount is represented as 3.14 and the
currency as `USD`.

```json JSON theme={null}
{
  "amount": "3.14",
  "currency": "USD"
}
```

### Blockchain addresses

```json JSON theme={null}
{
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "currency": "USD",
  "chain": "ETH"
}
```


# Circle APIs: API and Entity Errors
Source: https://developers.circle.com/circle-mint/circle-apis-api-errors



Circle APIs use two kinds of error codes:

* **API response errors** return right away with the HTTP response.
* **Entity errors** attach to resources such as payments. They usually show up
  seconds or minutes later.

## Error responses

When an API request is made and the error is known immediately, Circle APIs will
return the appropriate HTTP status code along with a JSON error response.
Because HTTP status codes do not always provide sufficient information about the
cause of an error, Circle's API errors provide more detailed JSON responses to
help you determine what's gone wrong.

In the example below, the request is missing a required field. The HTTP status
code in this case would be `HTTP/1.1 400 Bad Request`

```json JSON theme={null}
{
  "code": 2,
  "message": "Invalid entity. metadata.email may not be empty (was null)",
  "errors": [
    {
      "error": "invalid_value",
      "location": "metadata.email",
      "message": "metadata.email may not be empty (was null)"
    }
  ]
}
```

### Error types

You can automate the handling of certain error types. These include the
following error names, which include example messages and constraints, where
applicable:

| error                   | message                                                                             | constraints                                                                   |
| :---------------------- | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| `value_must_be_true`    | field1 must be true (was false)                                                     | NA                                                                            |
| `value_must_be_false`   | field1 must be false (was true)                                                     | NA                                                                            |
| `required`              | field1 may not be null (was null)                                                   | NA                                                                            |
| `not_required`          | field1 must be null (was foo)                                                       | NA                                                                            |
| `min_value`             | field1 must be greater than or equal to 2 (was 0)                                   | `"constraints": {    "min": 2 }`                                              |
| `min_value`             | field1 must be greater than 2.0 (was 2.0)                                           | `"constraints": {     "min": "2.0",     "inclusive": false }`                 |
| `max_value`             | field1 must be less than or equal to 99 (was 1024)                                  | `"constraints": {    "max": 99 }`                                             |
| `max_value`             | field1 be less than or equal to 99.99 (was 100)                                     | `"constraints": {     "max": "99.99",     "inclusive": true }`                |
| `length_outside_bounds` | field1 must be between 2 and 5 (was qwerty)                                         | `"constraints": {    "min": 2,    "max": 5 }`                                 |
| `pattern_mismatch`      | field1 must match "\[a-z]+" (was 123456)                                            | `"constraints": {     "pattern": "[a-z]+" }`                                  |
| `date_not_in_past`      | field1 must be in the past (was 2020-08-31T18:18:54.211Z)                           | NA                                                                            |
| `date_not_in_future`    | field1 must be in the future (was 2020-08-31T18:18:17.621Z)                         | NA                                                                            |
| `number_format`         | field1 numeric value out of bounds (\<3 digits>.\<2 digits> expected) (was 123.456) | `"constraints": {   "max-integral-digits": 3,   "max-fractional-digits": 2 }` |

### API error format

Whenever an API request results in an error, the JSON response contains both an
error code and a human-readable message in the body.

```json JSON theme={null}
{
  "code": 2,
  "message": "Invalid entity.\n[<error-message1>...\n<error-messageN>]"
}
```

### Extended error format

In some cases, you'll receive extended information about why a request has
failed. For example, if you fail to supply a value for a required field, you'll
receive the following error response:

```json JSON theme={null}
{
  "code": 2,
  "message": "Invalid entity.\nfield1 may not be null (was null)",
  "errors": [
    {
      "error": "required",
      "message": "field1 may not be null (was null)",
      "location": "field1",
      "invalidValue": "null",
      "constraints": {}
    }
  ]
}
```

This extended error response contains one or more associated error descriptions.
Error description attributes can be read as follows:

| Key            | Description                                                                                                                    | optional |
| :------------- | :----------------------------------------------------------------------------------------------------------------------------- | :------- |
| `error`        | type of an error                                                                                                               | false    |
| `message`      | human-friendly message                                                                                                         | false    |
| `location`     | period-separated path to the property that causes this error. An example could be `field1` or `address.billingCountry`         | false    |
| `invalidValue` | actual value of the property specified in `location` key, as received by the server                                            | true     |
| `constraints`  | special object that contains additional details about the error and could be used for programmatic handling on the client side | true     |

### List of API error codes

The table below shows the list of JSON error codes that may be returned in an
API error response.

| Code     | Message                                                           | Description                                                                                                                             |
| -------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `-1`     | Unknown Error                                                     | An unknown error occurred processing the API request                                                                                    |
| `1`      | Malformed authorization. Is the authorization type missing?       | API Key is missing or malformed                                                                                                         |
| `2`      | Invalid Entity                                                    | Error with the JSON object passed in the request body                                                                                   |
| `3`      | Forbidden                                                         | API Key used with request does not have one of the roles authorized to call the API endpoint                                            |
| `1077`   | Payment amount is invalid                                         | Payment amount must be greater than zero                                                                                                |
| `1078`   | Payment currency not supported                                    | An invalid currency value was used when making a payment                                                                                |
| `1083`   | Idempotency key already bound to other request                    | The idempotency key used when making a request was used with another payment. Retry with a different value                              |
| `1084`   | This item cannot be canceled                                      | A cancel or refund request cannot be canceled                                                                                           |
| `1085`   | This item cannot be refunded                                      | A cancel or refund request cannot be refunded                                                                                           |
| `1086`   | This payment was already canceled                                 | This payment was already canceled                                                                                                       |
| `1087`   | Total amount to be refunded exceeds payment amount                | Total amount to be refunded exceeds payment amount                                                                                      |
| `1088`   | Invalid source account                                            | An invalid source account was specified in a payout or transfer request                                                                 |
| `1089`   | The source account could not be found                             | Unable to find the source account specified in a payout or transfer request                                                             |
| `1093`   | Source account has insufficient funds                             | The source account has insufficient funds for the payout or transfer amount                                                             |
| `1096`   | Encryption key id could not be found                              | An encryption key id must be provided if request includes encrypted data                                                                |
| `1097`   | Original payment is failed                                        | Attempting to cancel or refund a failed payment                                                                                         |
| `1101`   | Invalid country format                                            | An invalid ISO 31660-2 country code was provided                                                                                        |
| `1106`   | Invalid district format                                           | Invalid district format, must be a 2 character value                                                                                    |
| `1107`   | Payout limit exceeded                                             | Payout can't be accepted as it would exceed the given limit                                                                             |
| `1108`   | Unsupported Country                                               | Country not supported for customer                                                                                                      |
| `1143`   | Checkout session not found                                        | The checkout session id passed in the request doesn't exist in the DB                                                                   |
| `1144`   | Checkout session is already in a completed state                  | The checkout session cannot be extended because it is already in a complete state                                                       |
| `2003`   | The recipient address already exists                              | The blockchain address has already been associated with the account                                                                     |
| `2004`   | The address is not a verified withdrawal address                  | The blockchain address must first be verified before it can be used as a destination in a transfer request                              |
| `2005`   | The address belongs to an unsupported blockchain                  | The blockchain type used as a transfer destination is not supported                                                                     |
| `2006`   | Wallet type is not supported                                      | The wallet type specified when creating an end user wallet is not supported                                                             |
| `2007`   | Unsupported transfer                                              | A transfer from the provided source to the provided destination is not supported                                                        |
| `2024`   | Address book identity is missing                                  | Address book identity is required for this entity                                                                                       |
| `2025`   | Address book ownership is missing                                 | Address book ownership is required for this entity                                                                                      |
| `2026`   | Address book VASP ID is missing                                   | Address book VASP ID is required for this entity                                                                                        |
| `2027`   | Address book ownership type is invalid                            | Address book ownership type is not supported for this entity                                                                            |
| `2028`   | Address book custody type is invalid                              | Address book custody type is not supported for this entity                                                                              |
| `2029`   | Address book custody is missing                                   | Address book custody is required for this entity                                                                                        |
| `2030`   | Address book VASP ID is invalid                                   | Address book VASP ID is not valid for this entity                                                                                       |
| `2031`   | Address book identity type is invalid                             | Address book identity type must be either individual or business                                                                        |
| `2032`   | Address book identity first name is missing                       | First name is required for individual identity                                                                                          |
| `2033`   | Address book identity last name is missing                        | Last name is required for individual identity                                                                                           |
| `2034`   | Address book identity business name is missing                    | Business name is required for business identity                                                                                         |
| `2035`   | Address book VASP ID is not allowed                               | VASP ID must not be provided for self-hosted custody                                                                                    |
| `2036`   | Identity is not allowed in address book patch requests            | The identity field cannot be updated via the patch endpoint                                                                             |
| `2037`   | Ownership is not allowed in address book patch requests           | The ownership field cannot be updated via the patch endpoint                                                                            |
| `5000`   | Invalid travel rule identity type                                 | The provided identity type must be either "individual" or "business"                                                                    |
| `5001`   | Payout not found                                                  | Payout doesn't exist based on the ID provided. Verify the payout ID.                                                                    |
| `5002`   | Invalid payout amount                                             | Payout amount must be more than 0                                                                                                       |
| `5003`   | Inactive destination address                                      | Cannot send payout to an inactive destination address. If you have just added the address, you may have to wait for 24 hours before use |
| `5004`   | Destination address not found                                     | The destination address for this payout could not be found                                                                              |
| `5005`   | Source wallet not found                                           | Source wallet for this payout could not be found                                                                                        |
| `5006`   | Insufficient funds                                                | The source wallet has insufficient funds for this payout                                                                                |
| `5007`   | Unsupported currency                                              | Currency not supported for this operation                                                                                               |
| `5011`   | Invalid destination address                                       | Can't send payout to an invalid destination address                                                                                     |
| `5012`   | Invalid destination location types                                | Can't search for both crypto and fiat payouts                                                                                           |
| `5013`   | Invalid source wallet id                                          | Source wallet id must be a number for payouts search                                                                                    |
| `5014`   | The address is not valid for the blockchain                       | Provided blockchain address is not valid for the corresponding blockchain                                                               |
| `5015`   | Invalid destination chain                                         | Provided blockchain address has an invalid chain in respect to the currency used                                                        |
| `5020`   | Invalid purpose of transfer                                       | The `purposeOfTransfer` field is missing or invalid for crypto payouts                                                                  |
| `500000` | Unsupported currency for reporting daily user balance             | User provided a currency other than USDC or EURC                                                                                        |
| `500001` | Custody balance `asOfDate` is too far from today's date           | `asOfDate` provided was before or after today's date                                                                                    |
| `500002` | Custody balance cannot be less than zero                          | Negative balances were provided                                                                                                         |
| `500003` | Local custody balance can't be greater than total custody balance | Total balance must be greater than or equal to local balance                                                                            |
| `500004` | Idempotency key can't be reused                                   | The same idempotency key was used for different requests                                                                                |
| `500005` | Custody balance report already exists                             | A custody balance report was already created for the provided date and currency. Contact customer care for edits.                       |

## Entity error responses

With entities such as payments, cards, bank wires, and transfers, an error is
generally not known immediately, so no error code can be returned at the time of
the request.

For instance, when making a payment, the transaction is processed asynchronously
and the create payment request will have a status of `pending`. After
processing, the status will eventually be set to `approved` or `failed`.

API entities such as payments and cards are processed asynchronously after the
initial create request is made. If a problem occurs while processing the request
(the status is shown as `failed`), the `errorCode` property is set on the entity
and can be retrieved either by polling the `GET` endpoint or via a notification.
The response explains why the payment was unsuccessful.

Here are some Entity error codes associated with payments, cards, bank wires,
and transfers.

### Payment error codes

| Code                              | Description                                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `payment_failed`                  | Payment failed due to an unknown reason                                                                |
| `payment_fraud_detected`          | Suspected fraud detected by issuing bank. Instruct your user to contact their bank directly to resolve |
| `payment_denied`                  | Payment denied by Circle Risk Service, see payment `riskReasonCode` for more details                   |
| `payment_not_supported_by_issuer` | Issuer bank was unable to process the transaction                                                      |
| `payment_not_funded`              | There were insufficient funds to cover the payment amount                                              |
| `payment_unprocessable`           | The provided `encryptedData` could not be processed                                                    |
| `payment_stopped_by_issuer`       | A stop has been placed by the issuer or customer                                                       |
| `payment_canceled`                | Payment was canceled                                                                                   |
| `payment_returned`                | Payment was returned                                                                                   |
| `payment_failed_balance_check`    | Payment failed the Plaid balance check due to insufficient funds                                       |
| `card_failed`                     | Card payment failed                                                                                    |
| `card_invalid`                    | The card is invalid                                                                                    |
| `card_address_mismatch`           | Card billing address does not match                                                                    |
| `card_zip_mismatch`               | Card billing ZIP code does not match                                                                   |
| `card_cvv_invalid`                | The card CVV is invalid                                                                                |
| `card_expired`                    | The card has expired                                                                                   |
| `card_limit_violated`             | Card limit was exceeded                                                                                |
| `card_not_honored`                | Card was not honored by the issuer                                                                     |
| `card_cvv_required`               | Card CVV is required but was not provided                                                              |
| `card_restricted`                 | Card use is restricted                                                                                 |
| `card_account_ineligible`         | Card account is not eligible for this transaction                                                      |
| `card_network_unsupported`        | The card network is not supported                                                                      |
| `channel_invalid`                 | The payment channel is invalid                                                                         |
| `unauthorized_transaction`        | Transaction was unauthorized                                                                           |
| `bank_account_ineligible`         | The bank account is not eligible for this transaction                                                  |
| `bank_transaction_error`          | There was an error processing the transaction on the bank                                              |
| `invalid_account_number`          | The bank account number is invalid                                                                     |
| `invalid_wire_rtn`                | The wire RTN is invalid                                                                                |
| `invalid_ach_rtn`                 | The ACH RTN is invalid                                                                                 |
| `ref_id_invalid`                  | The reference ID is invalid                                                                            |
| `account_name_mismatch`           | The name on the account does not match                                                                 |
| `account_number_mismatch`         | The account number does not match                                                                      |
| `account_ineligible`              | The account is not eligible for this transaction                                                       |
| `wallet_address_mismatch`         | The wallet address does not match                                                                      |
| `customer_name_mismatch`          | The customer name does not match                                                                       |
| `institution_name_mismatch`       | The institution name does not match                                                                    |
| `vendor_inactive`                 | The vendor is inactive                                                                                 |

### Payout error codes

| Code                          | Description                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| `insufficient_funds`          | Insufficient funds                                                                          |
| `transaction_denied`          | Transaction was denied by Circle Risk Service, see payout `riskEvaluation` for more details |
| `transaction_failed`          | Transaction failed due to an unknown reason                                                 |
| `transaction_returned`        | Transaction was returned                                                                    |
| `bank_transaction_error`      | There was an error processing the transaction on the bank                                   |
| `fiat_account_limit_exceeded` | The fiat account limit was exceeded                                                         |
| `invalid_bank_account_number` | The bank account number is invalid                                                          |
| `invalid_ach_rtn`             | The ACH RTN is invalid                                                                      |
| `invalid_wire_rtn`            | The wire RTN is invalid                                                                     |
| `vendor_inactive`             | The vendor is inactive                                                                      |

### Transfer error codes

| Code                 | Description                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| `transfer_failed`    | The transfer failed due to unknown reasons                                                     |
| `transfer_denied`    | The transfer was denied by Circle Risk Service, see transfer `riskEvaluation` for more details |
| `blockchain_error`   | There was an error processing the transfer onchain                                             |
| `insufficient_funds` | There was not enough funding to cover the transfer amount                                      |


# Notifications Quickstart
Source: https://developers.circle.com/circle-mint/circle-apis-notifications-quickstart

Configure a notification subscriber endpoint and be notified when a payment is received.

*Circle notifications will inform you every time the status of a resource
changes, such as changes in payment status. Notifications can be accessed by
setting up a notification subscriber endpoint on your end. This quickstart guide
shows how to set up notifications for the Circle APIs. Follow this to configure
a subscriber endpoint that sends a notification each time the resource status
changes.*

Note: This guide addresses the payment resource, but is applicable to any of the
resources mentioned in
[Circle API Notifications](/circle-mint/notifications-data-models).

## 1. Expose a Subscriber Endpoint

To receive notifications on changes in resource status, you must expose a
publicly accessible subscriber endpoint on your side. The endpoint must handle
both `HEAD` and `POST` requests over HTTPS.

To expose an endpoint for testing, you can use
[webhook.site](https://webhook.site/) to inspect, test and automate incoming
HTTPS requests or e-mails directly in the web browser.

<Note>
  **💡 Tip:**

  When you visit [webhook.site](https://webhook.site/) for the first time, you
  should see a status message that looks similar to the following:

  `Your unique URL (Please copy it from here, not from the address bar!) https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7`
</Note>

Navigate to [webhook.site](https://webhook.site/) and record the value of the
URL shown as `Your unique URL`:

<Frame>
  <img />
</Frame>

In the example above, the unique URL
is:`https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7`. Use the
public-facing URL you receive as you progress throughout this guide.

## 2. Subscribe to Status Notifications

Now that you have a publicly accessible endpoint, you need to register your
endpoint as a subscriber to webhook notifications by doing the following:

1. Navigate to **API > Subscriptions** in your Circle Mint account and click
   **Add Subscription**.
2. Enter your endpoint URL from above. It will be similar to the earlier
   example: `https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7`.
3. Click **Add Subscription**:

<Frame>
  <img />
</Frame>

4. You should receive two responses on your local server shell that confirm the
   subscription with a body similar to the following:

```json JSON theme={null}
{
  "Type": "SubscriptionConfirmation",
  "MessageId": "ddbdcdcf-d36a-45b5-927c-da25b9b009ae",
  "Token": "2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
  "TopicArn": "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic",
  "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic&Token=2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
  "Timestamp": "2020-04-11T20:50:16.324Z",
  "SignatureVersion": "1",
  "Signature": "kBr9z/ysQrr0ldowHY4lThkOA+dwyjcsyx7NwkbTkgEKG4N61BSSEA+43aYQEB/Ml09hclybvyjyRKWYOjaxQgbUXWmyWrCQ7vY93WYhuGvOqZxAMPiDiILxLs6/KtOxneKVvzfpK4abLrYyTTA+z/dQ52h9L8eoiSKSW81e4clfYBTJkGmuAPKFC08FvEAVT89VikPp68mBf4CctPv3Em0b4J1VvDhAB21B2LekgUmwUE0aE7fUbsF3XsKGQd/fDshLOJasQEuXSqdB5X7LITBA8r24FY+wCjwm8oR3VI9IMy21fUC6wMgoFIVZHW1KxzpEkMCSe7R1ySdNIru8SQ==",
  "SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem"
}
```

<Note>
  **Note:** The response body above is in a plain text format, so be sure you're
  not expecting a JSON content type.
</Note>

5. To complete the subscription process, visit the `SubscribeURL` link in each
   response. Messages won't be sent to the endpoint until you confirm the
   subscription by accessing the URL.
6. After you visit the `SubscribeURL` links, the subscription status updates to
   `COMPLETE`, indicating it's ready for use.

<Note>
  **Note:** In the Circle sandbox environment, if your subscription is stuck in
  the `PENDING` (unconfirmed) state, reach out to
  [customer-support@circle.com](mailto:customer-support@circle.com) to remove
  it.

  In the production environment, if your subscription is stuck in the `PENDING`
  state, it's automatically removed after 72 hours.
</Note>

<Frame>
  <img />
</Frame>

You now have a sample local environment ready to receive notifications.


# Circle SDKs
Source: https://developers.circle.com/circle-mint/circle-sdks

Use the TypeScript SDK to quickly get your codebase up and running with Circle APIs.

Circle's SDKs help you integrate Circle APIs. The TypeScript SDK is open source.
If you find a bug or need a feature, file an issue or contribute to the
[`node-sdk`](https://github.com/circlefin/circle-nodejs-sdk).

**Note:** This page contains code snippets and examples that can be run as is or
incorporated into your apps.

## Installing the SDK

Run one of the following commands from your project directory to install the
SDK.

<CodeGroup>
  ```shell Node theme={null}
  npm install @circle-fin/circle-sdk --save
  # or
  yarn add @circle-fin/circle-sdk
  ```
</CodeGroup>

## Configuration

<CodeGroup>
  ```typescript theme={null}
  import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

  const circle = new Circle(
    "<your-api-key>",
    CircleEnvironments.sandbox, // API base url
  );
  ```
</CodeGroup>

## List balances

<CodeGroup>
  ```typescript theme={null}
  async function listBalances() {
    const balancesRes = await circle.balances.listBalances();
  }
  ```
</CodeGroup>

## Create a crypto payment

<CodeGroup>
  ```typescript theme={null}
  async function createCryptoPayment() {
    const createCryptoPaymentRes =
      await circle.paymentIntents.createPaymentIntent({
        idempotencyKey: "5c6e9b91-6563-47ec-8c6d-0ce1103c50b3",
        amount: {
          amount: "3.14",
          currency: "USD",
        },
        settlementCurrency: "USD",
        paymentMethods: [
          {
            chain: "ETH",
            type: "blockchain",
          },
        ],
      });
  }
  ```
</CodeGroup>

## Get a crypto payment

<CodeGroup>
  ```typescript theme={null}
  async function getCryptoPayment(id: string) {
    const cryptoPayment = await circle.paymentIntents.getPaymentIntent(id);
  }
  ```
</CodeGroup>


# How Minting and Redemption Works
Source: https://developers.circle.com/circle-mint/concepts/how-minting-works

Understand how Circle Mint converts fiat to USDC (minting) and USDC back to fiat (redemption), including settlement timing, account structure, and compliance requirements.

Circle Mint's core operations are minting and redemption. Minting converts fiat
currency into stablecoins (USDC or EURC), and redemption converts stablecoins
back to fiat. Every token mints and redeems at a 1:1 ratio with the underlying
fiat currency. This page explains the mental model behind these operations,
including settlement timing, account structure, onchain transfers, fees, and
compliance.

## Minting

Minting (also known as an onramp) is the process of depositing fiat currency and
receiving an equivalent amount of stablecoins. When you send a fiat transfer to
Circle, Circle credits your Mint account balance with the corresponding
stablecoin amount at a 1:1 ratio.

The minting flow works as follows:

1. You initiate a fiat transfer from your linked bank account to Circle.
2. Circle receives the fiat deposit and credits your Mint account balance.
3. The stablecoins become available for onchain transfers or other operations.

Circle supports multiple payment rails for fiat deposits, including standard
wires (FedWire and SWIFT), real-time interbank rails (RTP, SPEI, SEPA, and
CHATS) in supported regions, and book transfers when you bank with one of
Circle's settlement partners. Rail availability depends on your region and the
currency you are depositing.

**Settlement timing:** Domestic wire deposits received before the daily cutoff
settle on the same business day. Real-time interbank rails settle in seconds,
subject to network operating hours and transaction limits. International wires
take 1-3 business days depending on intermediary banks. In the sandbox
environment, mock wire deposits process in batches and may take up to 15
minutes.

For step-by-step instructions, see
[Deposit Fiat](/circle-mint/howtos/deposit-fiat).

## Redemption

Redemption (also known as an offramp) is the reverse of minting. You convert
stablecoins back to fiat currency by creating a payout to a linked bank account.

The redemption flow works as follows:

1. You create a payout request specifying the amount and destination bank
   account.
2. Circle debits the stablecoin amount from your Mint account balance.
3. Circle sends a fiat transfer to your bank account using the appropriate rail
   for your region and bank.

**Settlement timing:** Payouts typically settle on the next business day. In
some cases, your bank may reject the incoming wire, resulting in a returned
withdrawal. If a payout is returned, the funds are credited back to your Mint
account balance.

For step-by-step instructions, see
[Withdraw Fiat](/circle-mint/howtos/withdraw-fiat).

## Account structure

Your Circle Mint account has several key components that work together to
support minting, redemption, and onchain transfers.

### Primary wallet

Every Circle Mint account has a primary wallet identified by a `masterWalletId`.
You retrieve this identifier from the `/v1/configuration` endpoint. The primary
wallet serves as the source for outbound transfers and the destination for
inbound deposits.

### Balances

Your account maintains two types of balances:

* **Available balance:** Settled funds you can transfer or redeem immediately.
* **Unsettled balance:** Funds that are in transit and not yet available. Wire
  deposits appear as unsettled until they clear.

### Linked bank accounts

You register external bank accounts to send and receive fiat. Each linked bank
account receives a unique Virtual Account Number (VAN). When you wire funds to
Circle using the VAN, Circle attributes the deposit to your account without
requiring a tracking reference in the payment instruction.

### Deposit addresses

Circle generates one deposit address per blockchain for your account. These
addresses receive inbound stablecoin transfers from external wallets. You
retrieve your deposit addresses through the API for each
[supported blockchain](/circle-mint/references/supported-chains-and-currencies).

### Recipient addresses

Recipient addresses are external blockchain addresses that you register and
allowlist for outbound transfers. You must create a recipient address before you
can send stablecoins to it. This allowlisting step provides an additional layer
of security for outbound transfers.

## Onchain transfers

Circle Mint supports both receiving and sending stablecoins onchain.

* **Receiving:** External wallets send USDC or EURC to your deposit address on
  any supported blockchain. Circle detects the transfer and credits your account
  after the required number of
  [blockchain confirmations](/circle-mint/references/blockchain-confirmations).
* **Sending:** You create a transfer to a registered recipient address. Circle
  debits your balance and broadcasts the transaction onchain.

### Transfer status lifecycle

Onchain transfers progress through the following statuses:

| Status     | Description                                                         |
| ---------- | ------------------------------------------------------------------- |
| `pending`  | The transfer request is created but not yet broadcast onchain.      |
| `running`  | The transaction is broadcast and awaiting blockchain confirmations. |
| `complete` | The required confirmations are reached and the transfer is final.   |

For details on confirmation requirements per blockchain, see
[Blockchain Confirmations](/circle-mint/references/blockchain-confirmations).
For step-by-step transfer instructions, see
[Transfer USDC Onchain](/circle-mint/howtos/transfer-on-chain).

## Network fees

Circle covers gas fees for outbound stablecoin transfers in most cases. You do
not need to hold the native token of each blockchain to send USDC or EURC from
your Mint account.

## Travel Rule compliance

Transfers of \$3,000 or more in value on supported blockchains are subject to the
FinCEN Travel Rule, which requires identity data about the originator of the
transaction.

How Circle handles the identity requirement depends on the type of transfer:

* **Business account transfers:** Circle uses your company's identity stored on
  file. You do not need to include identity data in each request.
* **Third-party payouts:** If you send funds on behalf of someone else, you must
  provide the originator's identity (name and address) in the payout request.
  Omitting required identity data causes the transfer to fail.

For the full list of supported blockchains and implementation details, see
[Travel Rule compliance](/circle-mint/howtos/transfer-on-chain#travel-rule-compliance).

## Approval workflows

Customers in France and Singapore are subject to additional recipient address
verification requirements. Before an outbound transfer can proceed, the
recipient address must be verified through the
[Mint Console](https://app.circle.com/signin). This approval step ensures
compliance with local regulatory requirements in those jurisdictions.


# Credit API
Source: https://developers.circle.com/circle-mint/credit-api/overview

Programmatically manage Settlement Advance and Line of Credit products through your Circle Mint account.

The Credit API provides programmatic access to Circle Mint's credit products.
You can initiate draws, track transfer status, manage fees, and process
repayments through a dedicated set of endpoints under `/v1/credit/`.

<Note>
  The Credit API is available to institutional Circle Mint customers with an
  approved credit facility. A separate offline credit contract through Circle is
  required before you can access these endpoints.

  [Contact Circle](https://www.circle.com/mint-contact) to learn more about credit
  products.
</Note>

## Credit products

<CardGroup>
  <Card title="Settlement Advance" icon="clock-rotate-left">
    Bridges settlement timing gaps through a reserve-then-request flow. You
    reserve funds, upload wire proof, and wait for Treasury approval before
    disbursement.
  </Card>

  <Card title="Line of Credit" icon="money-bill-transfer">
    Provides single-request draws with auto-approval and asynchronous
    disbursement. No wire proof required. Supports crypto repayment directly
    from your Circle Mint wallet.
  </Card>
</CardGroup>

## Key concepts

* **Credit line**: Your facility object, including credit limit, used and
  available amounts, fee rates, minimum balance requirement, and validation
  errors. Each customer has one credit line.
* **Credit transfers**: Individual draw requests against your credit line.
  Settlement Advance transfers progress through `funds_reserved`, `requested`,
  `disbursed`, and `paid`. Line of Credit transfers progress through
  `requested`, `disbursed`, and `paid`. Both can reach `past_due` if unpaid
  after the due date. Transfers on daily cadence have a 7-day repayment due date
  from disbursement, and transfers on hourly cadence have a 24-hour repayment
  due date from disbursement.
* **Fees**: Each draw can include two types of fees: a draw fee (Settlement
  Advance only) charged at disbursement and a recurring fee accrued on a cadence
  determined by your credit line's `feeCadence` setting: daily (every 24 hours)
  or hourly (every hour). The `recurringFee` rate in `feeRates` applies at
  whichever cadence your credit line uses. Hourly cadence is available only on
  Line of Credit. Fees are auto-deducted from your Circle Mint wallet balance.
* **Minimum balance**: A required USDC balance (`minBalance`) that you must
  maintain in your Circle Mint wallet while you have an active credit line.
* **Validation errors**: Conditions that block new transfer creation, such as
  `INSUFFICIENT_BALANCE`, `PENDING_FEES`, or `OVERDUE_TRANSFERS`. Returned in
  the credit line response so you can resolve them before initiating a draw.
* **Blockchain destination**: An optional feature that sends disbursed funds
  directly to a verified blockchain address instead of your Circle Mint wallet.
  Include the `destination` field when creating a transfer, referencing an
  address from your Circle Mint recipient address book. If omitted, funds are
  deposited into your Circle Mint wallet by default. To manage verified
  recipient addresses, use the
  [recipient address endpoints](/api-reference/circle-mint/account/create-business-recipient-address).

## Get started

<CardGroup>
  <Card title="Quickstart: Settlement Advance" icon="file-arrow-up" href="/circle-mint/credit-api/quickstart-settlement-advance">
    Reserve funds, upload wire proof, and track your advance through
    disbursement
  </Card>

  <Card title="Quickstart: Line of Credit" icon="bolt" href="/circle-mint/credit-api/quickstart-line-of-credit">
    Request a draw, monitor its status, and repay using crypto
  </Card>
</CardGroup>


# Quickstart: Line of Credit
Source: https://developers.circle.com/circle-mint/credit-api/quickstart-line-of-credit

Request a draw, track disbursement, and repay outstanding balances using the Credit API's Line of Credit endpoints.

This quickstart walks you through a complete Line of Credit draw and repayment
lifecycle using the Credit API. You check your available credit, request a draw,
track the transfer through disbursement, and repay using USDC from your Circle
Mint wallet.

## Prerequisites

Before you begin, ensure you have:

* An approved Line of Credit facility with Circle. Contact your Circle
  representative if you haven't completed the offline credit agreement.
* A Circle Mint API key with the Credit API entitlement enabled.
* Familiarity with
  [Circle Mint authentication](/circle-mint/quickstarts/getting-started) and
  [idempotent requests](/circle-mint/references/sandbox-and-testing#idempotent-requests).

## Step 1: Check your credit line status

Before requesting a draw, verify that your credit line is active and has
sufficient available credit. Call the `GET /v1/credit` endpoint to retrieve your
credit line details.

```bash theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/credit' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

```json Response theme={null}
{
  "data": {
    "id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
    "product": "lineOfCredit",
    "feeCadence": "daily",
    "status": "active",
    "limit": { "amount": "1000000.00", "currency": "USD" },
    "used": { "amount": "250000.00", "currency": "USD" },
    "available": { "amount": "750000.00", "currency": "USD" },
    "outstandingTransfers": 2,
    "feeRates": { "recurringFee": "0.0003" },
    "unpaidFees": { "amount": "150.00", "currency": "USD" },
    "minBalance": { "amount": "100000.00", "currency": "USD" },
    "validationErrors": [],
    "createDate": "2024-01-15T10:30:00.000Z",
    "updateDate": "2024-03-20T14:22:00.000Z"
  }
}
```

Confirm the following before proceeding:

* `product` is `lineOfCredit`.
* `status` is `active`.
* `available.amount` is greater than or equal to the amount you plan to draw.
* `validationErrors` is an empty array. If it contains errors such as
  `INSUFFICIENT_BALANCE`, `PENDING_FEES`, or `OVERDUE_TRANSFERS`, resolve them
  before you create a new transfer.

The `feeCadence` field indicates how frequently fees accrue on your credit line.
The `recurringFee` rate in `feeRates` applies at whichever cadence your credit
line uses.

* **Daily** (every 24 hours): Available on both products. Transfers have a 7-day
  due date from disbursement.
* **Hourly** (every hour): Available only on Line of Credit. Transfers have a
  24-hour due date from disbursement.

For an hourly cadence credit line, the relevant fields differ as follows:

```json Response (hourly cadence — other fields unchanged) theme={null}
{
  "data": {
    "feeCadence": "hourly",
    "feeRates": { "recurringFee": "0.0000125" }
  }
}
```

## Step 2: Request a draw

Request a draw against your credit line by calling `POST /v1/credit/transfers`
with an idempotency key and the desired amount. Unlike Settlement Advance
transfers, LoC draws are auto-approved and don't require wire proof or Treasury
review.

```bash theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/credit/transfers' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "amount": { "amount": "50000.00", "currency": "USD" },
  "destination": {
    "type": "verified_blockchain",
    "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }
}'
```

<Note>
  The `destination` field is optional. If included, disbursed funds are sent to
  the specified verified blockchain address instead of your Circle Mint wallet.
  The `addressId` must reference a verified address from your [Circle Mint
  recipient address
  book](/api-reference/circle-mint/account/create-business-recipient-address).
  If you omit `destination`, funds are deposited into your Circle Mint wallet by
  default.
</Note>

```json Response theme={null}
{
  "data": {
    "id": "a1c2e3f4-5678-4d90-b123-456789abcdef",
    "amount": { "amount": "50000.00", "currency": "USD" },
    "status": "requested",
    "blockchainDestination": {
      "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "status": "pending"
    },
    "createDate": "2024-03-20T14:20:00.000Z",
    "updateDate": "2024-03-20T14:20:00.000Z"
  }
}
```

Save the transfer `id` from the response. You need it to track the transfer in
the next step.

The transfer starts in `requested` status and automatically transitions to
`disbursed` once the funds are deposited into your Circle Mint wallet, or sent
to the verified blockchain address if you specified a `destination`. No manual
approval step is required.

## Step 3: Track the transfer

Monitor your transfer as it progresses from `requested` to `disbursed`. You can
poll the transfer endpoint or subscribe to webhook notifications.

### Poll the transfer endpoint

Call `GET /v1/credit/transfers/{id}` to check the current transfer status.

```bash theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/credit/transfers/a1c2e3f4-5678-4d90-b123-456789abcdef' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

Once the transfer is disbursed, the response includes fee and repayment details:

```json Response theme={null}
{
  "data": {
    "id": "a1c2e3f4-5678-4d90-b123-456789abcdef",
    "amount": { "amount": "50000.00", "currency": "USD" },
    "status": "disbursed",
    "outstanding": { "amount": "50150.00", "currency": "USD" },
    "fees": {
      "total": { "amount": "150.00", "currency": "USD" },
      "unpaid": { "amount": "150.00", "currency": "USD" }
    },
    "dueDate": "2024-03-27T14:22:00.000Z",
    "disbursedDate": "2024-03-20T14:22:00.000Z",
    "blockchainDestination": {
      "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "status": "complete",
      "transferId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
    },
    "createDate": "2024-03-20T14:20:00.000Z",
    "updateDate": "2024-03-21T00:00:00.000Z"
  }
}
```

The `outstanding` amount includes the original draw plus any accrued fees. The
`dueDate` indicates when repayment is expected. For lines on daily cadence, the
due date is 7 days from disbursement. For lines on hourly cadence, the due date
is 24 hours from disbursement.

If you included a `destination` in your request, the `blockchainDestination`
field tracks the status of the onchain transfer.

| Status      | Description                                 | `transferId` populated |
| ----------- | ------------------------------------------- | ---------------------- |
| `pending`   | Destination recorded, awaiting disbursement | No                     |
| `initiated` | Blockchain transfer submitted               | Yes                    |
| `complete`  | Funds arrived at destination address        | Yes                    |
| `failed`    | Blockchain transfer failed                  | Yes                    |

### Subscribe to webhook notifications

For real-time updates, subscribe to webhook notifications through the Circle
Mint webhook management UI:

* **`creditTransfers`**: Receive notifications whenever a transfer changes
  status, such as the transition from `requested` to `disbursed`.
* **`creditFees`**: Receive notifications when fees are accrued against your
  outstanding transfers.
* **`creditRepayments`**: Receive notifications when a repayment is received and
  allocated against your outstanding balance.

The Line of Credit transfer follows this status lifecycle:

```mermaid theme={null}
stateDiagram-v2
    [*] --> requested
    requested --> disbursed
    requested --> rejected
    disbursed --> paid
    disbursed --> past_due
    past_due --> paid
```

A transfer can also reach `rejected` (if the request is declined) or `past_due`
(if repayment is overdue after the due date).

## Step 4: Repay outstanding balances

You can repay Line of Credit draws in two ways:

* **Crypto repayment**: Deduct USDC directly from your Circle Mint wallet
  balance using the `POST /v1/credit/cryptoRepayment` endpoint.
* **Wire repayment**: Send a wire transfer to Circle using the account details
  from `GET /v1/credit/repaymentAccounts/{fiatAccountId}`. You need a
  `fiatAccountId` from your wire bank accounts (see
  [list wire bank accounts](/api-reference/circle-mint/account/list-business-wire-accounts)).
  Include the `trackingRef` value on your wire so Circle can match the payment
  to your credit line. For details on retrieving repayment account details, see
  the
  [Settlement Advance quickstart](/circle-mint/credit-api/quickstart-settlement-advance#step-2-get-repayment-account-details).

The following example shows a crypto repayment. Call
`POST /v1/credit/cryptoRepayment` with the amount you want to apply toward your
outstanding balance.

```bash theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/credit/cryptoRepayment' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "idempotencyKey": "d7a3e2c1-8f45-4b91-ae67-2c9d0f8b3e5a",
  "amount": { "amount": "25000.00", "currency": "USD" }
}'
```

```json Response theme={null}
{
  "data": {
    "id": "e5f6a7b8-9012-3456-efab-345678901234",
    "amount": { "amount": "25000.00", "currency": "USD" },
    "status": "pending",
    "createDate": "2024-03-25T10:00:00.000Z",
    "updateDate": "2024-03-25T10:00:00.000Z"
  }
}
```

<Note>
  The requested repayment amount is capped at your total outstanding balance. If
  you specify an amount greater than what you owe, the API applies only the
  outstanding balance. Crypto repayment is available exclusively for Line of
  Credit products.
</Note>

## Step 5: Verify repayment status

After initiating a repayment, verify that it completes successfully. You can
poll the repayments endpoint or subscribe to webhook notifications.

### Poll the repayments endpoint

Call `GET /v1/credit/repayments` to list all repayments and check their status.

```bash theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/credit/repayments' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

Once the repayment is processed, the response shows the completed payment with
the amount applied:

```json Response theme={null}
{
  "data": [
    {
      "id": "d4e5f6a7-b890-1234-defa-234567890123",
      "transferId": "a1c2e3f4-5678-4d90-b123-456789abcdef",
      "amountApplied": { "amount": "25000.00", "currency": "USD" },
      "paymentAmount": { "amount": "25000.00", "currency": "USD" },
      "type": "crypto",
      "status": "completed",
      "settlementDate": "2024-04-08T12:00:00.000Z",
      "createDate": "2024-04-08T12:00:00.000Z",
      "updateDate": "2024-04-08T12:00:00.000Z"
    }
  ]
}
```

The `transferId` field links the repayment to the original draw. The
`amountApplied` reflects the portion of the payment allocated to that transfer's
outstanding balance.

### Subscribe to webhook notifications

For real-time repayment tracking, subscribe to `creditRepayments` webhook
notifications through the Circle Mint webhook management UI. You receive
notifications when a repayment is received and allocated against your
outstanding transfers.


# Quickstart: Settlement Advance
Source: https://developers.circle.com/circle-mint/credit-api/quickstart-settlement-advance

Reserve funds, upload wire proof, and track your Settlement Advance through disbursement using the Credit API.

This quickstart walks you through a complete Settlement Advance draw lifecycle
using the Credit API. You check your available credit, reserve funds, upload
wire proof for Treasury review, and track the transfer through to disbursement.

## Prerequisites

Before you begin, ensure you have:

* An approved Settlement Advance credit facility with Circle. Contact your
  Circle representative if you haven't completed the offline credit agreement.
* A Circle Mint API key with the Credit API entitlement enabled.
* Familiarity with
  [Circle Mint authentication](/circle-mint/quickstarts/getting-started) and
  [idempotent requests](/circle-mint/references/sandbox-and-testing#idempotent-requests).

## Step 1: Check your credit line status

Before initiating a draw, verify that your credit line is active and has
sufficient available credit. Call the `GET /v1/credit` endpoint to retrieve your
credit line details.

```bash theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/credit' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

```json Response theme={null}
{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "product": "settlementAdvance",
    "feeCadence": "daily",
    "status": "active",
    "limit": { "amount": "500000.00", "currency": "USD" },
    "used": { "amount": "100000.00", "currency": "USD" },
    "available": { "amount": "400000.00", "currency": "USD" },
    "outstandingTransfers": 1,
    "feeRates": { "drawFee": "0.0001", "recurringFee": "0.0003" },
    "unpaidFees": { "amount": "0.00", "currency": "USD" },
    "minBalance": { "amount": "50000.00", "currency": "USD" },
    "validationErrors": [],
    "createDate": "2024-01-15T10:30:00.000Z",
    "updateDate": "2024-03-20T14:22:00.000Z"
  }
}
```

Confirm the following before proceeding:

* `status` is `active`.
* `available.amount` is greater than or equal to the amount you plan to reserve.
* `validationErrors` is an empty array. If it contains errors such as
  `INSUFFICIENT_BALANCE`, `PENDING_FEES`, or `OVERDUE_TRANSFERS`, resolve them
  before you create a new transfer.

The `feeCadence` field indicates how frequently fees accrue on your credit line.
Settlement Advance credit lines always use `daily` cadence.

## Step 2: Get repayment account details

Before initiating a draw, retrieve the repayment account details for your wire
bank account. You need the beneficiary information and tracking reference to
send your wire.

First, identify the `fiatAccountId` of the wire bank account you want to use for
repayment. You can list your existing wire bank accounts with
`GET /v1/businessAccount/banks/wires` (see the
[list wire bank accounts](/api-reference/circle-mint/account/list-business-wire-accounts)
API reference).

Once you have the `fiatAccountId`, call
`GET /v1/credit/repaymentAccounts/{fiatAccountId}` to get the beneficiary
details and tracking reference for your wire.

```bash theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/credit/repaymentAccounts/b8627ae8-732b-4d25-b947-1df8f4007a29' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

```json Response theme={null}
{
  "data": {
    "id": "c9f2a1b3-6d84-4e0f-b512-9a8c7e3d4f01",
    "description": "WELLS FARGO BANK, NA ****1111",
    "status": "unverified",
    "wireInstructions": {
      "trackingRef": "CIR3XBZZ4N",
      "beneficiary": {
        "name": "CIRCLE INTERNET FINANCIAL INC",
        "address1": "1 Main Street",
        "address2": "Suite 1"
      },
      "beneficiaryBank": {
        "swiftCode": "SVBKUS6S",
        "routingNumber": "121140399",
        "accountNumber": "3302726104",
        "currency": "USD",
        "name": "SILICON VALLEY BANK",
        "address": "3003 TASMAN DRIVE",
        "city": "SANTA CLARA",
        "postalCode": "95054",
        "country": "US"
      }
    }
  }
}
```

Use the `trackingRef` value (at `data.wireInstructions.trackingRef`) as the
reference on your wire transfer so that Circle can match the incoming payment to
your credit line. Save the beneficiary bank details for use when initiating your
wire.

A `status` of `unverified` is expected for first-time use. The status becomes
`active` after a completed credit repayment is matched to this account.

<Tip>
  **Sandbox only:** You can simulate an incoming wire payment without sending
  real funds by calling the mock repayment endpoint:

  ```bash theme={null}
  curl --location --request POST 'https://api-sandbox.circle.com/v1/credit/mocks/repayments' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fiatAccountId": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "amount": { "amount": "100000.00", "currency": "USD" }
  }'
  ```

  This creates a simulated wire arrival and auto-links the fiat account as a
  repayment account if it is not already linked.
</Tip>

## Step 3: Reserve funds

The reserve step holds the requested amount for you while you initiate and
confirm your wire transfer.

Reserve funds against your credit line by calling
`POST /v1/credit/transfers/reserveFunds`. This creates a transfer in
`funds_reserved` status and holds the requested amount against your available
credit.

```bash theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/credit/transfers/reserveFunds' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "amount": { "amount": "100000.00", "currency": "USD" },
  "destination": {
    "type": "verified_blockchain",
    "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }
}'
```

<Note>
  The `destination` field is optional. If included, disbursed funds are sent to
  the specified verified blockchain address instead of your Circle Mint wallet.
  The `addressId` must reference a verified address from your [Circle Mint
  recipient address
  book](/api-reference/circle-mint/account/create-business-recipient-address).
  If you omit `destination`, funds deposit into your Circle Mint wallet by
  default.
</Note>

```json Response theme={null}
{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "funds_reserved",
    "expiresAt": "2024-03-20T15:00:00.000Z",
    "blockchainDestination": {
      "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "status": "pending"
    },
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-20T14:30:00.000Z"
  }
}
```

Save the transfer `id` from the response. You need it for the remaining steps.

<Warning>
  Reserved funds expire after 30 minutes. If you don't upload wire proof before
  the `expiresAt` timestamp, the reservation automatically transitions to
  `expired` status and the funds return to your available credit.
</Warning>

Only one transfer can be in `funds_reserved` status per credit line at a time.
You must complete or cancel the current reservation before creating a new one.

## Step 4: Upload wire proof

Using the beneficiary details and tracking reference from Step 2 (found at
`data.wireInstructions.trackingRef` in the response), initiate your wire
transfer through your bank. Then upload proof of the wire to request
disbursement. Call `PUT /v1/credit/transfers/{id}/requestReservedFunds` with a
`multipart/form-data` request containing your wire proof document.

Accepted file types are PDF (`application/pdf`), JPEG (`image/jpeg`), and PNG
(`image/png`).

```bash theme={null}
curl --location --request PUT 'https://api-sandbox.circle.com/v1/credit/transfers/fc988ed5-c129-4f70-a064-e5beb7eb8e32/requestReservedFunds' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'fileName="wire-confirmation.pdf"' \
--form 'fileContent=@"/path/to/wire-confirmation.pdf"'
```

```json Response theme={null}
{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "requested",
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-20T14:45:00.000Z"
  }
}
```

The transfer status transitions from `funds_reserved` to `requested`. At this
point, Circle's Treasury team reviews the wire proof. No further action is
required from you until the review completes.

## Step 5: Track the transfer status

Monitor your transfer as it progresses through the review and disbursement
process. You can poll the transfer endpoint or subscribe to webhook
notifications.

### Poll the transfer endpoint

Call `GET /v1/credit/transfers/{id}` to check the current transfer status.

```bash theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/credit/transfers/fc988ed5-c129-4f70-a064-e5beb7eb8e32' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

Once Treasury approves the transfer and disburses funds, the response reflects
the `disbursed` status along with fee and repayment details:

```json Response theme={null}
{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "disbursed",
    "outstanding": { "amount": "102000.00", "currency": "USD" },
    "fees": {
      "total": { "amount": "2000.00", "currency": "USD" },
      "unpaid": { "amount": "2000.00", "currency": "USD" }
    },
    "dueDate": "2024-03-28T10:00:00.000Z",
    "disbursedDate": "2024-03-21T10:00:00.000Z",
    "blockchainDestination": {
      "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "status": "complete",
      "transferId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
    },
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-21T10:00:00.000Z"
  }
}
```

The `outstanding` amount includes the original draw plus any accrued fees. The
`dueDate` indicates when repayment is expected. Settlement Advance transfers use
daily cadence with a 7-day repayment due date from disbursement.

If you included a `destination` in your request, the `blockchainDestination`
field tracks the status of the onchain transfer.

| Status      | Description                                 | `transferId` populated |
| ----------- | ------------------------------------------- | ---------------------- |
| `pending`   | Destination recorded, awaiting disbursement | No                     |
| `initiated` | Blockchain transfer submitted               | Yes                    |
| `complete`  | Funds arrived at destination address        | Yes                    |
| `failed`    | Blockchain transfer failed                  | Yes                    |

### Subscribe to webhook notifications

For real-time updates, subscribe to webhook notifications through the Circle
Mint webhook management UI:

* **`creditTransfers`**: Receive notifications whenever a transfer changes
  status, such as the transition from `requested` to `disbursed`.
* **`creditFees`**: Receive notifications when fees are accrued against your
  outstanding transfers.
* **`creditRepayments`**: Receive notifications when a repayment is received and
  allocated against your outstanding balance.

The Settlement Advance transfer follows this status lifecycle:

```mermaid theme={null}
stateDiagram-v2
    [*] --> funds_reserved
    funds_reserved --> requested
    funds_reserved --> expired
    funds_reserved --> canceled
    requested --> disbursed
    requested --> rejected
    disbursed --> paid
    disbursed --> past_due
    past_due --> paid
```

A transfer can also reach `expired` (if the reservation times out), `rejected`
(if Treasury declines the request), or `past_due` (if repayment is overdue).

<Info>
  In sandbox, Settlement Advance requests are auto-approved. To simulate a
  rejection, reserve funds with an amount of `119.53`.
</Info>

## Cancel a reservation (optional)

If you need to cancel a reservation before uploading wire proof, call
`PUT /v1/credit/transfers/{id}/cancelReserve`. You can only cancel a transfer
that is in `funds_reserved` status.

```bash theme={null}
curl --location --request PUT 'https://api-sandbox.circle.com/v1/credit/transfers/fc988ed5-c129-4f70-a064-e5beb7eb8e32/cancelReserve' \
--header 'Authorization: Bearer YOUR_API_KEY'
```

```json Response theme={null}
{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "canceled",
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-20T14:50:00.000Z"
  }
}
```

After cancellation, the reserved amount returns to your available credit and you
can create a new reservation.


# Crypto Payouts Payment Reason Codes
Source: https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes

Payment reason codes for the Crypto Payouts API purposeOfTransfer field.

Use a `purposeOfTransfer` value when you
[create a crypto payout](/api-reference/circle-mint/payouts/create-payout), if
your entity configuration requires it. Each value is a payment reason code.

The table lists codes accepted for Crypto Payouts. Values align with
[CPN payment reason codes](/cpn/references/errors/payment-reason-codes). This
list adds `PMT000` for cases that do not match another code. Do not use
`PMT006`; it is not valid for crypto payouts.

| Reason code | Description                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `PMT000`    | Others                                                                                                 |
| `PMT001`    | Invoice payment                                                                                        |
| `PMT002`    | Payment for services                                                                                   |
| `PMT003`    | Payment for software                                                                                   |
| `PMT004`    | Payment for imported goods                                                                             |
| `PMT005`    | Travel services                                                                                        |
| `PMT007`    | Repayment of loans                                                                                     |
| `PMT008`    | Payroll                                                                                                |
| `PMT009`    | Payment of property rental                                                                             |
| `PMT010`    | Information service charges                                                                            |
| `PMT011`    | Advertising and public relations related expenses                                                      |
| `PMT012`    | Royalty fees, trademark fees, patent fees, and copyright fees                                          |
| `PMT013`    | Fees for brokers, front end fee, commitment fee, guarantee fee, and custodian fee                      |
| `PMT014`    | Fees for advisors, technical assistance, and academic knowledge including remuneration for specialists |
| `PMT015`    | Representative office expenses                                                                         |
| `PMT016`    | Tax payment                                                                                            |
| `PMT017`    | Transportation fees for goods                                                                          |
| `PMT018`    | Construction costs/expenses                                                                            |
| `PMT019`    | Insurance premium                                                                                      |
| `PMT020`    | General goods trades (offline)                                                                         |
| `PMT021`    | Insurance claims payment                                                                               |
| `PMT022`    | Remittance payments to friends or family                                                               |
| `PMT023`    | Education-related student expenses                                                                     |
| `PMT024`    | Medical treatment                                                                                      |
| `PMT025`    | Donations                                                                                              |
| `PMT026`    | Mutual fund investment                                                                                 |
| `PMT027`    | Currency exchange                                                                                      |
| `PMT028`    | Advance payments for goods                                                                             |
| `PMT029`    | Merchant settlement                                                                                    |
| `PMT030`    | Repatriation fund settlement                                                                           |


# Quickstart: Exchange Local Currency for USDC
Source: https://developers.circle.com/circle-mint/exchange-local-currency-usdc



The Cross-Currency API lets you swap local currency for USDC. To onramp funds in
this way, you must first have a fiat account linked to your Circle Mint account.

This guide walks you through how to use the Cross-Currency API to obtain a quote
for a local currency to USDC exchange and then execute the swap.

## Prerequisites

Before you begin this quickstart, ensure that you have:

* Obtained an API key for Mint from Circle
* Obtained access to the Cross-Currency API
* Installed cURL on your development machine
* Linked a fiat account to your Circle Mint account

This quickstart provides API requests in cURL format, along with example
responses.

## Part 1: Request a quote

To begin an onramp from fiat to USDC, you must first request a quote. Quotes
have a rate guarantee until they expire.

<Note>
  **Note:** [Step 1.1.](#11-get-a-list-of-linked-fiat-accounts) and [Step
  1.2.](#12-specify-which-fiat-account-to-use) only need to be performed once.
  If you want to switch the fiat account attached to your FX trading account,
  you can repeat these two steps.
</Note>

### 1.1. Get a list of linked fiat accounts

Retrieve a list of the fiat accounts linked to your Circle Mint account using
the following request:

```shell Shell theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/businessAccount/banks/pix' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json JSON theme={null}
{
  "data": [
    {
      "id": "763a80d8-9bbb-4876-a67d-e8089389b016",
      "type": "wire",
      "status": "complete",
      "createDate": "2025-09-16T15:53:47.251Z",
      "updateDate": "2025-09-16T15:53:48.293Z",
      "description": "Banco Azteca ****7771",
      "trackingRef": "CIR3A3R7EV",
      "virtualAccountEnabled": true,
      "fingerprint": "faf6b92c-4e76-426c-9741-95aed1415715",
      "billingDetails": {
        "name": "Satoshi Nakamoto",
        "line1": "100 Money Street",
        "line2": "Suite 1",
        "city": "Boston",
        "postalCode": "01234",
        "district": "MA",
        "country": "US",
        "valid": true
      },
      "bankAddress": {
        "bankName": "Banco Azteca",
        "line1": "Iabel la Católica 165",
        "line2": "Colonia Obrera",
        "city": "México DF",
        "district": "México DF",
        "country": "MX"
      }
    }
  ]
}
```

### 1.2. Specify which fiat account to use

Register your local fiat account with the Cross-Currency API to make it the
account that settles trades. The following is an example request to register
your fiat account:

```shell Shell theme={null}
curl --location --request PUT 'https://api-sandbox.circle.com/v1/exchange/fxConfigs/accounts' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fiatAccountId": "763a80d8-9bbb-4876-a67d-e8089389b016",
    "currency": "MXN"
}'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "currency": "MXN",
    "fiatAccountId": "763a80d8-9bbb-4876-a67d-e8089389b016",
    "createDate": "2025-01-09T17:50:09.452241Z",
    "updateDate": "2025-02-28T17:25:15.866900Z"
  }
}
```

### 1.3. Request a quote from the API

Using a UUIDv4 generator, generate a UUID to use as the idempotency key. Using
the idempotency key, generate a quote for exchanging a specific amount of local
currency to USDC. You must include an `amount` field on either the `from` or the
`to` object, but not both. The `type` field must be set to `tradable` to get a
locked rate quote. The following is an example request for a quote:

<Note>
  **Note:** Quotes are valid for 3 seconds and must be refreshed if not used in
  that time frame.
</Note>

```shell Shell theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/exchange/quotes' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "tradable",
  "idempotencyKey": "07c238ad-b144-4607-9b70-51d1ffbb3c7b",
  "from": {
    "currency": "MXN",
    "amount": 100.00
  },
  "to": {
    "currency": "USDC",
    "amount": null
  }
}
'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "id": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1",
    "rate": 0.0597,
    "from": {
      "currency": "MXN",
      "amount": 100.0
    },
    "to": {
      "currency": "USDC",
      "amount": 5.01
    },
    "expiry": "2023-10-26T14:37:20.804786Z",
    "type": "tradable"
  }
}
```

## Part 2: Initiate the trade

Once you have obtained a quote, you can lock in the rate by accepting it and
initiating the trade. If you were building a UI for your users, you would
display the quote to your users and let them confirm the trade.

### 2.1. Create the trade

Generate another idempotency key, and then use it to confirm the quote and lock
in the rate using the following example request:

```shell Shell theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/exchange/trades' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "7a6cba1e-6b8d-4bb8-b236-5c20a12e88f6",
  "quoteId": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1"
}
'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "id": "7a6cba1e-6b8d-4bb8-b236-5c20a12e88f6",
    "from": {
      "currency": "MXN",
      "amount": 100
    },
    "to": {
      "currency": "USDC",
      "amount": 5.01
    },
    "status": "pending",
    "createDate": "2023-10-26T14:37:20.804786Z",
    "updateDate": "2023-10-26T14:37:20.804786Z",
    "quoteId": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1"
  }
}
```

### 2.2. Check the trade status

After creating a trade, you must check the trade status before sending funds.
Use the following request to retrieve the trade status:

```shell Shell theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/exchange/trades/7a6cba1e-6b8d-4bb8-b236-5c20a12e88f6' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "id": "7a6cba1e-6b8d-4bb8-b236-5c20a12e88f6",
    "from": {
      "currency": "MXN",
      "amount": 100
    },
    "to": {
      "currency": "USDC",
      "amount": 5.01
    },
    "status": "confirmed",
    "createDate": "2023-10-26T14:37:20.804786Z",
    "updateDate": "2023-10-26T14:37:21.123456Z",
    "quoteId": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1"
  }
}
```

<Warning>
  Only proceed to send funds when the trade status is `confirmed`. The possible
  status values are:

  * `pending`: The trade is not yet executed. Do not send funds.
  * `confirmed`: The trade is fully executed. You can proceed to send funds.
  * `failed`: The trade has failed. Do not send funds.
</Warning>

## Part 3: Send the funds

Once you have confirmed that your trade status is `confirmed`, you can send the
fiat funds to Circle. Do not send funds if the trade status is `pending` or
`failed`. Once received, the USDC is transferred to the appropriate address.

### 3.1. Get settlement batches

Retrieve unsettled payment batches from the API using the following example
request:

```shell Shell theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/exchange/trades/settlements' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json JSON theme={null}
{
  "data": [
    {
      "id": "67276b7d-7ea5-4f22-a231-09e2d2891c36",
      "entityId": "c5692eb6-33f9-431d-9481-2eee38f02081",
      "status": "pending",
      "createDate": "2025-09-11T15:45:04.729442Z",
      "updateDate": "2025-09-11T15:45:04.729443Z",
      "details": [
        {
          "id": "02bd22dc-b40f-49b8-b2d8-6e69f82cfca0",
          "type": "payable",
          "status": "pending",
          "reference": "ezBrwN2nP5Bz18Lu",
          "amount": {
            "currency": "MXN",
            "amount": "100.00"
          },
          "expectedPaymentDueAt": "2025-09-11T16:45:00Z",
          "createDate": "2025-09-11T15:45:04.728466Z",
          "updateDate": "2025-09-11T15:45:04.728466Z"
        },
        {
          "id": "afbd8d53-34ea-42fa-9691-4a5c0dd96c53",
          "type": "receivable",
          "status": "pending",
          "amount": {
            "currency": "USDC",
            "amount": "5.01"
          },
          "createDate": "2025-09-11T15:45:04.728479Z",
          "updateDate": "2025-09-11T15:45:04.728479Z"
        }
      ]
    }
  ]
}
```

### 3.2. Get payment instructions

Retrieve the settlement instructions for the currency you are using with the
following example request. Note that this step only needs to be performed once,
as the values are static and can be safely cached.

```shell Shell theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/exchange/trades/settlements/instructions/MXN' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "currency": "MXN",
    "fiatAccountType": "wire",
    "instruction": {
      "beneficiary": {
        "name": "PLATAFORMA INTEGRAL DE CRIPTOS Y OTROS A",
        "address1": "AVENIDA INSURGENTES SUR 3579",
        "address2": "COLONIA VILLA OLÍMPICA, ALCALDÍA TLALPAN"
      },
      "beneficiaryBank": {
        "swiftCode": "AZTKMXMMXXX",
        "routingNumber": "322286803",
        "accountNumber": "127180987654321012",
        "currency": "MXN",
        "name": "BANCO AZTECA",
        "address": "AVENIDA INSURGENTES SUR 3579",
        "postalCode": "14020",
        "country": "MX"
      },
      "trackingRef": "ezBrwN2nP5Bz18Lu"
    }
  }
}
```

### 3.3. Create a fiat transfer

Initiate an inbound fiat transfer to the account specified in the instructions.
You should include the reference to the settlement batch in the transfer
request. When Circle receives the transfer, Circle updates the settlement batch
and transfers USDC to your Mint account.

If you were building a UI for your users, you would display instructions on how
to complete the transfer. In such a scenario, when the USDC is allocated to your
Mint account, you must then transfer it to the end user that requested the
trade.

<Warning>
  **Warning:** You must only send the fiat transfer on the specified payment rail.
  In this example, for `MXN`, you must send the transfer on the SPEI payment rail.
  Transfers on unsupported payment rails may take significant time and cost to
  recover.
</Warning>


# How Stablecoin Payins and Payouts Work
Source: https://developers.circle.com/circle-mint/how-stablecoin-payins-and-payouts-work

Learn how stablecoin payins and payouts work, including payment intents, payin and payout flows, and refunds.

Stablecoin payins and payouts let you move USDC and EURC onchain through Circle
Mint. A stablecoin payin is when your customer sends USDC or EURC to you onchain
and Circle records that transfer. A stablecoin payout is when you send USDC or
EURC to a customer, vendor, or supplier onchain.

## Payment intents

You create a payment intent when a customer chooses to pay with USDC or EURC on
a
[supported blockchain](/circle-mint/references/supported-chains-and-currencies).
The intent carries settlement currency, allowed chains, and the deposit address
your customer uses.

### Continuous and transient modes

In practice, think of the two payment intent modes like this:

* **Continuous** fits repeat deposits. The customer gets a long-lived deposit
  address they can use more than once (for example top-ups or billing that
  reuses one address). Each successful inbound transfer is recorded as its own
  payment.
* **Transient** fits a one-time checkout. You declare a fixed amount for one
  purchase or session (for example one cart or invoice). You still create a
  payment intent and show a deposit address, but this address cannot be reused
  for later top-ups or future orders.

The
[Create payment intent](/api-reference/circle-mint/payments/create-payment-intent)
endpoint reflects that split in the request and response. Continuous omits a
top-level `amount` at creation. Transient requires `type: "transient"` and an
`amount`. The following table compares what you send when you create an intent
and how you should use the deposit address in each mode.

|                    | Continuous                                           | Transient                                        |
| ------------------ | ---------------------------------------------------- | ------------------------------------------------ |
| Amount at creation | Omitted. You set `currency` and settlement.          | You set a fixed `amount`.                        |
| Deposit address    | Same address can receive multiple transfers.         | Suited to a single checkout or one-time payment. |
| How you select it  | Omit `type` (default) or set `type` to `continuous`. | Set `type` to `transient`.                       |

When a transfer settles, Circle creates a
[payment](/api-reference/circle-mint/payments/get-payment) for it. For
continuous payment intents, each transfer is represented as its own payment. For
transient payment intents, the deposit address is used for a single checkout or
one-time payment.

## Payin flow

To [receive a stablecoin payin](/circle-mint/receive-stablecoin-payin), the
customer, your customer-facing UI, your server, and Circle follow the same steps
whether the intent is continuous or transient. The customer-facing UI is the
interface your customer uses to make a payment, such as your website or mobile
app. Your server calls Circle Mint APIs and handles webhooks or polling.

<Steps>
  <Step title="Create a payment intent">
    On checkout, the customer chooses to pay with stablecoins in your
    customer-facing UI. Your server calls the [Create a payment
    intent](/api-reference/circle-mint/payments/create-payment-intent) endpoint
    with the currency, blockchain, payment intent type, and (for transient only)
    amount.
  </Step>

  <Step title="Get the deposit address">
    Your server receives the deposit address by using
    [webhooks](/circle-mint/circle-apis-notifications-quickstart) or by polling
    the [Get a payment
    intent](/api-reference/circle-mint/payments/get-payment-intent) endpoint
    until `paymentMethods` includes an `address`.
  </Step>

  <Step title="Customer sends funds onchain">
    Your customer-facing UI shows the deposit address (and for transient only,
    the amount). The customer sends USDC or EURC from their wallet to that
    address on the correct blockchain.
  </Step>

  <Step title="Receive confirmation">
    Circle detects the transfer. It creates or updates payment data and sends
    notifications. Your server treats the payin as complete when payment and
    payment intent state match your policies.
  </Step>
</Steps>

The following diagram illustrates the payin flow at checkout:

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant W as Customer-facing UI
    participant S as Your server
    participant M as Circle Mint APIs

    Note over C,M: Create payment intent
    C->>W: Chooses to pay with stablecoins on a blockchain
    W->>S: Requests onchain deposit
    S->>M: Sends payment intent creation request
    M-->>S: Sends payment intent

    Note over C,M: Send and display deposit address
    M-->>S: Sends notification containing: <br> payment intent status (pending), <br> deposit address
    S->>W: Sends deposit address
    W->>C: Displays deposit address

    Note over C,M: Customer pays onchain and Circle notifies your server
    C->>M: Transfers funds to deposit address
    M-->>S: Sends notification containing: <br> payment status (paid)
    M-->>S: Sends notification containing: <br> payment intent status (complete)

    Note over C,M: Confirm payment to customer
    S->>W: Sends payment confirmation
    W->>C: Displays payment confirmation
```

## Payout flow

To [send a stablecoin payout](/circle-mint/send-stablecoin-payout), your server
calls the Crypto Payouts API. The recipient receives USDC or EURC at the wallet
address you register.

<Steps>
  <Step title="Create an address book recipient">
    Your server creates a recipient by calling the [Create address book
    recipient](/api-reference/circle-mint/payouts/create-address-book-recipient)
    endpoint with the destination blockchain and address. The recipient status
    must be `active` before continuing.
  </Step>

  <Step title="Create a payout">
    Your server calls the [Create
    payout](/api-reference/circle-mint/payouts/create-payout) endpoint with the
    address book recipient ID, `sourceWalletId`, and amounts. The payout starts
    in `pending`.
  </Step>

  <Step title="Circle delivers onchain">
    Circle debits your Mint balance and sends funds to the registered address on
    the selected blockchain.
  </Step>

  <Step title="Receive confirmation">
    Treat the payout as finalized when the `status` is `complete`. Use
    [webhooks](/circle-mint/circle-apis-notifications-quickstart) for `payout`
    events or poll the [Get
    payout](/api-reference/circle-mint/payouts/get-payout) endpoint.
  </Step>
</Steps>

The following diagram illustrates the payout flow:

```mermaid theme={null}
sequenceDiagram
    participant S as Your server
    participant M as Circle Mint APIs
    participant R as Recipient wallet

    Note over S,M: Create address book recipient
    S->>M: Sends create address book recipient request
    M-->>S: Sends address book recipient

    Note over S,M: Create payout
    S->>M: Sends create payout request
    M-->>S: Sends payout (pending)

    Note over M,R: Onchain delivery
    M->>R: Transfers USDC or EURC to registered address

    Note over S,M: Payout complete
    M-->>S: Sends notification containing: <br> payout status (complete)
```

## Payment intent expiration

A payment intent can expire. Expiration does not automatically return funds. The
intent mainly tells the customer which deposit address to use. If funds still
arrive at that address, Circle processes it as a payin on your Mint account.

## Refunds

[Issue a full or partial refund](/circle-mint/refund-stablecoin-payin) through
the refund APIs or by signing in to your
[Circle Mint](https://app.circle.com/signin) account.

What you should know about refunds:

* Start a refund after at least one payment on the intent has completed and
  settled. You cannot start a refund while a payment is still pending.
* Submit refunds within 30 days of creating the payment intent. During that
  period you can send more than one partial refund, up to the limits of your
  Mint account.
* After you start a refund, the payment intent status moves to `refunded`. The
  intent stops accepting new payins. Don't reuse a refunded intent for new
  checkouts. Funds sent to that address might not match the intent and can
  require support.
* If you use your Circle Mint account to refund, the refund cannot be canceled
  once submitted.


# How-to: Deposit Fiat
Source: https://developers.circle.com/circle-mint/howtos/deposit-fiat

Link a bank account and deposit fiat to mint USDC or EURC in your Circle Mint account.

Deposit fiat (onramp) from an external bank account to mint USDC or EURC in your
Circle Mint balance. The `/wires` endpoint supports multiple payment rails,
including standard wires (FedWire and SWIFT), real-time interbank rails (RTP,
SPEI, SEPA, and CHATS) where available, and book transfers when you bank with
one of Circle's settlement partners.

<Note>
  This guide focuses on standard wire deposits. The same endpoint handles other
  rails -- Circle routes the deposit based on your linked bank and region.
  Rail-specific parameters and additional endpoints (such as CUBIX and PIX for
  local currencies) are out of scope here.
</Note>

## Prerequisites

Before you begin:

* Complete the
  [account and API key setup](/circle-mint/quickstarts/getting-started).
* Have access to a bank account that can send wire transfers.

## Step 1. Link a bank account

Use the
[create a wire bank account](/api-reference/circle-mint/account/create-business-wire-account)
endpoint to register your external bank account with Circle Mint.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/banks/wires \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"ba943ff1-ca16-49b2-ba55-1057e70ca5c7","accountNumber":"12340010","routingNumber":"121000248","billingDetails":{"name":"Satoshi Nakamoto","city":"Boston","country":"US","line1":"100 Money Street","district":"MA","postalCode":"01234"},"bankAddress":{"bankName":"SAN FRANCISCO","city":"SAN FRANCISCO","country":"US","line1":"100 Money Street","district":"CA"}}'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
    "status": "pending",
    "description": "WELLS FARGO BANK, NA ****0010",
    "trackingRef": "CIR2GKYL4B",
    "virtualAccountEnabled": true,
    "billingDetails": {
      "name": "Satoshi Nakamoto",
      "line1": "100 Money Street",
      "city": "Boston",
      "postalCode": "01234",
      "district": "MA",
      "country": "US"
    },
    "bankAddress": {
      "bankName": "WELLS FARGO BANK, NA",
      "line1": "100 Money Street",
      "city": "SAN FRANCISCO",
      "district": "CA",
      "country": "US"
    },
    "createDate": "2023-11-04T20:02:21.062Z",
    "updateDate": "2023-11-04T20:02:21.062Z"
  }
}
```

Record the `id` and `trackingRef` values from the response. You use both in the
following steps.

## Step 2. Retrieve wire instructions

Use the
[get wire instructions](/api-reference/circle-mint/account/get-business-wire-account-instructions)
endpoint to fetch the beneficiary details your bank needs to send the wire.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/banks/wires/${BANK_ACCOUNT_ID}/instructions \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

Expected response:

```json theme={null}
{
  "data": {
    "trackingRef": "CIR22FEP33",
    "beneficiary": {
      "name": "CIRCLE INTERNET FINANCIAL INC",
      "address1": "1 MAIN STREET",
      "address2": "SUITE 1"
    },
    "virtualAccountEnabled": true,
    "beneficiaryBank": {
      "name": "CRYPTO BANK",
      "address": "1 MONEY STREET",
      "city": "NEW YORK",
      "postalCode": "1001",
      "country": "US",
      "swiftCode": "CRYPTO99",
      "routingNumber": "999999999",
      "accountNumber": "123815146304",
      "currency": "USD"
    }
  }
}
```

The response includes:

* **Beneficiary details** -- the name and address of the recipient (Circle).
* **Routing information** -- the bank name, SWIFT code, and routing number for
  the beneficiary bank.
* **Virtual Account Number** -- the `beneficiaryBank.accountNumber` field,
  unique to your linked bank account.
* **Tracking reference** -- the `trackingRef` value to include in the wire memo.

### Virtual account numbers

Not all Circle settlement banks support Virtual Account Numbers. When
`virtualAccountEnabled` is `true` in the wire instructions response, the linked
bank account has a unique VAN in the `beneficiaryBank.accountNumber` field. When
the sender includes the VAN as the account number on their wire, the tracking
reference in the wire memo becomes optional.

When `virtualAccountEnabled` is `false`, the sender must include the
`trackingRef` in the wire memo so Circle can match the deposit to your account.

Benefits of using a VAN (where supported):

* Eliminates the need for senders to include tracking references in payment
  instructions.
* Reduces wire returns caused by missing or incorrect tracking references.
* Supports all wire types: domestic, international, and SWIFT.

## Step 3. Send the wire deposit

In production, initiate the wire transfer from your bank using the instructions
returned in Step 2. Confirm that the wire details -- beneficiary name, account
number, and routing number -- match exactly. Mismatched details can result in
wire returns or processing delays of several business days.

Domestic wire deposits received before the daily cutoff typically settle on the
same business day. International wires may take longer depending on intermediary
banks.

### Simulate a deposit in sandbox

In the sandbox environment, use the
[mock wire payment](/api-reference/circle-mint/account/create-mock-wire-payment)
endpoint to simulate a wire deposit without sending real funds. Provide the
`trackingRef` from Step 2 and the `beneficiaryBank.accountNumber` (the VAN) from
the wire instructions response.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/mocks/payments/wire \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"amount":{"amount":"50.00","currency":"USD"},"trackingRef":"CIR22FEP33","beneficiaryBank":{"accountNumber":"123815146304"}}'
```

Expected response:

```json theme={null}
{
  "data": {
    "trackingRef": "CIR22FEP33",
    "amount": {
      "amount": "50.00",
      "currency": "USD"
    },
    "beneficiaryBank": {
      "accountNumber": "123815146304"
    },
    "status": "pending"
  }
}
```

<Note>
  The mock wire endpoint is available in sandbox only. Mock wire deposits
  process in batches and may take up to 15 minutes to complete.
</Note>

## Step 4. Verify the deposit

Use the
[list deposits](/api-reference/circle-mint/account/list-business-deposits)
endpoint to confirm the incoming fiat deposit has settled.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/deposits \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

Expected response:

```json theme={null}
{
  "data": [
    {
      "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
      "sourceWalletId": "1000066041",
      "destination": {
        "type": "wallet",
        "id": "1000066041"
      },
      "amount": {
        "amount": "50.00",
        "currency": "USD"
      },
      "status": "complete",
      "createDate": "2024-01-01T12:00:00.000Z"
    }
  ]
}
```

## See also

* [How Minting and Redemption Works](/circle-mint/concepts/how-minting-works) --
  understand the minting process
* [Sandbox to Production](/circle-mint/references/sandbox-and-testing) --
  transition to production
* [Create a wire bank account](/api-reference/circle-mint/account/create-business-wire-account)
  \-- API reference


# How-to: Transfer USDC Onchain
Source: https://developers.circle.com/circle-mint/howtos/transfer-on-chain

Receive USDC and EURC via deposit addresses and send them to external blockchain wallets using the Circle Mint API.

Receive USDC or EURC by generating deposit addresses for external wallets to
send to, or send USDC or EURC to allowlisted recipient addresses on supported
blockchains. Transfers of \$3,000 or more require Travel Rule compliance data for
third-party payouts.

## Prerequisites

Before you begin:

* Complete the
  [account and API key setup](/circle-mint/quickstarts/getting-started).
* Review
  [supported chains and currencies](/circle-mint/references/supported-chains-and-currencies)
  for available blockchains.
* (For sending) Have a funded Circle Mint account.
* (For sending) All recipient addresses must be approved by an account
  administrator through the [Mint Console](https://app.circle.com/signin) before
  you can create transfers. If your account is domiciled in France or Singapore,
  addresses require additional verification through the Mint Console.

## Step 1. Receive USDC via deposit address

### Step 1.1. Create a deposit address

Use the create deposit address endpoint to generate an address for receiving
USDC or EURC on a specific blockchain.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/deposit \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "currency": "USD", "chain": "ARC"}'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "d51d72d2-9955-4340-b3fd-2f07a82a1e6c",
    "address": "0xbd01242af414961c25aa72dcae06646fc52e9b92",
    "currency": "USD",
    "chain": "ARC"
  }
}
```

<Note>
  You can create one deposit address per blockchain. Use the same address for
  all deposits on that blockchain.
</Note>

### Step 1.2. Send funds to your deposit address

This step happens outside the Circle Mint API. The sender transfers USDC or EURC
from their external wallet to your deposit address on the matching blockchain.

<Warning>
  Sending funds on the wrong blockchain results in permanent loss. Always
  confirm the blockchain network matches between the sender's wallet and your
  deposit address.
</Warning>

### Step 1.3. Verify the deposit

Use the
[list transfers](/api-reference/circle-mint/account/list-business-transfers)
endpoint to confirm the incoming transfer has settled.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/transfers \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

Expected response:

```json theme={null}
{
  "data": [
    {
      "id": "a6a1b575-13d5-4e73-9da7-73e2a3e4418a",
      "source": {
        "type": "blockchain",
        "chain": "ARC"
      },
      "destination": {
        "type": "wallet",
        "id": "1000066041"
      },
      "amount": {
        "amount": "100.00",
        "currency": "USD"
      },
      "transactionHash": "0x4cfd25b5ab46e9fe25e845e7a7e0ea2f1f7e4bba3c6e0f1db0b846e4a1bc5fd2",
      "status": "complete",
      "createDate": "2024-01-01T12:00:00.000Z"
    }
  ]
}
```

The transfer reaches `complete` status after the required number of
[blockchain confirmations](/circle-mint/references/blockchain-confirmations) for
the deposit's blockchain.

## Step 2. Send USDC to an external address

### Step 2.1. Add a recipient address

Use the create recipient address endpoint to allowlist an external blockchain
address for outbound transfers.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "2a308497-e66e-4c42-ac1e-7bedab86d958", "address": "0x493A9869E3B5f846f72267ab19B76e9bf99d51b1", "chain": "ARC", "currency": "USD", "description": "Treasury wallet"}'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "cfa01bb0-d166-5506-a48a-56f2beab559f",
    "address": "0x493a9869e3b5f846f72267ab19b76e9bf99d51b1",
    "chain": "ARC",
    "currency": "USD",
    "description": "Treasury wallet"
  }
}
```

Adding a recipient address through the API creates a pending request. An account
administrator must approve the address through the
[Mint Console](https://app.circle.com/signin) before you can send transfers to
it. A confirmation notification is sent to all administrators.

### Step 2.2. Create a transfer

Use the create transfer endpoint to send funds to the approved recipient
address.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/transfers \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "6ec3827d-15bb-442e-9d4c-32e73e61cbf4", "destination": {"type": "verified_blockchain", "addressId": "cfa01bb0-d166-5506-a48a-56f2beab559f"}, "amount": {"currency": "USD", "amount": "25.00"}}'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "21fd4ec4-bad1-4eb2-9fc5-60320dedc7ea",
    "source": {
      "type": "wallet",
      "id": "1016875042"
    },
    "destination": {
      "type": "blockchain",
      "address": "0x493a9869e3b5f846f72267ab19b76e9bf99d51b1",
      "chain": "ARC"
    },
    "amount": {
      "amount": "25.00",
      "currency": "USD"
    },
    "status": "pending",
    "createDate": "2024-07-15T16:41:12.395Z"
  }
}
```

### Step 2.3. Check the transfer status

Use the get transfer endpoint to monitor the status of your transfer.

```bash theme={null}
curl -X GET https://api-sandbox.circle.com/v1/businessAccount/transfers/21fd4ec4-bad1-4eb2-9fc5-60320dedc7ea \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

The transfer progresses through these statuses:

* **`pending`**: Circle received the request.
* **`running`**: The transaction is broadcast onchain. The response includes a
  `transactionHash`.
* **`complete`**: Blockchain finality reached -- the required number of
  confirmations passed.

Expected response for a running transfer:

```json theme={null}
{
  "data": {
    "id": "21fd4ec4-bad1-4eb2-9fc5-60320dedc7ea",
    "source": {
      "type": "wallet",
      "id": "1016875042"
    },
    "destination": {
      "type": "blockchain",
      "address": "0x493a9869e3b5f846f72267ab19b76e9bf99d51b1",
      "chain": "ARC"
    },
    "amount": {
      "amount": "25.00",
      "currency": "USD"
    },
    "transactionHash": "0x0654eee4f609f9c35e376cef9455dd9fc1546c482c5c32c8f8d434ead14fcf97",
    "status": "running",
    "createDate": "2024-07-15T16:41:12.395Z"
  }
}
```

## Travel Rule compliance

The Financial Crimes Enforcement Network (FinCEN) Travel Rule requires financial
institutions to share originator and beneficiary information for transfers of
\$3,000 or more.

### When it applies

Travel Rule applies to onchain transfers of \$3,000 or more on these blockchains:

* Algorand (ALGO)
* Aptos (APTOS)
* Arbitrum (ARB)
* Avalanche (AVAX)
* Base (BASE)
* Celo (CELO)
* Ethereum (ETH)
* NEAR (NEAR)
* Optimism (OP)
* Polygon PoS (POLY)
* Ripple (XRPL)
* Solana (SOL)
* Stellar (XLM)

### Business account transfers

For transfers from your Circle Mint account using
`POST /v1/businessAccount/transfers`, Circle uses your company identity on file.
No additional data is required in the API request.

### Third-party payouts

For payouts to third parties using the
[Crypto Payouts API](/circle-mint/send-stablecoin-payout) (`POST /v1/payouts`),
you must include the originator's identity in the `source.identities` array.

The following table describes the identities schema:

| Field                    | Type   | Required                    | Description                             |
| ------------------------ | ------ | --------------------------- | --------------------------------------- |
| `type`                   | string | Yes                         | `individual` or `business`              |
| `name`                   | string | Yes                         | Full legal name                         |
| `addresses`              | array  | No                          | Array of address objects                |
| `addresses[].line1`      | string | Yes (if addresses provided) | Street address                          |
| `addresses[].city`       | string | Yes (if addresses provided) | City                                    |
| `addresses[].district`   | string | No                          | State/province (2-letter code for `US`) |
| `addresses[].country`    | string | Yes (if addresses provided) | ISO 3166-1 alpha-2 country code         |
| `addresses[].postalCode` | string | No                          | Postal code                             |

The following example shows a payout request with originator identity data:

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "source": {"type": "wallet", "id": "12345", "identities": [{"type": "individual", "name": "Satoshi Nakamoto", "addresses": [{"line1": "100 Money Street", "city": "Boston", "district": "MA", "country": "US", "postalCode": "01234"}]}]}, "destination": {"type": "blockchain", "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F", "chain": "ETH"}, "amount": {"amount": "3000.00", "currency": "USD"}}'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "b36cbf12-6ed1-47ed-9eb9-5874f8991ca8",
    "source": {
      "type": "wallet",
      "id": "12345",
      "identities": [
        {
          "type": "individual",
          "name": "Satoshi Nakamoto",
          "addresses": [
            {
              "line1": "100 Money Street",
              "city": "Boston",
              "district": "MA",
              "country": "US",
              "postalCode": "01234"
            }
          ]
        }
      ]
    },
    "destination": {
      "type": "blockchain",
      "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
      "chain": "ETH"
    },
    "amount": {
      "amount": "3000.00",
      "currency": "USD"
    },
    "status": "pending",
    "createDate": "2024-07-10T02:13:30.000Z"
  }
}
```

### Receiving transfers

If you are a regulated financial institution, Circle provides originator
identity data on inbound transfers of \$3,000 or more. Use
`returnIdentities=true` as a query parameter on GET endpoints:

```bash theme={null}
curl -X GET "https://api-sandbox.circle.com/v1/payouts/{id}?returnIdentities=true" \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

### Failure behavior

If a transfer requires identity data and it is omitted, the transfer fails with:

* `riskEvaluation.decision`: `denied`
* `riskEvaluation.reason`: `3220`

## See also

* [How Minting and Redemption Works](/circle-mint/concepts/how-minting-works) --
  understand the transfer lifecycle
* [Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
  \-- confirmation counts by blockchain
* [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  \-- available blockchains


# How-to: Withdraw Fiat
Source: https://developers.circle.com/circle-mint/howtos/withdraw-fiat

Redeem USDC or EURC to fiat and withdraw funds to your bank account using the Circle Mint API.

Redeem (offramp) USDC or EURC in your Circle Mint balance to fiat and send funds
to a linked bank account. You can track payout status from `pending` through
`complete` or `failed`, and handle returned withdrawals caused by bank-side
rejections. Payouts route through the `/wires` endpoint and support standard
wires, real-time interbank rails (RTP, SPEI, SEPA, CHATS) where available, and
book transfers when applicable -- Circle selects the rail based on your
destination bank and region.

## Prerequisites

Before you begin:

* Complete the
  [account and API key setup](/circle-mint/quickstarts/getting-started).
* Have a funded Circle Mint account with available USDC or EURC balance.
* Have a linked bank account. If you have not linked one, see
  [Deposit Fiat](/circle-mint/howtos/deposit-fiat) Step 1.
* If your Circle Mint account is domiciled in Singapore or France, verify your
  payout recipients through the [Mint Console](https://app.circle.com/signin)
  before proceeding. Unverified recipients cause payouts to remain in `pending`
  status.

## Step 1. Verify your balance

Before you initiate a withdrawal, confirm that your available balance covers the
amount you plan to send.

```bash theme={null}
curl -X GET https://api-sandbox.circle.com/v1/businessAccount/balances \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json"
```

Expected response:

```json theme={null}
{
  "data": {
    "available": [
      {
        "amount": "150.00",
        "currency": "USD"
      }
    ],
    "unsettled": [
      {
        "amount": "25.00",
        "currency": "USD"
      }
    ]
  }
}
```

The `available` array shows funds you can withdraw immediately. The `unsettled`
array shows funds that are still being processed and are not yet available.

## Step 2. Create a payout

Use the
[create a payout](/api-reference/circle-mint/account/create-business-payout)
endpoint to send funds from your Circle Mint account to your linked bank
account.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/payouts \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "'$(uuidgen)'", "destination": {"type": "wire", "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636"}, "amount": {"currency": "USD", "amount": "75.00"}}'
```

Replace the `destination.id` value with the bank account ID returned when you
linked your bank account.

Expected response:

```json theme={null}
{
  "data": {
    "id": "9cf38c76-cac4-40d8-a516-f46e9a610a85",
    "amount": {
      "amount": "75.00",
      "currency": "USD"
    },
    "status": "pending",
    "sourceWalletId": "1016875042",
    "destination": {
      "type": "wire",
      "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
      "name": "WELLS FARGO BANK, NA ****0010"
    },
    "createDate": "2024-01-15T14:22:31.062Z",
    "updateDate": "2024-01-15T14:22:31.062Z"
  }
}
```

Record the `id` from the response to check the payout status in the next step.

## Step 3. Check the payout status

Use the [get a payout](/api-reference/circle-mint/account/get-business-payout)
endpoint to check the current status of your withdrawal.

```bash theme={null}
curl -X GET https://api-sandbox.circle.com/v1/businessAccount/payouts/9cf38c76-cac4-40d8-a516-f46e9a610a85 \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json"
```

A payout moves through the following statuses:

* **`pending`**: Circle has received the payout request and is processing it.
* **`complete`**: Funds have been sent to the receiving bank.
* **`failed`**: The payout could not be processed. Check the `errorCode` field
  for details.

Expected response for a completed payout:

```json theme={null}
{
  "data": {
    "id": "9cf38c76-cac4-40d8-a516-f46e9a610a85",
    "amount": {
      "amount": "75.00",
      "currency": "USD"
    },
    "status": "complete",
    "sourceWalletId": "1016875042",
    "destination": {
      "type": "wire",
      "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
      "name": "WELLS FARGO BANK, NA ****0010"
    },
    "createDate": "2024-01-15T14:22:31.062Z",
    "updateDate": "2024-01-16T09:15:42.778Z"
  }
}
```

Payouts are asynchronous. To track status changes without polling, subscribe to
`payouts` webhook notifications. Alternatively, poll the get a payout endpoint
at a reasonable interval until the status reaches `complete` or `failed`.

### Returned withdrawals

Even after a payout reaches `complete` status, bank-side issues can cause the
wire to be returned. Common reasons include:

* Incorrect account details, such as a wrong routing number or a closed account.
* Compliance holds at the receiving bank.
* Beneficiary name mismatch between the payout and the bank account on file.

When a wire is returned, the funds are re-credited to your Circle Mint balance.
Monitor webhook notifications for `payouts` events to detect returns. If a
payout fails or is returned, verify the bank account details and retry with a
new idempotency key.

## See also

* [How Minting and Redemption Works](/circle-mint/concepts/how-minting-works) --
  understand the redemption process
* [Sandbox to Production](/circle-mint/references/sandbox-and-testing) --
  production settlement timing differences
* [Create a payout](/api-reference/circle-mint/account/create-business-payout)
  \-- API reference


# Notifications Data Models
Source: https://developers.circle.com/circle-mint/notifications-data-models

Learn about the events and data models used in Circle Notifications.

Circle API notifications are subscriber endpoints that enable you to receive
notifications every time the status of a resource changes.

## Common attributes

All notification messages have the following attributes:

| Name               | Type              | Description                   | Sample                                 |
| :----------------- | :---------------- | :---------------------------- | :------------------------------------- |
| `clientId`         | `string` (UUIDv4) | Client identifier             | `c60d2d5b-203c-45bb-9f6e-93641d40a599` |
| `notificationType` | `string`          | The type of notification      | `payouts`                              |
| `version`          | `int`             | The version of the data model | `1`                                    |

## Implementations

This section lists all notification models.

### Payout

#### Completed

*Completed* payouts are settled payouts. Therefore, the funds should be
available in the destination wallet. The following structure represents the
notifications for completed payouts.

```json Completed Payout Notification Payload theme={null}
{
   "clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
   "notificationType": "payouts",
   "payout": {...}
}
```

The `payout` payload is a
[payout object](/circle-mint/circle-api-resources#payout-object).

#### Failed

Failed payouts notifications are structured as follows:

```json Failed Payout Notification Payload theme={null}
{
   "clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
   "notificationType": "payouts",
   "payout": {...}
}
```

The `payout` payload is a
[payout object](/circle-mint/circle-api-resources#payout-object).

### Transfer

#### Created

A notification with the structure below is sent on transfer creation.

```json Created Transfer Notification Payload theme={null}
{
   "clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
   "notificationType": "transfers",
   "transfer": {...}
}
```

The `transfer` payload is a
[transfer object](/circle-mint/circle-api-resources#transfer-object).

#### Failed

Failed transfers notifications are structured as follows:

```json Failed Transfer Notification Payload theme={null}
{
   "clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
   "notificationType": "transfers",
   "transfer": {...}
}
```

The `transfer` payload is a
[transfer object](/circle-mint/circle-api-resources#transfer-object).

#### Completed

Completed transfers notifications are structured as follows:

```json Completed Transfer Notification Payload theme={null}
{
   "clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
   "notificationType": "transfers",
   "transfer": {...}
}
```

The `transfer` payload is a
[transfer object](/circle-mint/circle-api-resources#transfer-object).


# Postman Suite
Source: https://developers.circle.com/circle-mint/postman

Use Circle's Postman collections to easily send API requests and try out our APIs.

*Circle's Postman collection holds sample requests for Circle APIs. Run them in
Postman, an API client. The Circle Mint workspace has one collection per area:
API Overview, Core Functionality, Stablecoin Payins, and Stablecoin Payouts.
Folders follow the same layout as the
[API References](/api-reference/circle-mint/general/ping).*

## How To Use It

### Run in Postman

Select one of the six **Run in Postman** links below. You'll be asked whether
you want to fork the collection to your workspace, view the collection in the
public workspace, or import the collection into Postman.

Fork: Creates a copy of the collection while maintaining a link to the parent.
View: Allows you to quickly try out the API without having to import anything
into your Postman suite. Import: Creates a copy of the collection but does not
maintain a link to Circle's copy.

| Collection          | Run it!                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| API Overview        | [![Run in Postman](https://run.pstmn.io/button.svg)](https://www.google.com/url?q=https://god.gw.postman.com/run-collection/21445022-e6b3ea60-0ff0-4919-9a58-eaf262989f82?action%3Dcollection%252Ffork%26source%3Drip_markdown%26collection-url%3DentityId%253D21445022-e6b3ea60-0ff0-4919-9a58-eaf262989f82%2526entityType%253Dcollection%2526workspaceId%253D791ff53c-d236-499c-89ea-307d24ddd289\&sa=D\&source=docs\&ust=1708733799579019\&usg=AOvVaw1J5pjlBnXW56T9Jg1Jem4R) |
| Core Functionality  | [![Run in Postman](https://run.pstmn.io/button.svg)](https://www.google.com/url?q=https://god.gw.postman.com/run-collection/21445022-3e1635b1-7620-4001-998d-3b3aebbfc44f?action%3Dcollection%252Ffork%26source%3Drip_markdown%26collection-url%3DentityId%253D21445022-3e1635b1-7620-4001-998d-3b3aebbfc44f%2526entityType%253Dcollection%2526workspaceId%253D791ff53c-d236-499c-89ea-307d24ddd289\&sa=D\&source=docs\&ust=1708733799581882\&usg=AOvVaw2MrbS0b_WrIS2xff7v4UMs) |
| Crypto Deposits API | [![Run in Postman](https://run.pstmn.io/button.svg)](https://www.google.com/url?q=https://god.gw.postman.com/run-collection/21445022-27cbac71-8b44-4d50-9c83-7e39a90a7325?action%3Dcollection%252Ffork%26source%3Drip_markdown%26collection-url%3DentityId%253D21445022-27cbac71-8b44-4d50-9c83-7e39a90a7325%2526entityType%253Dcollection%2526workspaceId%253D791ff53c-d236-499c-89ea-307d24ddd289\&sa=D\&source=docs\&ust=1708733799584756\&usg=AOvVaw1lqKomXCegg8MBf7mppUOm) |
| Crypto Payouts API  | [![Run in Postman](https://run.pstmn.io/button.svg)](https://www.google.com/url?q=https://god.gw.postman.com/run-collection/21445022-53206224-cf33-4bbd-8e8a-09d5a780795a?action%3Dcollection%252Ffork%26source%3Drip_markdown%26collection-url%3DentityId%253D21445022-53206224-cf33-4bbd-8e8a-09d5a780795a%2526entityType%253Dcollection%2526workspaceId%253D791ff53c-d236-499c-89ea-307d24ddd289\&sa=D\&source=docs\&ust=1708733799587291\&usg=AOvVaw3tZLn5_kLwqQDkwELUpt3M) |

<Note>
  **Authorization**

  To authorize your session authorization, use Circle's Postman variable `apiKey`
  and add your API key to the `environment` or `collection` variables. See
  Postman's
  [using variables](https://learning.postman.com/docs/sending-requests/variables/)
  for details.

  Need a Circle sandbox API Key? Sign up for a
  [Circle account](https://app-sandbox.circle.com/signup)—it only takes a minute
  or two.
</Note>


# Set Up Your Account and API Key
Source: https://developers.circle.com/circle-mint/quickstarts/getting-started

Create a sandbox account, generate an API key, and make your first Circle Mint API request.

This guide walks you through creating a sandbox account, generating an API key,
and verifying that you can connect to the Circle Mint API.

## Prerequisites

Before you begin, ensure you have:

* A valid email address to register for a Circle Mint sandbox account
* [curl](https://curl.se/) or another tool for making HTTP requests

## Step 1: Create a sandbox account

The sandbox environment lets you test API integrations without processing real
transactions. For more details on sandbox versus production environments, see
[Sandbox to Production](/circle-mint/references/sandbox-and-testing).

<Steps>
  <Step title="Sign up for a sandbox account">
    Go to [app-sandbox.circle.com/signup](https://app-sandbox.circle.com/signup)
    and complete the registration form.
  </Step>

  <Step title="Verify your email address">
    Check your inbox and confirm your email to activate your account.
  </Step>

  <Step title="Log in to the sandbox">
    After activation, log in at `https://app-sandbox.circle.com`.
  </Step>
</Steps>

## Step 2: Generate an API key

Circle Mint uses API keys to authenticate all requests. Create and manage keys
in the [Mint Console](https://app-sandbox.circle.com/developer).

<Steps>
  <Step title="Open the Mint Console">
    Go to
    [app-sandbox.circle.com/developer](https://app-sandbox.circle.com/developer).
  </Step>

  <Step title="Select the API Keys tab" />

  <Step title="Click Create an API key" />

  <Step title="Enter a name for your key" />

  <Step title="(Optional) Add IP addresses to the allowlist">
    Restrict where the key can be used from.
  </Step>

  <Step title="Click Create API key" />

  <Step title="Copy the key and store it securely" />
</Steps>

<Warning>
  API keys grant access to privileged operations on Circle APIs. Store your API
  key securely and never expose it in client-side code, public repositories, or
  other publicly accessible locations. All API requests must be made over HTTPS.
  You can create a maximum of 10 API keys per environment.
</Warning>

## Step 3: Test connectivity

Test raw connectivity by calling the `/ping` endpoint. This endpoint does not
require authentication, so it confirms that your application can reach the API.

```bash theme={null}
curl -s https://api-sandbox.circle.com/ping
```

If your application reached the API, you see the following response:

```json theme={null}
{ "message": "pong" }
```

## Step 4: Verify your API key

Circle Mint uses Bearer token authentication. Include your API key in the
`Authorization` header of every request using the format `Bearer YOUR_API_KEY`.

Call the `/v1/configuration` endpoint to confirm that your API key is valid and
properly configured:

```bash theme={null}
curl -s https://api-sandbox.circle.com/v1/configuration \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

A successful response returns your account configuration, including your
`masterWalletId`. The `masterWalletId` is the identifier for the primary wallet
associated with your Circle Mint account, used as the source or destination in
transfer and payout operations.

```json theme={null}
{ "data": { "payments": { "masterWalletId": "1234567890" } } }
```

If the API key is missing or malformed, you receive a `401 Unauthorized` error:

```json theme={null}
{
  "code": 401,
  "message": "Malformed authorization. Are the credentials properly encoded?"
}
```

If you see this error, verify that your `Authorization` header uses the `Bearer`
prefix and that you copied the full API key from the Mint Console.


# Quickstart: Mint and Redeem USDC
Source: https://developers.circle.com/circle-mint/quickstarts/mint-and-redeem

Deposit fiat to mint USDC, transfer it onchain, and redeem USDC back to fiat using the Circle Mint API.

This guide walks you through a complete mint-and-redeem cycle in the Circle Mint
sandbox: link a bank account, deposit fiat to mint USDC, transfer USDC onchain,
and redeem USDC back to fiat.

## Prerequisites

Before you begin, complete the
[account and API key setup](/circle-mint/quickstarts/getting-started).

Replace `${YOUR_API_KEY}` in the examples below with your sandbox API key.

## Step 1: Create a bank account

Register a mock bank account using the
[create a wire bank account](/api-reference/circle-mint/account/create-business-wire-account)
endpoint. This bank account serves as the source for depositing fiat and the
destination for redeeming USDC.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/banks/wires \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "unique-id-1",
    "accountNumber": "12340010",
    "routingNumber": "121000248",
    "billingDetails": {
      "name": "Satoshi Nakamoto",
      "city": "Boston",
      "country": "US",
      "line1": "100 Money Street",
      "district": "MA",
      "postalCode": "01234"
    },
    "bankAddress": {
      "bankName": "WELLS FARGO BANK, NA",
      "city": "San Francisco",
      "country": "US",
      "line1": "420 Montgomery Street",
      "district": "CA"
    }
  }'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
    "status": "pending",
    "description": "WELLS FARGO BANK, NA ****0010",
    "trackingRef": "CIR2GKYL4B",
    "fingerprint": "a9a71b77-d83d-4fbc-997f-41a33550c594",
    "virtualAccountEnabled": true,
    "billingDetails": {
      "name": "Satoshi Nakamoto",
      "line1": "100 Money Street",
      "city": "Boston",
      "postalCode": "01234",
      "district": "MA",
      "country": "US"
    },
    "bankAddress": {
      "bankName": "WELLS FARGO BANK, NA",
      "city": "SAN FRANCISCO",
      "district": "CA",
      "country": "US"
    },
    "createDate": "2026-01-15T12:00:00.000Z",
    "updateDate": "2026-01-15T12:00:00.000Z"
  }
}
```

Save the bank account `id` from the response. You need it in the following
steps.

## Step 2: Get wire instructions

Retrieve the wire instructions for your bank account using the
[get wire instructions](/api-reference/circle-mint/account/get-business-wire-account-instructions)
endpoint. The response includes the `trackingRef` and beneficiary
`accountNumber` you need to simulate a wire deposit.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/banks/wires/9d1fa351-b24d-442a-8aa5-e717db1ed636/instructions \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

Expected response:

```json theme={null}
{
  "data": {
    "trackingRef": "CIR2GKYL4B",
    "beneficiary": {
      "name": "CIRCLE INTERNET FINANCIAL INC",
      "address1": "99 High Street",
      "address2": "Boston, MA 02110"
    },
    "beneficiaryBank": {
      "name": "CUSTOMERS BANK",
      "routingNumber": "031101279",
      "accountNumber": "123815146304",
      "city": "Phoenixville",
      "postalCode": "19460",
      "country": "US"
    }
  }
}
```

Save the `trackingRef` and the `beneficiaryBank.accountNumber` values for the
next step.

## Step 3: Deposit fiat to mint USDC

Simulate a wire deposit using the
[create a mock wire payment](/api-reference/circle-mint/account/create-mock-wire-payment)
endpoint. In the sandbox, this mints USDC into your Circle Mint account without
moving real funds.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/mocks/payments/wire \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { "amount": "100.00", "currency": "USD" },
    "trackingRef": "CIR2GKYL4B",
    "beneficiaryBank": { "accountNumber": "123815146304" }
  }'
```

Expected response:

```json theme={null}
{
  "data": {
    "trackingRef": "CIR2GKYL4B",
    "amount": { "amount": "100.00", "currency": "USD" },
    "status": "pending"
  }
}
```

<Note>
  Sandbox mock wire deposits process in batches and may take up to 15 minutes to
  complete. Wait for the deposit to settle before continuing.
</Note>

After the deposit settles, verify your balance using the
[list all balances](/api-reference/circle-mint/account/list-business-balances)
endpoint:

```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/balances \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

Expected response:

```json theme={null}
{
  "data": {
    "available": [{ "amount": "100.00", "currency": "USD" }],
    "unsettled": []
  }
}
```

The `available` balance confirms that your fiat deposit minted USDC
successfully.

## Step 4: Transfer USDC onchain

Send USDC from your Circle Mint account to an external blockchain address. This
step requires two API calls: create a recipient address, then create a transfer.

### 4.1. Create a recipient address

Register a destination address using the
[create a recipient address](/api-reference/circle-mint/account/create-business-recipient-address)
endpoint. This example uses the Ethereum blockchain.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "unique-id-2",
    "address": "0x493A9869E3B5f846f72267ab19B76e9bf99d51b1",
    "chain": "ETH",
    "currency": "USD",
    "description": "External Ethereum wallet"
  }'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "cfa01bb0-d166-5506-a48a-56f2beab559f",
    "address": "0x493a9869e3b5f846f72267ab19b76e9bf99d51b1",
    "chain": "ETH",
    "currency": "USD",
    "description": "External Ethereum wallet"
  }
}
```

### 4.2. Create a transfer

Send USDC to the recipient address using the
[create a transfer](/api-reference/circle-mint/account/create-business-transfer)
endpoint:

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/transfers \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "unique-id-3",
    "destination": {
      "type": "verified_blockchain",
      "addressId": "cfa01bb0-d166-5506-a48a-56f2beab559f"
    },
    "amount": { "currency": "USD", "amount": "25.00" }
  }'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "21fd4ec4-bad1-4eb2-9fc5-60320dedc7ea",
    "source": { "type": "wallet", "id": "1016875042" },
    "destination": {
      "type": "blockchain",
      "address": "0x493a9869e3b5f846f72267ab19b76e9bf99d51b1",
      "chain": "ETH"
    },
    "amount": { "amount": "25.00", "currency": "USD" },
    "status": "pending"
  }
}
```

The transfer starts in `pending` status, moves to `running` once broadcast
onchain, and reaches `complete` after enough
[blockchain confirmations](/circle-mint/references/blockchain-confirmations).

## Step 5: Redeem USDC to fiat

Convert your remaining USDC balance back to fiat by creating a payout to the
bank account you registered in Step 1. Use the
[create a payout](/api-reference/circle-mint/account/create-business-payout)
endpoint:

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/payouts \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "unique-id-4",
    "destination": {
      "type": "wire",
      "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636"
    },
    "amount": { "currency": "USD", "amount": "75.00" }
  }'
```

Expected response:

```json theme={null}
{
  "data": {
    "id": "9cf38c76-cac4-40d8-a516-f46e9a610a85",
    "amount": { "amount": "75.00", "currency": "USD" },
    "status": "pending",
    "sourceWalletId": "1016875042",
    "destination": {
      "type": "wire",
      "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
      "name": "WELLS FARGO BANK, NA ****0010"
    }
  }
}
```

## Step 6: Verify the round trip

Check your final balance to confirm both the transfer and payout processed:

```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/balances \
  -H "Authorization: Bearer ${YOUR_API_KEY}"
```

Expected response:

```json theme={null}
{
  "data": {
    "available": [{ "amount": "0.00", "currency": "USD" }],
    "unsettled": []
  }
}
```

You completed the full Circle Mint cycle:

1. Deposited \$100 USD via wire to mint 100 USDC.
2. Transferred 25 USDC onchain to an Ethereum address.
3. Redeemed 75 USDC back to fiat via wire payout.

Your available balance returns to zero, confirming every dollar is accounted
for.

<Note>
  The mock wire endpoint used in Step 3 is only available in the sandbox. In
  production, initiate wire transfers from your own banking interface using the
  wire instructions from Step 2. All other API calls in this guide work the same
  in production. See [Sandbox to
  Production](/circle-mint/references/sandbox-and-testing) for details on
  transitioning.
</Note>


# Quickstart: Receive a Stablecoin Payin
Source: https://developers.circle.com/circle-mint/receive-stablecoin-payin

Create a payment intent, obtain a deposit address, and confirm onchain USDC or EURC payins using the Crypto Deposits API.

Use the Crypto Deposits API to accept onchain USDC or EURC
[stablecoin payins](/circle-mint/how-stablecoin-payins-and-payouts-work) into
Circle Mint from your customers' wallets. You create the payment intent, share
the deposit address, have the customer send funds, then confirm the transfer
using the API or webhooks. The examples in this quickstart use Ethereum, but you
can use any
[supported blockchain](/circle-mint/references/supported-chains-and-currencies).

## Prerequisites

Before you begin this tutorial, ensure you've:

* Obtained a
  [Circle Mint sandbox API key](/circle-mint/quickstarts/getting-started) with
  access to the Crypto Deposits API (stablecoin payins).
* Obtained a `merchantWalletId` for the wallet that receives settled funds.
* Installed cURL for API calls.
* (Optional) Configured
  [webhook notifications](/circle-mint/circle-apis-notifications-quickstart).

## Step 1: Create a payment intent

Call
[Create a payment intent](/api-reference/circle-mint/payments/create-payment-intent)
when the customer chooses to pay with USDC or EURC onchain. Choose continuous or
transient mode.

**Expected result:** a response with a payment intent `id` and `timeline`
including `created`.

<Tabs>
  <Tab title="Continuous (default mode)">
    Continuous payment intents are the default type. You do not include an `amount`
    at creation.

    Example request:

    ```bash cURL theme={null}
    curl --location --request POST 'https://api-sandbox.circle.com/v1/paymentIntents' \
    --header 'X-Request-Id: ${GUID}' \
    --header 'Authorization: Bearer ${YOUR_API_KEY}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "idempotencyKey": "17607606-e383-4874-87c3-7e46a5dc03dd",
      "currency": "USD",
      "settlementCurrency": "USD",
      "merchantWalletId": "${MERCHANT_WALLET_ID}",
      "paymentMethods": [
        {
          "type": "blockchain",
          "chain": "ETH"
        }
      ],
      "type": "continuous"
    }'
    ```

    Example response:

    ```json JSON theme={null}
    {
      "data": {
        "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
        "currency": "USD",
        "settlementCurrency": "USD",
        "amountPaid": {
          "amount": "0.00",
          "currency": "USD"
        },
        "paymentMethods": [
          {
            "type": "blockchain",
            "chain": "ETH"
          }
        ],
        "timeline": [
          {
            "status": "created",
            "time": "2023-01-21T20:13:35.579331Z"
          }
        ],
        "type": "continuous",
        "createDate": "2023-01-21T20:13:35.578678Z",
        "updateDate": "2023-01-21T20:13:35.578678Z"
      }
    }
    ```
  </Tab>

  <Tab title="Transient">
    Transient intents include a specific `amount` and are intended for a single
    checkout payment. You must set the `type` to `transient`.

    Example request:

    ```bash cURL theme={null}
    curl --location --request POST 'https://api-sandbox.circle.com/v1/paymentIntents' \
    --header 'X-Request-Id: ${GUID}' \
    --header 'Authorization: Bearer ${YOUR_API_KEY}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "idempotencyKey": "17607606-e383-4874-87c3-7e46a5dc03dd",
      "type": "transient",
      "amount": {
        "amount": "1.00",
        "currency": "USD"
      },
      "settlementCurrency": "USD",
      "merchantWalletId": "${MERCHANT_WALLET_ID}",
      "paymentMethods": [
        {
          "type": "blockchain",
          "chain": "ETH"
        }
      ]
    }'
    ```

    Example response:

    ```json JSON theme={null}
    {
      "data": {
        "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
        "amount": {
          "amount": "1.00",
          "currency": "USD"
        },
        "amountPaid": {
          "amount": "0.00",
          "currency": "USD"
        },
        "amountRefunded": {
          "amount": "0.00",
          "currency": "USD"
        },
        "settlementCurrency": "USD",
        "paymentMethods": [
          {
            "type": "blockchain",
            "chain": "ETH"
          }
        ],
        "paymentIds": [],
        "timeline": [
          {
            "status": "created",
            "time": "2022-07-21T20:13:35.579331Z"
          }
        ],
        "createDate": "2022-07-21T20:13:35.578678Z",
        "updateDate": "2022-07-21T20:19:24.859052Z"
      }
    }
    ```
  </Tab>
</Tabs>

## Step 2: Obtain the deposit address

Circle does not return the deposit address in the create response. Use webhooks
or poll
[Get a payment intent](/api-reference/circle-mint/payments/get-payment-intent)
until `paymentMethods.address` is set.

**Expected result:** you have the onchain deposit address to show the customer.

<Tabs>
  <Tab title="Webhooks">
    After you
    [subscribe to notifications](/circle-mint/circle-apis-notifications-quickstart)
    for `paymentIntents`, you receive updates when the payment intent changes. When
    `paymentMethods.address` is set, the payload includes an updated `timeline` of
    the historical payment intent statuses and timestamps.

    **Expected result:** the notification includes `paymentIntent.paymentMethods`
    with `address` and `timeline` with `pending` after the address is assigned.

    Example `paymentIntents` notification after the deposit address is assigned:

    <CodeGroup>
      ```json Continuous theme={null}
      {
        "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
        "notificationType": "paymentIntents",
        "version": 1,
        "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
        "paymentIntent": {
          "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
          "currency": "USD",
          "settlementCurrency": "USD",
          "amountPaid": { "amount": "0.00", "currency": "USD" },
          "amountRefunded": { "amount": "0.00", "currency": "USD" },
          "paymentMethods": [
            {
              "type": "blockchain",
              "chain": "ETH",
              "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
            }
          ],
          "fees": [
            { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
          ],
          "paymentIds": [],
          "refundIds": [],
          "timeline": [
            { "status": "pending", "time": "2023-01-21T20:13:38.188286Z" },
            { "status": "created", "time": "2023-01-21T20:13:35.579331Z" }
          ],
          "type": "continuous",
          "createDate": "2023-01-21T20:13:35.578678Z",
          "updateDate": "2023-01-21T20:13:38.186831Z"
        }
      }
      ```

      ```json Transient theme={null}
      {
        "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
        "notificationType": "paymentIntents",
        "version": 1,
        "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
        "paymentIntent": {
          "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
          "amount": { "amount": "1.00", "currency": "USD" },
          "amountPaid": { "amount": "0.00", "currency": "USD" },
          "amountRefunded": { "amount": "0.00", "currency": "USD" },
          "settlementCurrency": "USD",
          "paymentMethods": [
            {
              "type": "blockchain",
              "chain": "ETH",
              "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
            }
          ],
          "fees": [
            { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
          ],
          "paymentIds": [],
          "refundIds": [],
          "timeline": [
            { "status": "pending", "time": "2022-07-21T20:13:38.188286Z" },
            { "status": "created", "time": "2022-07-21T20:13:35.579331Z" }
          ],
          "createDate": "2022-07-21T20:13:35.578678Z",
          "updateDate": "2022-07-21T20:13:38.186831Z",
          "expiresOn": "2022-07-21T21:13:38.087275Z"
        }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Polling">
    Call the
    [Get a payment intent](/api-reference/circle-mint/payments/get-payment-intent)
    endpoint until `paymentMethods.address` is present in the response.

    **Expected result:** the response `data` includes `paymentMethods` with
    `address` for the deposit.

    Example request:

    ```bash cURL theme={null}
    curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/{id}' \
    --header 'X-Request-Id: ${GUID}' \
    --header 'Authorization: Bearer ${YOUR_API_KEY}'
    ```

    Example response after the address is available:

    <CodeGroup>
      ```json Continuous theme={null}
      {
        "data": {
          "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
          "currency": "USD",
          "settlementCurrency": "USD",
          "amountPaid": { "amount": "0.00", "currency": "USD" },
          "amountRefunded": { "amount": "0.00", "currency": "USD" },
          "paymentMethods": [
            {
              "type": "blockchain",
              "chain": "ETH",
              "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
            }
          ],
          "fees": [
            { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
          ],
          "paymentIds": [],
          "refundIds": [],
          "timeline": [
            { "status": "pending", "time": "2023-01-21T20:13:38.188286Z" },
            { "status": "created", "time": "2023-01-21T20:13:35.579331Z" }
          ],
          "type": "continuous",
          "createDate": "2023-01-21T20:13:35.578678Z",
          "updateDate": "2023-01-21T20:13:38.186831Z"
        }
      }
      ```

      ```json Transient theme={null}
      {
        "data": {
          "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
          "amount": { "amount": "1.00", "currency": "USD" },
          "amountPaid": { "amount": "0.00", "currency": "USD" },
          "amountRefunded": { "amount": "0.00", "currency": "USD" },
          "settlementCurrency": "USD",
          "paymentMethods": [
            {
              "type": "blockchain",
              "chain": "ETH",
              "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
            }
          ],
          "fees": [
            { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" }
          ],
          "paymentIds": [],
          "refundIds": [],
          "timeline": [
            { "status": "pending", "time": "2022-07-21T20:13:38.188286Z" },
            { "status": "created", "time": "2022-07-21T20:13:35.579331Z" }
          ],
          "createDate": "2022-07-21T20:13:35.578678Z",
          "updateDate": "2022-07-21T20:13:38.186831Z",
          "expiresOn": "2022-07-21T21:13:38.087275Z"
        }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Step 3: Have the customer pay onchain

Display the deposit address and have the customer send USDC or EURC on the
chosen chain.

**Expected result:** an onchain transfer to the deposit address is submitted
(you confirm settlement in Step 4).

### 3.1. Display the deposit address

Give the customer the deposit address, the stablecoin to send (USDC or EURC),
and for transient intents the amount. Plain text or a QR code is fine.

**Expected result:** the customer can send funds from their wallet.

<Note>
  For transient payment intents, you can display the `expiresOn` time to show the
  customer how long they have to pay.

  If the customer does not send funds before `expiresOn`, the payment intent moves
  to a `complete` status with context `expired`. You cannot reuse an expired
  intent. Create a new payment intent to retry the checkout.
</Note>

### 3.2. Customer sends funds onchain

The customer sends USDC or EURC to the deposit address on the specified
blockchain.

**Expected result:** the transfer appears onchain against that address.

## Step 4: Confirm payment completion

After Circle confirms the transfer, it updates the payment intent and creates a
payment record for that inbound transfer. Confirm the intent and the payment
match what you expect using webhooks or polling.

**Expected result:** payment intent `timeline` shows `complete` with context
`paid`, and the linked payment has `status` `paid`.

### 4.1. Inspect the payment intent

<Tabs>
  <Tab title="Webhooks">
    Subscribe to `paymentIntents` notifications. After the customer pays, the
    payload includes an updated `timeline`, `amountPaid`, and `paymentIds`.

    **Expected result:** `paymentIntent` in the notification includes:

    * `timeline` with `complete` and context `paid`
    * `paymentIds` listing the payin payment for this transfer
    * `amountPaid` reflecting the settled amount

    Example when the payment intent is complete and paid:

    <CodeGroup>
      ```json Continuous theme={null}
      {
        "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
        "notificationType": "paymentIntents",
        "version": 1,
        "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
        "paymentIntent": {
          "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
          "currency": "USD",
          "settlementCurrency": "USD",
          "amountPaid": { "amount": "1.00", "currency": "USD" },
          "amountRefunded": { "amount": "0.00", "currency": "USD" },
          "paymentMethods": [
            {
              "type": "blockchain",
              "chain": "ETH",
              "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
            }
          ],
          "fees": [
            { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" },
            { "type": "totalPaymentFees", "amount": "0.01", "currency": "USD" }
          ],
          "paymentIds": ["66c56b6a-fc79-338b-8b94-aacc4f0f18de"],
          "refundIds": [],
          "timeline": [
            {
              "status": "complete",
              "context": "paid",
              "time": "2023-01-21T20:19:24.861094Z"
            },
            { "status": "pending", "time": "2023-01-21T20:13:38.188286Z" },
            { "status": "created", "time": "2023-01-21T20:13:35.579331Z" }
          ],
          "type": "continuous",
          "createDate": "2023-01-21T20:13:35.578678Z",
          "updateDate": "2023-01-21T20:19:24.859052Z"
        }
      }
      ```

      ```json Transient theme={null}
      {
        "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
        "notificationType": "paymentIntents",
        "version": 1,
        "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
        "paymentIntent": {
          "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
          "amount": { "amount": "1.00", "currency": "USD" },
          "amountPaid": { "amount": "1.00", "currency": "USD" },
          "amountRefunded": { "amount": "0.00", "currency": "USD" },
          "settlementCurrency": "USD",
          "paymentMethods": [
            {
              "type": "blockchain",
              "chain": "ETH",
              "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
            }
          ],
          "fees": [
            { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" },
            { "type": "totalPaymentFees", "amount": "0.01", "currency": "USD" }
          ],
          "paymentIds": ["2b8f9d4e-515f-3c3a-a409-8ab99a2e72c7"],
          "refundIds": [],
          "timeline": [
            {
              "status": "complete",
              "context": "paid",
              "time": "2022-07-21T20:19:24.861094Z"
            },
            { "status": "pending", "time": "2022-07-21T20:13:38.188286Z" },
            { "status": "created", "time": "2022-07-21T20:13:35.579331Z" }
          ],
          "createDate": "2022-07-21T20:13:35.578678Z",
          "updateDate": "2022-07-21T20:19:24.859052Z",
          "expiresOn": "2022-07-21T21:13:38.087275Z"
        }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Polling">
    Call the
    [Get a payment intent](/api-reference/circle-mint/payments/get-payment-intent)
    endpoint on an interval until the newest `timeline` entry has `status` as
    `complete` and `context` as `paid`, or until `amountPaid` matches what you
    expect.

    **Expected result:** the response `data` includes:

    * `timeline` with `complete` and context `paid`
    * `paymentIds` listing the payin payment for this transfer
    * `amountPaid` reflecting the settled amount

    Example request:

    <CodeGroup>
      ```curl Continuous theme={null}
      curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/e2e90ba3-9d1f-490d-9460-24ac6eb55a1b' \
      --header 'X-Request-Id: ${GUID}' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}'
      ```

      ```curl Transient theme={null}
      curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/6e4d4047-db14-4c09-b238-1215aee50d03' \
      --header 'X-Request-Id: ${GUID}' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}'
      ```
    </CodeGroup>

    Example response when one payin has completed:

    <CodeGroup>
      ```json Continuous theme={null}
      {
        "data": {
          "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
          "currency": "USD",
          "settlementCurrency": "USD",
          "amountPaid": { "amount": "1.00", "currency": "USD" },
          "amountRefunded": { "amount": "0.00", "currency": "USD" },
          "paymentMethods": [
            {
              "type": "blockchain",
              "chain": "ETH",
              "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
            }
          ],
          "fees": [
            { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" },
            { "type": "totalPaymentFees", "amount": "0.01", "currency": "USD" }
          ],
          "paymentIds": ["66c56b6a-fc79-338b-8b94-aacc4f0f18de"],
          "refundIds": [],
          "timeline": [
            {
              "status": "complete",
              "context": "paid",
              "time": "2023-01-21T20:19:24.861094Z"
            },
            { "status": "pending", "time": "2023-01-21T20:13:38.188286Z" },
            { "status": "created", "time": "2023-01-21T20:13:35.579331Z" }
          ],
          "type": "continuous",
          "createDate": "2023-01-21T20:13:35.578678Z",
          "updateDate": "2023-01-21T20:19:24.859052Z"
        }
      }
      ```

      ```json Transient theme={null}
      {
        "data": {
          "id": "6e4d4047-db14-4c09-b238-1215aee50d03",
          "amount": { "amount": "1.00", "currency": "USD" },
          "amountPaid": { "amount": "1.00", "currency": "USD" },
          "amountRefunded": { "amount": "0.00", "currency": "USD" },
          "settlementCurrency": "USD",
          "paymentMethods": [
            {
              "type": "blockchain",
              "chain": "ETH",
              "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
            }
          ],
          "fees": [
            { "type": "blockchainLeaseFee", "amount": "0.00", "currency": "USD" },
            { "type": "totalPaymentFees", "amount": "0.01", "currency": "USD" }
          ],
          "paymentIds": ["2b8f9d4e-515f-3c3a-a409-8ab99a2e72c7"],
          "refundIds": [],
          "timeline": [
            {
              "status": "complete",
              "context": "paid",
              "time": "2022-07-21T20:19:24.861094Z"
            },
            { "status": "pending", "time": "2022-07-21T20:13:38.188286Z" },
            { "status": "created", "time": "2022-07-21T20:13:35.579331Z" }
          ],
          "createDate": "2022-07-21T20:13:35.578678Z",
          "updateDate": "2022-07-21T20:19:24.859052Z",
          "expiresOn": "2022-07-21T21:13:38.087275Z"
        }
      }
      ```
    </CodeGroup>

    For continuous payment intents, the same deposit address can receive multiple
    transfers. Each settled transfer adds another ID to `paymentIds`.
  </Tab>
</Tabs>

### 4.2. Inspect the payment for the same transfer

The payment record holds the onchain `transactionHash` and the customer's
`fromAddresses` for that transfer.

<Tabs>
  <Tab title="Webhooks">
    Subscribe to `payments` notifications to receive the updated `payment` object
    when the transfer settles.

    **Expected result:** `payment` in the notification has `status` `paid`, a
    populated `transactionHash`, and `fromAddresses` for the sender.

    ```json JSON theme={null}
    {
      "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
      "notificationType": "payments",
      "version": 1,
      "customAttributes": { "clientId": "f1397191-56e6-42fd-be86-0a7b9bd91522" },
      "payment": {
        "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de",
        "type": "payment",
        "status": "paid",
        "amount": { "amount": "1.00", "currency": "USD" },
        "fees": { "amount": "0.01", "currency": "USD" },
        "createDate": "2023-01-21T20:16:35.092Z",
        "updateDate": "2023-01-21T20:19:24.719Z",
        "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
        "merchantWalletId": "1000999922",
        "paymentIntentId": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
        "settlementAmount": { "amount": "1.00", "currency": "USD" },
        "fromAddresses": {
          "chain": "ETH",
          "addresses": ["0x0d4344cff68f72a5b9abded37ca5862941a62050"]
        },
        "depositAddress": {
          "chain": "ETH",
          "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
        },
        "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
      }
    }
    ```
  </Tab>

  <Tab title="Polling">
    Poll the [Get a payment](/api-reference/circle-mint/payments/get-payment)
    endpoint using the ID from `paymentIds` on the
    [payment intent](#4-1-inspect-the-payment-intent). Stop when that payment
    `status` is `paid` and, if you check onchain, when `transactionHash` matches the
    transfer you expect.

    For continuous payment intents, `paymentIds` can list more than one transfer
    over time. Make sure you poll the ID for this specific transfer.

    **Expected result:** `data` has `type` `payment` and `status` `paid`, a
    populated `transactionHash`, and `fromAddresses` for the sender when the payin
    has settled.

    Example request:

    ```bash cURL theme={null}
    curl --location --request GET 'https://api-sandbox.circle.com/v1/payments/{id}' \
    --header 'X-Request-Id: ${GUID}' \
    --header 'Authorization: Bearer ${YOUR_API_KEY}'
    ```

    Example response:

    ```json JSON theme={null}
    {
      "data": {
        "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de",
        "type": "payment",
        "status": "paid",
        "amount": { "amount": "1.00", "currency": "USD" },
        "fees": { "amount": "0.01", "currency": "USD" },
        "createDate": "2023-01-21T20:16:35.092Z",
        "updateDate": "2023-01-21T20:19:24.719Z",
        "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
        "merchantWalletId": "1000999922",
        "paymentIntentId": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
        "settlementAmount": { "amount": "1.00", "currency": "USD" },
        "fromAddresses": {
          "chain": "ETH",
          "addresses": ["0x0d4344cff68f72a5b9abded37ca5862941a62050"]
        },
        "depositAddress": {
          "chain": "ETH",
          "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
        },
        "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  For blockchains that use a memo or address tag (for example, XLM or HBAR), the
  `addressTag` field can appear on `depositAddress` in payment payloads.
</Note>

The payment is complete when `status` is `paid`.


# Blockchain Confirmations
Source: https://developers.circle.com/circle-mint/references/blockchain-confirmations

Confirmation requirements and approximate times for each blockchain supported by Circle Mint.

## What are blockchain confirmations?

When you submit a transaction to a blockchain, it starts in a pending state. The
network must include it in a block and validate it before it counts as
confirmed. Each new block added after that makes the transaction harder to
reverse.

A **confirmation number** is the number of blocks that must follow a
transaction's block before it is final. Once the confirmation number is reached,
the transaction can't be reversed.

## Why confirmations matter

Without enough confirmations, transactions are at risk of reorganizations
(reorgs). A reorg happens when validators discard recent blocks and replace them
with new ones, rewriting part of the blockchain's history. This can reverse
transactions that appeared settled.

Each extra confirmation makes a reorg less likely. Because blockchains differ in
design, block times, and consensus, the number of confirmations needed varies by
blockchain.

## Confirmation numbers

Confirmations show how safe a transaction is from reorg. The confirmation number
is how many blocks must be added until a block is considered permanent.

Each blockchain's confirmation number is different, and determined by Circle.
Confirmation numbers are based on a variety of factors, including the
blockchain's history, potential for reorg, and overall network architecture.

For layer-2 (L2) blockchains that settle transactions on a separate base layer,
Circle waits for blocks on the layer-1 (L1) base blockchain. This happens after
the L2 block gets included in an L1 block.

| Chain              | Confirmations     | Approximate time   |
| ------------------ | ----------------- | ------------------ |
| Algorand           | **1**             | \~3 seconds        |
| Aptos              | **1**             | \~500 milliseconds |
| Arbitrum           | **12 ETH Blocks** | \~4 to 6 minutes   |
| Avalanche C-Chain  | **1**             | \~2 seconds        |
| Base               | **12 ETH Blocks** | \~3 to 9 minutes   |
| Celo               | **12 ETH Blocks** | \~3 to 9 minutes   |
| Codex              | **12 ETH Blocks** | \~3 to 9 minutes   |
| EDGE               | **12 ETH Blocks** | \~3 to 5 minutes   |
| Ethereum           | **12**            | \~3 minutes        |
| Hedera             | N/A               | \~3 seconds        |
| HyperEVM           | **1**             | under 1 second     |
| Injective          | **1**             | under 1 second     |
| Ink                | **12 ETH Blocks** | \~3 to 9 minutes   |
| Linea              | **65 ETH Blocks** | \~6 to 32 hours    |
| Monad              | **4**             | \~1.6 seconds      |
| Morph              | **64**            | \~20 to 30 minutes |
| NEAR               | **1**             | \~2 seconds        |
| Noble              | **1**             | \~1.53 seconds     |
| OP Mainnet         | **12 ETH Blocks** | \~3 to 9 minutes   |
| Pharos             | **1**             | \~20 seconds       |
| Plume              | **12 ETH Blocks** | \~3 to 9 minutes   |
| Polkadot Asset Hub | **1**             | \~12 seconds       |
| Polygon PoS        | **2-3**           | \~8 seconds        |
| Sei                | **1**             | \~400 milliseconds |
| Solana             | **1**             | \~400 milliseconds |
| Sonic              | **1**             | \~1 second         |
| Starknet           | **65 ETH Blocks** | \~4 to 8 hours     |
| Stellar            | **1**             | \~5 seconds        |
| Sui                | **1**             | \~500 milliseconds |
| Unichain           | **12 ETH Blocks** | \~3 to 9 minutes   |
| World Chain        | **12 ETH Blocks** | \~3 to 9 minutes   |
| XDC                | **3**             | \~6 seconds        |
| XRPL               | **1**             | \~5 seconds        |
| ZKsync Era         | **65 ETH Blocks** | \~5 to 7 hours     |

<Note>
  **Hedera**: Hedera is built on a hashgraph, not a blockchain. As such, there
  isn't a count of confirmations before Circle considers a transfer valid. This
  determination is performed on Hedera directly and is then shared back to Circle.
  See [Hedera consensus](https://hedera.com/how-it-works) to learn more.

  **Linea**: Linea requires 65 ETH block confirmations. However, Linea only posts
  batches to Ethereum every 6-32 hours, so the approximate confirmation time
  reflects this batch posting interval rather than the ETH block time alone.
</Note>

## Transfer status

When an incoming transfer is included in a block, the API makes it available for
you. However, the transfer remains in the `running` status. It won't credit the
balance of the associated wallet with the transfer amount until the required
number of confirmations has been reached.

Once the confirmation number is reached, the transfer status changes to
`completed`. If you subscribed to webhook notifications, you receive a message
about this change.

You can use transfers in your processes before they reach `completed` status.
This comes with risk. A blockchain reorganization (reorg) occurs when validators
discard recent blocks and replace them with new ones, reversing transactions
that appeared settled. If a reorg reverses a transfer you already acted on, the
credited balance is rolled back. Reorgs are rare, but if you use transfers
before they get enough confirmations, you take on this risk.

<Note>
  Waiting for confirmations only applies to onchain transfers. These are transfers
  where the `source` is type `blockchain`. Transfers between hosted wallets don't
  need to wait. These transfers have a `source` type of `wallet` and happen
  instantly.
</Note>


# Sandbox to Production
Source: https://developers.circle.com/circle-mint/references/sandbox-and-testing

Transition your Circle Mint integration from the sandbox environment to production.

Circle provides a sandbox environment at `https://api-sandbox.circle.com` for
prototyping and integration testing. Sandbox APIs match production APIs, so you
can develop and test without generating real financial transactions. Simulated
transactions use
[test networks only](/stablecoins/usdc-contract-addresses#testnet) and do not
move real funds. For details on idempotent requests, pagination, and date
filtering, see the [API reference](/api-reference/idempotent-requests).

After completing your integration in the sandbox, follow these steps to move to
production. If you have questions, contact your Circle solutions engineer or
[customer support](mailto:customer-support@circle.com).

<Steps>
  <Step title="Replace sandbox URLs with production URLs">
    Update all API base URLs from `https://api-sandbox.circle.com` to
    `https://api.circle.com`.
  </Step>

  <Step title="Replace sandbox API keys with production API keys">
    Use the [Mint Console](https://app.circle.com/) to create a production
    API key.

    <Warning>
      Production API keys allow you to work with real funds. Treat production
      keys with appropriate security protocols. Consult your security team for
      key management best practices.
    </Warning>
  </Step>

  <Step title="(Optional) Set up an IPv4 allowlist">
    If you configure an IP allowlist, Circle only accepts requests using your
    production API key that originate from an IP address on that list. Verify
    that the static addresses in your system match the ones you registered with
    Circle.
  </Step>

  <Step title="Verify API key roles">
    In the sandbox, your API key provides access to all endpoints. In
    production, access is restricted to the APIs your entity is authorized to
    use.

    * Test each API call to confirm it works in production. For example, verify
      that your
      [list all balances](/api-reference/circle-mint/account/list-business-balances)
      call returns results.
    * If you receive `403` responses or need additional capabilities, contact
      your Circle representative.
  </Step>

  <Step title="Allow for production settlement times">
    Sandbox settlement times are kept short for testing convenience. Production
    settlement times reflect real-world processing and are longer. For onchain
    transfers, the time to finality depends on the number of
    [blockchain confirmations](/circle-mint/references/blockchain-confirmations)
    required for each blockchain.

    * Test actual settlement times in production.
    * Decide whether to perform actions (such as releasing goods) after
      confirmation or after settlement.
  </Step>

  <Step title="Anticipate transaction fees">
    Sandbox fees may not reflect your client agreement with Circle.

    * Review your contract with Circle to understand production fees.
    * Test transactions in production to determine actual fees.
    * Update your interface if you pass fees along to your customers.
  </Step>
</Steps>


# Supported Chains and Currencies
Source: https://developers.circle.com/circle-mint/references/supported-chains-and-currencies

Blockchains and currencies supported by Circle Mint and related APIs.

<Warning>
  **Unsupported assets**

  Circle Mint and Circle APIs only support USDC and EURC tokens on the indicated
  blockchains. Don't send unsupported tokens such as USDT or bridged USDC to your
  Circle Mint address. Doing so might result in a loss of funds.

  **Cosmos appchains**

  Circle Mint and Circle APIs only support USDC from Noble. If you transfer USDC
  from Noble to other appchains via IBC (Inter-Blockchain Communication), you must
  transfer it back to Noble before you transfer it to your Circle Mint address.

  Don't attempt to deposit USDC from an appchain other than Noble to your Circle
  Mint address. Doing so might result in a loss of funds.

  **Polkadot parachains**

  Circle Mint and Circle APIs only support USDC from Polkadot Asset Hub. If you
  transfer USDC from Polkadot Asset Hub to other parachains via XCM, you must
  transfer it back to Polkadot Asset Hub before you transfer it to your Circle
  Mint address.

  Don't attempt to deposit XCM-transferred USDC from a parachain other than
  Polkadot Asset Hub to your Circle Mint address. Doing so might result in a loss
  of funds.

  **Injective**

  Circle Mint only supports USDC deposits on Injective through the EVM layer.
  Cosmos-layer USDC deposits are not supported. If you deposit USDC through the
  Cosmos layer, your funds are stuck and not credited to your Circle Mint account.
  To recover stuck funds, contact
  [Circle Support](https://help.circle.com/s/submit-ticket).
</Warning>

## USDC

| Chain              | API Chain Code | API Currency Code |
| ------------------ | -------------- | ----------------- |
| Algorand           | `ALGO`         | `USD`             |
| Aptos              | `APTOS`        | `USD`             |
| Arbitrum           | `ARB`          | `USD`             |
| Avalanche C-Chain  | `AVAX`         | `USD`             |
| Base               | `BASE`         | `USD`             |
| Celo               | `CELO`         | `USD`             |
| Codex              | `CODEX`        | `USD`             |
| EDGE               | `EDGE`         | `USD`             |
| Ethereum           | `ETH`          | `USD`             |
| Hedera             | `HBAR`         | `USD`             |
| HyperEVM           | `HYPEREVM`     | `USD`             |
| Injective          | `INJECTIVE`    | `USD`             |
| Ink                | `INK`          | `USD`             |
| Linea              | `LINEA`        | `USD`             |
| Monad              | `MONAD`        | `USD`             |
| Morph              | `MORPH`        | `USD`             |
| NEAR               | `NEAR`         | `USD`             |
| Noble              | `NOBLE`        | `USD`             |
| OP Mainnet         | `OP`           | `USD`             |
| Pharos             | `PHAROS`       | `USD`             |
| Plume              | `PLUME`        | `USD`             |
| Polkadot Asset Hub | `PAH`          | `USD`             |
| Polygon PoS        | `POLY`         | `USD`             |
| Sei                | `SEI`          | `USD`             |
| Solana             | `SOL`          | `USD`             |
| Sonic              | `SONIC`        | `USD`             |
| Starknet           | `STRK`         | `USD`             |
| Stellar            | `XLM`          | `USD`             |
| Sui                | `SUI`          | `USD`             |
| Unichain           | `UNI`          | `USD`             |
| World Chain        | `WORLDCHAIN`   | `USD`             |
| XDC                | `XDC`          | `USD`             |
| XRPL               | `XRP`          | `USD`             |
| ZKsync Era         | `ZKS`          | `USD`             |

## EURC

| Chain             | API Chain Code | API Currency Code |
| ----------------- | -------------- | ----------------- |
| Avalanche C-Chain | `AVAX`         | `EUR`             |
| Base              | `BASE`         | `EUR`             |
| Ethereum          | `ETH`          | `EUR`             |
| Solana            | `SOL`          | `EUR`             |
| Stellar           | `XLM`          | `EUR`             |
| World Chain       | `WORLDCHAIN`   | `EUR`             |

## Crypto Deposits and Payouts APIs

The Crypto Deposits API and Crypto Payouts API support a subset of blockchains
that have USDC available. The following table outlines which blockchain each API
supports.

| Chain              | Crypto Deposits API | Crypto Payouts API |
| ------------------ | ------------------- | ------------------ |
| Algorand           | ✓                   | ✓                  |
| Aptos              | ✗                   | ✗                  |
| Arbitrum           | ✓                   | ✓                  |
| Avalanche C-Chain  | ✓                   | ✓                  |
| Base               | ✓                   | ✓                  |
| Celo               | ✗                   | ✗                  |
| Codex              | ✓                   | ✓                  |
| EDGE               | ✓                   | ✓                  |
| Ethereum           | ✓                   | ✓                  |
| Hedera             | ✓                   | ✓                  |
| HyperEVM           | ✓                   | ✓                  |
| Injective          | ✓                   | ✓                  |
| Ink                | ✓                   | ✓                  |
| Linea              | ✓                   | ✓                  |
| Monad              | ✓                   | ✓                  |
| Morph              | ✓                   | ✓                  |
| NEAR               | ✗                   | ✗                  |
| Noble              | ✓                   | ✓                  |
| OP Mainnet         | ✓                   | ✓                  |
| Pharos             | ✓                   | ✓                  |
| Plume              | ✓                   | ✓                  |
| Polkadot Asset Hub | ✗                   | ✗                  |
| Polygon PoS        | ✓                   | ✓                  |
| Sei                | ✓                   | ✓                  |
| Solana             | ✓                   | ✓                  |
| Sonic              | ✓                   | ✓                  |
| Starknet           | ✓                   | ✓                  |
| Stellar            | ✓                   | ✓                  |
| Sui                | ✗                   | ✗                  |
| Unichain           | ✗                   | ✗                  |
| World Chain        | ✓                   | ✓                  |
| XDC                | ✓                   | ✓                  |
| XRPL               | ✓                   | ✓                  |
| ZKsync Era         | ✗                   | ✗                  |

## Using chains and currencies in the API

Any time you refer to a currency in a Circle Mint API call, you use a currency
and chain pair. For example, to
[create a USDC transfer](/api-reference/circle-mint/account/create-business-transfer)
on Ethereum, specify the `USD` currency on the `ETH` chain.

When referring to balances, you only need to refer to the currency because the
value of the currency for Circle-hosted assets is independent of the chain.


# Supported Countries
Source: https://developers.circle.com/circle-mint/references/supported-countries

Countries that support wire transfers for minting and redeeming USDC.

&#x20;

## Wire transfers for minting and redeeming USDC

The Circle Core API supports wire transfers from and to bank accounts domiciled
in the following countries:

### Asia

* Armenia
* Azerbaijan
* Bahrain
* Bangladesh
* Bhutan
* Bonaire, Sint Eustatius and Saba
* Brunei Darussalam
* Cambodia
* Georgia
* Hong Kong
* Indonesia
* Israel
* Japan
* Jordan
* Kazakhstan
* Kuwait
* Kyrgyzstan
* Malaysia
* Mongolia
* Oman
* Philippines
* Republic of Korea
* Saudi Arabia
* Singapore
* Sri Lanka
* Taiwan
* Tajikistan
* Thailand
* Timor-Leste
* Turkey
* United Arab Emirates
* Uzbekistan
* Vietnam

### Africa

* Angola
* Benin
* Botswana
* British Indian Ocean Territory
* Burkina Faso
* Burundi
* Cameroon
* Chad
* Egypt
* Ethiopia
* The French Southern Territories
* The Gambia
* Ghana
* Kenya
* Madagascar
* Malawi
* Mauritius
* Mayotte
* Morocco
* Mozambique
* Namibia
* Niger
* Réunion
* Rwanda
* Saint Helena, Ascension and Tristan da Cunha
* Senegal
* Seychelles
* South Africa
* Tanzania
* Tunisia
* Western Sahara
* Zambia
* Zimbabwe

### Europe

* Åland Islands
* Andorra
* Austria
* Belgium
* Bosnia and Herzegovina
* Bulgaria
* Croatia
* Cyprus
* Czechia
* Denmark
* Estonia
* The Faroe Islands
* Finland
* France
* Germany
* Gibraltar
* Greece
* Guernsey
* Holy See (Vatican City State)
* Hungary
* Iceland
* Ireland
* Isle of Man
* Italy
* Jersey
* Latvia
* Liechtenstein
* Lithuania
* Luxembourg
* Malta
* The Republic of Moldova
* Monaco
* Montenegro
* Republic of North Macedonia
* Netherlands
* Norway
* Poland
* Portugal
* Romania
* San Marino
* Serbia
* Slovakia
* Slovenia
* Spain
* Svalbard and Jan Mayen
* Sweden
* Switzerland
* United Kingdom

### North America

* Anguilla
* Antigua and Barbuda
* Aruba
* The Bahamas
* Belize
* Bermuda
* British Virgin Islands
* Canada
* Cayman Islands
* Costa Rica
* Curaçao
* Dominica
* The Dominican Republic
* El Salvador
* Greenland
* Grenada
* Guadeloupe
* Honduras
* Martinique
* Mexico
* Montserrat
* Puerto Rico
* Saint Barthelemy
* Saint Lucia
* Saint Martin (French part)
* Saint Pierre and Miquelon
* Saint Vincent and the Grenadines
* Sint Maarten (Dutch part)
* The Turks and Caicos Islands
* United States (excluding HI and NY)
* United States Minor Outlying Islands
* U.S. Virgin Islands

### South America

* Argentina
* Bouvet Island
* Brazil
* Chile
* Colombia
* Ecuador
* French Guiana
* Guatemala
* Guyana
* Paraguay
* Peru
* The Falkland Islands (Malvinas)
* South Georgia and the South Sandwich Islands
* Uruguay

### Oceania

* American Samoa
* Australia
* Christmas Island
* The Cocos (Keeling) Islands
* The Cook Islands
* Federated States of Micronesia
* Fiji
* French Polynesia
* Guam
* Heard Island and McDonald Islands
* Kiribati
* The Marshall Islands
* Nauru
* New Caledonia
* New Zealand
* Niue
* Norfolk Island
* The Northern Mariana Islands
* Palau
* Pitcairn
* Samoa
* Tokelau
* Tuvalu
* Wallis and Futuna

### Antarctica

* Antarctica

<Warning>
  This list is subject to change as Circle adds banking partners. Contact the
  [Customer Care team](https://support.circle.com/) for the latest information.
</Warning>


# Quickstart: Refund a Stablecoin Payin
Source: https://developers.circle.com/circle-mint/refund-stablecoin-payin

Start full or partial stablecoin payin refunds with the Crypto Deposits API.

Use the Crypto Deposits API to refund USDC or EURC after a completed
[payin](/circle-mint/how-stablecoin-payins-and-payouts-work#refunds), which is a
stablecoin deposit from an external wallet into your Circle Mint account. The
examples use a continuous
[payment intent](/circle-mint/how-stablecoin-payins-and-payouts-work#continuous-and-transient-modes)
(open-ended checkout), but the same steps apply to transient intents (single
checkout with a fixed amount). Complete
[Receive a Stablecoin Payin](/circle-mint/receive-stablecoin-payin) first if you
have not accepted a payin yet.

## Prerequisites

Before you begin this tutorial, ensure you've:

* Obtained a
  [Circle Mint sandbox API key](/circle-mint/quickstarts/getting-started) with
  access to the Crypto Deposits API (stablecoin payins).
* [Confirmed a completed stablecoin payin](/circle-mint/receive-stablecoin-payin#step-4-confirm-payment-completion)
  on the payment intent you want to refund.
* Confirmed there is no pending payment on that intent.
* Installed cURL for API calls.

## Step 1: Start a refund on the payment intent

Call the
[Refund a payment intent](/api-reference/circle-mint/payments/refund-payment-intent)
endpoint.

* Partial refund: set `toAmount` to the amount you return to the customer. You
  can send multiple partial refunds up to what was settled.
* Full refund: use the request fields for refunding the remaining balance as
  described in the API reference.

**Expected result:** a `refund` object with `status` `pending` and a refund
`id`.

Example request:

```bash cURL theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/paymentIntents/e2e90ba3-9d1f-490d-9460-24ac6eb55a1b/refund' \
--header 'Accept: application/json' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "9aed1aab-292a-427f-aae1-e0e358fef1c9",
  "destination": {
    "chain": "ETH",
    "address": "0xcd7475eaed9ee9678cf219cec748e25aba068a69"
  },
  "amount": {
    "currency": "USD"
  },
  "toAmount": {
    "amount": "0.50",
    "currency": "USD"
  }
}'
```

Example response:

```json JSON theme={null}
{
  "data": {
    "id": "3389f4ba-aafd-4eef-aaa2-3292df8f62e6",
    "type": "refund",
    "status": "pending",
    "amount": {
      "currency": "USD"
    },
    "createDate": "2023-01-22T15:29:58.000000Z",
    "updateDate": "2023-01-22T15:29:58.000000Z",
    "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
    "merchantWalletId": "1000999922",
    "paymentIntentId": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "settlementAmount": {
      "amount": "0.50",
      "currency": "USD"
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0xcd7475eaed9ee9678cf219cec748e25aba068a69"
    }
  }
}
```

## Step 2: Inspect the payment intent

Call
[Get a payment intent](/api-reference/circle-mint/payments/get-payment-intent)
to confirm the refund is reflected on the intent.

**Expected result:** the response includes these fields:

* `amountRefunded`: cumulative amount refunded on this intent so far.
* `refundIds`: refund IDs associated with this intent.
* `paymentIds`: IDs of payin payments on this intent.
* `timeline`: includes a `refunded` entry after the refund is recorded
  (alongside earlier statuses such as `paid`).

Example request:

```bash cURL theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/e2e90ba3-9d1f-490d-9460-24ac6eb55a1b' \
--header 'Accept: application/json' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
```

Example response:

```json JSON theme={null}
{
  "data": {
    "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "currency": "USD",
    "settlementCurrency": "USD",
    "amountPaid": {
      "amount": "1.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.50",
      "currency": "USD"
    },
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      },
      {
        "type": "totalPaymentFees",
        "amount": "0.01",
        "currency": "USD"
      }
    ],
    "paymentIds": ["66c56b6a-fc79-338b-8b94-aacc4f0f18de"],
    "refundIds": ["3389f4ba-aafd-4eef-aaa2-3292df8f62e6"],
    "timeline": [
      {
        "status": "refunded",
        "time": "2023-01-22T15:30:00.000000Z"
      },
      {
        "status": "complete",
        "context": "paid",
        "time": "2023-01-21T20:19:24.861094Z"
      },
      {
        "status": "pending",
        "time": "2023-01-21T20:13:38.188286Z"
      },
      {
        "status": "created",
        "time": "2023-01-21T20:13:35.579331Z"
      }
    ],
    "type": "continuous",
    "createDate": "2023-01-21T20:13:35.578678Z",
    "updateDate": "2023-01-22T15:30:00.000000Z"
  }
}
```

## Step 3: Confirm refund completion

Call [Get a payment](/api-reference/circle-mint/payments/get-payment) with the
original payin payment `id` or with the refund `id` from
[Step 1](#step-1-start-a-refund-on-the-payment-intent).

**Expected result:** the response has `type` `refund` and `status` `paid` when
the refund has settled onchain.

If `status` is still `pending`, the refund has not finished. Poll
[Get a payment](/api-reference/circle-mint/payments/get-payment) on an interval,
or subscribe to `payments` notifications (see the
[notifications quickstart](/circle-mint/circle-apis-notifications-quickstart))
to learn when the status changes.

Example request: (replace the ID with the payment or refund `id`)

```bash cURL theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/payments/3389f4ba-aafd-4eef-aaa2-3292df8f62e6' \
--header 'Accept: application/json' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
```

Example response:

```json JSON theme={null}
{
  "data": {
    "id": "3389f4ba-aafd-4eef-aaa2-3292df8f62e6",
    "type": "refund",
    "status": "paid",
    "amount": {
      "currency": "USD"
    },
    "fees": {
      "amount": "0.01",
      "currency": "USD"
    },
    "createDate": "2023-01-22T15:29:58.000000Z",
    "updateDate": "2023-01-22T15:35:12.000000Z",
    "merchantId": "f1397191-56e6-42fd-be86-0a7b9bd91522",
    "merchantWalletId": "1000999922",
    "paymentIntentId": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "settlementAmount": {
      "amount": "0.50",
      "currency": "USD"
    },
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x0d4344cff68f72a5b9abded37ca5862941a62050"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0xcd7475eaed9ee9678cf219cec748e25aba068a69"
    },
    "transactionHash": "0xa1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678"
  }
}
```


# Quickstart: Send a Stablecoin Payout
Source: https://developers.circle.com/circle-mint/send-stablecoin-payout

Create an address book recipient, send USDC or EURC onchain, and confirm payout completion with the Crypto Payouts API.

Use the Crypto Payouts API to send onchain USDC or EURC
[stablecoin payouts](/circle-mint/how-stablecoin-payins-and-payouts-work) from
Circle Mint to third-party blockchain addresses. You create a recipient, wait
until it is active, create a payout, then confirm completion using the API or
webhooks. The examples in this quickstart use Ethereum, but you can use any
[supported blockchain](/circle-mint/references/supported-chains-and-currencies).

<Tip>
  Stablecoin payouts are for transferring funds to third-party recipients such as
  vendors, contractors, remittances, or customers. If you want to transfer funds
  to a wallet your business owns or controls, see the
  [Transfer USDC Onchain](/circle-mint/howtos/transfer-on-chain) guide.
</Tip>

## Prerequisites

Before you begin this tutorial, ensure you've:

* Obtained a
  [Circle Mint sandbox API key](/circle-mint/quickstarts/getting-started) with
  access to the Crypto Payouts API (stablecoin payouts).
* Obtained a source wallet ID (`source.id`) with funds available for payouts.
* Installed cURL for API calls.
* (Optional) Configured
  [webhook notifications](/circle-mint/circle-apis-notifications-quickstart).

## Step 1: Create an address book recipient

Add a recipient in your Mint address book before any payout. If delayed
withdrawals are on in the Circle Mint console, new recipients stay `inactive`
for 24 hours before they become `active`. If delayed withdrawals are off,
recipients become `active` within seconds.

<Note>
  Toggle **delayed withdrawals** under your Mint account settings in the Circle
  Mint console.
</Note>

### 1.1. Create a recipient

Call
[Create address book recipient](/api-reference/circle-mint/payouts/create-address-book-recipient).

**Expected result:** a recipient `id` (status may be `pending` until active).

Example request:

```bash cURL theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/addressBook/recipients' \
--header 'Accept: application/json' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "9352ec9e-5ee6-441f-ab42-186bc71fbdde",
  "chain": "ETH",
  "address": "0x65BFCf1a6289a0b77b4D3F7d12005a05949FD8C3",
  "metadata": {
    "email": "satoshi@circle.com",
    "bns": "testbns",
    "nickname": "test nickname desc"
  }
}'
```

Example response:

```json JSON theme={null}
{
  "data": {
    "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "pending",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}
```

### 1.2. Confirm recipient status

The recipient must be `active` before you create a payout. Use webhooks or poll
[Get address book recipient](/api-reference/circle-mint/payouts/get-address-book-recipient).
If delayed withdrawals are on, wait until status moves from `inactive` to
`active`.

**Expected result:** `status` is `active`.

<Tabs>
  <Tab title="Webhooks">
    After you
    [subscribe to notifications](/circle-mint/circle-apis-notifications-quickstart)
    for `addressBookRecipients`, Circle sends updates when a recipient is created or
    its status changes.

    Example `addressBookRecipients` notification when the recipient becomes active:

    ```json JSON theme={null}
    {
      "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
      "notificationType": "addressBookRecipients",
      "version": 1,
      "customAttributes": {
        "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
      },
      "addressBookRecipient": {
        "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe",
        "chain": "ETH",
        "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
        "metadata": {
          "nickname": "test nickname desc",
          "email": "satoshi@circle.com",
          "bns": "testbns"
        },
        "status": "active",
        "updateDate": "2022-09-22T14:16:34.985353Z",
        "createDate": "2022-09-22T14:16:34.985353Z"
      }
    }
    ```
  </Tab>

  <Tab title="Polling">
    Call the
    [Get address book recipient](/api-reference/circle-mint/payouts/get-address-book-recipient)
    endpoint on an interval until the recipient `status` is `active`.

    Example request: (use the `id` from the
    [create recipient](#1-1-create-a-recipient) response)

    ```bash cURL theme={null}
    curl --location --request GET 'https://api-sandbox.circle.com/v1/addressBook/recipients/dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe' \
    --header 'Accept: application/json' \
    --header 'X-Request-Id: ${GUID}' \
    --header 'Authorization: Bearer ${YOUR_API_KEY}'
    ```

    Example response when the recipient is active:

    ```json JSON theme={null}
    {
      "data": {
        "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe",
        "chain": "ETH",
        "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
        "metadata": {
          "nickname": "test nickname desc",
          "email": "satoshi@circle.com",
          "bns": "testbns"
        },
        "status": "active",
        "updateDate": "2022-09-22T14:16:34.985353Z",
        "createDate": "2022-09-22T14:16:34.985353Z"
      }
    }
    ```
  </Tab>
</Tabs>

Do not continue until the recipient `status` is `active`.

## Step 2: Create a payout

Call [Create payout](/api-reference/circle-mint/payouts/create-payout) with the
recipient `id` from [Create a recipient](#1-1-create-a-recipient), your source
wallet, and amounts. If `toAmount.currency` is omitted, `amount.currency` is
used as the receiving currency.

**Expected result:** a payout `id` with `status` `pending`.

<Warning>
  `source.identities` is required for payouts of 3,000 USD or more. It describes
  the sender (your organization) for FinCEN
  [Travel Rule](/circle-mint/howtos/transfer-on-chain#travel-rule-compliance)
  compliance.
</Warning>

Example request:

```bash cURL theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/payouts' \
--header 'Accept: application/json' \
--header 'X-Request-Id: ${GUID}' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "source": {
    "type": "wallet",
    "id": "12345",
    "identities": [
      {
        "type": "individual",
        "name": "Satoshi Nakamoto",
        "addresses": [
          {
            "line1": "100 Money Street",
            "line2": "Suite 1",
            "city": "Boston",
            "district": "MA",
            "postalCode": "01234",
            "country": "US"
          }
        ]
      }
    ]
  },
  "destination": {
    "type": "address_book",
    "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe"
  },
  "amount": {
    "amount": "3000.14",
    "currency": "USD"
  },
  "toAmount": {
    "currency": "USD"
  }
}'
```

Example response:

```json JSON theme={null}
{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe"
    },
    "amount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "status": "pending",
    "updateDate": "2020-04-10T02:13:30.000Z",
    "createDate": "2020-04-10T02:13:30.000Z"
  }
}
```

<Note>
  If [Get payout](/api-reference/circle-mint/payouts/get-payout) later returns
  `status` `failed`, check the payload for an `errorCode` and related fields (for
  example insufficient balance or an invalid recipient). Retry only after you fix
  the underlying issue.
</Note>

## Step 3: Confirm payout completion

Confirm the payout using webhooks or by polling
[Get payout](/api-reference/circle-mint/payouts/get-payout).

**Expected result:** `status` is `complete` when funds are sent and delivered
onchain.

<Tabs>
  <Tab title="Webhooks">
    Subscribe to `payout` notifications to receive updates as status changes. Each
    message includes the payout object with the latest `status`.

    Example `payout` notification when the `status` is `complete`:

    ```json JSON theme={null}
    {
      "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
      "notificationType": "payout",
      "version": 1,
      "customAttributes": {
        "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
      },
      "payout": {
        "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
        "sourceWalletId": "12345",
        "destination": {
          "type": "address_book",
          "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe"
        },
        "amount": {
          "amount": "3000.14",
          "currency": "USD"
        },
        "toAmount": {
          "amount": "3000.14",
          "currency": "USD"
        },
        "fees": {
          "amount": "0.00",
          "currency": "USD"
        },
        "networkFees": {
          "amount": "0.30",
          "currency": "USD"
        },
        "status": "complete",
        "createDate": "2020-04-10T02:13:30.000Z",
        "updateDate": "2020-04-10T02:13:30.000Z"
      }
    }
    ```
  </Tab>

  <Tab title="Polling">
    Call the [Get payout](/api-reference/circle-mint/payouts/get-payout) endpoint on
    an interval until `status` is `complete`.

    Example request: (use the payout `id` from the
    [create payout](#step-2-create-a-payout) response)

    ```bash cURL theme={null}
    curl --location --request GET 'https://api-sandbox.circle.com/v1/payouts/b8627ae8-732b-4d25-b947-1df8f4007a29' \
    --header 'Accept: application/json' \
    --header 'X-Request-Id: ${GUID}' \
    --header 'Authorization: Bearer ${YOUR_API_KEY}'
    ```

    Example response when the payout is complete:

    ```json JSON theme={null}
    {
      "data": {
        "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
        "sourceWalletId": "12345",
        "destination": {
          "type": "address_book",
          "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe"
        },
        "amount": {
          "amount": "3000.14",
          "currency": "USD"
        },
        "toAmount": {
          "amount": "3000.14",
          "currency": "USD"
        },
        "fees": {
          "amount": "0.00",
          "currency": "USD"
        },
        "networkFees": {
          "amount": "0.30",
          "currency": "USD"
        },
        "status": "complete",
        "createDate": "2020-04-10T02:13:30.000Z",
        "updateDate": "2020-04-10T02:13:30.000Z"
      }
    }
    ```
  </Tab>
</Tabs>


# Quickstart: Swap Between USDC and EURC
Source: https://developers.circle.com/circle-mint/swap-between-usdc-and-eurc



The Cross-Currency API lets you swap between USDC and EURC.

This guide walks you through how to use the Cross-Currency API to obtain a quote
for a EURC to USDC exchange and then execute the swap.

## Prerequisites

Before you begin this quickstart, ensure that you have:

* Obtained an API key for Mint from Circle
* Obtained access to the Cross-Currency API
* cURL installed on your development machine
* Funded your Circle Mint account with EURC

This quickstart provides API requests in cURL format, along with example
responses.

## Part 1: Request a quote

Using a UUIDv4 generator, generate a UUID to use as the idempotency key. Using
the idempotency key, request a quote from the
[`/exchange/quotes`](/api-reference/circle-mint/cross-currency/get-quote)
endpoint for exchanging a specific amount of EURC to USDC. You must include an
`amount` field on either the `from` or the `to` object, but not both. The `type`
field must be set to `tradable` to get a locked rate quote. The following is an
example request for a quote:

<Note>
  **Note:** Quotes are valid for 3 seconds and must be refreshed if not used in
  that time frame.
</Note>

```shell Shell theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/exchange/quotes' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "tradable",
  "idempotencyKey": "07c238ad-b144-4607-9b70-51d1ffbb3c7b",
  "from": {
    "currency": "EURC",
    "amount": 100
  },
  "to": {
    "currency": "USDC",
    "amount": null
  }
}
'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "id": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1",
    "rate": 0.1974,
    "from": {
      "currency": "EURC",
      "amount": 100.0
    },
    "to": {
      "currency": "USDC",
      "amount": 110.0
    },
    "expiry": "2023-10-26T14:37:20.804786Z",
    "type": "tradable"
  }
}
```

## Part 2: Initiate the trade

Generate another idempotency key, and then use it to confirm the quote with the
[`/exchange/trades`](/api-reference/circle-mint/cross-currency/create-fx-trade)
endpoint and initiate the trade. This locks in the rate. Funds are debited from
your Circle Mint account in accordance with your settlement schedule.

The following is an example request:

```shell Shell theme={null}
curl --location --request POST 'https://api-sandbox.circle.com/v1/exchange/trades' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "idempotencyKey": "07c238ad-b144-4607-9b70-51d1ffbb3c7b",
  "quoteId": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1"
}
'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "id": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1",
    "from": {
      "currency": "EURC",
      "amount": 100.0
    },
    "to": {
      "currency": "USDC",
      "amount": 110.0
    },
    "status": "pending",
    "createDate": "2023-10-26T14:37:20.804786Z",
    "updateDate": "2023-10-26T14:37:20.804786Z",
    "quoteId": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1"
  }
}
```

## Part 3: Get the settlement batch (optional)

Once you have initiated the trade, you can optionally retrieve the settlement
batch from the
[`/exchange/trades/settlements`](/api-reference/circle-mint/cross-currency/get-settlements)
endpoint on your account and review the details of the settlement.

```shell Shell theme={null}
curl --location --request GET 'https://api-sandbox.circle.com/v1/exchange/trades/settlements' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json JSON theme={null}
{
  "data": [
    {
      "id": "7bf8cf16-2dc1-4514-9b64-c471561a7321",
      "entityId": "2bcca31e-784f-4b21-9002-8239551e985f",
      "status": "settled",
      "createDate": "2025-05-27T19:00:48.688390Z",
      "updateDate": "2025-05-27T19:00:51.619761Z",
      "details": [
        {
          "id": "454fc27e-ae8a-461f-834b-d19d8dec481e",
          "type": "receivable",
          "status": "completed",
          "amount": {
            "currency": "EURC",
            "amount": "1.45"
          },
          "createDate": "2025-05-27T19:00:48.688333Z",
          "updateDate": "2025-05-27T19:00:51.617187Z"
        },
        {
          "id": "d22eebbc-0db9-4818-9f3a-24b39d02524a",
          "type": "payable",
          "status": "completed",
          "amount": {
            "currency": "USDC",
            "amount": "1.60"
          },
          "expectedPaymentDueAt": "2025-05-27T22:00:00Z",
          "createDate": "2025-05-27T19:00:48.688369Z",
          "updateDate": "2025-05-27T19:00:51.617187Z"
        }
      ]
    },
    {
      "id": "e8edbad2-d0a3-4560-b892-d035ca26ba69",
      "entityId": "2bcca31e-784f-4b21-9002-8239551e985f",
      "status": "settled",
      "createDate": "2025-05-19T22:10:29.945750Z",
      "updateDate": "2025-05-20T16:52:01.754271Z",
      "details": [
        {
          "id": "b19a182d-ac3d-436b-be4b-5f8b549c74fd",
          "type": "payable",
          "status": "completed",
          "amount": {
            "currency": "USDC",
            "amount": "1.60"
          },
          "expectedPaymentDueAt": "2025-05-19T22:00:00Z",
          "createDate": "2025-05-19T22:10:29.944724Z",
          "updateDate": "2025-05-20T16:52:01.750552Z"
        },
        {
          "id": "6644a7e5-4793-48ef-882b-742cf7bea4ee",
          "type": "receivable",
          "status": "completed",
          "amount": {
            "currency": "EURC",
            "amount": "1.45"
          },
          "createDate": "2025-05-19T22:10:29.944441Z",
          "updateDate": "2025-05-20T16:52:01.750552Z"
        }
      ]
    }
  ]
}
```


# Manage Webhook Subscriptions
Source: https://developers.circle.com/circle-mint/webhook-subscription-management

Subscribe to webhook notifications to be notified automatically when a transaction occurs.

*Circle's webhooks are an automated method for apps to receive notifications the
moment a transaction is completed or fails to complete. Circle will make a
request to your application when an operation is completed. That means your app
doesn't need to poll Circle to know whether an operation has completed in the
blockchain—the confirmation will arrive automatically.*

For configuring a notification subscriber endpoint, see the
[Notifications Quickstart](/circle-mint/circle-apis-notifications-quickstart).

## Set Up Subscriptions

Through the Circle UI in Sandbox or Production, you can set up webhook
subscriptions. This can be done by:

1. Navigating to Developer → Subscriptions in Sandbox or Production.
2. Selecting Add Subscription
3. Entering an endpoint URL you would like notifications to go to.
4. Selecting Add Endpoint

<Warning>
  **Automatic subscription removal** All subscriptions in sandbox are removed after 30 days.
</Warning>

<Frame>
  <img />
</Frame>

## View Subscriptions

Via Circle's UI you can view all subscriptions registered to your account on
Developer → Subscriptions. Circle's Sandbox environment permits up to three
subscriptions and the Production environment supports one.

## Remove Subscriptions

While viewing subscriptions you are also provided the option to remove
subscriptions. This is done by simply selecting kebab on the Endpoint and
selecting remove.

## API Endpoints

All these actions can also be done using Circle's APIs. See
[API reference subscriptions](/api-reference/circle-mint/general/create-subscription)
for more detail.


# Contracts
Source: https://developers.circle.com/contracts



Circle Contracts empowers developers to utilize smart contracts within their
applications. Contracts facilitates the creation, deployment, and execution of
smart contracts through an intuitive Developer Console or APIs, ensuring
flexibility and ease of integration. The goal is to simplify the process of
leveraging smart contracts for real-world use cases in applications.

Some examples of what developers can do using Contracts:

1. **Deploying Custom Contracts:** Bring your custom contracts to life by
   efficiently deploying them onto the blockchain, expanding the functionality
   and capabilities of your application.
2. **Deploying NFT Contracts:** Easily deploy NFT contracts and programmatically
   mint unique tokens for end-users, enabling the creation of digital assets and
   collectibles.
3. **Creating On-Chain Loyalty Programs:** Establish on-chain loyalty programs
   within your applications, allowing users to earn and redeem rewards
   seamlessly.
4. **Interacting with DeFi Projects:** Effortlessly integrate with popular DeFi
   projects like Uniswap, enabling users to interact with decentralized
   exchanges and other financial services with just a few clicks.
5. **Integrating Circle Contracts:** Seamlessly incorporate Circle contracts,
   such as [CCTP](/cctp/evm-smart-contracts)'s, into your application, providing
   secure and efficient transfer functionalities.
6. **Monitor Your Smart Contracts:** Set up push notifications for any events
   occurring in your smart contracts.

<Note>
  **No-code & API support** Contracts can be accessed in two ways by developers:

  1. **Console:** You can explore, interact and manage smart contracts without
     writing any code. This is ideal for non-technical users, or any low frequency
     use. The console supports exploring contracts (view functions, events,
     transactions), deploying contracts (via templates) and managing the contract
     (any read/write function on the contract).
  2. **SDK/API:** You can also receive the benefits of Contracts programmatically!
     Combining with developer-controlled wallets and Gas Station, you can deploy,
     interact and manage smart contracts at scale via simple APIs - in a gasless
     fashion! The APIs that we provide include deploying contracts (via bytecode
     or templates), read or write contract executions.
</Note>

## Explore smart contracts

The Developer Services console allows developers to view the details of any
smart contract. Developers can import a smart contract by adding its address and
blockchain. Once imported, developers can explore the contract, view the ABI
functions, read the source code, see all transactions, subscribe to events, or
execute function calls.

## Deploy smart contracts

Developers can deploy smart contracts using Circle Contracts by writing their
contracts or using pre-vetted templates provided by Circle. To deploy a
contract, developers need to create a Developer-controlled wallet using Circle
Wallets and use it to deploy the contract across any supported chains.
Deployment can be done through the console in a no-code way or programmatically
using APIs.

### Deploy a custom contract

If you have already written a smart contract on an IDE, you can deploy it by
providing the compiled bytecode and ABI. For console deployment, create a
console wallet (a smart contract wallet) and use it to deploy the contract on
the desired chain. Include the source code, ABI, and bytecode for API deployment
in the request parameters.

### Deploy contracts with templates

For developers unfamiliar with smart contract engineering, Templates provide
code snippets to deploy contracts without writing any solidity code. These
templates, curated by the Circle team and audited by third-party auditors, cover
popular onchain use cases. Fill in the required properties and deploy the
contract. Templates can be deployed through the console or APIs.

Some templates that we support include:

* Token (ERC-20) contract, by Thirdweb
* NFT (ERC-721) contract, by Thirdweb
* Multi-Token (ERC-1155) contract, by Thirdweb
* Airdrop contract, by Thirdweb

## Manage smart contracts

Once deployed, you can use the console to manage your smart contracts. This
includes viewing analytics, calling contract admin functions (e.g. changing
ownership, updating configs) or subscribing to events. The console provides an
easy way to update and manage contracts post-deployment. Developers can access
analytics such as transactions and events for contracts deployed using Contracts
via APIs.

## Interact with smart contracts

Interacting with smart contracts allows you to integrate existing onchain
contracts into your applications. Import the contract and explore its various
functions. You can add parameters and generate API resources to interact with
the contract in a straightforward manner.

## Event Monitoring

Event Monitoring allows developers to track onchain events emitted by their
smart contracts in real time. By setting up event monitors, you can receive
instant notifications whenever specified events occur. This capability enables
developers to respond programmatically to important actions within their
applications, making it easier to implement automation and enhance user
experiences.


# Airdrop Template
Source: https://developers.circle.com/contracts/airdrop



The Airdrop template is an audited, ready-to-deploy, airdrop smart contract for
ERC-20, ERC-721, ERC-1155, or native tokens. The airdrop is performed by
“pushing tokens,” which happens when the contract owner transfers tokens to the
receivers' addresses. Receivers do not need to take any action and do not incur
a gas fee.

The following are common use cases for the Airdrop template:

* **Bulk token distribution**: Automatically distribute tokens to users in bulk.
  For example, project teams or token issuers can reward their community
  members, early adopters, and participants in specific campaigns by
  distributing tokens directly to their blockchain addresses.
* **Marketing and promotion**: Increase awareness and engagement with a project
  or token. When a project distributes tokens to a large number of users, this
  attracts attention and incentivizes users to explore and participate in the
  project's ecosystem.
* **Community building and engagement**: Foster a strong and active community
  around a project. Distribute tokens to community members to incentivize them
  to stay engaged, participate in discussions, provide feedback, and contribute
  to the overall growth and success of the project.

<Warning>
  We recommend setting a maximum of 500 recipients per airdrop transaction. More
  than 500 recipients can cause the blockchain fees to spike or the transaction
  to fail.
</Warning>

## Deployment parameters

The Airdrop template creates a customized airdrop smart contract to distribute
ERC-20, ERC-721, ERC-1155, or native tokens to multiple users. To create a
contract using this template, provide the following parameter values when
deploying a smart contract template. To deploy a template, send a `POST` request
to the `/templates/{id}/deploy` endpoint.

**Template ID**: 13e322f2-18dc-4f57-8eed-4bddfc50f85e

### Template deployment parameters

| Parameter      | Type   | Required | Description                                                                                                                                                                                                            |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultAdmin` | Add    | X        | Address of the default admin. This address can execute permissable functions on the contract. <br /> <br />**Important:** You lose administrative access to the contract if this is not set to an address you control. |
| `contractURI`  | String |          | URL for the marketplace metadata of your contract.                                                                                                                                                                     |

## Common functions

This section lists the most commonly used functions on the Airdrop template,
their respective parameters, and potential failure scenarios. These functions
include:

* [setOwner \[write\]](#setowner-write)
* [airdropERC1155 \[write\]](#airdroperc1155-write)
* [airdropERC721 \[write\]](#airdroperc721-write)
* [airdropERC20 \[write\]](#airdroperc20-write)
* [owner \[read\]](#owner-read)

## setOwner \[write]

The `setOwner` function sets the owner of the smart contract or transfers
ownership from the existing owner to a new owner.

### Parameters

<Note>The name of the parameter is not used in the request body.</Note>

| Parameter    | Type    | Description               |
| :----------- | :------ | :------------------------ |
| \_*newOwner* | address | Address of the new owner. |

### Failure scenarios

* The `setOwner` function fails if it is called by a non-admin.

## airdropERC1155 \[write]

The `airdropERC1155` function allows the owner of this address to send ERC-1155
tokens to a list of recipients.

### Parameters

<Note>The names of the parameters are not used in the request body.</Note>

| Parameter    | Type                                                        | Description                                                                                                                                                                                                                           |
| ------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_*newOwner* | address                                                     | Address of the new owner.                                                                                                                                                                                                             |
| \_*contents* | tuple: <br /> <br />- address<br />- uint256<br />- uint256 | Array of recipient information: <br /> <br />- Address that is to receive the airdrop<br />- ID of the token within the ERC-1155 contract to be distributed<br />- Amount of the token within the ERC-1155 contract to be distributed |

### Failure scenarios

The `airdropERC1155` function fails if:

* It is called by a non-admin
* It contains incorrect token information, such as an invalid token ID
* The Airdrop contract is not approved for what's being transferred, which means
  it is not authorized to transfer assets on the airdropper's behalf
* Airdropping to a contract without a receive function

### Example

The following sample code shows the new owner address and contents when sending
a `POST` request to the `/developer/transactions/contractExecution` endpoint:

```javascript JSON theme={null}
"abiParameters": [
    "0x2B5AD5c4795c026514f8317c7a215E218DcCD6cF",
    [
        ["0x4CCeBa2d7D2B4fdcE4304d3e09a1fea9fbEb1528", 0, 10],
        ["0xf4e2B0fcbd0DC4b326d8A52B718A7bb43BdBd072", 0, 10],
    ]
]
```

## airdropERC721 \[write]

The `airdropERC721` function allows the owner of this address to send ERC-20
tokens to a list of recipients.

### Parameters

<Note>The names of the parameters are not used in the request body.</Note>

| Parameter        | Type                                         | Description                                                                                                                                                    |
| ---------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_*tokenAddress* | address                                      | Address of the new owner.                                                                                                                                      |
| \_*contents*     | tuple: <br /> <br />- address<br />- uint256 | Array of recipient information: <br /> <br />- Address that is to receive the airdrop<br />- Amount of the token within the ERC-721 contract to be distributed |

### Failure scenarios

The `airdropERC721` function fails if:

* It is called by a non-admin
* It contains incorrect token information, such as an invalid token ID
* The Airdrop contract is not approved for what's being transferred, which means
  it is not authorized to transfer assets on the airdropper's behalf
* Airdropping to a contract without a receive function

### Example

The following sample code shows the token address and contents when sending a
`POST` request to the `/developer/transactions/contractExecution` endpoint:

```javascript JSON theme={null}
"abiParameters": [
    "0x2B5AD5c4795c026514f8317c7a215E218DcCD6cF",
    [
        ["0x4CCeBa2d7D2B4fdcE4304d3e09a1fea9fbEb1528", 0],
        ["0xf4e2B0fcbd0DC4b326d8A52B718A7bb43BdBd072", 1],
    ]
]
```

## airdropERC20 \[write]

The `airdropERC20` function allows the owner of this address to send NFTs to a
list of recipients.

### Parameters

<Note>The names of the parameters are not used in the request body.</Note>

| Parameter        | Type                                         | Description                                                                                                                       |
| ---------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| \_*tokenAddress* | address                                      | Address of the token.                                                                                                             |
| \_*contents*     | tuple: <br /> <br />- address<br />- uint256 | Array of recipient information: <br /> <br />- Address that is to receive the airdrop<br />- Quantity of tokens to be transferred |

### Failure scenarios

The `airdropERC20` function fails if:

* It is called by a non-admin
* The Airdrop contract is not approved for what's being transferred, which means
  it is not authorized to transfer assets on the airdropper's behalf
* Airdropping to a contract without a receive function

### Example

The following sample code shows the token address and contents when sending a
`POST` request to the `/developer/transactions/contractExecution` endpoint:

```javascript JSON theme={null}
"abiParameters": [
    "0x2B5AD5c4795c026514f8317c7a215E218DcCD6cF",
    "0xd41c057fd1c78805AAC12B0A94a405c0461A6FBb",
    [
        [
        "0x4CCeBa2d7D2B4fdcE4304d3e09a1fea9fbEb1528",
        100
        ]
    ]
]
```

## owner \[read]

The `owner` function retrieves the address of the current owner.

### Example

The following sample code shows the `owner` function when sending a `POST`
request to the `/contracts/query` endpoint:

```javascript JSON theme={null}
"abiFunctionSignature": "owner()"
```


# How-to: Create an API Key
Source: https://developers.circle.com/contracts/create-api-key

Create an API key in the Circle Console to authenticate Smart Contract Platform API requests.

## Overview

Create an API key so your server-side applications can authenticate requests to
Circle's APIs. You can create and manage API keys in the
[Circle Console](https://console.circle.com/).

## Prerequisites

Before you begin, ensure you have:

* Signed up for a Circle Developer account at
  [console.circle.com/signup](https://console.circle.com/signup).
* Reviewed the [Keys](/build/keys) page for background on key types and
  authentication.

## Steps

### Step 1. Open the API & Client Keys page

Sign in to the [Circle Console](https://console.circle.com/) and select **API &
Client Keys** from the left sidebar.

### Step 2. Create a key

Select **Create a key**, then choose **API Key**.

Enter a name for your API key and select the access level:

* **Standard**: grants read/write access to all APIs, including newly introduced
  endpoints.
* **Restricted Access**: limits the key to specific products and permission
  levels.

When you choose restricted access, configure the following options.

Select the products the key can access:

* **Webhooks**: endpoints for
  [webhook subscriptions](/api-reference/wallets/common/create-subscription).
* **Wallets**: all endpoints for
  [user-controlled](/api-reference/wallets/user-controlled-wallets/create-user)
  and developer-controlled wallets.
* **Contracts**: endpoints for
  [smart contracts](/api-reference/contracts/smart-contract-platform/import-contract).

Set the permission level for each product:

* **No permission**: the key cannot call any endpoints for that product.
* **Read**: the key can call read-only GET endpoints.
* **Read/Write**: the key can call all endpoints.

<Note>
  You can also add IP addresses or ranges to the IP allowlist for additional
  security.
</Note>

### Step 3. Copy your API key

After the Console confirms that your key was generated, select **Show** to
reveal the key value. Copy it and store it securely. You need it to authenticate
API requests.


# Quickstart: Deploy an ERC-1155 Contract Template
Source: https://developers.circle.com/contracts/deploy-smart-contract-template

Use Circle Contract Templates to deploy smart contracts without writing Solidity

This quickstart walks you through deploying an ERC-1155 Multi-Token contract
using Contract Templates and minting your first token.

Contract Templates make it easy to integrate smart contracts into your
application without writing Solidity code. Deploy contracts in minutes using
curated and audited templates that support popular onchain use cases.

<Note>
  **Note:** This quickstart provides all the code you need to deploy an ERC-1155
  contract and mint tokens. You can deploy using either the
  [Console](#console-path) or [API](#api-path).
</Note>

## Prerequisites

Before you begin, ensure you have:

* A [Circle Developer Account](https://console.circle.com)
* For the API path:
  * An [API key](/contracts/create-api-key)
  * A [dev-controlled wallet](/wallets/dev-controlled/create-your-first-wallet)
  * Your
    [Entity Secret registered](/wallets/dev-controlled/register-entity-secret)

## Evaluate templates

To learn more about the ERC-1155 template or other templates, visit:

* **[Console](https://console.circle.com):** View templates, their use cases,
  ABI functions, events, and code.
* **[Templates Glossary](/contracts/scp-templates-overview):** Review all
  templates and their configuration options.

<Frame>
  <img />
</Frame>

***

## Console path

Use the Console and a Console Wallet to deploy a smart contract template and
mint a token. This is the preferred method for those new to smart contracts.

### Step 1: Set up your Console Wallet

Console Wallets are Smart Contract Accounts designed for use within the Console.
They leverage [Gas Station](/wallets/gas-station), eliminating the need to
maintain gas for transaction fees.

If you don't have a Console Wallet, you'll be prompted to create one during
deployment.

<Warning>
  **Console Wallet Deploy Cost:** Unlike EOAs, SCAs cost gas to deploy. With
  lazy deployment, you won't pay the gas fee at wallet creation as it's charged
  when you initiate your first outbound transaction.
</Warning>

### Step 2: Deploy the smart contract

In the [Console](https://console.circle.com):

1. Navigate to the **Templates** tab.
2. Select **Multi-Token** ERC-1155.
3. Fill in the deployment parameters:

| Parameter                  | Description                                                                                            |
| :------------------------- | :----------------------------------------------------------------------------------------------------- |
| **Name**                   | The offchain name of the contract, only visible in Circle's systems. Use `MyERC1155Contract`.          |
| **Contract Name**          | The onchain name for the contract. Use `MyERC1155Contract`.                                            |
| **Default Admin**          | The address with admin permissions to execute permissioned functions. Use your Console Wallet address. |
| **Primary Sale Recipient** | The address that receives first-time sale proceeds. Use your Console Wallet address.                   |
| **Royalty Recipient**      | The address that receives royalties from secondary sales. Use your Console Wallet address.             |
| **Royalty Percent**        | The royalty share as a decimal (for example, `0.05` for 5% of secondary sales). Use `0`.               |
| **Network**                | The blockchain network to deploy onto. Select `Arc Testnet`.                                           |
| **Select Wallet**          | The wallet to deploy the smart contract from. Select your Console Wallet.                              |
| **Deployment Speed**       | The fee level affecting transaction processing speed (FAST, AVERAGE, SLOW). Select `AVERAGE`.          |

4. Select **Deploy**.

<Note>
  **Console Wallet Creation:** After selecting a network, you'll be prompted to
  create a Console Wallet. This wallet is automatically created on all available
  networks. On testnet, a [Gas Station Policy](/wallets/gas-station/policy-management) is also created.

  <Frame>
    <img />
  </Frame>
</Note>

Once deployed, you'll return to the **Contracts** dashboard. The deployment
status will initially show **Pending**, then change to **Complete** after a few
seconds.

<Frame>
  <img />
</Frame>

### Step 3: Mint a token

In the [Console](https://console.circle.com):

1. Navigate to the **Contracts** tab.
2. Select your **MyERC1155Contract**.
3. Select the **ABI Functions** tab → **Write** → **mintTo**.
4. Fill in the parameters:

| Parameter     | Description                                                                                                                                                                                                                                        |
| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\_to**      | The wallet address to receive the minted token. Use your Console Wallet address.                                                                                                                                                                   |
| **\_tokenId** | The token ID to mint, identifying the token type in ERC-1155. Use max uint256 (`115792089237316195423570985008687907853269984665640564039457584007913129639935`) to create token ID 0. For subsequent tokens, use `0` for ID 1, `1` for ID 2, etc. |
| **\_uri**     | The URI for the token metadata, such as an IPFS CID or CDN URL.                                                                                                                                                                                    |
| **\_amount**  | The quantity of tokens to mint. Use `1`.                                                                                                                                                                                                           |

5. Select **Execute Function** → ensure your Console Wallet is selected →
   **Execute**.

<Frame>
  <img />
</Frame>

Select **View Transaction History** to monitor the transaction. Once the state
shows **Complete**, the token has been minted successfully.

<Note>
  **Inbound Transaction:** You'll also see an inbound transfer indicating the
  token was minted to your Console Wallet.
</Note>

***

## API path

Use APIs to deploy a smart contract template and mint a token programmatically.
This option requires an API key and a Dev-Controlled Wallet.

### Step 1: Set up your environment

#### 1.1. Get your wallet information

Retrieve your wallet ID using the
[`GET /wallets`](/api-reference/wallets/developer-controlled-wallets/get-wallets)
API. Ensure:

* Wallet custody type is **Dev-Controlled**
* Blockchain is **Arc Testnet**
* Account type is **SCA** (recommended—removes need for gas)

Note your wallet's address for subsequent steps.

#### 1.2. Understand deployment parameters

| Parameter                | Description                                                                                                                           |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `idempotencyKey`         | A unique value for request deduplication.                                                                                             |
| `name`                   | The offchain contract name. Use `MyERC1155Contract`.                                                                                  |
| `walletId`               | The ID of the wallet deploying the contract. Use your dev-controlled wallet ID.                                                       |
| `templateId`             | The template identifier. Use `aea21da6-0aa2-4971-9a1a-5098842b1248` for ERC-1155. See [Templates](/contracts/scp-templates-overview). |
| `blockchain`             | The network to deploy onto. Use `ARC-TESTNET`.                                                                                        |
| `entitySecretCiphertext` | The re-encrypted entity secret. See [How the Entity Secret Works](/wallets/dev-controlled/entity-secret-management).                  |
| `feeLevel`               | The fee level for transaction processing. Use `MEDIUM`.                                                                               |
| `templateParameters`     | The onchain initialization parameters (see below).                                                                                    |

#### 1.3. Template parameters

| Parameter              | Description                                                                       |
| :--------------------- | :-------------------------------------------------------------------------------- |
| `name`                 | The onchain contract name. Use `MyERC1155Contract`.                               |
| `defaultAdmin`         | The address with admin permissions. Use your Dev-Controlled Wallet address.       |
| `primarySaleRecipient` | The address for first-time sale proceeds. Use your Dev-Controlled Wallet address. |
| `royaltyRecipient`     | The address for secondary sale royalties. Use your Dev-Controlled Wallet address. |
| `royaltyPercent`       | The royalty share as a decimal (for example, `0.05` for 5%). Use `0`.             |

### Step 2: Deploy the smart contract

Deploy by making a request to
[`POST /templates/{id}/deploy`](/api-reference/contracts/smart-contract-platform/deploy-contract-template):

<CodeGroup>
  ```javascript Node.js theme={null}
  import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
  import { initiateSmartContractPlatformClient } from "@circle-fin/smart-contract-platform";

  const circleDeveloperSdk = initiateDeveloperControlledWalletsClient({
    apiKey: "<API_KEY>",
    entitySecret: "<ENTITY_SECRET>",
  });

  const circleContractSdk = initiateSmartContractPlatformClient({
    apiKey: "<API_KEY>",
    entitySecret: "<ENTITY_SECRET>",
  });

  const response = await circleContractSdk.deployContractTemplate({
    id: "aea21da6-0aa2-4971-9a1a-5098842b1248",
    blockchain: "ARC-TESTNET",
    name: "MyERC1155Contract",
    walletId: "<WALLET_ID>",
    templateParameters: {
      name: "MyERC1155Contract",
      defaultAdmin: "<WALLET_ADDRESS>",
      primarySaleRecipient: "<WALLET_ADDRESS>",
      royaltyRecipient: "<WALLET_ADDRESS>",
      royaltyPercent: 0,
    },
    fee: {
      type: "level",
      config: {
        feeLevel: "MEDIUM",
      },
    },
  });
  ```

  ```python Python theme={null}
  from circle.web3 import utils, developer_controlled_wallets, smart_contract_platform

  client = utils.init_developer_controlled_wallets_client(
      api_key="<API_KEY>",
      entity_secret="<ENTITY_SECRET>"
  )

  scpClient = utils.init_smart_contract_platform_client(
      api_key="<API_KEY>",
      entity_secret="<ENTITY_SECRET>"
  )

  api_instance = smart_contract_platform.TemplatesApi(scpClient)

  request = smart_contract_platform.TemplateContractDeploymentRequest.from_dict({
      "blockchain": "ARC-TESTNET",
      "name": "MyERC1155Contract",
      "walletId": "<WALLET_ID>",
      "templateParameters": {
          "name": "MyERC1155Contract",
          "defaultAdmin": "<WALLET_ADDRESS>",
          "primarySaleRecipient": "<WALLET_ADDRESS>",
          "royaltyRecipient": "<WALLET_ADDRESS>",
          "royaltyPercent": "0",
      },
      "feeLevel": "MEDIUM"
  })

  request.template_parameters["royaltyPercent"] = 0

  response = api_instance.deploy_contract_template("aea21da6-0aa2-4971-9a1a-5098842b1248", request)
  ```

  ```shell cURL theme={null}
  curl --request POST \
    --url 'https://api.circle.com/v1/w3s/templates/aea21da6-0aa2-4971-9a1a-5098842b1248/deploy' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header 'authorization: Bearer <API_KEY>' \
    --data '{
      "idempotencyKey": "<IDEMPOTENCY_KEY>",
      "blockchain": "ARC-TESTNET",
      "name": "MyERC1155Contract",
      "walletId": "<WALLET_ID>",
      "templateParameters": {
        "name": "MyERC1155Contract",
        "defaultAdmin": "<WALLET_ADDRESS>",
        "primarySaleRecipient": "<WALLET_ADDRESS>",
        "royaltyRecipient": "<WALLET_ADDRESS>",
        "royaltyPercent": 0
      },
      "feeLevel": "MEDIUM",
      "entitySecretCiphertext": "<ENTITY_SECRET_CIPHERTEXT>"
    }'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "contractIds": ["b7c35372-ce69-4ccd-bfaa-504c14634f0d"],
    "transactionId": "601a0815-f749-41d8-b193-22cadd2a8977"
  }
}
```

<Note>
  A successful response indicates deployment has been **initiated**, not
  completed. Use the `transactionId` to check status.
</Note>

#### 2.1. Check deployment status

Verify deployment with
[`GET /transactions/{id}`](/api-reference/wallets/developer-controlled-wallets/get-transaction):

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await circleDeveloperSdk.getTransaction({
    id: "601a0815-f749-41d8-b193-22cadd2a8977",
  });
  ```

  ```python Python theme={null}
  api_instance = developer_controlled_wallets.TransactionsApi(client)
  response = api_instance.get_transaction(id="601a0815-f749-41d8-b193-22cadd2a8977")
  ```

  ```shell cURL theme={null}
  curl --request GET \
    --url 'https://api.circle.com/v1/w3s/transactions/601a0815-f749-41d8-b193-22cadd2a8977' \
    --header 'accept: application/json' \
    --header 'authorization: Bearer <API_KEY>'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "transaction": {
      "id": "601a0815-f749-41d8-b193-22cadd2a8977",
      "blockchain": "ARC-TESTNET",
      "state": "COMPLETE"
    }
  }
}
```

### Step 3: Mint a token

Use the `mintTo` function to mint tokens. The wallet must have `MINTER_ROLE`.

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await circleDeveloperSdk.createContractExecutionTransaction({
    walletId: "<WALLET_ID>",
    abiFunctionSignature: "mintTo(address,uint256,string,uint256)",
    abiParameters: [
      "<WALLET_ADDRESS>",
      "115792089237316195423570985008687907853269984665640564039457584007913129639935",
      "ipfs://bafkreibdi6623n3xpf7ymk62ckb4bo75o3qemwkpfvp5i25j66itxvsoei",
      "1",
    ],
    contractAddress: "<CONTRACT_ADDRESS>",
    fee: {
      type: "level",
      config: {
        feeLevel: "MEDIUM",
      },
    },
  });
  ```

  ```python Python theme={null}
  api_instance = developer_controlled_wallets.TransactionsApi(client)

  request = developer_controlled_wallets.CreateContractExecutionTransactionForDeveloperRequest.from_dict({
      "walletId": "<WALLET_ID>",
      "abiFunctionSignature": "mintTo(address,uint256,string,uint256)",
      "abiParameters": [
          "<WALLET_ADDRESS>",
          "115792089237316195423570985008687907853269984665640564039457584007913129639935",
          "ipfs://bafkreibdi6623n3xpf7ymk62ckb4bo75o3qemwkpfvp5i25j66itxvsoei",
          "1"
      ],
      "contractAddress": "<CONTRACT_ADDRESS>",
      "feeLevel": "MEDIUM",
  })

  response = api_instance.create_developer_transaction_contract_execution(request)
  ```

  ```shell cURL theme={null}
  curl --request POST \
    --url 'https://api.circle.com/v1/w3s/developer/transactions/contractExecution' \
    --header 'authorization: Bearer <API_KEY>' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{
      "abiFunctionSignature": "mintTo(address,uint256,string,uint256)",
      "abiParameters": [
        "<WALLET_ADDRESS>",
        "115792089237316195423570985008687907853269984665640564039457584007913129639935",
        "ipfs://bafkreibdi6623n3xpf7ymk62ckb4bo75o3qemwkpfvp5i25j66itxvsoei",
        "1"
      ],
      "idempotencyKey": "<IDEMPOTENCY_KEY>",
      "contractAddress": "<CONTRACT_ADDRESS>",
      "feeLevel": "MEDIUM",
      "walletId": "<WALLET_ID>",
      "entitySecretCiphertext": "<ENTITY_SECRET_CIPHERTEXT>"
    }'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "id": "601a0815-f749-41d8-b193-22cadd2a8977",
    "state": "INITIATED"
  }
}
```

Check the transaction status using
[`GET /transactions/{id}`](/api-reference/wallets/developer-controlled-wallets/get-transaction)
as shown above.

***

## Summary

After completing this quickstart, you've successfully:

* Deployed an ERC-1155 Multi-Token contract on Arc Testnet
* Minted your first token using either the Console or API

## Next steps

* Explore the [Templates Glossary](/contracts/scp-templates-overview) for other
  contract templates
* Learn about [Gas Station](/wallets/gas-station) for sponsoring transactions
* View your contract on the [Arc Testnet Explorer](https://testnet.arcscan.app/)


# Multi-Token Template
Source: https://developers.circle.com/contracts/erc-1155-multi-token



The Multi-Token template is an audited, ready-to-deploy smart contract for the
ERC-1155 multi-token standard. ERC-1155 is a versatile token standard that
allows for creating and managing multiple types of tokens within a single smart
contract. Unlike other token standards, like ERC-20 and ERC-721, ERC-1155
supports fungible and non-fungible tokens, providing flexibility for various use
cases.

The ERC-1155 standard enables the creation of tokens representing different
types of assets, such as digital collectibles, in-game items, unique artwork,
and more, all within the same contract. This reduces the need to deploy separate
contracts for different token types, improving efficiency and reducing costs.

Some use cases of the standard include:

* **Gaming assets:** With ERC-1155, developers can create game assets that can
  be fungible or non-fungible. For example, fungible ERC-1155 tokens can
  represent in-game currencies, while non-fungible ERC-1155 tokens can represent
  unique weapons, characters, or virtual land.

* **Digital collectibles:** Similar to ERC-721, ERC-1155 can be used to create
  and trade digital collectibles. However, ERC-1155 offers additional
  flexibility, allowing for the creation of fungible and non-fungible tokens
  under the same contract. This enables the creation of collections with varying
  levels of scarcity and uniqueness.

* **Tokenized real-world assets:** ERC-1155 tokens can also represent ownership
  of real-world assets such as real estate or shares in a company. By combining
  fungible and non-fungible tokens, ERC-1155 offers a more efficient solution
  for fractional ownership of assets.

* **Batch operations:** One of the significant advantages of ERC-1155 is the
  ability to perform batch operations. Developers can transfer multiple tokens
  in a single transaction, making it more cost-efficient and reducing gas fees.

In this comprehensive guide, you explore the Multi-Token template, which
provides all the necessary information to deploy and understand the contract's
common functions.

## Deployment parameters

The Multi-Token template creates a smart contract representing and controlling
any number of token types. These tokens can of the ERC-20, ERC-721 or any other
standard. To create a contract using this template, provide the following
parameter values when deploying a smart contract template using the
[`POST: /templates/{id}/deploy`](/api-reference/contracts/smart-contract-platform/deploy-contract-template)
API.

**Template ID:** aea21da6-0aa2-4971-9a1a-5098842b1248

### Template deployment parameters

| Parameter              | Type      | Required | Description                                                                                                                                             |
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                 | String    | X        | Name of the contract - stored on-chain.                                                                                                                 |
| `symbol`               | String    |          | Symbol of the token - stored onchain. The symbol is usually 3 or 4 characters in length.                                                                |
| `defaultAdmin`         | String    | X        | The address of the default admin. This address can execute permissioned functions on the contract.                                                      |
| `primarySaleRecipient` | String    | X        | The recipient address for first-time sales.                                                                                                             |
| `platformFeeRecipient` | String    |          | The recipient address for all sale fees.                                                                                                                |
| `platformFeePercent`   | Float     |          | The percentage of sales that go to the platform fee recipient. For example, set it as 0.1 if you want 10% of sales fees to go to platformFeeRecipient.  |
| `royaltyRecipient`     | String    | X        | The recipient address for all royalties (secondary sales). This allows the contract creator to benefit from further sales of the contract token.        |
| `royaltyPercent`       | Float     | X        | The percentage of secondary sales that go to the royalty recipient. For example, set it as 0.05 if you want royalties to be 5% of secondary sales.      |
| `contractUri`          | String    |          | The URL for the marketplace metadata of your contract.                                                                                                  |
| `trustedForwarders`    | String\[] |          | A list of addresses that can forward ERC2771 meta-transactions to this contract.                                                                        |

Here is an example of the `templateParameters`JSON object within the request
body to
[deploy a contract from a template](/api-reference/contracts/smart-contract-platform/deploy-contract-template)
for the ERC-1155 Multi-Token template.

<Note>
  In this example, the `defaultAdmin`, `primarySaleRecipient`, and
  `royaltyRecipient` parameters are the same address but can be set distinctly
  based on your use case.
</Note>

```json JSON theme={null}
...

"templateParameters": {
  "name": "My Multi-Token Contract",
  "defaultAdmin": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6",
  "primarySaleRecipient": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6",
  "royaltyRecipient": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6",
  "royaltyPercent": 0.05
}
```

## Common functions

This section lists the most commonly used functions on the Multi-Token template,
along with their respective parameters and potential failure scenarios. These
functions include:

* [mintTo \[write\]](#mintto-write)

* [safeTransferFrom \[write\]](#safetransferfrom-write)

* [setApprovalForAll \[write\]](#setapprovalforall-write)

* [setTokenURI \[write\]](#settokenuri-write)

* [burn \[write\]](#burn-write)

* [safeBatchTransferFrom \[write\]](#safebatchtransferfrom-write)

* [balanceOfBatch \[read\]](#balanceofbatch-read)

* [balanceOf \[read\]](#balanceof-read)

* [nextTokenIdToMint \[read\]](#nexttokenidtomint-read)

* [uri \[read\]](#uri-read)

<Note>
  At this time, not all failure scenarios or error messages received from the
  blockchain are passed through Circle's APIs. Instead, you will receive a
  generic [`ESTIMATION_ERROR`](/contracts/error-codes#transaction-errors) error.
  If available, the `errorDetails` field will have more information on the cause
  of failure.
</Note>

## mintTo \[write]

The `mintTo` function allows you to create new NFTs or increase the supply of
existing NFTs. It is a flexible function that can cater to both scenarios.

### Parameters

| Parameter  | Type     | Description                                                                                                                                                                                   |
| :--------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_to`      | address  | The address to which the newly minted NFT will be assigned.                                                                                                                                   |
| `_tokenId` | unit256  | The unique identifier for the NFT. If the value is set to `type(uint256).max`, the function will assign the next available token ID. Otherwise, it will assign the provided `_tokenId` value. |
| `_uri`     | calldata | The Uniform Resource Identifier (URI) for the NFT's metadata. It specifies the location from where the metadata can be retrieved.                                                             |
| `_amount`  | unit256  | The amount of the newly minted NFTs to be assigned.                                                                                                                                           |

### Failure scenarios

* **Insufficient Role:** The `mintTo` function is defined with the
  `onlyRole(MINTER\_ROLE)` modifier, meaning only addresses with the
  `MINTER\_ROLE` can call this function. The function will revert and fail if
  the caller does not have the necessary role.
* **Token ID Overflow:** If the `_tokenId` parameter is set to
  `type(uint256).max` (the maximum value for a uint256), the function will
  attempt to create a new token and assign the next available token ID. However,
  an overflow can occur if the `nextTokenIdToMint` variable has reached its
  maximum value. This overflow condition will cause the function to fail.
* **Invalid Token ID:** If the `_tokenId` parameter is not set to
  `type(uint256).max`, the function will attempt to mint an NFT with the
  specified token ID. However, if the provided `_tokenId` value is greater than
  or equal to the value of `nextTokenIdToMint`, the function will revert and
  fail with the following error message.\
  *"invalid id"*
* **Existing Token ID with Non-Empty URI:** When `_tokenId` is provided and
  already exists, the function checks whether the associated metadata URI for
  that token ID is empty. If the URI is not empty, the token has already been
  minted and has an associated URI. In this case, the function will fail and
  revert, preventing the same token ID from being minted multiple times.
* **Minting to Zero Address:** The function checks whether the `_to` address is
  the zero address `address(0)`. Minting tokens to the zero address is
  prohibited, as it represents an invalid or non-existent address. If `_to` is
  the zero address, the function will fail and revert with the following error
  message.\
  *"ERC1155: mint to the zero address"*
* **Rejection by ERC1155Receiver Contract:** If the recipient address `_to` is a
  contract, the function will attempt to call the `onERC1155Received` function
  of that contract to check if the contract supports receiving the NFT. If the
  contract's `onERC1155Received` function rejects the transfer by returning a
  value other than `IERC1155ReceiverUpgradeable.onERC1155Received.selector`, the
  function will revert and fail with the following error message.\
  \_ "ERC1155: ERC1155Receiver rejected tokens"\_

### Notes

* **Creating New NFTs:** When you pass `type(uint256).max` via the `_tokenId`
  parameter, the function will create a new NFT with `_tokenId` equal to
  `nextTokenIdToMint` and assign it to the specified `_to` address. The `_uri`
  parameter allows you to provide the metadata URI for the newly created NFT.
  The `amount` parameter allows you to specify how many instances of this NFT
  with the given ID should be minted.
* **Increasing Supply of Existing NFTs:** If you pass an existing token ID via
  the `tokenId` parameter, the function will increase the supply of that
  specific NFT. Instead of creating a new token ID, the function will mint
  additional instances of the existing NFT, adding to the current supply. Again,
  the `_amount` parameter determines how many additional instances of the NFT
  should be minted.

```solidity Solidity theme={null}
// Lets an account with MINTER_ROLE mint an NFT.
function mintTo(
  address _to,
  uint256 _tokenId,
  string calldata _uri,
  uint256 _amount
) external onlyRole(MINTER_ROLE) {
  uint256 tokenIdToMint;
  if (_tokenId == type(uint256).max) {
    tokenIdToMint = nextTokenIdToMint;
    nextTokenIdToMint += 1;
  } else {
    require(_tokenId < nextTokenIdToMint, "invalid id");
    tokenIdToMint = _tokenId;
  }

  // `_mintTo` is re-used. `mintTo` just adds a minter role check.
  _mintTo(_to, _uri, tokenIdToMint, _amount);
}
```

## safeTransferFrom \[write]

The `safeTransferFrom` function allows for transferring a specified amount of a
particular token ID from one address `from` to another address `to`.

### Parameters

| Parameter | Type    | Description                                                                                                                                                  |
| :-------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`    | address | The address of the current token owner, from whom the tokens will be transferred.                                                                            |
| `to`      | address | The address of the recipient who will receive the transferred tokens.                                                                                        |
| `id`      | uint256 | The unique identifier for transferring the token.                                                                                                            |
| `amount`  | uint256 | The amount of tokens being transferred. This represents the number of tokens to be transferred.                                                              |
| `data`    | bytes   | Optional additional data to pass to the receiver contract if it is a contract. This can include custom arguments or instructions for the receiving contract. |

### Failure scenarios

* **Transfer to Zero Address:** The function verifies if the to address is the
  zero address `address(0)`. Transfers to the zero address are not permitted, as
  it represents an invalid or non-existent address. If the `to` address is the
  zero address, the function fails and reverts with the following error
  message.\
  *"ERC1155: transfer to the zero address"*
* **Insufficient Balance:** The function checks if the from address has a
  sufficient balance of the specified token ID (id) to perform the transfer. If
  the balance exceeds the specified amount, the function fails and reverts to
  the following error message.\
  *"ERC1155: insufficient balance for transfer"*
* **Caller Not Authorized:** The function verifies if the caller of the
  `_msgSender()` function is either the owner of the tokens (`from`) or has been
  approved as an operator for `from`. If the caller is neither the token owner
  nor an approved operator, the function fails and reverts with the following
  error message.\
  *"ERC1155: caller is not token owner or approved"*
* **Before/After Token Transfer Hooks:** The function calls the
  `_beforeTokenTransfer` and `_afterTokenTransfer` hooks to update any necessary
  state or perform additional checks. These hooks may contain custom business
  logic that can cause the transfer to fail if certain conditions are not met.
* **ERC1155Receiver Contract Rejection:** If the `to` address is a contract, the
  function attempts to call the `onERC1155Received` function of that contract to
  check if the contract supports receiving the tokens. If the contract's
  `onERC1155Received` function rejects the transfer by returning a value other
  than `IERC1155ReceiverUpgradeable.onERC1155Received.selector`, the function
  fails and reverts with the following error message.\
  *"ERC1155: ERC1155Receiver rejected tokens"*

```solidity Solidity theme={null}
// See IERC1155-safeTransferFrom.
function safeTransferFrom(
  address from,
  address to,
  uint256 id,
  uint256 amount,
  bytes memory data
) public virtual override {
  require(
    from == _msgSender() || isApprovedForAll(from, _msgSender()),
    "ERC1155: caller is not token owner or approved"
  );
  _safeTransferFrom(from, to, id, amount, data);
}
```

## setApprovalForAll \[write]

The `setApprovalForAll` function is used to set the approval status for an
operator to manage all tokens of the caller (owner) on their behalf.

### Parameters

| Parameter  | Type    | Description                                                                                                                              |
| :--------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `operator` | address | The operator's address for whom the approval status is set. The operator will be able to manage all tokens owned by the caller.          |
| `approved` | bool    | The boolean value indicates whether the operator is approved (true) or disapproved (false) to manage all tokens on behalf of the caller. |

### Failure scenarios

* The function requires that the caller (owner) cannot set the approval status
  for themselves. If the operator address provided is the same as the owner
  address, the function will fail with the given following error message.\
  *"ERC1155: setting approval status for self"*

### Notes

* Once an operator is approved using the `setApprovalForAll` function, they can
  act on behalf of the token owner. This includes performing actions such as
  transferring tokens.

```solidity Solidity theme={null}
// See {IERC1155-setApprovalForAll}.
function setApprovalForAll(address operator, bool approved) public virtual override {
  _setApprovalForAll(_msgSender(), operator, approved);
}


// Approve `operator` to operate on all of `owner` tokens
// Emits an {ApprovalForAll} event.
function _setApprovalForAll(address owner, address operator, bool approved) internal virtual {
  require(owner != operator, "ERC1155: setting approval status for self");
  _operatorApprovals[owner][operator] = approved;
  emit ApprovalForAll(owner, operator, approved);
}
```

## setTokenURI \[write]

The `setTokenURI` function is used to set the metadata URI for a given NFT.

### Parameters

| Parameter | Type    | Description                                                                  |
| :-------- | :------ | :--------------------------------------------------------------------------- |
| `tokenId` | unit256 | The unique identifier of the NFT for which the metadata URI needs to be set. |
| `uri`     | string  | The URI string represents the metadata's location associated with the NFT.   |

### Failure scenarios

* The function requires the metadata URI to have a length greater than zero.
  This error occurs when the input parameter `_uri` is an empty string.\
  \_"NFTMetadata: empty metadata" \_
* This error occurs if the `_canSetMetadata()` function returns false. It
  indicates that the caller has no authority or permission to set the metadata
  for the given NFT.\
  *"NFTMetadata: not authorized to set metadata"*
* This error occurs when `uriFrozen` is true, indicating that the metadata is
  frozen and cannot be updated.\
  *"NFTMetadata: metadata is frozen"*

```solidity Solidity theme={null}
// Sets the metadata URI for a given NFT.
function setTokenURI(uint256 _tokenId, string memory _uri) public virtual {
  require(_canSetMetadata(), "NFTMetadata: not authorized to set metadata.");
  require(!uriFrozen, "NFTMetadata: metadata is frozen.");
  _setTokenURI(_tokenId, _uri);
}

// Sets the metadata URI for a given NFT.
function _setTokenURI(uint256 _tokenId, string memory _uri) internal virtual {
  require(bytes(_uri).length > 0, "NFTMetadata: empty metadata.");
  _tokenURI[_tokenId] = _uri;

  emit MetadataUpdate(_tokenId);
}
```

## burn \[write]

This function allows a token owner to burn a specified amount (value) of tokens
they own.

### Parameters

| Parameter | Type    | Description                                                    |
| :-------- | :------ | :------------------------------------------------------------- |
| `account` | address | The address of the token owner who wants to burn their tokens. |
| `id`      | unit256 | The unique identifier of the token to be burned.               |
| `value`   | unit256 | The amount of tokens to be burned.                             |

### Failure scenarios

* This error occurs when the caller of the burn function is neither the owner of
  the tokens nor approved to burn them. The caller must either be the account
  that owns the tokens or have approval from the owner to burn the tokens.\
  \_"ERC1155: caller is not owner nor approved" \_
* The function checks that the burning amount does not exceed the available
  balance. This error occurs if the amount of tokens specified to be burned
  (`amount`) is greater than the balance of tokens (`fromBalance`) owned by the
  specified account.\
  *"ERC1155: burn amount exceeds balance"*
* This error occurs if the from address (the address from which the tokens are
  being burned) is the zero address (0x000...). This address is generally
  reserved as an invalid or non-existent address and cannot be used for token
  burning.\
  *"ERC1155: burn from the zero address"*

```solidity Solidity theme={null}
// Lets a token owner burn the tokens they own (i.e. destroy for good)
function burn(address account, uint256 id, uint256 value) public virtual {
  require(
    account == _msgSender() || isApprovedForAll(account, _msgSender()),
    "ERC1155: caller is not owner nor approved."
  );

  _burn(account, id, value);
}
```

## safeBatchTransferFrom \[write]

This function enables the safe transfer of multiple ERC1155 tokens from one
address (`from`) to another address (`to`) in a batch.

### Parameters

| Parameter | Type       | Description                                                                            |
| :-------- | :--------- | :------------------------------------------------------------------------------------- |
| `from`    | address    | The address from which the tokens are transferred.                                     |
| `to`      | address    | The address to which the tokens are transferred.                                       |
| `ids`     | uint256\[] | An array of unique identifiers of the tokens to be transferred.                        |
| `amounts` | uint256\[] | An array specifying the corresponding amounts of tokens to be transferred for each ID. |
| `data`    | bytes      | Additional data to pass along with the transfer. Optional parameter.                   |

### Failure scenarios

* This error occurs if the caller of the function is neither the token owner nor
  approved to perform the transfer. The caller must either be the from address
  or have approval from the from address to transfer the tokens.\
  *"ERC1155: caller is not token owner or approved"*
* This error occurs if the lengths of the `ids` and amounts arrays do not match.
  Each ID should have a corresponding amount to be transferred. The arrays
  should have the same length.\
  *"ERC1155: ids and amounts length mismatch"*
* This error occurs if the `to` address is the zero address (0x000...).
  Transferring tokens to the zero address is not allowed as it is generally used
  to represent an invalid or non-existent address.\
  *"ERC1155: transfer to the zero address"*
* This error occurs if the from address does not have a sufficient balance of
  tokens to transfer. The function checks that the from address has enough
  tokens of each ID to fulfill the transfer.\
  *"ERC1155: insufficient balance for transfer"*
* This error occurs if the to address is a contract and the contract does not
  implement the `onERC1155BatchReceived` function from the
  `IERC1155ReceiverUpgradeable` interface or if the function returns a value
  other than `onERC1155BatchReceived.selector`. This check ensures that the
  receiving contract can handle the transferred tokens properly.\
  *"ERC1155: ERC1155Receiver rejected tokens"*

```solidity Solidity theme={null}
// IERC1155-safeBatchTransferFrom
function safeBatchTransferFrom(
  address from,
  address to,
  uint256[] memory ids,
  uint256[] memory amounts,
  bytes memory data
) public virtual override {
    require(
        from == _msgSender() || isApprovedForAll(from, _msgSender()),
        "ERC1155: caller is not token owner or approved"
    );
    _safeBatchTransferFrom(from, to, ids, amounts, data);
}
```

## balanceOfBatch \[read]

The `balanceOfBatch` function retrieves the balances of multiple accounts for
multiple token IDs in a single function call.

### Parameters

| Parameter  | Type       | Description                                                                |
| :--------- | :--------- | :------------------------------------------------------------------------- |
| `accounts` | address\[] | An array of addresses representing the accounts to query the balances for. |
| `ids`      | unit256\[] | An array of unique identifiers of the tokens to query the balances for.    |

### Failure scenarios

* **Mismatched Array Lengths:** The function requires that the length of the
  accounts array is equal to the length of the `ids` array. If this condition is
  not met, it will throw a required exception with the following error
  message.\
  *"ERC1155: accounts and ids length mismatch"*

```solidity Solidity theme={null}
// IERC1155-balanceOfBatch
// Requirements:
// `accounts` and `ids` must have the same length.
function balanceOfBatch(
  address[] memory accounts,
  uint256[] memory ids
) public view virtual override returns (uint256[] memory) {
  require(accounts.length == ids.length, "ERC1155: accounts and ids length mismatch");

  uint256[] memory batchBalances = new uint256[](accounts.length);

  for (uint256 i = 0; i < accounts.length; ++i) {
    batchBalances[i] = balanceOf(accounts[i], ids[i]);
  }

  return batchBalances;
}
```

## balanceOf \[read]

The `balanceOf` function retrieves the balance of a specific account for a
particular token ID.

### Parameters

| Parameter | Type    | Description                                                         |
| :-------- | :------ | :------------------------------------------------------------------ |
| `account` | address | The EVM address for which the balance is being queried.             |
| `id`      | unit256 | The unique token identifier for which the balance is being queried. |

### Failure scenarios

* **Zero Address:** The function requires that the account parameter is not set
  to the zero address `address(0)`. If this condition is not met, it will throw
  a required exception with the following error message.\
  *"ERC1155: address zero is not a valid owner".*

```solidity Solidity theme={null}
// See IERC1155-balanceOf
// Requirements:
// account cannot be the zero address.
function balanceOf(address account, uint256 id) public view virtual override returns (uint256) {
  require(account != address(0), "ERC1155: address zero is not a valid owner");
  return _balances[id][account];
}
```

## uri \[read]

The URI function retrieves the associated URI with a specific token ID. This URI
provides a way to access metadata and additional information about the token.

### Parameters

| Parameter | Type    | Description                                                 |
| :-------- | :------ | :---------------------------------------------------------- |
| `tokenId` | unit256 | This is the unique token identifier for retrieving the URI. |

```solidity Solidity theme={null}
// Returns the URI for a tokenId
function uri(uint256 _tokenId) public view override returns (string memory) {
  return _tokenURI[_tokenId];
}
```

## Public Variables

Public variables are accessible from within the contract and can be accessed
from external contracts. Solidity automatically generates a getter function for
public state variables.

## nextTokenIdToMint \[read]

The `nextTokenIdToMint` variable is a public constant on the smart contract. An
unsigned integer (uint256) represents the next token ID minted or created when
`type(uint256).max` is passed to the `mintTo` function.

```solidity Solidity theme={null}
// The next token ID of the NFT to mint.
uint256 public nextTokenIdToMint;
```


# Token Template
Source: https://developers.circle.com/contracts/erc-20-token



The Token template is an audited, ready-to-deploy smart contract for an ERC-20
token. The ERC-20 standard is the most popular standard for fungible tokens. The
token's fungibility allows it to be used for a variety of use cases, including:

* **Stablecoins:** ERC-20 tokens serve as the foundation for stablecoins like
  USDC, backed by US dollars. To learn more about the USDC contract, see
  [0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48](https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
  on Etherscan.

* **Loyalty points:** ERC-20 tokens can represent on-chain loyalty points to
  incentivize and reward users for their activities within a platform or
  ecosystem.

* **Governance:** ERC-20 tokens can represent governance rights, allowing
  holders to participate in protocol decisions. Notable examples include tokens
  utilized by platforms like Uniswap.

* **Ownership:** ERC-20 tokens can also represent fractional ownership in
  real-world assets, such as houses, ounces of gold, or company shares.

In this comprehensive guide, you explore the Token template, which provides all
the necessary information to deploy and understand the contract's common
functions.

## Deployment parameters

The Token template creates a customized, fully compliant ERC-20 smart contract.
To create a contract using this template, provide the following parameter values
when deploying a smart contract template using the
[`POST: /templates/{id}/deploy`](/api-reference/contracts/smart-contract-platform/deploy-contract-template)
API.

**Template ID:** a1b74add-23e0-4712-88d1-6b3009e85a86

### Template deployment parameters

| Parameter              | Type       | Required | Description                                                                                                                                                                                                               |
| ---------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                 | String     | X        | Name of the contract - stored as a property of the contract on-chain.                                                                                                                                                     |
| `symbol`               | String     |          | Symbol of the token - stored on-chain. The symbol is usually 3 or 4 characters in length.                                                                                                                                 |
| `defaultAdmin`         | String     | X        | The address of the default admin. This address can execute permissioned functions on the contract. <br />**Important:** You will lose administrative access to the contract if this is not set to an address you control. |
| `primarySaleRecipient` | String     | X        | The recipient address for first-time sales.                                                                                                                                                                               |
| `platformFeeRecipient` | String     |          | The recipient address for all sales fees. If you deploy a template on someone else's behalf, you can set this to your own address.                                                                                        |
| `platformFeePercent`   | Float      |          | The percentage of sales that go to the platform fee recipient. For example, set it as 0.1 if you want 10% of sales fees to go to the  `platformFeeRecipient`.                                                             |
| `contractUri`          | String     |          | The URL for the marketplace metadata of your contract. This is used on marketplaces like OpenSea. See [Contract-level Metadata](https://docs.opensea.io/docs/contract-level-metadata) for more information.               |
| `trustedForwarders`    | Strings\[] |          | A list of addresses that can forward ERC2771 meta-transactions to this contract. See [ethereum.org](https://eips.ethereum.org/EIPS/eip-2771) for more information.                                                        |

Here is an example of the `templateParameters` JSON object within the request
body to
[deploy a contract from a template](/api-reference/contracts/smart-contract-platform/deploy-contract-template)
for the ERC-20 Token template.

<Note>
  In this example, the `defaultAdmin` and `primarySaleRecipient` parameters are
  the same address but can be set distinctly based on your use case.
</Note>

```json JSON theme={null}
"templateParameters": {
  "name": "My Token Contract",
  "defaultAdmin": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6",
  "primarySaleRecipient": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6"
}
```

## Common functions

This section lists the most commonly used functions on the Token template, their
respective parameters and potential failure scenarios. These functions include:

* [approve \[write\]](#approve-write)

* [transfer \[write\]](#transfer-write)

* [mintTo \[write\]](#mintto-write)

* [burn \[write\]](#burn-write)

* [grantRole \[write\]](#grantrole-write)

* [revokeRole \[write\]](#revokerole-write)

* [balanceOf \[read\]](#balanceof-write)

* [allowance \[read\]](#allowance-write)

<Note>
  At this time, not all failure scenarios or error messages received from the
  blockchain are passed through Circle's APIs. Instead, you will receive a
  generic [`ESTIMATION_ERROR`](/contracts/error-codes#transaction-errors) error.
  If available, the `errorDetails` field will have more information on the cause
  of failure.
</Note>

## approve \[write]

The `approve` function lets token owners specify a limit on the number of tokens
another account address can spend on their behalf.

### Parameters

| Parameter | Type    | Description                                                                                                                                               |
| :-------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spender` | address | The owner approves the account address to spend tokens. It could be another smart contract address or an externally owned account address.                |
| `amount`  | unit256 | The number of tokens the owner approves for spending by the specified spender. The amount should be set in the smallest denomination of the ERC-20 token. |

### Failure scenarios

* The approve function fails if the `spender` is the zero address.\
  *"ERC20: approve to the zero address"*

### Notes

* If `amount` is the maximum uint256 value the allowance is not updated when the
  `transferFrom` function is called. This is semantically equivalent to an
  infinite approval.

* There is no balance check on the `approve` function so token owners may
  approve allowances greater than their current balance.

```solidity Solidity theme={null}
function approve(address spender, uint256 amount) public virtual override returns (bool) {
  address owner = _msgSender();
  _approve(owner, spender, amount);
  return true;
}
```

## transfer \[write]

Allows the token owner to transfer a specified number of tokens to another
account address.

### Parameters

| Parameter | Type    | Description                                                                                                         |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------ |
| `to`      | address | The address to which the token will be transferred. This can be another user's address or a smart contract address. |
| `amount`  | unit256 | The number of tokens to transfer.                                                                                   |

### Failure scenarios

* The `to` address parameter is checked to ensure it is not the zero address
  `address(0)`.\
  *"ERC20: transfer to the zero address"*
* The `beforeTokenTransfer` hook is called, which checks `TOKEN_TRANSFER`
  permissions.\
  "restricted to TRANSFER\_ROLE holders”
* The token owner doesn't have a sufficient balance to transfer the specified
  token amount.\
  *"ERC20: transfer amount exceeds balance"*

```solidity Solidity theme={null}
function transfer(address to, uint256 amount) public virtual override returns (bool) {
  address owner = _msgSender();
  _transfer(owner, to, amount);
  return true;
}
```

## mintTo \[write]

A designated minter can create a specified number of tokens and assign them to a
specified account address.

### Parameters

| Parameter | Type    | Description                                                              |
| :-------- | :------ | :----------------------------------------------------------------------- |
| `to`      | address | The address to which the newly minted tokens will be assigned.           |
| `amount`  | unit256 | The number of tokens to be minted and assigned to the specified address. |

### Failure scenarios

* The function checks if the caller has the `MINTER_ROLE`. The function will
  fail if the caller does not have the minter role. Expect to see the following
  error:\
  *"not minter."*
* The function ensures that the account address is not the zero address
  `address(0)`, as this is an invalid address to mint tokens to.\
  *"ERC20: mint to the zero address"*
* The `beforeTokenTransfer` hook is called, which checks `TOKEN_TRANSFER`
  permissions.\
  *"restricted to* TRANSFER*ROLE \_holders”*

```solidity Solidity theme={null}
function mintTo(address to, uint256 amount) public virtual {
  require(hasRole(MINTER_ROLE, _msgSender()), "not minter.");
  _mintTo(to, amount);
}
```

## burn \[write]

Allows a token holder to burn (destroy) a specified number of the token total
supply.

### Parameters

| Parameter | Type    | Description                        |
| :-------- | :------ | :--------------------------------- |
| `amount`  | unit256 | The number of tokens to be burned. |

### Failure scenarios

* The `_beforeTokenTransfer`  hook is called, which checks `TOKEN_TRANSFER`
  permissions.\
  *"restricted to TRANSFER\_ROLE holders”*
* The token owner has no sufficient balance to burn the specified token
  amount.\
  *"ERC20: burn amount exceeds balance"*

```solidity Solidity theme={null}
function burn(uint256 amount) public virtual {
  _burn(_msgSender(), amount);
}
```

### Permissions and roles

Roles are referred to by their `bytes32` identifier. For example:

```solidity Solidity theme={null}
bytes32 public constant MY_ROLE = keccak256("MY_ROLE");
```

Roles can also represent a set of permissions. To restrict access to a function
call, use `hasRole`:

```solidity Solidity theme={null}
function foo() public {
  require(hasRole(MY_ROLE, msg.sender));
  ...
}
```

Roles can be granted and revoked dynamically via the `grantRole` and
`revokeRole` functions. Each role has an associated admin role, and only
accounts that have a role's admin role can call `grantRole` and `revokeRole`. By
default, the admin role for all roles is `DEFAULT_ADMIN_ROLE`. Only accounts
with the `DEFAULT_ADMIN_ROLE` can grant or revoke other roles. You can use the
`_setRoleAdmin` function to create more complex role relationships.

## grantRole \[write]

Grants a specified role to an account. Only an account address that has the
admin role assigned can call this function.

### Parameters

| Parameter | Type    | Description                                       |
| :-------- | :------ | :------------------------------------------------ |
| `role`    | bytes32 | The bytes32 identifier of the role to be granted. |
| `account` | address | The address to which the role will be granted.    |

### Failure scenarios

* The `onlyRole(getRoleAdmin(role))` modifier ensures that the function caller
  has the admin role for the specified role. Only addresses with the admin role
  can grant roles to other accounts.\
  *"AccessControl: account ", StringsUpgradeable.toHexString(account), " is
  missing role ", StringsUpgradeable.toHexString(uint256(role), 32)*
* The function checks if the account already has the specified role using the
  `hasRole` function. If the account does not have the role, the function
  continues. There is no error message.

```solidity Solidity theme={null}
function grantRole(bytes32 role, address account) public virtual override onlyRole(getRoleAdmin(role)) {
  _grantRole(role, account);
}
```

## revokeRole \[write]

Revoke the specified role from an account address. Only account addresses with
the admin role assigned can call this function.

### Parameters

| Parameter | Type    | Description                                      |
| :-------- | :------ | :----------------------------------------------- |
| `role`    | bytes32 | The role to be revoked.                          |
| `account` | address | The address from which the role will be revoked. |

### Failure scenarios

* The `onlyRole(getRoleAdmin(role))` modifier ensures that the function caller
  has the admin role for the specified role. Only addresses with the admin role
  can revoke roles from other accounts.\
  *"AccessControl: account ", StringsUpgradeable.toHexString(account), " is
  missing role ", StringsUpgradeable.toHexString(uint256(role), 32)*

```solidity Solidity theme={null}
function revokeRole(bytes32 role, address account) public virtual override onlyRole(getRoleAdmin(role)) {
  _revokeRole(role, account);
}
```

## balanceOf \[read]

Retrieves the balance of tokens owned by a specific account address.

### Parameters

| Parameter | Type    | Description                                               |
| :-------- | :------ | :-------------------------------------------------------- |
| `account` | address | The address for which the token balance is being fetched. |

```solidity Solidity theme={null}
function balanceOf(address account) public view virtual override returns (uint256) {
  return _balances[account];
}
```

## allowance \[read]

Returns the maximum amount the spender is approved to withdraw from the owner's
account. This function retrieves the allowance granted by the owner account
address to the spender account address.

### Parameters

| Parameter | Type    | Description                                           |
| :-------- | :------ | :---------------------------------------------------- |
| `owner`   | address | The address that granted the allowance.               |
| `spender` | address | The address for which the allowance is being fetched. |

```solidity Solidity theme={null}
function allowance(address owner, address spender) public view virtual override returns (uint256) {
  return _allowances[owner][spender];
}

```


# NFT Template
Source: https://developers.circle.com/contracts/erc-721-nft



The NFT template is an audited, ready-to-deploy smart contract for creating and
managing NFTs. It implements the ERC-721 standard, which is widely used for
representing non-fungible tokens (NFTs) on a blockchain. Unlike ERC-20 tokens,
which represent fungible and interchangeable assets, ERC-721 NFTs are unique and
non-interchangeable, making them suitable for digital collectibles, gaming
assets, and many other use cases.

The ERC-721 NFT standard has gained significant popularity and has been
implemented by numerous projects and platforms. Some key use cases for ERC-721
NFTs include:

* **Digital collectibles:** ERC-721 NFTs are extensively used for creating and
  trading unique digital collectibles. These collectibles can represent various
  items such as artwork, trading cards, virtual pets, in-game assets, and more.

* **Tokenized assets:** ERC-721 NFTs can represent ownership in real-world
  assets such as real estate, artwork, jewelry, and other physical assets. This
  enables fractional ownership, providing liquidity and opening up investment
  opportunities.

* **Gaming assets:** ERC-721 NFTs are a perfect fit for representing in-game
  assets, enabling players to own, trade, and transfer virtual items securely
  and transparently. This functionality has facilitated the emergence of
  blockchain-based gaming ecosystems.

In this comprehensive guide, you explore the NFT template, which provides all
the necessary information to deploy and understand the contract's common
functions.

## Deployment parameters

The NFT template creates a customized, fully compliant ERC-721 smart contract.
To create a contract using this template, provide the following parameter values
when deploying a smart contract template using the
[`POST: /templates/{id}/deploy`](/api-reference/contracts/smart-contract-platform/deploy-contract-template)
API.

**Template ID:** 76b83278-50e2-4006-8b63-5b1a2a814533

### Template deployment parameters

|        Parameter       | Type      | Required |                                                                                                  Description                                                                                                 |
| :--------------------: | --------- | :------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|         `name`         | String    |     X    |                                                                    Name of the contract - stored as a property of the contract on-chain.                                                                     |
|        `symbol`        | String    |          |                                                           Symbol of the token - stored onchain. The symbol is usually 3 or 4 characters in length.                                                           |
|     `defaultAdmin`     | String    |     X    |     The address of the default admin. This address can execute permissioned functions on the contract. You will lose administrative access to the contract if this is not set to an address you control.     |
| `primarySaleRecipient` | String    |     X    |                                                                                 The recipient address for first-time sales.                                                                                  |
| `platformFeeRecipient` | String    |          |                                      The recipient address for all sale fees. You can set this to your address if you are deploying a template on someone else's behalf.                                     |
|  `platformFeePercent`  | Float     |          |                           The percentage of sales that go to the platform fee recipient. For example, set it as 0.1 if you want 10% of sales fees to go to *platformFeeRecipient*.                           |
|   `royaltyRecipient`   | String    |     X    |                               The recipient address for all royalties (secondary sales). This allows the contract creator to benefit from further sales of the contract token.                               |
|    `royaltyPercent`    | Float     |     X    |                           The percentage of secondary sales that go to the royalty recipient. For example, set it as 0.05 if you want royalties to be 5% of secondary sales value.                           |
|      `contractUri`     | String    |          | The URL for the marketplace metadata of your contract. This is used on marketplaces like OpenSea. See [Contract-level Metadata](https://docs.opensea.io/docs/contract-level-metadata) for more information.  |
|   `trustedForwarders`  | String\[] |          |                      A list of addresses that can forward ERC2771 meta-transactions to this contract. See [ethereum.org](https://eips.ethereum.org/EIPS/eip-2771) for more information.                      |

Here is an example of the `templateParameters` JSON object within the request
body to
[deploy a contract from a template](/api-reference/contracts/smart-contract-platform/deploy-contract-template)
for the ERC-721 NFT template.

<Note>
  In this example, the `defaultAdmin`, `primarySaleRecipient`, and
  `royaltyRecipient` parameters are the same address but can be set distinctly
  based on your use case.
</Note>

```json JSON theme={null}
...
"templateParameters": {
  "name": "My NFT Contract",
  "defaultAdmin": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6",
  "primarySaleRecipient": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6",
  "royaltyRecipient": "0x4F77E56dfA40990349e1078e97AC3Eb479e0dAc6",
  "royaltyPercent": 0.05
}
```

## Common functions

This section lists the most commonly used functions on NFT template, their
respective parameters and potential failure scenarios. These functions include:

* [approve \[write\]](#approve-write)

* [mintTo \[write\]](#mintto-write)

* [safeTransferFrom \[write\]](#safetransferfrom-write)

* [setTokenURI \[write\]](#settokenuri-write)

* [ownerOf \[read\]](#ownerof-read)

* [balanceOf \[read\]](#balanceof-address-owner-read)

<Note>
  At this time, not all failure scenarios or error messages received from the
  blockchain are passed through Circle's APIs. Instead, you will receive a
  generic [`ESTIMATION_ERROR`](/contracts/error-codes#transaction-errors) error.
  If available, the `errorDetails` field will have more information on the cause
  of failure.
</Note>

## approve \[write]

The approve function allows the owner of an ERC721 NFT to approve another
address to transfer the token on their behalf.

### Parameters

| Parameter | Type    | Description                                              |
| :-------- | :------ | :------------------------------------------------------- |
| `to`      | address | The address approved to transfer the token.              |
| `tokenId` | unit256 | The identifier of the token being approved for transfer. |

**Failure Scenarios:**

* If the *to* address matches the current owner of the token (owner), the
  function will fail. This check ensures that the approval is not granted to the
  same owner, preventing unnecessary approvals. *"ERC721: approval to current
  owner"*
* The function requires that the caller `_msgSender` either be the token's owner
  or have been approved for all by the owner. If this condition is not met, the
  function will fail. This validation prevents unauthorized users from approving
  transfers on behalf of the token owner. *"ERC721: approve caller is not token
  owner or approved for all"*

```solidity Solidity theme={null}
function approve(address to, uint256 tokenId) public virtual override {
  address owner = ERC721Upgradeable.ownerOf(tokenId);
  require(to != owner, "ERC721: approval to current owner");

  require(
    _msgSender() == owner || isApprovedForAll(owner, _msgSender()),
    "ERC721: approve caller is not token owner or approved for all"
  );

  _approve(to, tokenId);
}
```

## mintTo \[write]

The `mintTo` function is a function that mints a new NFT and assigns it to a
specific address. This function can only be called by an address with the
`MINTER_ROLE`.

### Parameters

| Parameter | Type    | Description                                                    |
| :-------- | :------ | :------------------------------------------------------------- |
| `to`      | address | The address to which the minted NFT will be assigned.          |
| `uri`     | string  | The URI (Uniform Resource Identifier) of the newly minted NFT. |

### Returns

| Parameter       |         |                                          |
| :-------------- | :------ | :--------------------------------------- |
| `tokenIdToMint` | uint256 | The unique identifier of the minted NFT. |

### Failure scenarios

* If the caller of the function does not have the `MINTER_ROLE` assigned, the
  function will fail and throw an exception. *"AccessControl: account ",
  StringsUpgradeable.toHexString(account), " is missing role ",
  StringsUpgradeable.toHexString(uint256(role), 32)*
* The function checks if the length of the \_uri string is greater than 0,
  ensuring that the URI is not empty.\
  *"empty uri."*
* *The function checks that the to address is not the zero address.*\
  *"ERC721: mint to the zero address"*
* The function checks that the `tokenId` has not already been created. *"ERC721:
  token already minted"*

```solidity Solidity theme={null}
function mintTo(address _to, string calldata _uri) external onlyRole(MINTER_ROLE) returns (uint256) {
  // `_mintTo` is re-used. `mintTo` just adds a minter role check.
  return _mintTo(_to, _uri);
}

function _mintTo(address _to, string calldata _uri) internal returns (uint256 tokenIdToMint) {
  tokenIdToMint = nextTokenIdToMint;
  nextTokenIdToMint += 1;

  require(bytes(_uri).length > 0, "empty uri.");
  _setTokenURI(tokenIdToMint, _uri);

  _safeMint(_to, tokenIdToMint);

  emit TokensMinted(_to, tokenIdToMint, _uri);
}
```

## safeTransferFrom \[write]

This function allows the transfer of an ERC721 NFT from the `from` address to
the `to` address. It requires that the caller is the token owner or has been
approved to transfer the token.

### Parameters

| Parameter | Type    | Description                                               |
| :-------- | :------ | :-------------------------------------------------------- |
| `from`    | address | The address that owns the token and wants to transfer it. |
| `to`      | address | The address that will receive ownership of the token.     |
| `tokenId` | unit256 | The unique identifier of the token being transferred.     |

### Failure scenarios

* The `isApprovedOrOwner` function is called to check if the caller is the token
  owner or an approved address. This check ensures that the transfer can only be
  performed by the token owner or an approved address.\
  *"ERC721: caller is not token owner or approved"*
* If the to address is a contract, the `checkOnERC721Received` function is
  called to check if the to address is a contract that implements the
  `onERC721Received` function correctly - according to the ERC721 standard.
* It checks if the token being transferred `tokenId` parameter is owned by the
  `from` address parameter. *"ERC721: transfer from incorrect owner"*
* It checks that the `to` address parameter is not the zero address. If it is
  the zero address, the function throws an exception with the message.\
  *"ERC721: transfer to the zero address"*
* If the transfer is restricted on the contract, it still allows burning and
  minting. It checks whether the `TRANSFER_ROLE` is assigned to either the
  `from` or `to` address. This ensures that token transfers comply with specific
  access control restrictions defined by the contract.\
  *"restricted to TRANSFER\_ROLE holders”*
* The function will check if the `to` address is a contract. If it is, the
  `_checkOnERC721Received` hook will check if the receiver address properly
  handles the received token. I\
  *"ERC721: transfer to non ERC721Receiver implementer"*

```solidity Solidity theme={null}
// safeTransferFrom
function safeTransferFrom(address from, address to, uint256 tokenId) public virtual override {
  safeTransferFrom(from, to, tokenId, "");
}

// safeTransferFrom - with data parameter
function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory data) public virtual override {
  require(_isApprovedOrOwner(_msgSender(), tokenId), "ERC721: caller is not token owner or approved");
  _safeTransfer(from, to, tokenId, data);
}
```

## setTokenURI \[write]

This function is responsible for setting the metadata URI for a specific NFT
token.

### Parameters

| Parameter | Type    | Description                                                                     |
| :-------- | :------ | :------------------------------------------------------------------------------ |
| `tokenId` | unit256 | The unique identifier of the NFT token for which the metadata URI is being set. |
| `uri`     | string  | The new metadata URI that will be associated with the NFT token.                |

### Failure scenarios

* The function checks if the caller is authorized to set the metadata URI. It
  calls the `canSetMetadata` function, which checks the authorization based on
  certain conditions specified in the contract.\
  *"NFTMetadata: not authorized to set metadata."*
* The function verifies if the metadata URI is not frozen. It checks the
  `uriFrozen` boolean flag to determine if the metadata is in a frozen state. If
  the metadata is frozen, meaning it cannot be changed, the function will throw
  an exception.\
  *"NFTMetadata: metadata is frozen."*
* If the provided URI is empty, the function will throw an exception with the
  message\
  *"NFTMetadata: empty metadata."*

```solidity Solidity theme={null}
function setTokenURI(uint256 _tokenId, string memory _uri) public virtual {
  require(_canSetMetadata(), "NFTMetadata: not authorized to set metadata.");
  require(!uriFrozen, "NFTMetadata: metadata is frozen.");
  _setTokenURI(_tokenId, _uri);
}

function _setTokenURI(uint256 _tokenId, string memory _uri) internal virtual {
  require(bytes(_uri).length > 0, "NFTMetadata: empty metadata.");
  _tokenURI[_tokenId] = _uri;

  emit MetadataUpdate(_tokenId);
}
```

## ownerOf \[read]

This function is used to retrieve the address of the owner of the ERC721 NFT
with the specified `tokenId`.

### Parameters

| Parameter | Type    | Description                                                                        |
| :-------- | :------ | :--------------------------------------------------------------------------------- |
| `tokenId` | unit256 | The unique identifier of the token for which the owner's address is being fetched. |

### Failure scenarios

* The function checks if the owner's address is not the zero address. This check
  is performed to ensure that a valid owner address is returned. *"ERC721:
  invalid token ID"*

### Note

* The function does not revert if the token doesn't exist. The zero address will
  be returned.

```solidity Solidity theme={null}
function ownerOf(uint256 tokenId) public view virtual override returns (address) {
  address owner = _ownerOf(tokenId);
  require(owner != address(0), "ERC721: invalid token ID");
  return owner;
}
```

## balanceOf \[read]

This function retrieves the balance (number of tokens) owned by a specific owner
address.

### Parameters

| Parameter |         |                                                           |
| :-------- | :------ | :-------------------------------------------------------- |
| `owner`   | address | The address for which the token balance is being fetched. |

### Failure scenarios

* The function checks if the `owner` address is not the zero address. The zero
  address represents an invalid or nonexistent address. *"ERC721: address zero
  is not a valid owner"*

```solidity Solidity theme={null}
function balanceOf(address owner) public view virtual override returns (uint256) {
  require(owner != address(0), "ERC721: address zero is not a valid owner");
  return _balances[owner];
}
```


# Contracts API Error Codes
Source: https://developers.circle.com/contracts/error-codes

Descriptions of error codes returned by the Contracts API

The Wallets and Contracts APIs return an
[HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) when
they encounter an error in an API request:

* `4xx` errors are client errors, which are informative and actionable. They
  communicate a mistake to the user and suggest fixes.
* `5xx` errors are unexpected server-side errors.

The tables in the following sections describe some of the common error messages
you might encounter using the Wallets and Contracts APIs. Where possible, a
suggested fix is provided in the `Description` column.

## General error format

HTTP status codes do not always provide sufficient information to determine the
cause of the error. Since the status code is part of the header of the response,
the body of response contains additional, Circle-specific, error information.
For example, if a request contains an invalid parameter, the response includes
the following:

**Header**

`HTTP/1.1 400 Bad RequestContent-Type: application/json`

**Body**

```json JSON theme={null}
{
  "code": 2,
  "message": "API parameter invalid"
}
```

## Extended error format

In some cases, the response includes extended information about the cause of the
error. For example, if a request doesn't include a value for a required
parameter, the response includes a detailed error message:

**Header**

`HTTP/1.1 400 Bad RequestContent-Type: application/json`

**Body**

```json JSON theme={null}
{
  "code": 2,
  "message": "API parameter invalid",
  "errors": [
    {
      "error": "required",
      "message": "fail to bind request to CreateWalletSetRequest: EOF",
      "location": "field1",
      "invalidValue": "null",
      "constraints": {}
    }
  ]
}
```

## General errors

This section describes some common extended error messages you might encounter
using Wallets and Contracts APIs.

The following errors are general errors that can be returned for any request.

| Error Code | HTTP code | Error Message          | Description                                                      |
| :--------- | :-------- | :--------------------- | :--------------------------------------------------------------- |
| `-1`       | `400`     | `Something went wrong` | An unknown error occurred while processing the API request.      |
| `3`        | `403`     | `Forbidden`            | The API key used does not have access to the requested endpoint. |

### Invalid requests

A `400` HTTP status code indicates that the request is invalid or malformed.
When the request is invalid, the Circle-specific error code is `2`. The
following table describes the common error messages that can be returned for
invalid requests.

| Error Code | HTTP code | Error Message                                                             | Description                                                                                                          |
| :--------- | :-------- | :------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------- |
| `2`        | `400`     | `Invalid Entity`                                                          | There is an error in the JSON format passed in the request.                                                          |
| `2`        | `400`     | `Fail to bind request to parameter: invalid UUID format`                  | The parameter must be in UUID format.                                                                                |
| `2`        | `400`     | `Error: Field validation`                                                 | One of the fields in the request is invalid.                                                                         |
| `2`        | `400`     | `Error: Field validation for blockchain failed on the blockchain tag`     | The blockchain does not exist. Try again with a [supported blockchain](/wallets/supported-blockchains).              |
| `2`        | `400`     | `Error: Field validation for gasLimit failed on the required_without tag` | If `feeLevel` is provided, `gasLimit` should be set to `NULL`. If `feeLevel` is `NULL`, `gasLimit` must be provided. |
| `2`        | `400`     | `Error: Field validation for parameter failed on the min tag`             | The parameter is not in the correct format.                                                                          |
| `2`        | `400`     | `Cannot unmarshal`                                                        | The JSON body of the request is not valid.                                                                           |
| `2`        | `400`     | `INVALID: parameter empty`                                                | The parameter is required for this request. Try the request again with this parameter.                               |

## Contracts errors

This section includes the errors that can be returned from the Circle Contracts
API requests.

### Contract errors

| Error code | HTTP code | Error message                                                     | Description                                                                   |
| ---------- | --------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `175001`   | `404`     | `Contract not found.`                                             | The specified contract does not exist in the system.                          |
| `175002`   | `400`     | `No ABI JSON for the target contract.`                            | Cannot execute a read function on a contract without the ABI JSON.            |
| `175003`   | `400`     | `Constructor parameters length must match constructor signature.` | The number of constructor parameters must match the constructor signature.    |
| `175004`   | `409`     | `Contract already exists.`                                        | The contract already exists in the system.                                    |
| `175005`   | `400`     | `Address is not a contract address.`                              | The given address is not associated with a smart contract.                    |
| `175006`   | `400`     | `Contract is archived.`                                           | Attempted to interact with an archived contract.                              |
| `175007`   | `400`     | `Invalid ABI JSON.`                                               | The inputted ABI JSON is not correctly formatted.                             |
| `175008`   | `400`     | `Multi-layered proxies are not supported.`                        | Importing a multi-layered proxy contract is not supported.                    |
| `175009`   | `400`     | `Contract deployment pending.`                                    | Contract deployment must be completed before function execution is available. |
| `175010`   | `400`     | `ABI function not found.`                                         | The ABI function was not found on the contract.                               |
| `175011`   | `400`     | `Empty update on a contract.`                                     | An empty update for a contract is not allowed                                 |
| `175012`   | `400`     | `Unable to query contract.`                                       | Unable to query contract. Check your parameters and try again.                |
| `175013`   | `400`     | `ABI function is not supported.`                                  | The ABI function of the contract is not supported.                            |

### Template errors

| Error code | HTTP code | Error message                                      | Description                                                         |
| ---------- | --------- | -------------------------------------------------- | ------------------------------------------------------------------- |
| `175201`   | `404`     | `Template not found.`                              | The specified template does not exist in the system.                |
| `175202`   | `400`     | `Deploying this template is temporarily disabled.` | Deploying this template is temporarily disabled.                    |
| `175203`   | `400`     | `Invalid template deployment parameter.`           | The request contains an invalid field in the template parameters.   |
| `175204`   | `400`     | `Missing required template deployment parameter.`  | The request is missing a required field in the template parameters. |
| `175205`   | `400`     | `Estimation is not supported.`                     | Estimating the deployment of this template is not supported.        |

### Event subscription errors

| Error code | HTTP code | Error message                                   | Description                                                                         |
| ---------- | --------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
| `175301`   | `404`     | `Event subscription not found.`                 | The specified event subscription does not exist or is not accessible to the caller. |
| `175302`   | `409`     | `Event subscription already exist.`             | The specified event has already been created for this contract.                     |
| `175303`   | `400`     | `The specified event signature does not exist.` | The specified event signature does not exist on this contract.                      |

### Common errors

| Error code | HTTP code | Error message                                                                                                    | Description                                                                                                           |
| ---------- | --------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `175401`   | `400`     | `Fail to parse id as UUID in url.`                                                                               | The specified ID is invalid (must be in UUID format). Try again with a valid ID.                                      |
| `175402`   | `400`     | `The specified blockchain is either not supported or deprecated.`                                                | The specified blockchain is either not supported or deprecated.                                                       |
| `175403`   | `409`     | `Please use a new idempotency key.`                                                                              | Use a new idempotency key and try again.                                                                              |
| `175404`   | `400`     | `TEST_API key cannot be used with blockchain mainnets, or LIVE_API key cannot be used with blockchain testnets.` | TEST\_API key cannot be used with blockchain mainnets, or LIVE\_API key cannot be used with blockchain testnets.      |
| `175405`   | `401`     | `TEST_API key or LIVE_API key is not found for the request.`                                                     | TEST\_API key or LIVE\_API key is not found for the request.                                                          |
| `175406`   | `400`     | `This feature is temporarily disabled.`                                                                          | This feature is temporarily disabled.                                                                                 |
| `175407`   | `400`     | `The specified blockchain is unavailable.`                                                                       | The specified blockchain is unavailable. Check the [Circle Status page](https://status.circle.com/) for more details. |
| `175408`   | `404`     | `Cannot find corresponding pagination cursor in the system.`                                                     | Cannot find corresponding pagination cursor in the system.                                                            |
| `175409`   | `403`     | `Entities with restrictions cannot perform this operation.`                                                      | Entities with restrictions cannot perform this operation.                                                             |
| `175410`   | `400`     | `invalid address format`                                                                                         | The address format is invalid.                                                                                        |

### Transaction errors

| Error code | HTTP code | Error message                                                                                                        | Description                                                                                                                     |
| ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `177001`   | `400`     | `transaction nonce is inconsistent with sender's latest nonce`                                                       | The transaction nonce is inconsistent with the sender's latest nonce.                                                           |
| `177002`   | `400`     | `user op nonce can not be larger than 0 when smart contract wallet hasn't been deployed`                             | User op nonce can not be larger than 0 when the smart contract wallet hasn't been deployed.                                     |
| `177003`   | `400`     | `failed to execute this request on EVM due to insufficient token when estimating fee`                                | Failed to execute this request on EVM due to insufficient tokens when estimating the fee.                                       |
| `177004`   | `400`     | `the total cost of executing transaction is higher than the balance of the user's account when estimating fee`       | When estimating the fee, the total cost of executing the transaction is higher than the balance of the user's account.          |
| `177005`   | `400`     | `the sender address is not token owner or approved when estimating token transfer`                                   | The sender address is not token owner or approved when estimating token transfer.                                               |
| `177006`   | `400`     | `gas required exceeds allowance when estimating fee`                                                                 | Gas required exceeds allowance when estimating fee.                                                                             |
| `177007`   | `400`     | `estimate fee execution reverted`                                                                                    | Estimate fee execution reverted.                                                                                                |
| `177008`   | `400`     | `ABI function signature can't pack ABI parameter`                                                                    | ABI function signature can't pack ABI parameter.                                                                                |
| `177009`   | `400`     | `fails to perform transaction estimation`                                                                            | Fails to perform transaction estimation.                                                                                        |
| `177010`   | `400`     | `maxFee * gasLimit exceed configurable max transaction fee (default is 1 native token)`                              | The `MaxFee` \* `GasLimit` exceeds the configurable max transaction fee (default is 1 native token).                            |
| `177011`   | `400`     | `transaction needs feeLevel or gasLimit provided`                                                                    | The transaction requires `feeLevel` or `gasLimit` to be provided in the request.                                                |
| `177012`   | `400`     | `sca transaction needs feeLevel provided`                                                                            | The SCA transaction requires `feeLevel` to be provided in the request.                                                          |
| `177013`   | `400`     | `EIP1559 chains need maxFee/priorityFee provided`                                                                    | EIP1559 chains require `maxFee` and `priorityFee` to be provided in the request.                                                |
| `177014`   | `400`     | `priorityFee cannot be larger than maxFee in creating transaction request`                                           | Creating transaction requests`priorityFee` cannot be larger than `maxFee`.                                                      |
| `177015`   | `400`     | `missing bytecode for contract deployment`                                                                           | Missing bytecode for contract deployment.                                                                                       |
| `177016`   | `400`     | `cannot provide both WalletID and SourceAddress/Blockchain`                                                          | You cannot provide `WalletID` and `SourceAddress`/`Blockchain` in a request.                                                    |
| `177017`   | `400`     | `Invalid amount in contract execution request`                                                                       | The `amount` in the contract execution request is invalid.                                                                      |
| `177018`   | `400`     | `policy is not activated and cannot be used`                                                                         | The Gas Station paymaster policy is not activated and cannot be used.                                                           |
| `177019`   | `400`     | `exceeded max daily transaction of the policy`                                                                       | The Gas Station paymaster policy maximum daily transaction limit has been reached.                                              |
| `177020`   | `400`     | `exceeded max spend USD per transaction of the policy`                                                               | The transaction cost exceeds the Gas Station paymaster policy maximum spend per transaction in USD.                             |
| `177021`   | `400`     | `exceeded max spend USD daily of the policy`                                                                         | The Gas Station paymaster policy for maximum spending daily in USD has been reached.                                            |
| `177022`   | `400`     | `exceeded max native token daily of the policy`                                                                      | The Gas Station paymaster policy for maximum native tokens daily of the policy.                                                 |
| `177023`   | `400`     | `sender is in policy blocklist`                                                                                      | The sender is on the Gas Station paymaster policy blocklist.                                                                    |
| `177024`   | `400`     | `wallet and request's blockchain mismatch.`                                                                          | The wallet and blockchain in the request should be the same.                                                                    |
| `177301`   | `400`     | `wallet is Frozen`                                                                                                   | Frozen wallets can not be updated or interacted with; they can only be queried.                                                 |
| `177302`   | `400`     | `invalid sca wallet config`                                                                                          | The SCA wallet configuration is invalid.                                                                                        |
| `177303`   | `400`     | `sca wallet first-time transaction is still in progress`                                                             | The SCA wallet needs to wait for the first-time transaction to finish deploying the wallet before processing more transactions. |
| `177304`   | `400`     | `SCA account is not supported on the given blockchain`                                                               | The SCA account is not supported on the given blockchain.                                                                       |
| `177305`   | `400`     | `Entity is not eligible for SCA account creation. Please check paymaster policy setup`                               | The entity is not eligible for SCA account creation. Check the Gas Station paymaster policy setup.                              |
| `177601`   | `400`     | `could be caused by either no such wallet or wallet is not accessible to the caller`                                 | The target wallet cannot be found in the system. Either the specified wallet doesn't exist, or it's inaccessible to the caller. |
| `177602`   | `400`     | `reusing an entity secret ciphertext is not allowed. Please re-encrypt the entity secret to generate new ciphertext` | Reusing an entity's secret ciphertext is not allowed. Re-encrypt the entity secret to generate a new ciphertext.                |
| `177603`   | `400`     | `entity is likely not properly set up during the onboarding process`                                                 | The corresponding entity cannot be found in the system.                                                                         |
| `177604`   | `400`     | `the provided entity secret is invalid`                                                                              | The provided entity secret is invalid.                                                                                          |
| `177605`   | `400`     | `the entity secret has not been set yet. Please provide encrypted ciphertext in the console`                         | The entity secret has not been set up on your account. Provide encrypted ciphertext in the console.                             |
| `177606`   | `400`     | `current entity secret is invalid. Please rotate the entity secret first`                                            | The provided entity secret is invalid. Rotate the entity secret first and send another API request.                             |
| `177607`   | `400`     | `please use a new idempotency key`                                                                                   | Use a new idempotency key.                                                                                                      |
| `177901`   | `400`     | `smart contract query failed`                                                                                        | Error when querying contract. Check parameters and try again.                                                                   |


# Postman Collection
Source: https://developers.circle.com/contracts/postman

Use Circle's Postman collection to send API requests and explore the Smart Contract Platform APIs.

Circle's Postman collection provides template requests to help you learn about
the Smart Contract Platform APIs. These requests run on
[Postman](https://www.postman.com/), an API platform for learning, building, and
using APIs. The Postman Contracts workspace includes a collection that matches
the organization of the
[API reference](/api-reference/contracts/smart-contract-platform/list-contracts).

## Run in Postman

To use the Postman collection, select **Run in Postman** below. You can fork the
collection to your workspace, view the collection in the public workspace, or
import the collection into Postman.

* **Fork**: Creates a copy of the collection while maintaining a link to the
  parent.
* **View**: Allows you to try out the API without importing anything into your
  Postman suite.
* **Import**: Creates a copy of the collection but does not maintain a link to
  Circle's copy.

| Collection | Link                                                                                                                                                                                                                                                                                                                                                |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contracts  | [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/21445022-20c27ad9-62c1-4c95-8adc-e2d2a4a473cd?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D21445022-20c27ad9-62c1-4c95-8adc-e2d2a4a473cd%26entityType%3Dcollection%26workspaceId%3D73acd722-fab9-49b0-9382-086659476258) |

## Authorization

Paste your [API key](/contracts/create-api-key) in the Authorization tab of the
collection. To store your API key as a variable for more advanced testing, see
Postman's
[using variables](https://learning.postman.com/docs/sending-requests/variables/)
guide.


# Quickstart: Deploy a Smart Contract using Bytecode
Source: https://developers.circle.com/contracts/scp-deploy-smart-contract

Deploy smart contract bytecode using Circle Contracts

This quickstart walks you through deploying a smart contract using the compiled
bytecode and ABI using Circle Contracts.

Circle Contracts provides an API for deploying, exploring, and interacting with
smart contracts. The platform offers a powerful toolset for developers to build
decentralized applications and for businesses to transition onchain.

This guide can also be followed to deploy smart contracts on the other
[supported blockchains](/contracts/supported-blockchains) by changing the
`blockchain` parameter in your request. Additionally, you can deploy to Mainnet
by swapping out the Testnet API key for a Mainnet API key. See the
[Testnet vs Mainnet](/circle-mint/references/sandbox-and-testing#transition-to-production)
guide for more details.

## **Prerequisites**

Before you begin, ensure you've:

1. Created [an API key in the Circle Console](/contracts/create-api-key).
2. [Registered your Entity Secret](https://developers.circle.com/wallets/dev-controlled/register-entity-secret).

## **Step 1: Project setup**

Set up your local development environment and install the required dependencies.

### 1.1 Set up a new project

Create a new directory, navigate to it and initialize a new project with de1ault
settings

<CodeGroup>
  ```shell NodeJS theme={null}
  mkdir scp-bytecode-deploy
  cd scp-bytecode-deploy
  npm init -y
  npm pkg set type=module
  ```

  ```shell Python theme={null}
  mkdir scp-bytecode-deploy
  cd scp-bytecode-deploy
  python3 -m venv .venv
  source .venv/bin/activate
  ```
</CodeGroup>

### 1.2 Install dependencies

In the project directory, install the required dependencies. This guide uses
SDKs for Circle
[developer-controlled wallets](https://developers.circle.com/wallets/dev-controlled/create-your-first-wallet)
and [Contracts](https://developers.circle.com/contracts).

<CodeGroup>
  ```ts NodeJS theme={null}
  npm install @circle-fin/developer-controlled-wallets @circle-fin/smart-contract-platform
  ```

  ```py Python theme={null}
  pip install circle-smart-contract-platform circle-developer-controlled-wallets
  ```
</CodeGroup>

## Step 2: Create a wallet and fund it with testnet tokens

In this section, you will create a developer-controlled wallet with the SDK and
fund it with testnet USDC to pay for the gas fees needed to deploy the smart
contract. If you already have a developer-controlled wallet, skip to
[Step 3](#step-3:-compile-a-smart-contract).

### 2.1 Setup and run a create-wallet script

Import the developer-controlled wallets SDK and initialize the client. You will
require your API key and Entity Secret for this. Note that your API key and
Entity Secret are sensitive credentials. Do not commit them to Git or share them
publicly. Store them securely in environment variables or a secrets manager.\
Developer-controlled wallets are created in a wallet set, which is the source
from which individual wallet keys are derived.

<CodeGroup>
  ```typescript NodeJS theme={null}
  import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

  const client = initiateDeveloperControlledWalletsClient({
    apiKey: "<YOUR_API_KEY>",
    entitySecret: "<YOUR_ENTITY_SECRET>",
  });

  // Create a wallet set
  const walletSetResponse = await client.createWalletSet({
    name: "WalletSet 1",
  });
  console.log("Created WalletSet", walletSetResponse.data?.walletSet);

  // Create a wallet on Arc Testnet
  const walletsResponse = await client.createWallets({
    blockchains: ["ARC-TESTNET"],
    count: 1,
    walletSetId: walletSetResponse.data?.walletSet?.id ?? "",
  });
  console.log("Created Wallets", walletsResponse.data?.wallets);
  ```

  ```python Python theme={null}
  from circle.web3 import utils
  from circle.web3 import developer_controlled_wallets

  client = utils.init_developer_controlled_wallets_client(
      api_key="<YOUR_API_KEY>",
      entity_secret="<YOUR_ENTITY_SECRET>"
  )

  wallet_sets_api = developer_controlled_wallets.WalletSetsApi(client)
  wallets_api = developer_controlled_wallets.WalletsApi(client)

  # Create a wallet set
  wallet_set = wallet_sets_api.create_wallet_set(
      developer_controlled_wallets.CreateWalletSetRequest.from_dict({
          "name": "Wallet Set 1"
      })
  )

  # Create a wallet on Arc Testnet
  wallet = wallets_api.create_wallet(
      developer_controlled_wallets.CreateWalletRequest.from_dict({
          "blockchains": ["ARC-TESTNET"],
          "count": 1,
          "walletSetId": wallet_set.data.wallet_set.actual_instance.id
      })
  )
  ```
</CodeGroup>

If you are not using the developer-controlled wallets SDK, you can call the API
directly as well. You will need to make 2 requests, one to create the wallet set
and one to create the wallet. Make sure to replace the
[entity secret ciphertext](https://developers.circle.com/wallets/dev-controlled/entity-secret-management#entity-secret-ciphertext)
and idempotency key.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/w3s/developer/walletSets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entitySecretCiphertext": "<string>",
  "idempotencyKey": "<string>",
  "name": "WalletSet 1"
}
'
```

The wallet set ID is required for creating the wallet.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/w3s/developer/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "<string>",
  "blockchains": [
    "ARC-TESTNET"
  ],
  "entitySecretCiphertext": "<string>",
  "walletSetId": "<WALLET_SET_ID>",
  "accountType": "EOA",
  "count": 1,
  ]
}
'
```

You should end up with a new developer-controlled wallet, and the response will
look something like this:

```json theme={null}
[
  {
    "id": "a2f67c91-b7e3-5df4-9c8e-42bbd51a9fcb",
    "state": "LIVE",
    "walletSetId": "5c3e9f20-8d4b-55a1-a63b-c21f44de8a72",
    "custodyType": "DEVELOPER",
    "refId": "",
    "name": "",
    "address": "0x9eab451f27dca39bd3f5d76ef28c86cc0b3a72df",
    "blockchain": "ARC-TESTNET",
    "accountType": "EOA",
    "updateDate": "2025-11-07T01:35:03Z",
    "createDate": "2025-11-07T01:35:03Z"
  }
]
```

### 2.3 Fund the wallet with test USDC

Obtain some testnet USDC for executing transactions like making transfers and
paying gas fees for those transactions. Circle's
[Testnet Faucet](https://faucet.circle.com/) provides testnet USDC and can be
used once per hour to obtain additional USDC.

### 2.4 Check the wallet's balance

You can check your wallet's balance from the
[Developer Console](https://console.circle.com/wallets/dev/wallets) or
programmatically by making a request to
[`GET /wallets/{id}/balances`](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/list-wallet-balance)
with the wallet ID of the wallet you created.

<CodeGroup>
  ```ts NodeJS theme={null}
  const response = await client.getWalletTokenBalance({
    id: "<WALLET_ID>",
  });
  ```

  ```py Python theme={null}
  try:
      wallet_balance = wallets_api.list_wallet_balance(id="<WALLET_ID>")
      print(wallet_balance.json())
  except developer_controlled_wallets.ApiException as e:
      print("Exception when calling WalletsApi->list_wallet_balance: %s\n" % e)
  ```

  ```shell cURL theme={null}
  curl --request GET \
       --url 'https://api.circle.com/v1/w3s/wallets/{<WALLET_ID>}/balances' \
       --header 'accept: application/json' \
       --header 'authorization: Bearer <API_KEY>'
  ```
</CodeGroup>

## **Step 3: Compile a smart contract**

In this section, you will compile and deploy a minimal smart contract for an
onchain payment inbox using Contracts. Users pay by approving and depositing
USDC, payments are recorded via events, and the owner can withdraw the
accumulated balance.

<Note>
  This contract is intentionally minimal and for learning purposes only. Smart
  contracts that manage real funds typically require additional security
  patterns, testing, and audits, and often rely on community-reviewed libraries
  such as [OpenZeppelin](https://www.openzeppelin.com/).
</Note>

```solidity theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IERC20 {
    function transfer(address to, uint256 amount) external returns (bool);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);
    function balanceOf(address account) external view returns (uint256);
}

contract MerchantTreasuryUSDC {
    address public immutable owner;
    IERC20 public immutable usdc;

    event PaymentReceived(address indexed sender, uint256 amount);
    event FundsWithdrawn(address indexed to, uint256 amount);

    constructor(address _owner, address _usdc) {
        require(_owner != address(0), "Invalid owner");
        require(_usdc != address(0), "Invalid USDC");
        owner = _owner;
        usdc = IERC20(_usdc);
    }

    function deposit(uint256 amount) external {
        require(amount > 0, "Invalid amount");
        bool ok = usdc.transferFrom(msg.sender, address(this), amount);
        require(ok, "USDC transferFrom failed");
        emit PaymentReceived(msg.sender, amount);
    }

    function withdraw() external {
        require(msg.sender == owner, "Unauthorized");

        uint256 amount = usdc.balanceOf(address(this));
        require(amount > 0, "No funds");

        bool ok = usdc.transfer(owner, amount);
        require(ok, "USDC transfer failed");
        emit FundsWithdrawn(owner, amount);
    }

    function balance() external view returns (uint256) {
        return usdc.balanceOf(address(this));
    }
}
```

* `constructor(address _owner)`: Sets the treasury owner and the USDC token
  address at deployment
* `receive() (payable)`: Transfers approved USDC from the caller into the
  contract and emits `PaymentReceived(sender, amount)`
* `withdraw()`: Allows only the owner to withdraw the entire USDC balance; emits
  `FundsWithdrawn(to, amount)`
* `balance() (view)`: Returns the contract's current USDC balance

### 3.1 Obtain ABI and bytecode from Remix IDE

1. Open the [Remix IDE](https://remix.ethereum.org/).
2. Create a new file in the contracts folder called `MerchantTreasury.sol`.
   <Frame>
     <img />
   </Frame>
3. Copy and paste the Solidity code into the file, then click on the Compile
   button.
   <Frame>
     <img />
   </Frame>
4. Navigate to the Solidity Compiler tab from the left sidebar. Under Contracts,
   make sure MerchantTreasuryUSDC (Merchant Treasury.sol) is selected. You
   should see the option to copy the ABI and Bytecode. These values will be used
   in the next step.
   <Frame>
     <img />
   </Frame>
   1. The compiler output is available under Compilation Details. For more
      information on the Solidity compiler's outputs, see [using the
      compiler](https://docs.soliditylang.org/en/stable/using-the-compiler.html).
   2. The Application Binary Interface (ABI) is the standard way to interact
      with contracts on an EVM from outside the blockchain and for
      contract-to-contract interaction.

## Step 4: Deploy the smart contract

In this section, you will deploy the smart contract on Arc using the contract's
ABI and bytecode, which you have compiled in the previous step.

Import and initialize the Contracts SDK, then copy the ABI JSON and raw bytecode
over from Remix. Note that you need to append `0x` to the raw bytecode.

The `constructorParameters` correspond to the arguments encoded in the
contract's deployment bytecode. Since different contracts define different
constructors, these parameters vary based on the specific contract being
deployed. For this contract, the parameters are the wallet address of the owner
and the USDC token contract address on Arc Testnet.

<CodeGroup>
  ```typescript NodeJS theme={null}
  import { initiateSmartContractPlatformClient } from "@circle-fin/smart-contract-platform";

  const client = initiateSmartContractPlatformClient({
    apiKey: "<YOUR_API_KEY>",
    entitySecret: "<YOUR_ENTITY_SECRET>",
  });

  const abiJson = PASTE_YOUR_ABI_JSON_HERE;

  const bytecode = "0xPASTE_YOUR_BYTECODE_HERE";

  const response = await client.deployContract({
    name: "MerchantTreasury Contract",
    description:
      "Contract to receive payments and allow an owner to withdraw funds",
    blockchain: "ARC-TESTNET",
    walletId: "<WALLET_ID>",
    abiJson: JSON.stringify(abiJson, null, 2),
    bytecode: bytecode,
    constructorParameters: [
      "<WALLET_ADDRESS>", // Initial owner of the contract
      "0x3600000000000000000000000000000000000000", // USDC contract address on Arc Testnet
    ],
    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
  });
  console.log(response.data);
  ```

  ```python Python theme={null}
  from circle.web3 import smart_contract_platform
  from circle.web3 import utils

  client = utils.init_smart_contract_platform_client(
      api_key="<YOUR_API_KEY>",
      entity_secret="<YOUR_ENTITY_SECRET>"
  )

  api_instance = smart_contract_platform.DeployImportApi(client)

  abi_json_str = """PASTE_YOUR_ABI_JSON_HERE"""
  abi = json.loads(abi_json_str)
  abi_json = json.dumps(abi)

  request = smart_contract_platform.ContractDeploymentRequest.from_dict({
      "name": 'MerchantTreasury Contract',
      "description": 'Contract to receive payments and allow an owner to withdraw funds',
      "blockchain": 'ARC-TESTNET',
      "walletId": '<WALLET_ID>',
      "abiJson": abi_json,
      "bytecode": "0xPASTE_YOUR_BYTECODE_HERE",
      "constructorParameters": ['<WALLET_ADDRESS>', '0x360000000000000000000000000000000000000'],  # owner address and USDC contract address on Arc Testnet
      "feeLevel": 'MEDIUM',
  })

  response = api_instance.deploy_contract(
      contract_deployment_request=request
  )

  print(response.json())
  ```

  ```shell cURL theme={null}
  curl --request POST \
    --url https://api.circle.com/v1/w3s/contracts/deploy \
    --header 'Authorization: Bearer <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '
  {
    "idempotencyKey": "<string>",
    "name": "MerchantTreasury Contract",
    "description": "Contract to receive payments and allow an owner to withdraw funds",
    "walletId": "<WALLET_ID>",
    "blockchain": "ARC-TESTNET",
    "abiJson": "PASTE_YOUR_ABI_JSON_HERE",
    "bytecode": "0xPASTE_YOUR_BYTECODE_HERE",
    "constructorParameters": ["<WALLET_ADDRESS>", "0x36000000000000000000000000000000000000"],
    "feeLevel": "MEDIUM",
    "entitySecretCiphertext": "<string>"
  }
  '
  ```
</CodeGroup>

After running the script successfully, you should receive a response object that
looks like this:

```shell theme={null}
{
  contractId: 'xxxxxxxx-xxxx-7xxx-8xxx-xxxxxxxxxxxx',
  transactionId: 'xxxxxxxx-xxxx-5xxx-axxx-xxxxxxxxxxxx'
}
```

You can check the status of the deployment from the
[Developer Console](https://console.circle.com/smart-contracts/contracts) or run
`getContract` from the SDK directly.

<CodeGroup>
  ```ts NodeJS theme={null}
  const response = await circleContractSdk.getContract({
    id: "<CONTRACT_ID>",
  });
  ```

  ```py Python theme={null}
  api_instance = smart_contract_platform.ViewUpdateApi(client)

  response = api_instance.get_contract(id="<CONTRACT_ID>")
  print(response.json())
  ```

  ```shell cURL theme={null}
  curl --request GET \
    --url https://api.circle.com/v1/w3s/contracts/{CONTRACT_ID} \
    --header 'Authorization: Bearer <API_KEY>'
  ```
</CodeGroup>

Once your contract is deployed, you will be able to interact with it from your
application and mint new NFTs with it. You should be able to see it from the
console and on the [Arc Testnet Explorer](https://testnet.arcscan.app/).


# Quickstart: Event Monitoring for Smart Contracts
Source: https://developers.circle.com/contracts/scp-event-monitoring



In this guide you'll set up real-time push notifications for specific Events
that occur in your smart contracts. You can then use those events to trigger
important functionality in your application.

## Prerequisites

Before you begin:

* [Create an API key](/contracts/create-api-key) in the Circle Console

Perform the steps below:

1. [Step 1. Configure Your Webhook for Notifications](/contracts/scp-event-monitoring#step-1-configure-your-webhook-for-notifications)
2. [Step 2. Import Your Smart Contract](/contracts/scp-event-monitoring#step-2-import-your-smart-contract)
3. [Step 3. Create an Event Monitor](/contracts/scp-event-monitoring#step-3-create-an-event-monitor)
4. [Step 4. Fetch Event History](/contracts/scp-event-monitoring#step-4-fetch-event-history)

### Step 1. Configure Your Webhook for Notifications

To receive notifications from Circle, you must expose a publicly accessible
subscriber endpoint on your side. This endpoint should handle POST requests over
HTTPS.

For more information on setting up a webhook, refer to the
[Set Up Webhooks](/wallets/webhook-notifications), and optionally watch the
following video about Webhook Configurations.

<Accordion title="Video Tutorial: Webhook Configuration">
  <iframe title="Video Tutorial: Webhook Configuration" />
</Accordion>

## Customized Webhook Notifications

Customized webhook notifications enable you to listen to a restricted set of
notifications. To create a webhook for smart contract events only select Limit
to specific events when creating your webhook in the Developer Console, then
choose contracts.EventLog.

## The Event Log Notification

When a monitored event occurs, the webhook will receive a notification via POST
with the body formatted as follows: Notification

```json JSON theme={null}
{
  // A unique identifier for the subscription that received the notification.
  "subscriptionId": "c881d120-7692-4ae6-bab0-acfa8c9596c1",

  // A unique identifier for the notification itself.
  "notificationId": "aff457c5-2649-4cdb-a51e-84b33fdfebc9",

  // The type of notification; indicates an event log from a smart contract.
  "notificationType": "contracts.eventLog",

  // An object that contains details about the event log notification.
  "notification": {
    // The address of the smart contract that emitted the event.
    "contractAddress": "0x6bc50ff08414717f000431558c0b585332c2a53d",
    // The specific blockchain network where the event occurred.
    "blockchain": "ARB-SEPOLIA",
    // A hash to identify the on-chain transaction that caused the event.
    "txHash": "0xdc8c0ac07ca02f87754e931b729d9426a5bd7f6b062fbb40e58c8a7942992a7a",
    // A hash representing the user operation that triggered the event, if applicable.
    "userOpHash": "0xbaae33f07aa4877f5a2e9f2a90c5cc5c5006281043696ebaa7f887914058ead0",
    // The name and parameter types of the emitted event.
    "eventName": "Transfer(address,address,uint256)",
    // An array containing indexed parameters of the event. Each entry is a hashed representation of the parameter.
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "0x0000000000000000000000000000000000000000000000000000000000000000",
      "0x0000000000000000000000009d7fb3144729fff819fc1aa812d0a261ed8c8676"
    ],
    // The raw data associated with the event, consisting of non-indexed parameters as a concatenated hexadecimal string.
    "data": "0x00000000000000000000000000000000000000000000000000005af3107a3fff"
  },
  // The UTC timestamp of when the notification was generated, formatted to ISO 8601.
  "timestamp": "2024-10-21T18:44:07.614649603Z",
  // Indicates the version of the notification format.
  "version": 2
}
```

### Step 2. Import Your Smart Contract

Before creating an event monitor, import your smart contract into the Contracts
system. This ensures the Contracts platform is aware of your contract and can
manage event monitors effectively:

```javascript javascript theme={null}
const importResponse = await circleContractSdk.importContract({
  // The address of the smart contract to be imported.
  address: "0x6bc50ff08414717f000431558c0b585332c2a53d",
  // The blockchain from which the contract is being imported.
  blockchain: "ARB-SEPOLIA",
  // A unique key provided to ensure idempotency of the request. It prevents duplicate imports for the same contract if a retry occurs.
  idempotencyKey: "50d64a5e-6b2e-47ea-aa14-13feab9376e9",
  // A human-readable name for the contract being imported.
  name: "MyToken",
  // A brief description of the smart contract.
  description: "My ERC-20 Token Contract",
});
```

If you attempt to create an event monitor on an un-imported smart contract, you
will receive the following error message:

```json JSON theme={null}
{
  "code": 175001,
  "message": "contract not found"
}
```

For more information on importing a contract, see the Import a contract API
endpoint.

## Step 3. Create an Event Monitor

Event Monitors listen for configured events on the blockchain and trigger
notifications to your webhook endpoint when those events occur. Circle will also
save all emitted events under that monitor, allowing you to retrieve historical
data later. For more details, see Step 4. Fetch Event History.

### Finding and Using the Event Signature

An event signature uniquely identifies an event within a smart contract and is
derived from the event's name and parameter types using the keccak-256 hashing
function. For readability, event monitors are created using the human-readable
event signature, not the hash.

For example, the Transfer event in the ERC-20 interface is defined as:

```javascript JavaScript theme={null}
event Transfer(address indexed from, address indexed to, uint256 value);
```

The human-readable event signature is formatted as:
'Transfer(address,address,uint256)'.

<Note>**Note:** Spaces are not allowed in the event string signature.</Note>

Create an event monitor with the following code:

```javascript JavaScript theme={null}
const monitorResponse = await circleContractSdk.createEventMonitor({
  // The specific blockchain network where the event monitor will be created.
  blockchain: "ARB-SEPOLIA",
  // The address of the smart contract for which the event monitor is being created.
  contractAddress: "0x6bc50ff08414717f000431558c0b585332c2a53d",
  // The signature of the event to monitor, defining the event type and parameters being tracked.
  eventSignature: "Transfer(address,address,uint256)",
  // A unique key provided to ensure idempotency of the request, preventing duplicate event monitors from being created.
  idempotencyKey: "f80fcf44-bbb1-4336-870a-f1802ad98e0f",
});
```

The response will include details about the event monitor:

```json JSON theme={null}
{
  "data": {
    "eventMonitor": {
      // A unique identifier for the event monitor.
      "id": "01929bc2-aab3-76a2-b3fc-c99fc94b9218",
      // The address of the smart contract being monitored.
      "contractAddress": "0x6bc50ff08414717f000431558c0b585332c2a53d",
      // The specific blockchain where the event monitor is set up.
      "blockchain": "ARB-SEPOLIA",
      // The signature of the event being monitored, indicating the type and parameters.
      "eventSignature": "Transfer(address,address,uint256)",
      // The hash of the event signature used for efficient identification.
      "eventSignatureHash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      // A boolean indicating whether the event monitor is currently enabled.
      "isEnabled": true,
      // The date and time when the event monitor was created, in ISO 8601 format.
      "createDate": "2024-10-17T18:34:39.1558Z",
      // The date and time when the event monitor was last updated, in ISO 8601 format.
      "updateDate": "2024-10-17T18:34:39.1558Z"
    }
  }
}
```

If the event signature you are creating a monitor for does not exist, you will
receive the following error message:

```json JSON theme={null}
{
  "code": 175303,
  "message": "The specified event signature does not exist"
}
```

<Note>
  **Note:** Please ensure the event signature exists if you are using an
  unverified contract as Circle cannot verify event existence for unverified
  contracts.
</Note>

After creating an event monitor, you can view, disable, and delete your
monitors. For more information, see the
[Event Monitoring APIs](/api-reference/contracts/smart-contract-platform/get-event-monitors).

### Step 4. Fetch Event History

To retrieve historical events that match your monitors, utilize the event
history feature. This functionality is essential for doing analytics, auditing,
or reconstructing the application state based on past events:

```javascript JavaScript theme={null}
const eventHistoryResponse = await circleContractSdk.getEventHistory({
  // The address of the smart contract for which event history is being fetched.
  contractAddress: "0x6bc50ff08414717f000431558c0b585332c2a53d",
  // The specific blockchain network where the contract is deployed.
  blockchain: "ARB-SEPOLIA",
  // The signature of the event to fetch historical occurrences.
  eventSignature: "Transfer(address,address,uint256)",
});
```

The data returned will mirror the information in your Webhook Logs in the
[Circle Console](https://console.circle.com/):

```json JSON theme={null}
{
  "data": {
    "eventLogs": [
      {
        // A unique identifier for the event log.
        "id": "0192b064-c71d-7642-8882-aadc8f5df01a",
        // The blockchain network where the event occurred.
        "blockchain": "ARB-SEPOLIA",
        // The transaction hash associated with the event log.
        "txHash": "0xdc8c0ac07ca02f87754e931b729d9426a5bd7f6b062fbb40e58c8a7942992a7a",
        // The index of the log entry within the transaction.
        "logIndex": "1",
        // The hash of the block containing the transaction.
        "blockHash": "0x842dfd3c9339008d311c78154368f0f11f91801d5f40d7306745576aa9c246f7",
        // The height of the block in which the event occurred.
        "blockHeight": 90526683,
        // The address of the smart contract that emitted the event.
        "contractAddress": "0x6bc50ff08414717f000431558c0b585332c2a53d",
        // The signature of the event that was emitted.
        "eventSignature": "Transfer(address,address,uint256)",
        // The hash of the event signature for efficient identification.
        "eventSignatureHash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        // An array of topics indexed within the event log for filtering.
        "topics": [
          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0x0000000000000000000000000000000000000000000000000000000000000000",
          "0x0000000000000000000000009d7fb3144729fff819fc1aa812d0a261ed8c8676"
        ],
        // Raw data associated with the event, representing non-indexed parameters.
        "data": "0x00000000000000000000000000000000000000000000000000005af3107a3fff",

        // A hash representing the user operation that triggered the event, when applicable.
        "userOpHash": "0xbaae33f07aa4877f5a2e9f2a90c5cc5c5006281043696ebaa7f887914058ead0",
        // The date and time when the first confirmation of the event occurred.
        "firstConfirmDate": "2024-10-21T18:44:04Z"
      }
    ]
  }
}
```

<Note>
  **Note:**

  Event history for a monitor will always be available; however, the resource will
  stop being populated once the monitor is deleted.
</Note>

For more information, see the
[Event Monitoring APIs](/api-reference/contracts/smart-contract-platform/get-event-monitors)
and join our
[Discord - Build on Circle](https://discord.com/invite/buildoncircle) channel.


# Quickstart: Interact With a Smart Contract
Source: https://developers.circle.com/contracts/scp-interact-smart-contract



In this guide, we will interact with a deployed smart contract using APIs. If
you haven't deployed a smart contract, follow the
[deploy a smart contract](/contracts/scp-deploy-smart-contract) tutorial.

## 1. Retrieve the Smart Contract's Functions

To fetch the new Contract object, make a `GET /contracts/{id}` request that
includes the `contractId` object returned from your deployment request. The
`functions` property returned in the successful request contains a list of all
of the functions on the contract:

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  // Import and configure the developer-controlled wallet SDK
  const {
    initiateDeveloperControlledWalletsClient,
  } = require("@circle-fin/developer-controlled-wallets");
  const circleDeveloperSdk = initiateDeveloperControlledWalletsClient({
    apiKey: "<API_KEY>",
    entitySecret: "<ENTITY_SECRET>",
  });

  // Import and configure the smart contract SDK
  const {
    initiateSmartContractPlatformClient,
  } = require("@circle-fin/smart-contract-platform");
  const circleContractSdk = initiateSmartContractPlatformClient({
    apiKey: "<API_KEY>",
    entitySecret: "<ENTITY_SECRET>",
  });

  const response = await circleContractSdk.getContract({
    id: "0189db84-72b7-7fcc-832b-5bf886b9a0ef",
  });
  ```

  ```coffeescript Python SDK theme={null}
  from circle.web3 import smart_contract_platform, developer_controlled_wallets
  from circle.web3 import utils

  # Import and configure the developer-controlled wallet SDK
  client = utils.init_developer_controlled_wallets_client(api_key=key, entity_secret=entitySecret)
  # Import and configure the smart contract SDK
  scpClient = utils.init_smart_contract_platform_client(api_key=key, entity_secret=entitySecret)

  # create an api instance
  api_instance = smart_contract_platform.ViewUpdateApi(scpClient)
  try:
      response = api_instance.get_contract(id='0189db84-72b7-7fcc-832b-5bf886b9a0ef')
      print(response)
  except smart_contract_platform.ApiException as e:
      print("Exception when calling ViewUpdateApi->get_contract: %s\n" % e)
  ```

  ```curl cURL theme={null}
  curl --request GET \
       --url 'https://api.circle.com/v1/w3s/contracts/{id}' \
       --header 'accept: application/json' \
       --header 'authorization: Bearer <API_KEY>'
  ```
</CodeGroup>

```json JSON theme={null}
{
  "data": {
    "contract": {
      "id": "0189db84-72b7-7fcc-832b-5bf886b9a0ef",
      "entityId": "dcfa8149-98d8-4ed4-91fb-de7f3627b384",
      "deploymentTransactionId": "4f5bfa38-c598-56a6-932e-8b5bbd3d5fc9",
      "name": "First Contract Name",
      "description": "First Contract Description",
      "contractInputType": "BYTECODE",
      "createDate": "2023-08-09T18:17:17Z",
      "updateDate": "2023-08-09T18:17:17Z",
      "archived": false,
      "contractAddress": "0x1e124d7384cd34448ea5907bd0052a79355ab5eb",
      "blockchain": "MATIC-AMOY",
      "status": "COMPLETE",
      "deployerAddress": "0x1bf9ad0cc2ad298c69a2995aa806ee832788218c",
      "txHash": "0x241c4df6f08f9ed2b569c9f9b1cc48fb6074ffffaeee7552e716ce059161a743",
      "abiJson": "[\n\t{\n\t\t\"inputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"constructor\"\n\t},\n\t{\n\t\t\"anonymous\": false,\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"owner\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"approved\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"Approval\",\n\t\t\"type\": \"event\"\n\t},\n\t{\n\t\t\"anonymous\": false,\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"owner\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"operator\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"indexed\": false,\n\t\t\t\t\"internalType\": \"bool\",\n\t\t\t\t\"name\": \"approved\",\n\t\t\t\t\"type\": \"bool\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"ApprovalForAll\",\n\t\t\"type\": \"event\"\n\t},\n\t{\n\t\t\"anonymous\": false,\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"previousOwner\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"newOwner\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"OwnershipTransferred\",\n\t\t\"type\": \"event\"\n\t},\n\t{\n\t\t\"anonymous\": false,\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"from\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"to\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"indexed\": true,\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"Transfer\",\n\t\t\"type\": \"event\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"to\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"approve\",\n\t\t\"outputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"owner\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"balanceOf\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"getApproved\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"owner\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"operator\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"isApprovedForAll\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"bool\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"bool\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [],\n\t\t\"name\": \"name\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"string\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"string\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [],\n\t\t\"name\": \"owner\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"ownerOf\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [],\n\t\t\"name\": \"renounceOwnership\",\n\t\t\"outputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"to\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"safeMint\",\n\t\t\"outputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"from\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"to\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"safeTransferFrom\",\n\t\t\"outputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"from\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"to\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"bytes\",\n\t\t\t\t\"name\": \"data\",\n\t\t\t\t\"type\": \"bytes\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"safeTransferFrom\",\n\t\t\"outputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"operator\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"bool\",\n\t\t\t\t\"name\": \"approved\",\n\t\t\t\t\"type\": \"bool\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"setApprovalForAll\",\n\t\t\"outputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"bytes4\",\n\t\t\t\t\"name\": \"interfaceId\",\n\t\t\t\t\"type\": \"bytes4\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"supportsInterface\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"bool\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"bool\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [],\n\t\t\"name\": \"symbol\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"string\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"string\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"tokenURI\",\n\t\t\"outputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"string\",\n\t\t\t\t\"name\": \"\",\n\t\t\t\t\"type\": \"string\"\n\t\t\t}\n\t\t],\n\t\t\"stateMutability\": \"view\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"from\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"to\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"internalType\": \"uint256\",\n\t\t\t\t\"name\": \"tokenId\",\n\t\t\t\t\"type\": \"uint256\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"transferFrom\",\n\t\t\"outputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"function\"\n\t},\n\t{\n\t\t\"inputs\": [\n\t\t\t{\n\t\t\t\t\"internalType\": \"address\",\n\t\t\t\t\"name\": \"newOwner\",\n\t\t\t\t\"type\": \"address\"\n\t\t\t}\n\t\t],\n\t\t\"name\": \"transferOwnership\",\n\t\t\"outputs\": [],\n\t\t\"stateMutability\": \"nonpayable\",\n\t\t\"type\": \"function\"\n\t}\n]",
      "functions": [
        {
          "name": "approve",
          "type": "function",
          "inputs": [
            {
              "name": "to",
              "type": "address"
            },
            {
              "name": "tokenId",
              "type": "uint256"
            }
          ],
          "stateMutability": "nonpayable"
        },
        {
          "name": "balanceOf",
          "type": "function",
          "inputs": [
            {
              "name": "owner",
              "type": "address"
            }
          ],
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "uint256"
            }
          ]
        },
        {
          "name": "getApproved",
          "type": "function",
          "inputs": [
            {
              "name": "tokenId",
              "type": "uint256"
            }
          ],
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "address"
            }
          ]
        },
        {
          "name": "isApprovedForAll",
          "type": "function",
          "inputs": [
            {
              "name": "owner",
              "type": "address"
            },
            {
              "name": "operator",
              "type": "address"
            }
          ],
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "bool"
            }
          ]
        },
        {
          "name": "name",
          "type": "function",
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "string"
            }
          ]
        },
        {
          "name": "owner",
          "type": "function",
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "address"
            }
          ]
        },
        {
          "name": "ownerOf",
          "type": "function",
          "inputs": [
            {
              "name": "tokenId",
              "type": "uint256"
            }
          ],
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "address"
            }
          ]
        },
        {
          "name": "renounceOwnership",
          "type": "function",
          "stateMutability": "nonpayable"
        },
        {
          "name": "safeMint",
          "type": "function",
          "inputs": [
            {
              "name": "to",
              "type": "address"
            },
            {
              "name": "tokenId",
              "type": "uint256"
            }
          ],
          "stateMutability": "nonpayable"
        },
        {
          "name": "safeTransferFrom",
          "type": "function",
          "inputs": [
            {
              "name": "from",
              "type": "address"
            },
            {
              "name": "to",
              "type": "address"
            },
            {
              "name": "tokenId",
              "type": "uint256"
            }
          ],
          "stateMutability": "nonpayable"
        },
        {
          "name": "safeTransferFrom",
          "type": "function",
          "inputs": [
            {
              "name": "from",
              "type": "address"
            },
            {
              "name": "to",
              "type": "address"
            },
            {
              "name": "tokenId",
              "type": "uint256"
            },
            {
              "name": "data",
              "type": "bytes"
            }
          ],
          "stateMutability": "nonpayable"
        },
        {
          "name": "setApprovalForAll",
          "type": "function",
          "inputs": [
            {
              "name": "operator",
              "type": "address"
            },
            {
              "name": "approved",
              "type": "bool"
            }
          ],
          "stateMutability": "nonpayable"
        },
        {
          "name": "supportsInterface",
          "type": "function",
          "inputs": [
            {
              "name": "interfaceId",
              "type": "bytes4"
            }
          ],
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "bool"
            }
          ]
        },
        {
          "name": "symbol",
          "type": "function",
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "string"
            }
          ]
        },
        {
          "name": "tokenURI",
          "type": "function",
          "inputs": [
            {
              "name": "tokenId",
              "type": "uint256"
            }
          ],
          "stateMutability": "view",
          "outputs": [
            {
              "name": "",
              "type": "string"
            }
          ]
        },
        {
          "name": "transferFrom",
          "type": "function",
          "inputs": [
            {
              "name": "from",
              "type": "address"
            },
            {
              "name": "to",
              "type": "address"
            },
            {
              "name": "tokenId",
              "type": "uint256"
            }
          ],
          "stateMutability": "nonpayable"
        },
        {
          "name": "transferOwnership",
          "type": "function",
          "inputs": [
            {
              "name": "newOwner",
              "type": "address"
            }
          ],
          "stateMutability": "nonpayable"
        }
      ],
      "events": [
        {
          "name": "Approval",
          "type": "event",
          "inputs": [
            {
              "name": "owner",
              "type": "address",
              "indexed": true
            },
            {
              "name": "approved",
              "type": "address",
              "indexed": true
            },
            {
              "name": "tokenId",
              "type": "uint256",
              "indexed": true
            }
          ],
          "anonymous": false
        },
        {
          "name": "ApprovalForAll",
          "type": "event",
          "inputs": [
            {
              "name": "owner",
              "type": "address",
              "indexed": true
            },
            {
              "name": "operator",
              "type": "address",
              "indexed": true
            },
            {
              "name": "approved",
              "type": "bool",
              "indexed": false
            }
          ],
          "anonymous": false
        },
        {
          "name": "OwnershipTransferred",
          "type": "event",
          "inputs": [
            {
              "name": "previousOwner",
              "type": "address",
              "indexed": true
            },
            {
              "name": "newOwner",
              "type": "address",
              "indexed": true
            }
          ],
          "anonymous": false
        },
        {
          "name": "Transfer",
          "type": "event",
          "inputs": [
            {
              "name": "from",
              "type": "address",
              "indexed": true
            },
            {
              "name": "to",
              "type": "address",
              "indexed": true
            },
            {
              "name": "tokenId",
              "type": "uint256",
              "indexed": true
            }
          ],
          "anonymous": false
        }
      ],
      "verificationStatus": "UNVERIFIED"
    }
  }
```

**Note:** Smart contract functions are defined using the Application Binary
Interface (ABI). Some important ABI properties are:

1. `name`: The function name. This is used in the `abiFunctionSignature` to
   select which function to call when reading from or executing a function on a
   smart contract.
2. `inputs`: The names and types of the arguments to the function. These
   parameters are passed to the `contracts/read` or
   `developer/transactions/contractExecution` APIs via the `abiParameters`
   property.
3. `outputs`: The output values when the function returns. Some functions do not
   return anything.
4. `stateMutability`: Defines how the function interacts with the blockchain.
   1. `view` and `pure` functions do not change the state of the blockchain, so
      these are `read` functions.
   2. `nonpayable` and `payable` functions update the state of the blockchain,
      so these are `execute` functions. `nonpayable` is the default for a
      function if no `stateMutability` property exists.

## 2. Contract Query Function

Once you have selected a read function from the list, you can send an API
request to `POST /contracts/query`. The example below is making a request to the
`owner()` function to check the current owner of the contract

**Notes:**

* The `abiFunctionSignature` is derived from the function name and the
  parenthesized list of parameter types. For instance, the
  `abiFunctionSignature` for a function named `testFunction` that takes an
  `address` and an `uint256` would be `testFunction(address,uint256)`.
* Read interactions *do not* require gas on the blockchain, so you are not
  required to a specify a wallet.
* A shortened `abiJson`, containing only the part of the ABI describing the
  `owner` function of the contract, was used to demonstrate, but ordinarily, the
  entire ABI would be included in the request.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  response = await client.queryContract({
    abiFunctionSignature: "owner()",
    address: "0x1e124d7384cd34448ea5907bd0052a79355ab5eb",
    blockchain: "MATIC-AMOY",
    abiJson:
      '[{"inputs": [],"name": "owner","outputs": [{"internalType": "address","name": "","type": "address"}],"stateMutability": "view","type": "function"}]',
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = smart_contract_platform.InteractApi(scpClient)
  try:
      request = smart_contract_platform.ReadContractStateRequest.from_dict({
          "abiFunctionSignature": "owner()",
          "address": "0x1e124d7384cd34448ea5907bd0052a79355ab5eb",
          "blockchain": "MATIC-AMOY",
          "abiJson": "[{\"inputs\": [],\"name\": \"owner\",\"outputs\": [{\"internalType\": \"address\",\"name\": \"\",\"type\": \"address\"}],\"stateMutability\": \"view\",\"type\": \"function\"}]"
      })
      response = api_instance.query_contract(request)
  except smart_contract_platform.ApiException as e:
      print("Exception when calling InteractApi->read_contract: %s\n" % e)
  ```

  ```curl Bash theme={null}
  curl --request POST \
    --url https://api.circle.com/v1/w3s/contracts/query \
    --header "Authorization: Bearer $API_KEY" \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{
        "abiFunctionSignature": "owner()",
        "address": "0x1e124d7384cd34448ea5907bd0052a79355ab5eb",
        "blockchain": "MATIC-AMOY",
        "abiJson": "[{\"inputs\": [],\"name\": \"owner\",\"outputs\": [{\"internalType\": \"address\",\"name\": \"\",\"type\": \"address\"}],\"stateMutability\": \"view\",\"type\": \"function\"}]"
      }'
  ```
</CodeGroup>

```json Response Body theme={null}
{
  "data": {
    "outputData": "0x000000000000000000000000D4D2DB6B4e42Db2c2C0797F009942b35e466DB29",
    "outputValues": ["0xD4D2DB6B4e42Db2c2C0797F009942b35e466DB29"]
  }
}
```

## 3. Contract Execution Function

Once you have chosen an execute function you can make a request to
`POST developer/transactions/contractExecution` or
`user/transactions/contractExecution`, for developer-controlled and
user-controlled wallets, respectively. The example below uses the
developer-controlled endpoint to call the `safeMint()` function to mint an NFT.
The function takes in two parameters: the `to` address and the assigned
`tokenId` for the NFT. The `abiFunctionSignature` is
`safeMint(address, uint256)`.

* **Note:** The `safeMint` function must be called by the `owner` of the
  contract. We specified this function modifier when generating the contract
  earlier.
* **Note:** Write functions *do* require gas on the blockchain, so a `walletId`
  must be specified in the request.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  const response = await circleDeveloperSdk.createContractExecutionTransaction({
    walletId: "ce714f5b-0d8e-4062-9454-61aa1154869b",
    contractAddress: "0x2f3A40A3db8a7e3D09B0adfEfbCe4f6F81927557",
    abiFunctionSignature: "safeMint(address, uint256)",
    abiParameters: ["0x6E5eAf34c73D1CD0be4e24f923b97CF38e10d1f3", 1],
    fee: {
      type: "level",
      config: {
        feeLevel: "MEDIUM",
      },
    },
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = developer_controlled_wallets.TransactionsApi(client)
  try:
      request = developer_controlled_wallets.CreateContractExecutionTransactionForDeveloperRequest.from_dict({
          "walletId": 'ce714f5b-0d8e-4062-9454-61aa1154869b',
          "contractAddress": '0x2f3A40A3db8a7e3D09B0adfEfbCe4f6F81927557',
          "abiFunctionSignature": 'safeMint(address, uint256)',
          "abiParameters": ['0x6E5eAf34c73D1CD0be4e24f923b97CF38e10d1f3', 1],
          "feeLevel": 'MEDIUM'
      })
      response = api_instance.create_developer_transaction_contract_execution(request)
      print(response)
  except developer_controlled_wallets.ApiException as e:
      print("Exception when calling TransactionsApi->create_developer_transaction_contract_execution: %s\n" % e)
  ```

  ```curl Bash theme={null}
  curl --request POST \
       --url 'https://api.circle.com/v1/w3s/developer/transactions/contractExecution' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --data '
  {
    "idempotencyKey":  "d6d56c67-9d8b-4e87-a618-1c44fa04a495",
    "walletId":  "ce714f5b-0d8e-4062-9454-61aa1154869b",
    "contractAddress": "0x1e124d7384cd34448ea5907bd0052a79355ab5eb",
    "abiFunctionSignature": "safeMint(address, uint256)",
    "abiParameters": [
      "0x6E5eAf34c73D1CD0be4e24f923b97CF38e10d1f3",
      1
    ],
    "feeLevel": "MEDIUM",
    "entitySecretCiphertext": "N8sYP20DJvujfnlSM4qirGXGN8Pr+FjgMWN7zHc96EiSJnPxoGviniZlNaLT..."
  }
  ```
</CodeGroup>

```json Response Body theme={null}
{
  "data": {
    "transactionId": "84cb1754-f236-4bfc-8562-70fa6ee168c8"
  }
}
```


# Contracts Templates
Source: https://developers.circle.com/contracts/scp-templates-overview

Deploy pre-audited smart contracts without writing Solidity code.

Smart contract templates are audited contracts that you can deploy using the
Contracts API. Each template uses a standard token format and has built-in
access control. You can deploy contracts in minutes without writing Solidity
code.

## Available templates

The table below lists all templates. Select a template to view its settings and
functions.

| Template                                       | Standard | Template ID                            | Use cases                                               |
| ---------------------------------------------- | -------- | -------------------------------------- | ------------------------------------------------------- |
| [Token](/contracts/erc-20-token)               | ERC-20   | `a1b74add-23e0-4712-88d1-6b3009e85a86` | Fungible tokens, loyalty points, governance tokens      |
| [NFT](/contracts/erc-721-nft)                  | ERC-721  | `76b83278-50e2-4006-8b63-5b1a2a814533` | Digital collectibles, gaming assets, tokenized assets   |
| [Multi-Token](/contracts/erc-1155-multi-token) | ERC-1155 | `aea21da6-0aa2-4971-9a1a-5098842b1248` | Mixed fungible and non-fungible tokens, batch transfers |
| [Airdrop](/contracts/airdrop)                  | N/A      | `13e322f2-18dc-4f57-8eed-4bddfc50f85e` | Bulk token distribution to multiple recipients          |

## Benefits of templates

Using templates instead of custom contracts has several benefits:

* **Security**: Third-party firms audit each template. This lowers the risk of
  common exploits.

* **Lower gas costs**: Templates use patterns that reduce transaction fees for
  you and your users.

* **Standard compliance**: Templates follow ERC standards. This ensures they
  work with wallets, marketplaces, and other blockchain tools.

* **Faster deployment**: Deploy contracts in minutes.

## Deploy a template

To deploy a template, send a `POST` request to the
[`/templates/{id}/deploy`](/api-reference/contracts/smart-contract-platform/deploy-contract-template)
endpoint with the template ID and your settings. For a full guide, see
[Deploy a smart contract](/contracts/scp-deploy-smart-contract).


# Circle Contracts Supported Blockchains
Source: https://developers.circle.com/contracts/supported-blockchains

Mainnet and testnet blockchains supported by Circle Contracts for smart contract deployment and management.

Circle Contracts is available on the following blockchains:

## Mainnet

| Blockchain  |
| ----------- |
| Arbitrum    |
| Avalanche   |
| Base        |
| Ethereum    |
| Monad       |
| OP Mainnet  |
| Polygon PoS |
| Unichain    |

## Testnet

| Blockchain       |
| ---------------- |
| Arbitrum Sepolia |
| Arc Testnet      |
| Avalanche Fuji   |
| Base Sepolia     |
| Ethereum Sepolia |
| Monad Testnet    |
| OP Sepolia       |
| Polygon PoS Amoy |
| Unichain Sepolia |


# Circle Payments Network
Source: https://developers.circle.com/cpn

Fast, cost-effective, and compliant global payments

Circle Payments Network (CPN) is a next-generation payment infrastructure
designed to reduce reliance on multiple intermediaries while enhancing
transparency, security, and speed. Using onchain primitives and built-in
compliance capabilities, CPN delivers near-instant cross-border settlement. CPN
allows participating financial institutions to rapidly expand their global
footprint with a single integration.

This developer documentation focuses on **Originating Financial Institutions
(OFIs)** that facilitate cross-border payments for their customers. The main
institution roles in CPN are:

<CardGroup>
  <Card title="OFIs" icon="building-columns">
    Work with senders, onramp fiat to crypto, and connect through CPN for
    cross-border payments.
  </Card>

  <Card title="BFIs" icon="hand-holding-dollar">
    Receive stablecoins through CPN and offramp into local fiat for receivers in
    the destination market.
  </Card>

  <Card title="CPN" icon="chart-network">
    Coordinates OFIs and BFIs by aggregating quotes, routing payments, and
    managing onchain settlement between participants.
  </Card>
</CardGroup>

CPN is part of Circle's broader ecosystem of financial products and is designed
to work with the USDC ecosystem for global payment operations.

## Prerequisites

As an OFI, plan for the following before onboarding:

* Access to USDC liquidity from your own sources or through Circle. If you use
  Circle, see
  [How-to: Set Up Circle On/Off-Ramps for CPN Payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments)
  for fiat-to-USDC and related transfers.
* A custodial or signing solution for USDC and technical capability to interact
  with blockchains (sign and observe transactions). If you use Circle for the
  operational wallet, see
  [How-to: Set Up a Circle Wallet for CPN Payments](/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments).
  If you use your own wallet stack, see
  [Bring your own wallet for CPN](/cpn/concepts/wallets/bring-your-own-wallet)
  and the
  [Wallet provider compatibility](/cpn/references/blockchains/wallet-provider-compatibility)
  reference.
* Established Know Your Customer (KYC) and Anti-Money Laundering (AML) processes
  in place for your customers

<Note>
  Circle Wallets and Circle On/Off-Ramps are **optional** capabilities for CPN.
  Many institutions already hold USDC and use their own wallets. The same
  developer documentation applies to every CPN customer; the linked how-tos are
  for teams that choose Circle for those layers. If you're a BFI or payout
  partner, Circle may reach out proactively as CPN grows.
</Note>

## Key features

<CardGroup>
  <Card title="Real-time FX quoting and locking" icon="chart-line">
    CPN returns quotes from several BFIs in one step and locks the FX rate for
    the payment, limiting exchange-rate risk for the OFI and customer.
  </Card>

  <Card title="Smart routing" icon="diagram-project">
    Each payment is assigned to a BFI according to the OFI's pricing and
    operational preferences, for example cost and settlement speed.
  </Card>

  <Card title="Stablecoin-powered transfers" icon="coins">
    Payments are settled using USDC across [supported
    blockchains](/cpn/references/blockchains/supported-blockchains) and
    exchanged to local fiat currencies for the receiver through the BFI.
  </Card>

  <Card title="API integration" icon="code">
    REST APIs and webhooks support payment flows and status monitoring, with
    detailed documentation and support for integrators.
  </Card>

  <Card title="End-to-end encryption" icon="lock">
    Travel rule and beneficiary account data is encrypted by the OFI throughout
    the payment process and can only be decrypted by the designated BFI.
  </Card>

  <Card title="Ticketing support" icon="ticket">
    CPN allows institutions to create and manage support tickets for payments,
    disputes, and reversals through the API. Circle handles routing and
    resolution across the network.
  </Card>
</CardGroup>

<Note>
  **CPN White Paper**

  Read the
  [CPN White Paper](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/PDFs/Whitepapers/CPN_Whitepaper.pdf)
  to learn more about the motivation for creating CPN and its intended use cases.
</Note>

## Entities in CPN

The following entities are referenced in this documentation and make up the key
entities that allow CPN to perform cross-border transactions.

* **Senders** (external): Businesses or individuals initiating cross-border
  payments
* **Receivers** (external): Businesses or individuals receiving cross-border
  payments
* **Originating Financial Institutions (OFIs)**: Financial institutions that
  interface with senders, onramp fiat to USDC, and connect with BFIs through CPN
  for transfer and fiat offramp
* **Beneficiary Financial Institutions (BFIs)**: Financial institutions that
  receive USDC from OFIs through CPN and provide an offramp to local fiat
  currency
* **Circle Payments Network (CPN)**: Orchestration layer that aggregates
  financial institutions, vets participants, and facilitates money movement
  through onchain and offchain services.

<Frame>
  <img />
</Frame>

## CPN workflow

The following is a generic example of how a payment in CPN is performed. In this
example, the OFI has a sender in the United States. The sender already has an
account and completed KYC with the OFI. The sender wants to pay a receiver in
Brazil. The sender wants to pay with USD and the receiver wants to receive the
payment in Brazilian real (BRL).

<Steps>
  <Step title="Quote generation">
    * OFI requests a list of quotes for the payment (USDC to BRL) from CPN
    * CPN aggregates quotes from multiple BFIs
    * CPN returns a list of quotes to the OFI
    * OFI selects the best quote or asks the sender to select their preferred
      quote
  </Step>

  <Step title="Payment creation">
    * Sender accepts the quote
    * OFI gets the requirements for travel rule data and beneficiary account
      information
    * OFI creates a payment request (USDC to BRL) in CPN
    * OFI collects and
      [encrypts](/cpn/guides/payments/encrypt-travel-rule-beneficiary-data)
      necessary payment details, such as travel rule data and beneficiary account
      information, and includes the encrypted data in the payment request
    * BFI reviews the travel rule data (and may [request additional
      information](/cpn/concepts/compliance/rfis)) and approves the payment
      request
  </Step>

  <Step title="Onchain transaction">
    * OFI ensures the required USDC balance is available in the operational
      wallet that will sign the transfer (onramping or internal treasury
      movements may be required first)
    * OFI requests an onchain transaction object to transfer USDC to the
      destination address from CPN to sign
    * OFI signs the onchain transaction object and sends it to CPN
    * CPN validates and broadcasts the transaction
    * CPN notifies the OFI and BFI when the onchain transaction is confirmed
  </Step>

  <Step title="Fiat settlement (no OFI action required)">
    * BFI initiates fiat payment after the onchain transaction is confirmed
      (transfer BRL to receiver's bank account)
    * BFI notifies CPN when the fiat payment is initiated and complete
    * CPN notifies the OFI with the appropriate payment statuses
  </Step>

  <Step title="Payment management">
    * OFI can query payment status at any time from the CPN API
    * CPN provides real-time status updates on the payment via webhooks
    * You can use payment history and reporting for reconciliation
  </Step>
</Steps>

## Get started

Run the OFI quickstart, learn how the CPN API fits together, then subscribe to
payment webhooks:

<CardGroup>
  <Card title="Integrate with CPN as an OFI" icon="rocket" href="/cpn/quickstarts/integrate-with-cpn-ofi">
    Request a quote, create a payment, complete the onchain USDC transfer, and
    track status using Transactions V1 or V2.
  </Card>

  <Card title="CPN Integration Concepts" icon="diagram-project" href="/cpn/concepts/api/api-integration">
    Understand how CPN APIs work together, including quotes, payments,
    transactions, and the JSON request and response model.
  </Card>

  <Card title="Set up Webhook Notifications" icon="bell" href="/cpn/guides/webhooks/setup-webhook-notifications">
    Expose a subscriber endpoint and register for CPN notifications so your
    systems react to payment and transaction updates.
  </Card>
</CardGroup>


# CPN Integration Concepts
Source: https://developers.circle.com/cpn/concepts/api/api-integration



This page discusses key concepts for integrating with CPN. Understanding these
concepts can help you integrate with CPN more effectively.

## Authentication

CPN authenticates your API requests using a unique key associated with your
account. All authentication is performed in the HTTP header of requests to the
API. If a key is not provided, or an incorrect key is provided, the API returns
a `401 - Invalid Credentials` error. All requests must use HTTPS; the API
rejects any requests using plain HTTP.

Circle provides API keys for authentication with the CPN API. These keys are
provided manually during onboarding. The following is an example of how to set
up the authentication header:

```shell Shell theme={null}
curl --location --request GET 'https://api.circle.com/v1/cpn/payments' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {YOUR_API_KEY}'
```

### Security notes

* Your API key provides full access to the CPN API, so make sure they are stored
  securely. They should never be exposed in public repositories and they should
  only be shared within your organization using secure methods. As a best
  practice, you should rotate your API keys periodically.
* When setting up your API key with Circle, you can request that only certain IP
  addresses be allowed to make API calls using the key. Talk to your Circle
  representative about establishing an IP allowlist for your API key.
* You should ensure that API requests are always made over TLS/encrypted
  connections to prevent the exposure of your key.
* For webhook subscriptions, you must provide an HTTPS endpoint, and validate
  the signature with Circle-provided public keys.

## Idempotency

For endpoints that create transactions and payments, CPN requires an idempotency
key to be included in the request body. The idempotency key must be in the UUID
∂v4 format. This allows the API to identify if a repeated request is unique or
duplicate, and prevent unintended duplicate transactions.

To generate an idempotency key, use a UUID generator in your selected
programming language. Generated UUIDs can then be passed to the API as
idempotency keys.


# JSON Schema
Source: https://developers.circle.com/cpn/concepts/api/json-schema



CPN uses [JSON Schema](https://json-schema.org/) to define and validate the
structure of JSON data used to pass RFI data. A JSON Schema is a blueprint for
the compliance data that OFIs must provide. CPN uses the
[Draft 2020-12](https://json-schema.org/draft/2020-12) version of the JSON
Schema standard.

Using JSON Schema to define the structure of this data has the following
benefits:

* **Clarity:** the schema defines every requirement programmatically, including
  required fields, data types, formats, and structures. This eliminates
  guesswork.
* **Client-side validation:** OFIs can validate their response against the
  schema before making the API call, providing instant feedback for developers
  and preventing common integration errors.
* **Rich data structures:** schemas support complex requirements like nested
  address objects and conditional logic.

## Interpreting JSON Schema

When you call the
[get details for an RFI endpoint](/api-reference/cpn/cpn-platform/get-rfi), the
API returns the JSON Schema for the required response data. The following are
key parts of the schemas to understand when reading them:

* `properties`: defines the fields you can provide in your JSON response
* `required`: contains a list of field names that must be present in the
  response
* `$defs` and `$ref`: usable complex objects (defined in `$defs` and referenced
  using the `$ref` directive)

## Client-side validation

JSON Schema allows you to validate your response before sending it to the API.
CPN expects that OFIs perform client-side validation against the provided schema
before submitting a response to CPN. Doing so provides a first line of defense
to reduce API errors and failed payments.

Common libraries for JSON Schema validation are:

* **Java:**
  [`networknt/json-schema-validator`](https://github.com/networknt/json-schema-validator)
* **Python:**
  [`jsonschema`](https://python-jsonschema.readthedocs.io/en/stable/)
* **Node.js:** [`ajv`](https://ajv.js.org/)

### Additional validation

JSON Schema validates structure and format only. You are still responsible for
ensuring the data is contextually correct. The schema ensures that you send the
data in the correct shape; you ensure the data is accurate. For example, you can
[validate CNPJ and CPF numbers using their check digits](/cpn/references/compliance/validating-brazil-tax-account-id).


# Requests for Information
Source: https://developers.circle.com/cpn/concepts/compliance/rfis



When a BFI needs more information about a sender or an
OFI, they create a Request for Information (RFI). This
additional information is required to meet regulatory or risk compliance checks.
The OFI is required to gather the appropriate information and respond to the
request in a set period of time. If the OFI does not respond in time, the
payment associated with the RFI is cancelled.

CPN defines [3 levels of RFI requests](/cpn/references/compliance/rfi-levels),
each with a specific set of fields. The OFI is expected to include all fields
specified by the level when responding to the RFI. Failure to provide the
appropriate fields can lead to payment failure.

The BFI can initiate an RFI at the following points of the payment process:

1. At payment creation
2. After the onchain transaction is complete, but before fiat payout
3. After the payment is complete

Depending on the point in the process where the RFI is created, the OFI may be
notified synchronously in an API response, or asynchronously by webhook. RFIs
are typically resolved by returning the relevant information through the API.
RFIs can also be raised and resolved through direct support tickets with CPN.


# CPN Component States and Workflows
Source: https://developers.circle.com/cpn/concepts/payments/component-states-and-workflows



This page contains information about the states that high-level components of
the CPN system can be in. Your integration should be able to handle and respond
to each of the various states that a given component may present. In some cases,
the state of a component requires immediate or rapid action from an OFI.
Reference these states as a way to confirm your integration is comprehensive.

## Payments

A payment represents the end-to-end CPN payment flow, including the onchain
transaction and RFI check. It is initiated by locking in a quote and providing
the required recipient details.

Payments have the following workflow:

<Frame>
  <img />
</Frame>

### Payment States

| State                    | Description                                                                                                                                                                                                                                                                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CREATED`                | A quote has been accepted and the payment is initialized.<br /><br />When a payment requires an RFI in the created state the RFI must be resolved before the payment can proceed.<br /><br />A payment can be in the created state without an associated RFI while the BFI completes its compliance check. This can take up to 1 business day to complete. |
| `CRYPTO_FUNDS_PENDING`   | The payment has passed a compliance check and is waiting for the onchain transaction of crypto.<br /><br />The OFI is required to complete the onchain transaction in order to proceed.                                                                                                                                                                    |
| `FIAT_PAYMENT_INITIATED` | The BFI has received and validated the crypto transfer and has initiated the fiat payment.                                                                                                                                                                                                                                                                 |
| `COMPLETED`              | The BFI has completed the fiat transfer. Depending on the transfer method, the receiver may or may not have received the transfer.                                                                                                                                                                                                                         |
| `FAILED`                 | The payment can't be completed.                                                                                                                                                                                                                                                                                                                            |

A payment can also include an optional `statusAddendum` field that provides
additional context about the current payment status. This field does not
represent a separate state — it supplements the main `status` field. CPN omits
`statusAddendum` from the response when no additional context applies.

| Status addendum              | Associated status        | Description                                                                                                                        |
| ---------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `IN_MANUAL_REVIEW`           | `CREATED`                | The payment is on hold for a compliance or manual review. The payment remains in the `CREATED` state until the review is complete. |
| `PAYMENT_SETTLEMENT_DELAYED` | `FIAT_PAYMENT_INITIATED` | Settlement timing has slipped. The payment remains in progress while the delay is resolved.                                        |

When a payment is initiated, the BFI performs an initial payment review, which
affects the state that the payment is created in:

* If the BFI approves the initial payment review outright, the payment is
  created in the `CRYPTO_FUNDS_PENDING` state.
* If the BFI rejects the initial payment review outright, the payment is created
  in the `FAILED` state.
* If the BFI needs to take additional steps to review the payment, the payment
  is created in the `CREATED` state. Final approval or rejection of the payment
  is sent asynchronously.

## RFIs

Requests for information (RFI) is a process that is initiated by the BFI when
more detailed information about the sender is required to meet regulatory or
risk compliance checks.

RFIs have the following workflow:

<Frame>
  <img />
</Frame>

### RFI states

| State                  | Description                                                                                                                      |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `INFORMATION_REQUIRED` | Initial status. OFI is required to submit the requested data to resolve the RFI.                                                 |
| `IN_REVIEW`            | OFI has submitted the requested data and BFI is reviewing.                                                                       |
| `APPROVED`             | BFI approves the additional information.                                                                                         |
| `FAILED`               | BFI rejects the additional information. This is a resolved state where the OFI can't resubmit additional information to the BFI. |

## Refunds

Refunds occur when the BFI can't complete the transfer of fiat to the receiver.
The BFI creates an onchain transaction to transfer the cryptocurrency back to
the OFI.

Refunds have the following workflow:

<Frame>
  <img />
</Frame>

### Refund states

| State       | Description                                                                                                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CREATED`   | The refund is initialized but the onchain transaction has not been created yet. Some BFIs may skip this status and create the refund directly into the `COMPLETED` or `FAILED` state. |
| `FAILED`    | The onchain transaction failed.                                                                                                                                                       |
| `COMPLETED` | The onchain transaction was successfully broadcast and confirmed by the BFI. The transaction hash is available.                                                                       |

## Transactions

A transaction on CPN is a data object that represents a funds transfer
transaction on the blockchain. When the payment is in the `CRYPTO_FUNDS_PENDING`
state, the OFI should initiate the onchain transaction with CPN as soon as
possible.

Transactions have the following workflow:

<Frame>
  <img />
</Frame>

### Transaction states

| State         | Description                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `CREATED`     | Transaction has been created and the payload returned to the caller, awaiting signature.          |
| `PENDING`     | OFI has submitted the signed transaction. The transaction is pending broadcast to the blockchain. |
| `BROADCASTED` | The signed transaction has been broadcast to the blockchain.                                      |
| `COMPLETED`   | The transaction is confirmed onchain.                                                             |
| `FAILED`      | The transaction can't be completed.                                                               |

## Support tickets

The CPN support tickets API allows you to raise and manage transaction-related
issues such as settlement delays, missing information, or refunds. These tickets
are stored in the CPN platform and routed to the appropriate party for
resolution.

<Frame>
  <img />
</Frame>


# Payment Reference
Source: https://developers.circle.com/cpn/concepts/payments/payment-reference



When you
[create a payment with the CPN API](/api-reference/cpn/cpn-platform/create-payment),
you should provide the `refCode` field to carry a meaningful reference for the
transaction. This field can be either an invoice ID or a customer reference. How
this reference appears on the beneficiary's bank statement depends on the
capabilities of the payment rail, which is handled as follows:

* **Metadata support by rail and BFI:** The sender's name (OFI's customer name)
  from the travel rule data appears directly on the recipient's bank statement
  as the ultimate remitter, and the `refCode` appears in the memo field. This
  provides the highest level of transparency for the recipient to recognize and
  reconcile the payments.
* **Partial metadata support:** If the payment rail doesn't support displaying
  the sender's name separately but allows a memo/reference field, the BFI
  populates this memo with a concatenated string in the format
  `{refCode} + {Sender Name}`
* **Minimal metadata support:** If neither the sender name or reference field is
  supported on the rail, Circle returns a `fiatNetworkPaymentRef`, which is a
  rail-specific transaction reference. This ID is visible to the beneficiary on
  their bank statement, and is returned to the OFI by webhook and in the
  [get payment endpoint](/api-reference/cpn/cpn-platform/get-payment).


# Payment
Source: https://developers.circle.com/cpn/concepts/payments/payments



A payment represents the end-to-end CPN payment flow, including the onchain
transaction and RFI check. It is initiated by locking in a quote and providing
the required recipient details.

The payment process begins when an OFI locks in a quote and submits sender and
beneficiary details. The transaction undergoes compliance checks, including the
RFI process if required. Once all necessary compliance checks are completed, the
payment enters the onchain transaction phase, where it awaits the transfer of
USDC. After the crypto transfer is received, the BFI initiates a fiat transfer
to the final recipient.

During the fiat transfer, the CPN sends webhook notifications to the OFI
indicating that the transfer has been confirmed or canceled. If the fiat
transfer is canceled or fails for any reason, the BFI issues a refund of crypto
to the OFI.


# Quotes
Source: https://developers.circle.com/cpn/concepts/quotes



Quotes are real-time exchange rates and settlement costs for a specific payment
corridor. A quote includes the following key elements:

* **Exchange rate lock**: The quote locks in an exchange rate for a specified
  time window, protecting both the OFI and the sender from market volatility
  during the payment process. When the time window expires, a new quote must be
  requested.
* **Two-way quotes**: You may query the quote based on the source amount and the
  destination amount. For instance, if a customer holding USDC wants to pay a
  recipient in BRL and the recipient needs an accurate amount of BRL, you can
  query using the destination amount. If a quote is for a remittance use case,
  where the customer needs an accurate amount of USDC to send, you can query
  using the source amount.
* **Cost breakdown**: The quote response includes details of all applicable
  fees, including fee and any additional charges at the transaction level,
  ensuring transparent cost estimation.
* **Competitive aggregation**: By providing multiple quotes, CPN ensures that
  OFIs can choose the most competitive option based on price, speed, and
  compliance.


# Block Confirmation and Transaction Finality
Source: https://developers.circle.com/cpn/concepts/transactions/block-confirmation-and-finality



When you submit a transaction to CPN, it is initially in the `pending` state and
waiting to be broadcast to the blockchain. Once the transaction is broadcast to
the blockchain, it transitions to the `broadcasted` state, and the transaction
is waiting to be included in a block.

CPN monitors each block of supported blockchains and the status of CPN
transactions on those chains, updating the status as necessary.

## Block confirmation

Block confirmation is the process of validating and adding transactions to a
block on a blockchain. Each time a new block is added to a blockchain, it
confirms the previous blocks.

Without a sufficient number of confirmations, transactions are vulnerable to
alteration through blockchain reorganization. Blockchain reorganization occurs
when validators discard one or more blocks that were previously part of the
canonical chain and replace them with a different set of blocks, rewriting part
of the chain.

<Note>
  **Note:** Blockchain reorganizations can happen for a variety of reasons. It's
  an engineering best practice to expect reorganizations and make your system
  resilient to them.
</Note>

Each additional block confirmation added after a block makes that block less
likely to be removed in a reorganization. Each block confirmation adds
confidence that the transaction is permanently included in the blockchain.

## Confirmation number

For a given block, the confirmation number is the number of subsequent blocks
added to the blockchain.

For a given transaction included in a block, CPN waits for a set number of
blocks (in addition to the original) to be added to the chain before it
considers the transaction final. This number varies across supported
blockchains. When a sufficient number of blocks are appended after the original
block, CPN updates the status of the transaction to `completed` and notifies
both the OFI and BFI of the status change.

<Note>
  **Note:** Even if a transaction is visible on a block explorer, it doesn't
  necessarily mean that the transaction is considered `completed` by CPN,
  because it's possible that it hasn't reached the number of block confirmations
  for finality.
</Note>

## Reorganization risk

Although Circle may broadcast transactions initiated through CPN to the
blockchain network, Circle cannot guarantee that the transaction is recorded or
permanently confirmed by the network. Transactions over CPN may be dependent on
underlying blockchain networks that Circle does not control, and CPN
Participants assume all risks associated with the blockchain network operations
and any operating changes, including in the unlikely event of a deep
reorganization or other invalidation of previously confirmed transactions.

Circle shall not be liable for any loss or damage arising from issues with, or
any delays, reversals, or failures of transactions caused by such operations and
operating changes.


# Transaction
Source: https://developers.circle.com/cpn/concepts/transactions/transaction-overview



A transaction in the CPN API represents a transfer of funds onchain to fund the
payment. Once payment is in the `CRYPTO_FUNDS_PENDING` status, the OFI should
create the onchain transaction using CPN's transaction endpoints. Through these
endpoints, the OFI can initiate and broadcast the transaction. The OFI uses its
own wallet integration to sign transactions before sending them to the API. CPN
provides transaction updates through webhooks. Transactions follow these steps:

1. The OFI initiates a transaction request, and Circle returns the raw
   transaction data
2. The OFI validates the response and signs the transaction
3. The OFI submits the signed transaction to the CPN API
4. CPN verifies the transaction content and broadcasts it to the blockchain
5. CPN notifies the OFI and the BFI of the transaction status


# Transactions V2
Source: https://developers.circle.com/cpn/concepts/transactions/transactions-v2



CPN supports two versions of onchain transactions: V1 and an optional upgrade,
V2, which enables secure and compliant stablecoin settlement across all
blockchains that
[CPN supports](/cpn/references/blockchains/supported-blockchains). Both deliver
the same core payment capabilities but differ in how gas fees, signing, and
orchestration are managed.

## Gas abstraction

Transactions V2 provides gas abstraction which removes the requirement for you
to pay native tokens for gas fees during transaction broadcast. This provides a
lower-complexity operational model for you by eliminating the need to acquire
and maintain a native token balance in your wallet.

When a Transaction V2 quote is created, the `fees` field includes a fixed gas
fee denoted in USDC. This gas fee is valid as long as the payment remains
active. During transaction settlement, the payment settlement smart contract
withdraws the fee amount from your wallet and distributes it to the beneficiary.

The transaction fee you pay is fixed regardless of fluctuations of the native
blockchain gas fee levels. CPN ensures that the transaction gets broadcast
accurately and on time. This removes the need for manual acceleration and
monitoring by delegating it to CPN.

## EVM payment settlement contract and `Permit2`

In EVM blockchains, Transactions V2 uses a payment settlement smart contract
that allows you to send verified payments to the BFI that are authorized by you,
an attester (CPN), and (optionally) the BFI. The contract ensures that the
transaction is accurate and correct, and can serve as proof of payment after the
transaction has settled.

Unlike Transactions V1, which uses EIP-3009 for token approvals, the payment
settlement contract uses the `Permit2` contract, Uniswap's universal token
approval system. `Permit2` makes integrations more straightforward by using
gasless, offchain signatures for token transfers. `Permit2` permits are
signature-based, time-bound, and single-use.

The payment settlement smart contract uses `Permit2` to execute funds transfer
from your wallet to the recipient wallet in a single contract execution. In
practice, this means that you sign an EIP-712 typed-data message of the
`PermitWitnessTransferFrom` method call to allow the payment settlement smart
contract to transfer USDC out of your wallet and into the recipient wallet.

```json JSON theme={null}
{
  "types": {
    "EIP712Domain": [
      {
        "name": "name",
        "type": "string"
      },
      {
        "name": "chainId",
        "type": "uint256"
      },
      {
        "name": "verifyingContract",
        "type": "address"
      }
    ],
    "PermitWitnessTransferFrom": [
      { "name": "permitted", "type": "TokenPermissions" },
      { "name": "spender", "type": "address" },
      { "name": "nonce", "type": "uint256" },
      { "name": "deadline", "type": "uint256" },
      { "name": "witness", "type": "PaymentIntent" }
    ],
    "TokenPermissions": [
      { "name": "token", "type": "address" },
      { "name": "amount", "type": "uint256" }
    ],
    "PaymentIntent": [
      { "name": "from", "type": "address" },
      { "name": "to", "type": "address" },
      { "name": "value", "type": "uint256" },
      { "name": "validAfter", "type": "uint256" },
      { "name": "validBefore", "type": "uint256" },
      { "name": "nonce", "type": "bytes32" },
      { "name": "beneficiary", "type": "address" },
      { "name": "maxFee", "type": "uint256" },
      { "name": "requirePayeeSign", "type": "bool" },
      { "name": "attester", "type": "address" }
    ]
  },
  "domain": {
    "name": "Permit2",
    "chainId": 11155111,
    "verifyingContract": "PERMIT2_ADDRESS"
  },
  "message": {
    "permitted": {
      "token": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "amount": "100050000"
    },
    "spender": "CPN_SMART_CONTRACT_ADDRESS",
    "nonce": "0",
    "deadline": "1234567890",
    "witness": {
      "from": "OFI_PAYER_ADDRESS",
      "to": "BFI_PAYEE_ADDRESS",
      "value": "100000000",
      "validAfter": "0",
      "validBefore": "1234567890",
      "nonce": "ONCHAIN_PAYMENT_REF",
      "beneficiary": "CIRCLE_BENEFICIARY_ADDRESS",
      "maxFee": "50000",
      "requirePayeeSign": false,
      "attester": "CPN_WALLET_ADDRESS"
    }
  },
  "primaryType": "PermitWitnessTransferFrom"
}
```

### `Permit2` allowance

The use of `Permit2` requires you to grant an allowance of USDC to the `Permit2`
contract ahead of the payment. This allowance grants the `Permit2` contract
permission to transfer USDC from your wallet in a CPN settlement. When you sign
a CPN transaction, that transaction allows the payment settlement contract to
consume the USDC allowance previously granted to `Permit2`.

The allowance amount can be set to a specific value based on the expected
payment volume or to the maximum `uint256` value for unlimited transfers. The
allowance is the foundational authorization that makes the entire CPN payment
settlement system possible through `Permit2`'s signature-based transfer
mechanism.


# Wallet Nonce Management
Source: https://developers.circle.com/cpn/concepts/transactions/wallet-nonce-management



<Note>
  **Note:** This topic applies to EVM blockchains only, and is only a
  requirement for Transactions V1. For [Transactions
  V2](/cpn/concepts/transactions/transactions-v2), nonces are managed by CPN so
  you don't need to actively manage them.
</Note>

This topic explains how nonces work in Ethereum Virtual Machine (EVM)
transactions. It also gives you tips for managing nonces when you handle many
transactions at once.

Before you read this, you should know the basics about EVM wallets and how
transactions are signed.

## What is a nonce?

In EVM-based blockchains, a wallet nonce is a counter. It tracks how many
transactions you sent from a specific wallet address. Each transaction must use
a different nonce. You must use nonces in order, one after another.

Key points:

* New wallets start with nonce 0
* Each successful transaction adds 1 to the nonce
* You must use nonces in order (no gaps)
* Each wallet address has its own nonce count

## Nonce conflicts in concurrent transactions

Problems can happen when you create many transactions at the same time from one
wallet address.

This problem often happens when many users create transactions at once, and your
system uses the same EVM wallet for all these requests.

When signing transactions, multiple threads in your system might try to get the
wallet's current nonce at the same time. If this race condition occurs, multiple
transactions might get assigned the same nonce number. When this occurs, only
the first transaction works. The others fail.

Another common problem happens when transactions get stuck in the blockchain's
mempool and block later transactions. Here's an example:

* Your CPN integration signs two transactions from the same wallet in the right
  order:
  * Transaction A with nonce 5
  * Transaction B with nonce 6
* Transaction A gets rejected by CPN because it has the wrong parameters
* Transaction B goes to the blockchain but gets stuck in the mempool because the
  blockchain needs nonce 5 first
* All future transactions from this wallet get blocked until you fix the gap

## Best practices for managing nonces

Your integration may vary based on your systems. Here are some general tips for
managing nonces:

**Set up one central system to track nonces for each wallet.** This system
should safely handle nonce assignment when multiple threads request to sign
transactions at once. Make sure each nonce gets assigned only once to prevent
duplicates. You can use a locking system or a queue system to manage nonce
assignment when handling multiple operations.

**Keep your system in sync with the blockchain to track the latest nonce
numbers.** Your local nonce tracking should reset its counter if it gets out of
sync with the blockchain's nonce state. Set up regular health checks to find
nonce gaps.

You should sync with the blockchain:

* Before starting new transaction batches
* After transactions fail or get rejected
* When your systems restart after downtime


# Bring Your Own Wallet for CPN
Source: https://developers.circle.com/cpn/concepts/wallets/bring-your-own-wallet

How using your own wallet infrastructure fits into Circle Payments Network integrations.

Circle Payments Network (CPN) requires a blockchain wallet to sign and submit
USDC transfer transactions on behalf of your organization. Circle doesn't
require this wallet to be a [Circle Wallet](/wallets/dev-controlled.mdx).
Institutions that already custody USDC and operate keys through an in-house or
third-party wallet stack can use that existing infrastructure with CPN.
Originating Financial Institutions (OFIs) that hold their own USDC often choose
this Bring Your Own Wallet (BYOW) approach and it's available on all
[blockchains that CPN supports](/cpn/references/blockchains/supported-blockchains).

## When to bring your own wallet

Bring Your Own Wallet (BYOW) is a good fit when your organization:

* Already operates wallet infrastructure with established key-management
  procedures.
* Requires custody arrangements that are specific to your compliance or
  regulatory environment.
* Manages USDC balances and blockchain interactions through an existing
  third-party provider.

If none of these apply, you can have Circle host the operational wallet instead.
See how to
[Set up a Circle wallet for CPN payments](/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments).

## Your responsibilities

When you bring your own wallet, you take on operational responsibilities that
Circle otherwise handles. The following table summarizes how those
responsibilities are divided.

| Responsibility                            | BYOW | Circle-hosted wallet |
| ----------------------------------------- | ---- | -------------------- |
| Key management and signing                | You  | Circle               |
| Blockchain support and connectivity       | You  | Circle               |
| Nonce handling                            | You  | Circle               |
| USDC balance management                   | You  | You                  |
| Native gas token funding (where required) | You  | Circle               |

<Note>
  Nonce handling requirements differ between CPN Transactions V1 and V2. V1
  requires you to manage nonces directly; V2 provides unsigned transaction data
  that includes nonce values. See the [Create Transaction
  V2](/api-reference/cpn/cpn-platform/create-transaction-v2) endpoint for
  details.
</Note>

Your wallet implementation must satisfy the technical expectations described in
[Wallet provider compatibility](/cpn/references/blockchains/wallet-provider-compatibility).

## How CPN works with your wallet

Regardless of which wallet option you choose, you interact with the same CPN
APIs. Payment creation, settlement, and reporting work identically; only the
custody and signing layer differs. If you use Transactions V1, your wallet also
manages nonce selection; V2 returns a complete unsigned payload.

The interaction between CPN and your wallet follows this pattern:

1. You call the CPN
   [Create Transaction](/api-reference/cpn/cpn-platform/create-transaction-v2)
   endpoint to prepare unsigned transaction data for a payment.
2. CPN returns unsigned transaction data (the payload your wallet needs to
   sign).
3. Your wallet infrastructure signs the transaction using its own key-management
   system.
4. You submit the signed transaction back to CPN through the
   [Submit Transaction](/api-reference/cpn/cpn-platform/submit-transaction-v2)
   endpoint.
5. CPN validates the signed transaction and broadcasts it to the blockchain.
6. CPN sends
   [webhook notifications](/cpn/guides/webhooks/setup-webhook-notifications)
   with transaction status updates.

<Note>
  CPN never accesses your private keys. It issues payment instructions that your
  wallet infrastructure executes by signing and submitting transactions to the
  appropriate blockchain.
</Note>

The same CPN transaction APIs apply whether you sign with Circle or with your
own keys, so migrating between a Circle-hosted wallet and BYOW does not require
changes to your CPN integration logic. For a full walkthrough, see the
[Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi)
quickstart.


# Webhook Retries
Source: https://developers.circle.com/cpn/concepts/webhooks/webhook-retries



When a webhook can't be delivered successfully (2xx status code returned), CPN
continues to try to deliver the webhook. To avoid encountering the same
transient error too many times, the retries are sent with a delay between them.
The number of retries varies between testing and production:

* **Testing:** 6 retries
* **Production:** 11 retries

The following table outlines the schedule for webhook retries:

| Retry attempt | Delay      |
| ------------- | ---------- |
| 1             | 1 second   |
| 2             | 10 seconds |
| 3             | 30 seconds |
| 4             | 1 minute   |
| 5             | 15 minutes |
| 6             | 1 hour     |
| 7             | 3 hours    |
| 8             | 5 hours    |
| 9             | 6 hours    |
| 10            | 10 hours   |
| 11            | 11 hours   |


# How-to: Set Up Circle On/Off-Ramps for CPN Payments
Source: https://developers.circle.com/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments

Use Circle APIs to move fiat and USDC in support of CPN payment flows (onramp liquidity and optional offramp).

This guide shows how to use Circle Mint account APIs for CPN payment flows when
using Circle for treasury and settlement. Use it to onramp fiat into USDC and
fund your operational wallet, and to offramp USDC to fiat when you need to.

## Overview

* Use this guide when you want Circle to supply USDC liquidity (fiat in, USDC to
  your operational wallet) or to offramp USDC to fiat.
* CPN does not require Circle on/off-ramps. You can source USDC from any
  compliant channel that meets your compliance and settlement needs.
* Circle on/off-ramp behavior is provided by Circle APIs (Circle Mint and
  related account APIs). Start with
  [Getting started with the Circle APIs](/circle-mint/quickstarts/getting-started)
  for authentication and environments.

<Note>
  Each step links to the Circle Mint API reference page for that operation,
  where request and response fields are fully defined. The steps map those
  Circle APIs to CPN scenarios.
</Note>

## Prerequisites

Before you begin, ensure you have:

* A [CPN Console](https://cpn.circle.com/signin) account with the Circle
  On/Off-Ramps capability enabled for your organization (after your CPN
  eligibility application is approved).
* An API key with Circle On/Off-Ramps (Circle APIs) permissions. Create and
  manage keys in
  [CPN Console → Developer → API Keys](https://cpn.circle.com/signin).
* Sandbox or mainnet access enabled for Circle On/Off-Ramps.
* An operational wallet address for USDC. To use a Circle wallet, see
  [Set up a Circle Wallet for CPN payments](/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments);
  otherwise use your own wallet infrastructure.

<Note>
  Mainnet access for Circle On/Off-Ramps is typically granted after your CPN
  eligibility application is approved and you request that capability. Sandbox
  uses the same request and response structure as production.

  This guide uses **Circle Mint** account APIs. For Mint, use the sandbox and
  production [API hosts](/circle-mint/references/sandbox-and-testing) and the API
  key for each environment. **CPN Platform** payment APIs use one base URL: the
  API key determines whether requests run in sandbox or production.
</Note>

## Onramp: Deposit fiat and transfer USDC to your operational wallet

As an Originating Financial Institution (OFI), you convert fiat to USDC and move
USDC to the wallet that signs CPN onchain transfers.

### Step 1: Link your bank account

Register the bank account you use to send fiat deposits. Use
[Create wire bank account](/api-reference/circle-mint/account/create-business-wire-account)
(`POST /v1/businessAccount/banks/wires`). For a guided walkthrough, see
[Deposit Fiat](/circle-mint/howtos/deposit-fiat).

### Step 2: Retrieve wire instructions and send funds

Retrieve instructions with
[Get wire transfer instructions](/api-reference/circle-mint/account/get-business-wire-account-instructions)
(`GET /v1/businessAccount/banks/wires/{id}/instructions`). Send the wire from
your bank. Include the tracking reference (or equivalent memo) Circle provides
so the deposit can be matched to your account.

In sandbox, simulate a deposit with
[Create mock wire payment](/api-reference/circle-mint/account/create-mock-wire-payment)
(`POST /v1/mocks/payments/wire`). Mock wires can take up to 15 minutes to
process.

### Step 3: Confirm your Circle business account balance

After the deposit is credited, confirm USDC with
[List balances](/api-reference/circle-mint/account/list-business-balances)
(`GET /v1/businessAccount/balances`).

### Step 4: Configure notifications for deposit status (optional)

Optionally subscribe to status notifications so your backend learns when a
deposit completes. Use
[Create subscription](/api-reference/circle-mint/general/create-subscription)
(`POST /v1/notifications/subscriptions`). The request body requires a public
HTTPS endpoint that can complete the AWS SNS subscription handshake (see the API
reference and
[Notifications quickstart](/circle-mint/circle-apis-notifications-quickstart)):

```json theme={null}
{
  "endpoint": "https://your-endpoint.example.com/webhooks"
}
```

Notification payloads use a `notificationType` field. For flows in this guide,
common values include `transfers` (onchain transfers) and `payouts` (bank
payouts); see
[Notifications data models](/circle-mint/notifications-data-models) for payload
shapes.

You can also manage subscriber endpoints in
[CPN Console → Developer → Webhooks](https://cpn.circle.com/signin) when your
organization exposes that UI for your Circle APIs integration.

### Step 5: Transfer USDC to your operational wallet

Allowlist your operational wallet address with
[Create recipient address](/api-reference/circle-mint/account/create-business-recipient-address)
(`POST /v1/businessAccount/wallets/addresses/recipient`), then send USDC onchain
with
[Create transfer](/api-reference/circle-mint/account/create-business-transfer)
(`POST /v1/businessAccount/transfers`). Track completion with
[Get transfer](/api-reference/circle-mint/account/get-business-transfer)
(`GET /v1/businessAccount/transfers/{id}`).

Example body for **create recipient** (see the API reference for all fields and
valid `chain` values; `description` is required):

```json theme={null}
{
  "idempotencyKey": "<unique_key>",
  "address": "<your_operational_wallet_address>",
  "chain": "ETH",
  "currency": "USD",
  "description": "CPN operational wallet"
}
```

Example body for **create transfer** with destination type `blockchain`:

```json theme={null}
{
  "idempotencyKey": "<unique_key>",
  "source": { "type": "wallet", "id": "merchant" },
  "destination": {
    "type": "blockchain",
    "address": "<your_operational_wallet_address>",
    "chain": "ETH"
  },
  "amount": { "amount": "<usdc_amount>", "currency": "USD" }
}
```

When the transfer completes, your operational wallet is ready for CPN onchain
steps.

A successful create-transfer response returns a `status` of `pending` and a
transfer `id`. Poll
[Get transfer](/api-reference/circle-mint/account/get-business-transfer)
(`GET /v1/businessAccount/transfers/{id}`) until the status reaches `complete`.
If the status is `failed`, check the `errorCode` field: common values include
`transfer_failed`, `transfer_denied`, and `insufficient_funds`. Do not reuse the
same `idempotencyKey` for a new request with different parameters; retrying with
identical parameters returns the original response. See
[API errors](/circle-mint/circle-apis-api-errors#transfer-error-codes) and
[Idempotent requests](/circle-mint/references/sandbox-and-testing#idempotent-requests).

## Offramp: Receive USDC and pay out to your bank account

As an OFI, you may need to offramp USDC to fiat: for example, when converting
received USDC to local currency, handling payment failures, or processing
returns. The steps below reverse the onramp flow: deposit USDC into your Circle
business account and initiate a bank payout.

### Step 1: Link your bank account

Use
[Create wire bank account](/api-reference/circle-mint/account/create-business-wire-account)
(`POST /v1/businessAccount/banks/wires`) for the account that will receive fiat
payouts.

### Step 2: Create a deposit address for your Circle business account

Generate an onchain deposit address with
[Create deposit address](/api-reference/circle-mint/account/create-business-deposit-address)
(`POST /v1/businessAccount/wallets/addresses/deposit`). USDC sent to that
address credits your Circle business account balance.

Example body (see the API reference for required fields and valid `chain`
values):

```json theme={null}
{
  "idempotencyKey": "<unique_key>",
  "currency": "USD",
  "chain": "ETH"
}
```

### Step 3: Configure notifications for inbound activity

Subscribe with
[Create subscription](/api-reference/circle-mint/general/create-subscription)
(`POST /v1/notifications/subscriptions`) using an HTTPS endpoint as in the
onramp step. Your handler receives payloads whose `notificationType` values are
documented in
[Notifications data models](/circle-mint/notifications-data-models). For
example, `transfers` notifications reflect onchain transfer status changes.
Where available, you can configure endpoints in
[CPN Console → Developer → Webhooks](https://cpn.circle.com/signin), in addition
to using the API.

CPN payment lifecycle events still use CPN subscriptions (see
[Webhook events](/cpn/references/webhooks/webhook-events)).

### Step 4: Offramp USDC to your bank account

Verify your balance with
[List balances](/api-reference/circle-mint/account/list-business-balances)
(`GET /v1/businessAccount/balances`), then create a payout with
[Create payout](/api-reference/circle-mint/account/create-business-payout)
(`POST /v1/businessAccount/payouts`).

Example body (see the API reference for all required fields):

```json theme={null}
{
  "idempotencyKey": "<unique_key>",
  "destination": {
    "type": "wire",
    "id": "<your_bank_account_id>"
  },
  "amount": { "amount": "<usdc_amount>", "currency": "USD" }
}
```

A successful response returns a `status` of `pending` and a payout `id`. Track
completion with
[Get payout](/api-reference/circle-mint/account/get-business-payout)
(`GET /v1/businessAccount/payouts/{id}`). The payout moves through `pending` to
`complete` or `failed`. If the status is `failed`, check the `errorCode` field —
common values include `insufficient_funds`, `transaction_denied`, and
`bank_transaction_error`. See
[API errors](/circle-mint/circle-apis-api-errors#payout-error-codes) and
[Idempotent requests](/circle-mint/references/sandbox-and-testing#idempotent-requests).

## See also

* With your operational wallet funded, return to
  [Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi) at
  Part 1: Request a quote.
* [Set up a Circle Wallet for CPN payments](/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments)
  for operational wallet setup with Circle dev-controlled wallets.


# How-to: Respond to an RFI
Source: https://developers.circle.com/cpn/guides/compliance/respond-to-rfi



This guide explains how to respond to an RFI request that is system-initiated.
In a system-initiated RFI, you are notified either synchronously when a payment
is created, or asynchronously by an RFI webhook.

This guide doesn't cover how to respond to an RFI when it is initiated by a
support ticket. For RFIs initiated this way, you must follow the support ticket
workflow.

## Steps

When a system-initiated RFI is created by a BFI, you are notified in one of two
ways:

1. In the synchronous response to the payment creation endpoint. When you create
   a payment, the endpoint responds with the created payment record containing a
   non-null `activeRfi` field.
2. Asynchronously by an RFI webhook. This can occur at any time in the payment
   flow after the payment is created. The RFI webhook doesn't contain the entire
   RFI object.

Once you have the full RFI object, you can use the following steps to respond to
the RFI.

### Step 1: Get the RFI requirements and certificate

Before you respond to an RFI, you need to get the requirements and the
certificate used for encrypting RFI responses.

The RFI requirements are available in the RFI object. If the RFI was created
synchronously, the full object is included in the `activeRfi` field of the
payment object. If the RFI was created asynchronously, you must retrieve the
full object using the
[get details for an RFI endpoint](/api-reference/cpn/cpn-platform/get-rfi). The
following is an example RFI object:

```json JSON theme={null}
{
  "id": "48dfd36c-cf6c-4d9d-b065-69bdbe9bfea1",
  "paymentId": "90dfd86c-cf6c-4d9d-b065-69bdbe9bfec8",
  "status": "INFORMATION_REQUIRED",
  "level": "LEVEL_1",
  "expireDate": "2025-01-28T19:41:33.076Z",
  "fieldRequirements": {
    "version": 1,
    "schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "title": "RFI Requirements",
      "type": "object",
      "description": "RFI Requirements",
      "properties": {
        "DATE_OF_BIRTH": {
          "description": "Individual's date of birth (YYYY-MM-DD)",
          "type": "string"
        },
        "NAME": {
          "description": "Individual's full name",
          "type": "string"
        }
      },
      "required": ["NAME", "DATE_OF_BIRTH"]
    }
  },
  "fileRequirements": [
    {
      "fileName": "PROOF_OF_ADDRESS",
      "required": false
    },
    {
      "fileName": "ORG_STRUCTURE",
      "required": false
    }
  ],
  "certificate": {
    "id": "0cc3c5fe-fa88-4e79-b5eb-1c5194a19b08",
    "certPem": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tTUlJQmpUQ0NBVE9nQXdJQkFnSVVMaWk2Mk5KME0rdTZOTDZWV0hWRkhIZmJCWUl3Q2dZSUtvWkl6ajBFQXdJd0tqRVhNQlVHQTFVRUF3d09ZWEJwTG1OcGNtTnNaUzVqYjIweER6QU5CZ05WQkFvTUJrTnBjbU5zWlRBZUZ3MHlOVEF6TVRjeU1EQXdNVFJhRncweU5qQXpNVGN5TURBd01UUmFNQ294RnpBVkJnTlZCQU1NRG1Gd2FTNWphWEpqYkdVdVkyOXRNUTh3RFFZRFZRUUtEQVpEYVhKamJHVXdXVEFUQmdjcWhrak9QUUlCQmdncWhrak9QUU1CQndOQ0FBUmgyTTU0Q2FVMTlaWFRFaXZJVUNLOXluMmgvYld6Uno0bUhJWVE0ZzFYWnArdHRiM3Z6bGY2ZDQzYUhNYlRaQUpPTG1pbkdFZGwxbUZMdFRUTXdYb3ZvemN3TlRBekJnTlZIUkVFTERBcWdnNWhjR2t1WTJseVkyeGxMbU52YllJU2QzZDNMbUZ3YVM1amFYSmpiR1V1WTI5dGh3UUtBQUFCTUFvR0NDcUdTTTQ5QkFNQ0EwZ0FNRVVDSUExbksrNUxBUC9ueUlxRFlUaVVLYmlHNWYwTjVPUmFMb2Y1VXpXU0dsUEJBaUVBaEVOcDFxakRydG41aGFpMHdKeTNORzJKZ2xra084Y1QzellhN21mRTBiST0tLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t",
    "domain": "api.circle.com",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "kid": "263521881931753643998528753619816524468853605762",
      "x": "YdjOeAmlNfWV0xIryFAivcp9of21s0c-JhyGEOINV2Y",
      "y": "n621ve_OV_p3jdocxtNkAk4uaKcYR2XWYUu1NMzBei8"
    }
  }
}
```

### Step 2: Create the RFI response

You must provide all of the fields that are marked as required. Circle
recommends providing the fields marked as optional for the highest likelihood of
an approved RFI. If you do not have the requested information about the sender,
you should request it.

Once you have all of the required information, you can create the RFI response.
Format it into the appropriate JSON format, based on the schema provided in the
`fieldRequirements` parameter.

Before encrypting and sending the response, you should validate the JSON
response object against the JSON schema. See
[How-to: Integrate with JSON Schema](/cpn/guides/payments/integrate-with-json-schema)
for more information.

The following is an example RFI response:

```json JSON theme={null}
{
  "ADDRESS": {
    "city": "San Francisco",
    "country": "US",
    "postalCode": "94105",
    "stateProvince": "CA",
    "street": "123 Market Street"
  },
  "NAME": "Alice Johnson",
  "DATE_OF_BIRTH": "1990-10-10",
  "NATIONAL_IDENTIFICATION_NUMBER": "12-9483432",
  "SOURCE_OF_FUNDS": "Company revenue",
  "METHOD_OF_VERIFICATION": "Electronic"
}
```

### Step 3: Encrypt the RFI response

The RFI response must be encrypted before it is sent to the BFI. It is encrypted
in the same manner as the travel rule and beneficiary account data. For a full
guide on the encryption process, see
[How-to: Encrypt Travel Rule and Beneficiary Account Data](/cpn/guides/payments/encrypt-travel-rule-beneficiary-data).

### Step 4: Submit the RFI response

Submit the encrypted RFI response with the
[submit RFI data endpoint](/api-reference/cpn/cpn-platform/submit-rfi) . The
request should include the encrypted data and the version of the RFI JSON
Schema. The version should match the version in the `fieldRequirements`
parameter of the RFI object. An example request body is shown below:

```json JSON theme={null}
{
  "rfi": {
    "version": 1,
    "data": "eyJhbGciOiJFQ0RILUVTK0ExMjhLVyIsImVuYyI6IkExMjhHQ00iLCJlcGsiOnsiY3J2IjoiUC0yNTYiLCJrdHkiOiJFQyIsIngiOiJ4ZzFRelVtaFRGdWV0Ti1Qd0N5dzdfRXd4SldKdk9ZTTFRLTNBRXFxZHdzIiwieSI6IjA0Z0dFMEsyT2ttVVZTMlhFUXZvR2hBUkJLWHQyWGRDRnRDNXpRMjQ3ajQifX0.Zaev1iHNNwG9_x0l3nwBcYlWBmlW9fP3.fmd2QQL_xKswDntW.1lYKjSoBZ_j7SKH4Q-kV8Zajcurh_zow1_e07zegfDNNEQ3DhsURPrjhDhyngtBe86T-WmDBM20j_1aChh1xwOS2vgKc-Kcv_4cNUzz0398ngYf2_xkEfvVckEexpX84omj5lmfqa0aleIQGldUVSuVV8fBl4YnH2oik5kDgvvQ4ap4MYhSTRqYJsi0bm6col7buPhnQJpojAjpp3ttoCYuOxbuDs5V_eNLIGuHPxF9KK7hS-l0qjLnNPcTnCbLL_fIveButXOzU54qB6lLssrE86O4xCH_d47_PAtaxJ296qtjGIB02dLSlrnORbVnvjrn17dhf8DmhkMy5GmFgtTs.TcOP8NKlgtgEaakORE1lXQ"
  }
}
```

### Step 5: Upload required files

If the RFI includes a `fileRequirements` field, you must upload documentation
about the sender in addition to submitting the RFI response. Files must be
encrypted and uploaded one at a time to the
[upload RFI file endpoint](/api-reference/cpn/cpn-platform/upload-rfi-file). You
can upload files before or after submitting the RFI response, as long as it is
before the RFI decision is made.

See
[How-to: Encrypt Files for RFI Transmission](/cpn/guides/payments/encrypt-files)
for more information on how to encrypt files.

The [upload RFI file endpoint](/api-reference/cpn/cpn-platform/upload-rfi-file)
accepts a `multipart/form-data` request body in three parts. The request body
should include the encrypted file, the encryption details, and the file
metadata. The file metadata should include the filename, file type, and file
key. The file key should match the `fileKey` in the `fileRequirements` field of
the RFI object.

The following is an example request body:

```text Text theme={null}
------WebKitFormBoundary
Content-Disposition: form-data; name="fileMetadata"
Content-Type: application/json

{
 "fileName": "example.pdf",
 "fileType": "application/pdf",
 "fileKey": "PROOF_OF_ADDRESS"
}

------WebKitFormBoundary
Content-Disposition: form-data; name="encryption"
Content-Type: application/json

{
 "encryptedAesKey": "<base64-encoded-encrypted-aes-key>",
 "iv": "<base64-encoded-iv-for-file-encryption>"}

------WebKitFormBoundary
Content-Disposition: form-data; name="encryptedFile"; filename="encrypted_data.bin"
Content-Type: application/octet-stream

[BINARY FILE DATA]
```

Once you submit the RFI response, you receive the decision on the RFI via
webhook. If the BFI approves the RFI, you can continue with the payment, or
create a new payment for the sender if the existing payment has expired.


# Encrypt Files for RFI Transmission
Source: https://developers.circle.com/cpn/guides/payments/encrypt-files



This guide explains how to set up encryption and decryption between an OFI and a
BFI during the RFI process so that a file can be passed securely. This
encryption varies from the method used to encrypt JSON communications between
OFI and BFI, but shares some features. For compactness, files are encrypted
using AES, and then the key is encrypted using JWE. Both are then transmitted to
the BFI for a two-stage decryption process.

In the CPN system, the OFI encrypts a payload with a randomly generated AES key.
This key is then encrypted with the BFI's public key using
[JSON Web Encryption](https://datatracker.ietf.org/doc/html/rfc7516). The
encrypted AES key and encrypted file payload are transmitted to the BFI. The BFI
decrypts the AES key using their private JWK and uses it to decrypt the file
contents.

## Steps

The following sections describe the steps necessary to encrypt a file sent from
an OFI to a BFI through the RFI endpoint.

### Step 1: Generate a random 128-bit AES key

Using your chosen implementation language, generate a random 128-bit AES key for
AES-128-GCM encryption.

```java Java theme={null}
import javax.crypto.KeyGenerator;
import javax.crypto.SecretKey;
import java.security.GeneralSecurityException;
import java.security.SecureRandom;


/**
 * @return A SecretKey for AES encryption.
 * @throws GeneralSecurityException if the AES algorithm is not available.
 */
public static SecretKey generateAesKey() throws GeneralSecurityException {
  KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
  keyGenerator.init(128, new SecureRandom());
  return keyGenerator.generateKey();
}
```

### Step 2: Generate a 12-byte IV

Using your chosen implementation language, generate a 12-byte IV.

```java Java theme={null}
import java.security.SecureRandom;

/**
 * @return A 12-byte array containing the IV.
 */
public static byte[] generateIv() {
  byte[] iv = new byte[12];
  new SecureRandom().nextBytes(iv);
  return iv;
}
```

### Step 3: Encrypt the file contents

Encrypt the file contents using AES-128-GCM using the key and IV from the
previous steps.

```java Java theme={null}
import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
import java.security.GeneralSecurityException;


/**
 * @param plaintextPayload The raw data to encrypt.
 * @param aesKey The AES key to use for encryption.
 * @param iv The 12-byte Initialization Vector.
 * @return The encrypted data, including the GCM authentication tag.
 * @throws GeneralSecurityException if a cryptographic error occurs.
 */
public static byte[] encryptPayload(byte[] plaintextPayload, SecretKey aesKey, byte[] iv) throws GeneralSecurityException {
  Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
  GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(128, iv);
  cipher.init(Cipher.ENCRYPT_MODE, aesKey, gcmParameterSpec);
  return cipher.doFinal(plaintextPayload);
}
```

### Step 4: Encrypt the AES key

Using the JWK data from the quote response, encrypt the AES key that was used to
encrypt the file contents with the following parameters using JWE:

* Algorithm: ECDH-ES+A128KW
* Encryption method: A128GCM

```java Java theme={null}
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWEEncrypter;
import com.nimbusds.jose.JWEHeader;
import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.Payload;
import com.nimbusds.jose.crypto.ECDHEncrypter;
import java.util.Base64;
import javax.crypto.SecretKey;
import java.security.interfaces.ECPublicKey;

   /**
    * @param aesKey The AES key to wrap.
    * @param bfiPublicKey The recipient's Elliptic Curve public key.
    * @return A compact, serialized JWE string representing the encrypted key.
    * @throws JOSEException if an error occurs during JWE creation or encryption.
    */
   public static String wrapAesKey(SecretKey aesKey, ECPublicKey bfiPublicKey) throws JOSEException {
  // Create the JWEHeader using ECDH_ES+AS128KW and AES-128-GCM
        JWEHeader header = new JWEHeader(
            JWEAlgorithm.ECDH_ES_A128KW,
            EncryptionMethod.A128GCM
        );

    // Base64 encode the AES key and wrap in JSON string
       String base64AesKey = Base64.getEncoder().encodeToString(aesKey.getEncoded());
       ObjectMapper objectMapper = new ObjectMapper();
       String jsonPayload = objectMapper.writeValueAsString(base64AesKey);

       Payload jwePayload = new Payload(jsonPayload);
       JWEObject jweObject = new JWEObject(header, jwePayload);
       JWEEncrypter encrypter = new ECDHEncrypter(bfiPublicKey);
       jweObject.encrypt(encrypter);
       return jweObject.serialize();
   }
```

### Step 5: Transmit the encrypted payload

After performing the encryption steps from the previous steps, you should have
three components:

* The AES-encrypted file content
* The JWE string containing the encrypted AES key
* The base64-encoded 12-byte IV

Use these components to create a `multipart/form-data` request to the
[upload RFI file endpoint](/api-reference/cpn/cpn-platform/upload-rfi-file). A
`200` response from the API indicates that the encryption was performed
correctly and the BFI can decrypt the file's contents.

<Warning>
  **Important:** Don't manually set the `Content-Type` header. Let your HTTP
  client library set it automatically. The header must include a boundary
  parameter like:

  ```text Text theme={null}
  Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
  ```

  If you manually set `Content-Type: multipart/form-data`, the request will fail.
</Warning>

```java Java theme={null}
import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.File;
import java.io.IOException;
import java.util.Base64;
import java.util.UUID;

/**
* Upload an encrypted RFI file using multipart/form-data.
*
* @param paymentId The payment UUID.
* @param rfiId The RFI UUID.
* @param encryptedFile The encrypted file to upload.
* @param fileName The original file name.
* @param fileType The file type (e.g., "PDF", "JPEG").
* @param fileKey The file key (e.g., "ID_DOCUMENT", "PROOF_OF_ADDRESS_DOCUMENT").
* @param encryptedAesKey The JWE-wrapped AES key.
* @param iv The Base64-encoded initialization vector.
* @param accessToken The Bearer token for authentication.
* @throws IOException if the HTTP request fails.
*/
public static void uploadRfiFile(UUID paymentId, UUID rfiId, File encryptedFile,
                               String fileName, String fileType, String fileKey,
                               String encryptedAesKey, byte[] iv, String accessToken) throws IOException {

   OkHttpClient client = new OkHttpClient();
   ObjectMapper objectMapper = new ObjectMapper();

   // Create data objects
   FileMetadata fileMetadata = new FileMetadata(fileName, fileType, fileKey);
   FileEncryption encryption = new FileEncryption(encryptedAesKey, Base64.getEncoder().encodeToString(iv));

   // Build multipart request
   RequestBody requestBody = new MultipartBody.Builder()
       .setType(MultipartBody.FORM)
       .addFormDataPart("fileMetadata", objectMapper.writeValueAsString(fileMetadata))
       .addFormDataPart("encryption", objectMapper.writeValueAsString(encryption))
       .addFormDataPart("encryptedFile", fileName,
           RequestBody.create(encryptedFile, MediaType.parse("application/octet-stream")))
       .build();

   Request request = new Request.Builder()
       .url(String.format("https://api.circle.com/v1/payments/%s/rfis/%s/files", paymentId, rfiId))
       .header("Authorization", "Bearer " + accessToken)
       .post(requestBody)
       .build();

   try (Response response = client.newCall(request).execute()) {
       if (!response.isSuccessful()) {
           throw new IOException("Upload failed: " + response.code());
       }
   }
}

public static class FileMetadata {
   public final String fileName;
   public final String fileType;
   public final String fileKey;

   public FileMetadata(String fileName, String fileType, String fileKey) {
       this.fileName = fileName;
       this.fileType = fileType;
       this.fileKey = fileKey;
   }
}

public static class FileEncryption {
   public final String encryptedAesKey;
   public final String iv;

   public FileEncryption(String encryptedAesKey, String iv) {
       this.encryptedAesKey = encryptedAesKey;
       this.iv = iv;
   }
}
```

An example request body is shown below:

```text Text theme={null}
------WebKitFormBoundary
Content-Disposition: form-data; name="fileMetadata"
Content-Type: application/json

{
  "fileName": "example.pdf",
  "fileType": "application/pdf",
  "fileKey": "PROOF_OF_ADDRESS"
}
------WebKitFormBoundary
Content-Disposition: form-data; name="encryption"
Content-Type: application/json

{
  "encryptedAesKey": "<base64-encoded-encrypted-aes-key>",
  "iv": "<base64-encoded-iv-for-file-encryption>",
}
------WebKitFormBoundary
Content-Disposition: form-data; name="encryptedFile"; filename="encrypted_data.bin"
Content-Type: application/octet-stream

[AES ENCRYPTED BINARY FILE DATA]
```


# How-to: Encrypt Travel Rule and Beneficiary Data
Source: https://developers.circle.com/cpn/guides/payments/encrypt-travel-rule-beneficiary-data



This guide explains how to set up encryption and decryption between an OFI and a
BFI so that messages can be passed securely during payment flow. CPN uses
[JSON Web Encryption](https://datatracker.ietf.org/doc/html/rfc7516) (JWE) for
encrypting data in a secure and compact manner. This encryption is implemented
after a quote is accepted: the JWK data and public key for encryption are shared
in the quote response. The encryption is also used when communicating RFI data.

Both OFI and BFI can implement this encryption system in any programming
language that supports the required primitives. This encryption scheme is
required when performing the following tasks in CPN:

* **Creating a payment**: for encrypting the travel rule and beneficiary account
  data
* **Submitting an RFI**: for encrypting the RFI JSON response

<Note>
  **Note:** If your RFI response includes a file, that file is
  [encrypted in a different manner](/cpn/guides/payments/encrypt-files).
</Note>

Regardless of the language used to implement the encryption, the following
parameters must be followed:

* Key agreement: ECDH-ES+A128KW
* Encryption method: A128-GCM

## Steps

The following sections describe the steps necessary to encrypt a message sent
from an OFI to a BFI. Note that this example uses beneficiary account data and
travel rule data, but the same encryption scheme applies for RFI data as well.

### Step 1: Retrieve the certificate from the quote response

Quote responses include a certificate field with required parameters to
establish encryption with the BFI. A sample (truncated) quote response is below:

```json JSON theme={null}
{
  "data": [
    {
      "id": "6e4c7e85-39eb-4411-8c4a-683ff73846d6",
      "paymentMethodType": "FPS",
      "blockchain": "MATIC-AMOY",
      "senderCountry": "US",
      "destinationCountry": "HK",
      "certificate": {
        "id": "0cc3c5fe-fa88-4e79-b5eb-1c5194a19b08",
        "certPem": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tTUlJQmpUQ0NBVE9nQXdJQkFnSVVMaWk2Mk5KME0rdTZOTDZWV0hWRkhIZmJCWUl3Q2dZSUtvWkl6ajBFQXdJd0tqRVhNQlVHQTFVRUF3d09ZWEJwTG1OcGNtTnNaUzVqYjIweER6QU5CZ05WQkFvTUJrTnBjbU5zWlRBZUZ3MHlOVEF6TVRjeU1EQXdNVFJhRncweU5qQXpNVGN5TURBd01UUmFNQ294RnpBVkJnTlZCQU1NRG1Gd2FTNWphWEpqYkdVdVkyOXRNUTh3RFFZRFZRUUtEQVpEYVhKamJHVXdXVEFUQmdjcWhrak9QUUlCQmdncWhrak9QUU1CQndOQ0FBUmgyTTU0Q2FVMTlaWFRFaXZJVUNLOXluMmgvYld6Uno0bUhJWVE0ZzFYWnArdHRiM3Z6bGY2ZDQzYUhNYlRaQUpPTG1pbkdFZGwxbUZMdFRUTXdYb3ZvemN3TlRBekJnTlZIUkVFTERBcWdnNWhjR2t1WTJseVkyeGxMbU52YllJU2QzZDNMbUZ3YVM1amFYSmpiR1V1WTI5dGh3UUtBQUFCTUFvR0NDcUdTTTQ5QkFNQ0EwZ0FNRVVDSUExbksrNUxBUC9ueUlxRFlUaVVLYmlHNWYwTjVPUmFMb2Y1VXpXU0dsUEJBaUVBaEVOcDFxakRydG41aGFpMHdKeTNORzJKZ2xra084Y1QzellhN21mRTBiST0tLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t",
        "domain": "api.circle.com",
        "jwk": {
          "kty": "EC",
          "crv": "P-256",
          "kid": "263521881931753643998528753619816524468853605762",
          "x": "YdjOeAmlNfWV0xIryFAivcp9of21s0c-JhyGEOINV2Y",
          "y": "n621ve_OV_p3jdocxtNkAk4uaKcYR2XWYUu1NMzBei8"
        }
      }
    }
  ]
}
```

### Step 2: Verify the certificate

<Note>
  **This step is only possible in the production environment. It will fail in the
  sandbox environment.**

  This step is strictly optional, however it is recommended as a best practice to
  verify that the certificate is valid.
</Note>

From the `certificate` object in the quote response, extract the `base64`
encoded format of the certificate from the `certPem` field, decode it, and
verify the following:

* The certificate is not expired
* The certificate is signed by a Circle-approved Certificate Authority listed in
  the Circle-provided CA bundle file
* The common name of the certificate is for a CPN BFI and matches the `domain`
  field in the response
* The verifiable public key of the certificate matches the `jwk` field in the
  response

```java Java theme={null}
public static void verify() throws Exception {
    // Assume the API response is stored in a file "response.json"
    String responseStr = new String(Files.readAllBytes(Paths.get("response.json")));
    JSONObject response = new JSONObject(responseStr);
    JSONObject certObj = response.getJSONArray("data").getJSONObject(0).getJSONObject("certificate");

    String caBundlePath = "ca_bundle.pem"; // CA bundle file provided by Circle

    // ---------- 1. Check certificate expiration ----------
    String certPemB64 = certObj.getString("certPem");
    byte[] pemData = Base64.getDecoder().decode(certPemB64);
    CertificateFactory cf = CertificateFactory.getInstance("X.509");
    InputStream in = new ByteArrayInputStream(pemData);
    X509Certificate certificate = (X509Certificate) cf.generateCertificate(in);
    Date expirationDate = certificate.getNotAfter();
    Date currentDate = new Date();
    if (currentDate.after(expirationDate)) {
        System.out.println("❌ Certificate has expired on " + expirationDate);
        System.exit(1);
    } else {
        System.out.println("✅ Certificate is valid until " + expirationDate);
    }

    // ---------- 2. Verify that the certificate was signed by a Circle approved CA ----------
    List<X509Certificate> caCerts = loadCABundle(caBundlePath);
    boolean trusted = false;
    for (X509Certificate caCert : caCerts) {
        if (certificate.getIssuerX500Principal().equals(caCert.getSubjectX500Principal())) {
            trusted = true;
            System.out.println("✅ Certificate is signed by trusted CA: " + caCert.getSubjectX500Principal());
            break;
        }
    }
    if (!trusted) {
        System.out.println("❌ Certificate verification failed. CA is not trusted.");
        System.exit(1);
    }

    // ---------- 3. Verify that the certificate's common name (CN) matches the expected domain ----------
    String certCN = getCommonName(certificate);
    String expectedDomain = certObj.getString("domain");
    if (certCN != null && certCN.equals(expectedDomain)) {
        System.out.println("✅ Certificate common name matches expected domain.");
    } else {
        System.out.println("❌ Certificate common name does not match expected domain.");
        System.exit(1);
    }

    // ---------- 4. Verify that the verifiable public key of the certificate is the same as the provided JWK ----------
    JSONObject providedJWK = certObj.getJSONObject("jwk");
    String xProvided = providedJWK.getString("x");
    String yProvided = providedJWK.getString("y");
    PublicKey pubKey = certificate.getPublicKey();
    if (pubKey instanceof ECPublicKey) {
        ECPublicKey ecPub = (ECPublicKey) pubKey;
        ECPoint point = ecPub.getW();
        String xCert = toBase64URL(point.getAffineX(), 32);
        String yCert = toBase64URL(point.getAffineY(), 32);
        if (xCert.equals(xProvided) && yCert.equals(yProvided)) {
            System.out.println("✅ Certificate public key matches provided JWK.");
        } else {
            System.out.println("❌ Certificate public key does not match provided JWK.");
            System.exit(1);
        }
    } else {
        System.out.println("❌ Certificate public key is not EC type.");
        System.exit(1);
    }
}
```

### Step 3: Extract and create the JWK

From the `certificate` field, extract the JWK parameters: `kty`, `crv`, `kid`,
`x`, `y` and create the JWK object in your code using a suitable library (for
example, Nimbus JOSE+JWT in Java).

```java Java theme={null}
import com.nimbusds.jose.jwk.JWK;

public static JWK parseJwkFromJson() throws ParseException {
    String jwkJson = """
        {
            "kty": "EC",
            "crv": "P-256",
            "kid": "263521881931753643998528753619816524468853605762",
            "x": "YdjOeAmlNfWV0xIryFAivcp9of21s0c-JhyGEOINV2Y",
            "y": "n621ve_OV_p3jdocxtNkAk4uaKcYR2XWYUu1NMzBei8"
        }
        """;

    JWK jwk = JWK.parse(jwkJson);

    return jwk;
}
```

### Step 4: Prepare the payload

Create the payload for travel rule data and beneficiary account data. Get the
required fields from the
[requirements endpoint](/api-reference/cpn/cpn-platform/get-payment-requirements)
and construct them to the correct format.

The correct format for travel rule data and beneficiary account data is a JSON
array of objects where each object contains two properties: `name` and `value`.
Whether an object is required to be present is defined by the `optional` field
in the object returned by the requirements endpoint.

An example of each is shown below:

**travelRuleData**

```json JSON theme={null}
[[
  {
    "name": "BENEFICIARY_ADDRESS",
    "value": {
      "city": "San Francisco",
      "country": "US",
      "postalCode": "94105",
      "stateProvince": "CA",
      "street": "123 Market Street"
    }
  },
  {
    "name": "BENEFICIARY_NAME",
    "value": "Alice Johnson"
  },
  {
    "name": "ORIGINATOR_ACCOUNT_NUMBER",
    "value": "9876543210"
  },
  {
    "name": "ORIGINATOR_ADDRESS",
    "value": {
      "city": "New York",
      "country": "US",
      "postalCode": "10001",
      "stateProvince": "NY",
      "street": "456 Madison Avenue"
    }
  },
  {
    "name": "ORIGINATOR_FINANCIAL_INSTITUTION_ADDRESS",
    "value": {
      "city": "Chicago",
      "country": "US",
      "postalCode": "60603",
      "stateProvince": "IL",
      "street": "789 Apple Drive"
    }
  },
  {
    "name": "ORIGINATOR_FINANCIAL_INSTITUTION_NAME",
    "value": "First National Bank"
  },
  {
    "name": "ORIGINATOR_NAME",
    "value": "Robert Smith"
  }
]
```

**beneficiaryAccountData**

```json JSON theme={null}
[
  {
    "name": "BANK_NAME",
    "value": "Test Bank"
  },
  {
    "name": "RECIPIENT_ADDRESS",
    "value": {
      "street": "123 Test St",
      "city": "Sacramento",
      "state": "CA"
    }
  },
  {
    "name": "RECIPIENT_CITY",
    "value": "Sacramento"
  }
]
```

### Step 5: Encrypt the payload

Convert the data from the previous step into a JSON string, then use the JWK to
encrypt it. Ensure that the following parameters are used:

* Algorithm: ECDH-ES+A128KW
* Encryption method: A128GCM

```java Java theme={null}
import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.JWEEncrypter;
import com.nimbusds.jose.JWEHeader;
import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.Payload;
import com.nimbusds.jose.crypto.ECDHEncrypter;
import com.nimbusds.jose.jwk.JWK;


   /**
     * Encrypts a payload using JWE (JSON Web Encryption) with ECDH-ES key agreement.
     *
     * This method creates a JWE compact string with the provided payload and encrypts it using
     * the recipient's public key. The encryption algorithm used is ECDH-ES with AES-128 key wrap,
     * and the content encryption method is AES GCM with 128-bit key.
     *
     * @param <T> the type of the payload to encrypt
     * @param payload the data to be encrypted
     * @param recipientJwk the recipient's JWK (JSON Web Key) containing the public key for encryption
     * @return the serialized JWE in compact form
     * @throws JOSEException if an error occurs during the encryption process
     */
public static <T> String encrypt(T payload, JWK recipientJwk) throws JOSEException {
  String plainText = JsonUtils.toJson(payload);

  // Create the JWEHeader using ECDH_ES+AS128KW and AES-128-GCM
  JWEHeader header = new JWEHeader(
      JWEAlgorithm.ECDH_ES_A128KW,
      EncryptionMethod.A128GCM
  );

  // Create the JWE object with the payload to encrypt
  JWEObject jweObject = new JWEObject(
      header,
      new Payload(plainText)
  );

  // Create an encrypter with the recipient's public key
  JWEEncrypter encrypter = new ECDHEncrypter(recipientJwk.toECKey());

  // Encrypt the JWE
  jweObject.encrypt(encrypter);

// Return the serialized JWE string in compact form
  return new jweObject.serialize();
}
```

### Step 6: Send and verify the encrypted payload

Send the encrypted payload in the API request to
[create a payment](/api-reference/cpn/cpn-platform/create-payment). The
preceding example uses version 1 for `beneficiaryAccountData` and
`travelRuleData` fields.

The API returns a `200` response if the data is properly encrypted and can be
decrypted by the BFI, otherwise an
[encryption-related error code](/cpn/references/errors/error-codes#encryption)
is returned.


# Integrate with JSON Schema
Source: https://developers.circle.com/cpn/guides/payments/integrate-with-json-schema



To facilitate the effective passing of RFI data, CPN provides
[JSON Schema](/cpn/concepts/api/json-schema) that gives a clear,
machine-readable contract you can validate your response against. This guide
provides information about how to integrate with the JSON Schema returned by the
[get details for an RFI endpoint](/api-reference/cpn/cpn-platform/get-rfi).

## Steps

Use the following steps to retrieve JSON Schema for a given quote and respond
with the required information.

### Step 1: Get the JSON Schema

Call the [get details for an RFI](/api-reference/cpn/cpn-platform/get-rfi)
endpoint. The API returns a JSON Schema object that defines the fields that must
be transmitted in the RFI response.

### Step 2: Build a JSON response

Using the schema as a blueprint, construct your RFI data as a JSON object. For
example, if the schema requires the `address` field, you should create a nested
JSON object for the address, as defined by the `properties` and `$defs` in the
schema.

### Step 3: Validate the response

Before encrypting the response for transit, CPN expects that you perform
client-side validation on the data. Using a JSON Schema validation library,
check your constructed JSON objects against the schemas from Step 1. This should
catch any structural or formatting errors before you interact with the CPN API.

### Step 4: Encrypt the response

Once validated, convert your JSON objects to strings and encrypt them. The steps
outlined in
[How-to: Encrypt Travel Rule and Beneficiary Account Data](/cpn/guides/payments/encrypt-travel-rule-beneficiary-data)
also apply to encrypting RFI data for transit.

### Step 5: Transmit the payload

Send the encrypted payload to the
[submit RFI data endpoint](/api-reference/cpn/cpn-platform/submit-rfi).

The following is an example payload:

```json JSON theme={null}
{
  "rfi": {
    "version": 1,
    "data": "eyJhbGciOiJFQ0RILUVTK0ExMjhLVyIsImVuYyI6IkExMjhHQ00iLCJlcGsiOnsiY3J2IjoiUC0yNTYiLCJrdHkiOiJFQyIsIngiOiI1TEtTbUtsNmVYV0dQNHlGb2tVaks4RGppU0l5YWpQdzJ6UUp1YVhFbEZzIiwieSI6IlRVT29MTV8wc294b0UzYVFmSExlUzRlRkZ3RU9tZ1VDRUh1eDVRMXdVYTQifX0.kVGnfB8eIqxq3bMvhedxUmZvkCrRfQOy.bTUOc_ilvZjb9VYP.pOS6Ul8Jnp_pijWtaQYC0b1NLN1Nc-t_MTsfj5EZy6s62ijQWGtAoo3enwx3gOpXIQDIIF7c-F3KSrVO33a5RIF8a4tvU7pRk_JDKVgHFVpSzvOaUHNHsMUvvctAncx1SneVE_gnm5ATkWO4_1i7irTkb-cjWLmvJ1vVEyJiC9ZgsEdK_eBAewpZTyyKxvoxBpo8IZ3g7qax712TvMsNpIJ_faQmsyRKwt2kBxDPyrWILcIvS1qij6uVOsEP2R6LXbWfBqVbklsgNPWjndXSmOJmsTdBjFzublMLSHmLxkfaD9gt3DxgD16rqDlKO9KmaRF3r322VumP4hrlfOsZUHHcVGeTpgjZwI9jrj76PiYtyCOeR7-kz97PamqrOQAfWRE8Rcp8QdCO6yFHFe3N2pI5kWakH783DVDAsm_x2VY_V8vCDe-xkIoJOabx3LqaxHq8_x_ATXZ01NX-5F9VqgtE73FOIGhinxt8G-Kfxvdlx6gv-QSfBvigVuoR1OCSPNB3OHirEKXY3IjWnjZuENNnXl9CqrCsHQZS1eb1KcaIkg_2NF6gi54htX6ijpUtyXS03IGZW6Bn6CSWqmmvMStIAIYO-8ZJrrleeCfU6WY5KjFlIvN6th-tE41JNJWS9mVqhjzwPC7GQ5bGkqq2zJKhALOuN_0oG4jXOYo1s3YAn-xw3kpq46fYyUrX4nLSocaKDeKOMMqh57_jcMDmHrXdmjlHGPMrBPdU_deub121c3ofTKgJg4KRC8mcTYcXe71uflARAr24msd9A_IPPVbhfvs06HOVKL2-jK6r_WL_9vWU3q-OPQHU3eWUOhI18vZ0CkGqJjtEKyBBmc4inWEbrsO02P2Zd5VTBCIoAaNrpY6n5mNyKPo6-PyrxNy27d6u2yoZvjG6QSuUO9DaX4AyGsE87agh_XgLW9RPXfcZQ7F5aUCQwEA0cF9YSEaYYBGziS7oQ99D1th1MQqEPcFxD5YPdyaPykU3Zbf5T8HSZz1risMbgQu97eXoarxm801pdw5cuKijqj39BVrgdLUfaQ9P-iGWcVJk8ZVXfHK3JHGaBuIjYNIy5lHF3TsKgV2x-wWxqER9vPdgejAGirkxHQaKPt2rg0rmbk3R7YTibT7yTKwO1PRiewi0lxKWvZqDbCoedyuYZCR0vup4S1ZVYX6uGBn-F5ODrnLoAZTbnV1tjDJgxFpA8EKsXWTrc78XH0715lY2OnbDtBOLMbxFJjK1_YDRU2UMkZTEx5BrhR4YibBd4-BCZT-dWTxanOHMxTKl823tyggY5lBQ8DlsLj1qZpOxKWYTM8WrLCZa7vZo9FmXw38FxYrqbwespe7xdS7onfmlI4Ug92eTtZ31FbZfcqOiAGgH9Etkj1M9scP0is6zVC6cIUQzC3NmHNxNtPv6XjMUWigijosvs7x9-qyVCqzJZlEGck2BJ6Uk7ug9QKcxHtaWgtuHPnA77KVE3Vi_dikYaXzxIdgjrGtqqUhXEhrAFkesvJ0UeH1ac94e-R8UrJX75w4DDoRyaFxQhDFdHVtD0ceVN7ekYJkmoS2eSAzWDwsKUvUrmafcfpQ922tZGq0RvnMh39SWy6I6xRFyYHarra24Gbawa5_THjB8TkHJ180giPC3KQAa_6Vz8CP-fks6_-MdGXPW0SYhNghNi_14ZXQ3rZYHaTICgeHhBfhJ4MQ6OlRkiRCrIkM5WSOTS_H715aeyUCL-dlZ0TiG2DpAIXkN1KMRp0jL_W12pg5SjKFAlOGnQgkgj9rO_C7pLxMyIhgEUKPHXMGN6Q7tpVhAAyTl0tabd7cvyWnf5L4UiyIpvb1qrt1bY6-VNA4KXz6Y5uiiBYFF_FIN3K6YZCT4l0zuh_gxmP9eba7zM5kgas1tr1IxYWI-mQiE9Rb8rX0hqXpMj27h9Mf_Sn56TJeEmW8d8x2Xy2Nb7KU9vQO-6uc_taXP0Lv5LFcSwZkdVe7FOeZD-GoaNDly9MdhXI4ELP4MOZXZFJeN7aCJvJeLRBPWnoM2aazDwtlA_KfhZVFtCsKKjJazv6J9h6CDHAm7NuexVJiPdtS1yknQDWrIBfneaLJasmtuhuAbRPtiTvvhQOXt51q0G7sjCSmmeNMwb5fFphe4wLJNmsbdgMFDcUVzb0ImIArCxqBEEK8uuRGcYaRifaLv0zkk29NAT99Ux580zaeN_x7aIMpJTt7jLP0-HZ-QU3MAGg3PLJ3_Oly6ABoULkEkmRhF0TtpU8z-kmmN6FtmzZK74kYEC75smgVTnnJK1kBdsZw9cxHeUx8aDJGrS3OK-uYN0dPJls2LC7X1rHD7ES179nPVBeJA2REm-jSlhVlV_I7JrVzlcXs0Fhx0hX-OgMKz_yQNHnM6RbgGnSLDcvND7vXqkEMgHeDRomhU1hMeu0DymctTKawtzIkV7MYwoibLDUeMvaXN8MicMs64D8I3Ld7BLtFf9o8rMeeNJ0Om7xdl9SGD2RYAep0cxw2rEIIr859e1vutBuvrrMz09dZKd05t1lu0jRztkQzUW9N-VZh9muTAoh_s3NrF2ZTFnRAfzxohwNLxxmX-Ov94FXBhuRHBQXb931I5m2URglrYcoAZ8RFoiAWW2AkHcyb5PRoQIt-LQhOM-bcn1VB44Okh10jqWpGbLno6AvE5FcoRVcspb0tor9EbksW2cipoypcaat5NhQgvo2rAPmkHGi8iB-z_xWORvUkaA2xknNW59myO6qTvjYQ_1P1ESbRO30nUeqgP3VoZrC1-bi9IbgSi-na31xEhdr-ZGuvtRSzyhWwqfviJgSMZ6_kkGW3gUI4ldurTwss6gDHWYmdV-lHtPMfYuD2KMQk1EyJ-3vZx0syLKDACL37HqAYvkW5GiOxrK9cNrSInQ8rZMDkXsaCZMEtvs03Qw2DyCBdoFeXPvFHJ6Vetou-7Oo6rdlmSkt5KdA-w9KKVIAt9WtYxNc-wjFm-vOMcOHb_xxzacDzYFJj8NxdW8GaVdrCvh3j5Yakr_3vSvRM5rpzQKMqw-B53SWV3oOHYu29qso5zSTz-dvAlZUL8Z1a3s13qdwhUkkRexIi6oTU0Da21pT-gCan2jSY_VKR8JdirKTLocn74JZ3InF8iH8XhOD0X7ySIbB69HqMLYRd9r13q2odfJ3cN1CWSF71zgIuZoYSbkO9DeFvCImA-WEIWrP1kJiYlpJi8VnFNQs8XWIxdCydft-8zvoXZbi0MoNt3kJExbKx7dReHx6B-6iwjuW8-o5RbeMvdTIYTp-y6YPsFhcVCvTlS7IefXqG4G3OrnNc5JIVnvdYXWCWUdWguiKdqB6FL_LSWOtsWrB6nIv69WP1WJJSa0Oa_EkxEwXK1BGH9-QpMqkP6rATSvsbaTywfCxqUqm7SzYH81lSCIvI5J7bWX5blk9rNZbp3aSeEpVRm03vwLrgUHLv9vMAopNnw5fZGKfcg3I5ZWYHNQo5BZk9LVpebMBYGijwNDnuFu08eF7ShlEzy50NsvgeDxZtfUVx8cviYn0MoTJBPlz1mXRSIr3zDIpefxDGnsQ1KK8LTi0Gbnt_ybeiT4yTmajrPLE4566D6AQIdDmCg_RsBtB_lAw.S2qu0MNMu2WNiEYoHh25ww"
  }
}
```


# Request Payment Configurations and Routes
Source: https://developers.circle.com/cpn/guides/payments/request-payment-config



You can use the API to discover which corridors, currencies, and payment methods
are available. Retrieving this information and handling it in your integration
allows you to show your users the available sources and destinations for funds
in CPN.

## Steps

Use the following steps to request CPN configuration overview, and get the
available routes from country to country.

### Step 1: Request configuration overview

Make a request to the
[configurations overview endpoint](/api-reference/cpn/cpn-platform/get-payment-configurations-overview)
to receive a list of supported currencies, countries, payment methods, and
blockchains.

```shell Shell theme={null}
curl -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET https://api.circle.com/v1/cpn/v1/ofi/configurations/overview
```

**Response**

```json JSON theme={null}
{
  "data": {
    "sourceCurrencies": ["USDC"],
    "destinationCountries": ["BR", "HK", "MX", "NG", "US"],
    "destinationCurrencies": ["BRL", "HKD", "MXN", "NGN", "USD"],
    "paymentMethodTypes": [
      "ACH-BANK-TRANSFER",
      "BANK-TRANSFER",
      "CHATS",
      "FPS",
      "PIX",
      "SPEI",
      "WIRE"
    ],
    "blockchains": ["ETH-SEPOLIA", "MATIC-AMOY", "SOL-DEVNET"]
  }
}
```

### Step 2: Request available route details

Evaluate the available route details for a specific transfer by making a request
to the
[supported payment routes endpoint](/api-reference/cpn/cpn-platform/list-routes).
This example evaluates a route from the US to Mexico, but other routes can be
evaluated by changing the query parameters. The endpoint accepts an optional
`transactionVersion` query param (`VERSION_1`, `VERSION_2`); with `VERSION_2`, a
chain-specific buffer is added to the crypto min limit to cover fees (for
example, gas fee), paid in USDC from the source amount.

```shell Shell theme={null}
curl -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET https://api.circle.com/v1/cpn/v1/ofi/configurations/routes?sourceCurrency=USDC&destinationCountry=MX
```

**Response**

```json JSON theme={null}
{
  "data": [
    {
      "destinationCurrency": "MXN",
      "paymentMethodType": "SPEI",
      "blockchain": "ETH-SEPOLIA",
      "fiatLimit": {
        "min": "168",
        "max": "837500",
        "currency": "MXN"
      },
      "cryptoLimit": {
        "min": "8.34",
        "max": "41552.14",
        "currency": "USDC"
      }
    }
  ]
}
```


# Create an Onchain Transaction
Source: https://developers.circle.com/cpn/guides/transactions/create-an-onchain-txn



When a payment is in the `CRYPTO_FUNDS_PENDING` state, the OFI must initiate an
onchain transaction to fulfill the payment in USDC. CPN provides an API to help
prepare and validate the onchain transaction call data, and to broadcast the
transaction and monitor its state.

There are two versions of the Transactions API: V1 and V2. This guide provides
information on both versions. Note that your quote must match the version of the
API that you are using.

## Prerequisites

Before you begin, ensure that you have:

* Created a quote through the CPN API. If you are following the Transactions V2
  example, your quote should be created with the `transactionVersion` parameter
  set to `VERSION_2`.
* USDC in your sender wallet
* (Transactions V1 only) Native tokens in your sender wallet
* (Transactions V2 on EVM chains only) Granted a USDC allowance to the `Permit2`
  contract. See
  [How-to: Grant USDC Allowance to Permit2](/cpn/guides/transactions/grant-usdc-allowance-to-permit2)
  for more information.
* (Solana only) Ensure your Solana account has been initialized and funded.

<Note>
  **Note:** For Transactions V2, gas fees are not charged in native tokens, but in
  USDC. They are determined at quote creation instead of transaction creation in
  the quote `fees` field. The gas fee is collected by Circle's payment settlement
  smart contract during onchain transaction processing.
</Note>

## Steps

Use the following steps to create and broadcast a USDC transfer to the
blockchain:

### Step 1: Prepare the call data

Call the
[create transaction](/api-reference/cpn/cpn-platform/create-transaction)
endpoint to get an unsigned message object. Note that transaction objects differ
between EVM blockchains and Solana.

For Transactions V2, call the
[create transaction V2](/api-reference/cpn/cpn-platform/create-transaction-v2)
endpoint to get an unsigned message object. Transactions V2 supports EVM chains
only.

The API call must include the sender wallet information (which must be an EOA
wallet). The rest of the transaction data such as amount, chain, destination
address, and other information is populated automatically by CPN using the
payment record.

### Step 2: Create and sign the transaction

Review the unsigned message object and ensure that it matches your expectations
for the crypto transaction. Depending on the blockchain, the signing process
varies.

#### EVM

<Tabs>
  <Tab title="Transactions V1">
    When the unsigned data has been confirmed, you must sign it in accordance with
    [EIP-712](https://eips.ethereum.org/EIPS/eip-712). Next, you construct an
    [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) transaction from the signed
    data:

    1. **Extract the signature**. Extract the signature components (`v`, `r`, `s`)
       from the signed typed data.
    2. **Encode the function call**. Using the ERC-20 smart contract's ABI for the
       `TransferWithAuthorization` function, encode the function call with the
       required parameters: sender address (`from`), recipient address (`to`),
       `validAfter`, `validBefore`, `nonce`, and the signature components, `v`, `r`,
       `s`. This encoding creates the data field for the raw transaction.
    3. **Construct the transaction object**. Build a raw transaction object that
       includes the target contract address (USDC), the encoded function call data,
       and other necessary parameters such as nonce, gas limit, max fee per gas, max
       priority fee per gas, and chain ID.
    4. **Serialize the transaction**. Serialize the transaction object into the
       proper RLP-encoded format so that it can be signed.

    The following is an example of the transaction object in
    [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) format, for EIP-3009
    `TransferWithAuthorization` contract execution.

    ```json JSON theme={null}
    {
      "to": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "value": "0x0",
      "gasLimit": "0x5208",
      "maxPriorityFeePerGas": "0x59682f00",
      "maxFeePerGas": "0x59682f00",
      "nonce": "0x8",
      "chainId": 1,
      "type": "0x2",
      "data": "0xe3ee160e000000000000000000000000a9d56270e9fd76be802ac4d45ef4be4322fdadbc0000000000000000000000006840c9f894b6b8264292e22b8abb2c57ae3946a700000000000000000000000000000000000000000000000000000000000f424000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000067ca8f131e790e4b5e8d2f801f12bdd8e8a9fcab490305f17a59a1620549791985617c36000000000000000000000000000000000000000000000000000000000000001cc8973666e8460a153a5a073a7a2878a4e6f42be09ffe012a04d342f2a729019b769e46ab7fefb0dadf8a6d0dd83a687d6dfcdfaf1c56af190eaaff8252e5929e"
    }
    ```

    Sign this transaction data and move on to the next step.
  </Tab>

  <Tab title="Transactions V2">
    When the unsigned data has been confirmed, you must sign the transaction payload
    from the API endpoint using [EIP-712](https://eips.ethereum.org/EIPS/eip-712)
    typed data signing from your sender wallet. The following is an example payload:

    ```json theme={null}
    {
      "type": "PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT",
      "types": {
        "EIP712Domain": [
          {
            "name": "name",
            "type": "string"
          },
          {
            "name": "chainId",
            "type": "uint256"
          },
          {
            "name": "verifyingContract",
            "type": "address"
          }
        ],
        "PaymentIntent": [
          {
            "name": "from",
            "type": "address"
          },
          {
            "name": "to",
            "type": "address"
          },
          {
            "name": "value",
            "type": "uint256"
          },
          {
            "name": "validAfter",
            "type": "uint256"
          },
          {
            "name": "validBefore",
            "type": "uint256"
          },
          {
            "name": "nonce",
            "type": "bytes32"
          },
          {
            "name": "beneficiary",
            "type": "address"
          },
          {
            "name": "maxFee",
            "type": "uint256"
          },
          {
            "name": "requirePayeeSign",
            "type": "bool"
          },
          {
            "name": "attester",
            "type": "address"
          }
        ],
        "TokenPermissions": [
          {
            "name": "token",
            "type": "address"
          },
          {
            "name": "amount",
            "type": "uint256"
          }
        ],
        "PermitWitnessTransferFrom": [
          {
            "name": "permitted",
            "type": "TokenPermissions"
          },
          {
            "name": "spender",
            "type": "address"
          },
          {
            "name": "nonce",
            "type": "uint256"
          },
          {
            "name": "deadline",
            "type": "uint256"
          },
          {
            "name": "witness",
            "type": "PaymentIntent"
          }
        ]
      },
      "domain": {
        "name": "Permit2",
        "chainId": "11155111",
        "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
      },
      "message": {
        "nonce": "25668617285137697861288274946631174355105919960416755114569514179393151588120",
        "spender": "0xe2B17D0C1736dc7C462ABc4233C91BDb9F27DD1d",
        "witness": {
          "to": "0xc75c3e371d617b3e60db1b6f3fa2f0689562e5a7",
          "fee": "0",
          "from": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
          "nonce": "0x38bfec2b230187932870d575132e8ae1f83b34c10e3bf6d64c377f0c13245718",
          "value": 14174474,
          "attester": "0x768919ef04853b5fd444ccff48cea154768a0291",
          "validAfter": "1757358106",
          "beneficiary": "0x4f1c3a0359A7fAd8Fa8E9E872F7C06dAd97C91Fd",
          "validBefore": "1757361726",
          "requirePayeeSign": false
        },
        "deadline": "1757362866",
        "permitted": {
          "token": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
          "amount": "14174474"
        }
      },
      "primaryType": "PermitWitnessTransferFrom"
    }
    ```

    After signing the payload, you should have an EIP-712 data signature in hex
    string format.
  </Tab>
</Tabs>

#### Solana

<Tabs>
  <Tab title="Transactions V1">
    For V1, the transfer data for Solana follows Solana's `Ed2559` transaction
    format. After confirming the unsigned data, a transaction object is constructed
    with the transfer data. You sign the transaction object and submit it to the
    API.

    To sign the transaction object, you can deserialize the `messageToBeSigned`
    field from the
    [POST /v1/cpn/payments/:paymentId/transactions](/api-reference/cpn/cpn-platform/create-transaction)
    endpoint, and sign it using a Solana library with your wallet key pair.

    ```typescript theme={null}
    import {
      Keypair,
      Transaction,
      PublicKey,
      TransactionInstruction,
    } from "@solana/web3.js";
    import bs58 from "bs58";

    function signTransaction(messageToBeSigned: any, keypair: Keypair): string {
      // 1. Create a new Transaction
      const transaction = new Transaction();

      // 2. Set recentBlockhash and feePayer
      transaction.recentBlockhash = messageToBeSigned.recentBlockhash;
      transaction.feePayer = new PublicKey(messageToBeSigned.feePayer);

      // 3. Add all instructions
      for (const instruction of messageToBeSigned.instructions) {
        const keys = instruction.keys.map((key: any) => ({
          pubkey: new PublicKey(key.pubkey),
          isSigner: key.isSigner,
          isWritable: key.isWritable,
        }));

        const programId = new PublicKey(instruction.programId);

        // Handle instruction data - can be array of numbers or base64 string
        let data: Buffer;
        if (Array.isArray(instruction.data)) {
          data = Buffer.from(instruction.data);
        } else if (typeof instruction.data === "string") {
          data = Buffer.from(instruction.data, "base64");
        } else {
          throw new Error(`Unexpected data format: ${typeof instruction.data}`);
        }

        transaction.add(
          new TransactionInstruction({
            keys,
            programId,
            data,
          }),
        );
      }

      // 4. Sign with keypair
      transaction.sign(keypair);

      // 5. Serialize signed transaction, which you can then submit to the
      // POST /v1/cpn/payments/:paymentId/transactions/:transactionId/submit endpoint
      const signedTransaction = transaction
        .serialize({ requireAllSignatures: false })
        .toString("base64");

      return signedTransaction;
    }
    ```

    If you are using the Circle Wallets, you can use the
    [sign transaction](/api-reference/wallets/developer-controlled-wallets/sign-transaction)
    endpoint to sign the transaction object.

    <Note>
      **Note:** Once signed, Solana transaction objects expire after one minute, so
      you should submit it immediately.
    </Note>
  </Tab>

  <Tab title="Transactions V2">
    For V2, the transfer data to be signed is encoded in the
    `encodedMessageToBeSigned` field from the
    [POST /v2/cpn/payments/:paymentId/transactions](/api-reference/cpn/cpn-platform/create-transaction-v2)
    endpoint. You would need to first decode it using the `base64` library and then
    sign it using a Solana library with your wallet key pair.

    ```typescript theme={null}
    import { Keypair, Transaction, Message } from "@solana/web3.js";
    import bs58 from "bs58";

    function signTransaction(
      encodedMessageToBeSigned: string,
      keypair: Keypair,
    ): string {
      // 1. Decode base64 message
      const messageBytes = Buffer.from(encodedMessageToBeSigned, "base64");

      // 2. Deserialize as Solana Message
      const message = Message.from(messageBytes);

      // 3. Create transaction with empty signatures
      const SIGNATURE_LENGTH = 64;
      const EMPTY_SIGNATURE_BASE58 = bs58.encode(
        Buffer.alloc(SIGNATURE_LENGTH).fill(0),
      );
      const numSignatures = message.header.numRequiredSignatures;

      const transaction = Transaction.populate(
        message,
        Array(numSignatures).fill(EMPTY_SIGNATURE_BASE58),
      );

      // 4. Sign with keypair
      transaction.partialSign(keypair);

      // 5. Serialize signed transaction, which you can then submit to the
      // POST /v2/cpn/payments/:paymentId/transactions/:transactionId/submit endpoint
      const signedTransaction = transaction
        .serialize({ requireAllSignatures: false })
        .toString("base64");

      return signedTransaction;
    }
    ```

    If you are using the Circle Wallets, you can use the
    [sign transaction](/api-reference/wallets/developer-controlled-wallets/sign-transaction)
    endpoint to sign the transaction object.

    ```typescript theme={null}
    import { Keypair, Transaction, Message } from "@solana/web3.js";
    import bs58 from "bs58";
    import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

    async function signTransactionWithCircleWallet(
      encodedMessageToBeSigned: string,
      walletId: string,
      apiKey: string,
      entitySecret: string,
    ): Promise<string> {
      // 1. Decode base64 message
      const messageBytes = Buffer.from(encodedMessageToBeSigned, "base64");

      // 2. Deserialize as Solana Message
      const message = Message.from(messageBytes);

      // 3. Create transaction with empty signatures
      const SIGNATURE_LENGTH = 64;
      const EMPTY_SIGNATURE_BASE58 = bs58.encode(
        Buffer.alloc(SIGNATURE_LENGTH).fill(0),
      );
      const numSignatures = message.header.numRequiredSignatures;

      const transaction = Transaction.populate(
        message,
        Array(numSignatures).fill(EMPTY_SIGNATURE_BASE58),
      );

      // 4. Serialize transaction
      const rawTransaction = transaction
        .serialize({ requireAllSignatures: false })
        .toString("base64");

      // 5. Initialize Circle client
      const circleClient = initiateDeveloperControlledWalletsClient({
        apiKey: apiKey,
        entitySecret: entitySecret,
      });

      // 6. Sign transaction, which you can then submit to the
      // POST /v2/cpn/payments/:paymentId/transactions/:transactionId/submit endpoint
      const signedTransaction = (
        await circleClient.signTransaction({
          walletId: walletId,
          rawTransaction: rawTransaction,
        })
      ).data.signedTransaction;

      return signedTransaction;
    }
    ```
  </Tab>
</Tabs>

### Step 3: Submit the signed transaction

Call the
[submit transaction](/api-reference/cpn/cpn-platform/submit-transaction)
endpoint to submit the signed transaction data to CPN. For Transactions V2, use
the
[submit transaction V2](/api-reference/cpn/cpn-platform/submit-transaction-v2)
endpoint. CPN broadcasts the transaction and provides a webhook to notify you of
the transaction status. This webhook is also provided to the BFI.

Once the BFI confirms that they have received the desired amount for the
payment, the BFI initiates the fiat payment.

#### Handling failures

If a transaction fails and the payment is still valid (for example, it has not
expired), you can address the issues with the transaction and initiate a new
transaction. For example, in a V1 transaction,if there was not enough gas to
cover the transaction, you could deposit additional gas tokens to the wallet,
and try again. In a V2 transaction, this is less likely to be an issue as gas
fees in native tokens are paid from a Circle-controlled wallet. You can use a
similar approach to address other onchain failures.

Only one active transaction is allowed at a time per payment, so you can only
initiate a new transaction once the previous one has failed.


# How-to: Grant USDC Allowance to Permit2
Source: https://developers.circle.com/cpn/guides/transactions/grant-usdc-allowance-to-permit2

Grant a USDC token allowance to the Permit2 contract using a Circle Wallets developer-controlled wallet or an EIP-1193 Ethereum wallet

For Transactions V2 on EVM blockchains, there is a dependency on the `Permit2`
contract to enable allowance management. To get the benefits of Transactions V2,
you must grant a USDC token allowance to the `Permit2` contract.

This guide shows two examples of how to grant a USDC token allowance to the
`Permit2` contract. The
[`Permit2` documentation](https://docs.uniswap.org/contracts/permit2/overview)
provides additional examples of how to grant this allowance.

## Prerequisites

The examples on this page show how to grant a USDC token allowance to the
`Permit2` contract using a
[Circle Wallets developer-controlled wallet](/wallets/dev-controlled) or a
generic EIP-1193 Ethereum wallet. Before you begin, ensure you have:

* If you are following the Circle Wallets example:
  * A Circle Developer Account
  * A
    [developer-controlled wallet](/wallets/dev-controlled/create-your-first-wallet)

* **Node.js** and **npm** installed on your development machine

* A project set up as described in the below section

### Set up your project

1. Initialize a new Node.js project and install dependencies:

   ```shell theme={null}
   npm init -y
   npm pkg set type=module
   npm install viem dotenv
   ```

2. In the project root, create a `.env` file and add the following variables:

   ```shell theme={null}
   USDC_CONTRACT_ADDRESS=<USDC_CONTRACT_ADDRESS>
   PERMIT2_CONTRACT_ADDRESS=<PERMIT2_CONTRACT_ADDRESS>
   APPROVAL_AMOUNT=<APPROVAL_AMOUNT>
   WALLET_ADDRESS=<WALLET_ADDRESS>
   ```

   The `PERMIT2_CONTRACT_ADDRESS` is the same across all EVM blockchains
   (`0x000000000022D473030F116dDEE9F6B43aC78BA3`), but you should verify it with
   the blockchain explorer on the chain you are using. You can find the
   `USDC_CONTRACT_ADDRESS` on the
   [USDC contract address page](/stablecoins/usdc-contract-addresses).

   <Note>
     The USDC token has 6 decimals. To approve \$100 USDC, set `APPROVAL_AMOUNT` to
     `100000000` (100 \* 10<sup>6</sup>).
   </Note>

   If you are following the Circle Wallets example, you will also need to add
   the following variables:

   ```shell theme={null}
   CIRCLE_WALLET_ID=<CIRCLE_WALLET_ID>
   CIRCLE_WALLETS_API_KEY=<CIRCLE_WALLETS_API_KEY>
   ENTITY_SECRET=<ENTITY_SECRET>
   ```

   If you are following the EIP-1193 Ethereum wallet example, or your Circle
   Wallet is on the generic `EVM` / `EVM-TESTNET` chain, you will also need to
   add the following variable:

   ```shell theme={null}
   RPC_URL=<RPC_URL>
   ```

3. Create an `index.js` file. You'll add code step by step in the following
   sections.

### Grant a USDC token allowance to the `Permit2` contract

The following example code shows the process for granting a USDC token allowance
to the
[`Permit2` contract](https://etherscan.io/address/0x000000000022D473030F116dDEE9F6B43aC78BA3)
using a Circle Wallets developer-controlled wallet or an EIP-1193 Ethereum
wallet.

<Tabs>
  <Tab title="Circle Wallets">
    <Note>
      **Note:** This example is for a Circle Wallets developer-controlled wallet on
      specific EVM blockchains (for example, `ETH`, `ETH-SEPOLIA`, `MATIC`,
      `MATIC-AMOY`, etc.). If your Circle Wallet is on the generic `EVM` /
      `EVM-TESTNET` chain, which is likely the case if you are migrating from
      Transactions V1 to V2, you can use the example in the "Circle Wallets (generic
      EVM)" tab.
    </Note>

    ```javascript theme={null}
    import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
    import { randomUUID } from "crypto";
    import dotenv from "dotenv";

    dotenv.config();

    /**
     * Approves a specified amount of USDC for the Permit2 contract using
     * a developer-controlled wallet managed by Circle.
     *
     * This function sends an on-chain transaction to call the ERC-20 `approve`
     * method on the USDC contract, allowing the Permit2 contract to spend
     * the specified amount on behalf of the wallet.
     *
     * @async
     * @function approveUSDCWithCircleWallets
     * @returns {Promise<object>} The transaction response data returned by Circle's API.
     */
    export async function approveUSDCWithCircleWallets() {
      const client = initiateDeveloperControlledWalletsClient({
        apiKey: process.env.CIRCLE_WALLETS_API_KEY,
        entitySecret: process.env.ENTITY_SECRET,
      });

      const response = await client.createContractExecutionTransaction({
        walletId: process.env.CIRCLE_WALLET_ID,
        contractAddress: process.env.USDC_CONTRACT_ADDRESS,
        abiFunctionSignature: "approve(address,uint256)",
        abiParameters: [
          process.env.PERMIT2_CONTRACT_ADDRESS,
          process.env.APPROVAL_AMOUNT,
        ],
        idempotencyKey: randomUUID(),
        fee: { type: "level", config: { feeLevel: "MEDIUM" } },
      });

      return response.data;
    }

    /* -------- Example usage with Circle ---------

    // For auth and wallet creation, see: https://developers.circle.com/interactive-quickstarts/dev-controlled-wallets
    const response = await approveUSDCWithCircleWallets();
    console.log('Response:', response);

    ---------------------------------- */
    ```
  </Tab>

  <Tab title="Circle Wallets (generic EVM)">
    <Note>
      **Note:** This example is for a Circle Wallets developer-controlled wallet on
      generic EVM blockchains (for example, `EVM`, `EVM-TESTNET`). If you are getting
      started with Transactions V2 instead of migrating from Transactions V1, Circle
      recommends that you use create chain-specific Circle Wallets (for example,
      `ETH`, `ETH-SEPOLIA`, `MATIC`, `MATIC-AMOY`) instead of a generic EVM wallet and
      follow the example in the "Circle Wallets" tab instead.
    </Note>

    ```javascript theme={null}
    import { createPublicClient, http, encodeFunctionData, erc20Abi } from "viem";
    import { sepolia } from "viem/chains";
    import dotenv from "dotenv";

    dotenv.config();

    /**
     * Signs a transaction using a developer-controlled wallet managed by Circle.
     *
     * For EVM chains, accepts a transaction object in JSON format.
     * The transaction object will be automatically stringified if needed.
     *
     * @async
     * @function signTransaction
     * @param {object} transaction - Transaction object for EVM chains
     * @returns {Promise<object>} The signature response data returned by Circle's API
     *
     * @example
     * const signature = await signTransaction({
     *   to: '0x...',
     *   value: '0x0',
     *   data: '0x...',
     *   nonce: 1,
     *   gasLimit: '0x5208',
     *   maxFeePerGas: '0x...',
     *   maxPriorityFeePerGas: '0x...',
     *   chainId: 1
     * });
     */
    export async function signTransaction(transaction) {
      const client = initiateDeveloperControlledWalletsClient({
        apiKey: process.env.CIRCLE_WALLETS_API_KEY,
        entitySecret: process.env.ENTITY_SECRET,
      });

      const transactionJson = JSON.stringify(
        transaction,
        (_, value) => (typeof value === "bigint" ? value.toString() : value),
        2,
      );

      const response = await client.signTransaction({
        walletId: process.env.CIRCLE_WALLET_ID,
        transaction: transactionJson,
      });

      return response.data;
    }

    /**
     * Composes a raw unsigned EIP-1559 transaction for approving USDC for the Permit2 contract.
     * This transaction can then be signed using Circle Wallets' raw transaction signing API.
     *
     * @async
     * @function composeUSDCApprovalTransaction
     * @returns {Promise<object>} The unsigned EIP-1559 transaction object.
     */
    export async function composeUSDCApprovalTransaction() {
      const publicClient = createPublicClient({
        chain: sepolia,
        transport: http(process.env.RPC_URL),
      });

      // Step 1: Encode the function call data
      const data = encodeFunctionData({
        abi: erc20Abi,
        functionName: "approve",
        args: [
          process.env.PERMIT2_CONTRACT_ADDRESS,
          BigInt(process.env.APPROVAL_AMOUNT),
        ],
      });

      // Step 2: Estimate gas fees (viem handles the calculation)
      const fees = await publicClient.estimateFeesPerGas();

      // Step 3: Prepare the transaction request (viem auto-fills nonce, gas, etc.)
      const transaction = await publicClient.prepareTransactionRequest({
        account: process.env.SENDER_WALLET_ADDRESS,
        to: process.env.USDC_CONTRACT_ADDRESS,
        value: 0n,
        data,
        ...fees,
      });

      return transaction;
    }

    /**
     * Broadcasts an signed transaction to the network.
     *
     * @async
     * @function broadcastSignedTransaction
     * @param {string} signedTransaction - The signed transaction as a hex string (with 0x prefix)
     * @returns {Promise<string>} The transaction hash
     */
    export async function broadcastSignedTransaction(signedTransaction) {
      const publicClient = createPublicClient({
        chain: sepolia, // use the correct chain for your wallet
        transport: http(process.env.RPC_URL),
      });

      // Send the raw signed transaction
      const txHash = await publicClient.sendRawTransaction({
        serializedTransaction: signedTransaction,
      });

      return txHash;
    }

    /* -------- Example usage with Circle ---------

    // For auth and wallet creation, see: https://developers.circle.com/interactive-quickstarts/dev-controlled-wallets
    const tx = await composeUSDCApprovalTransaction();
    const signature = await signTransaction(tx);
    const txHash = await broadcastSignedTransaction(signature.signedTransaction);

    ---------------------------------- */
    ```
  </Tab>

  <Tab title="EIP-1193 Ethereum Wallet">
    ```javascript theme={null}
    import {
      createWalletClient,
      createPublicClient,
      http,
      custom,
      erc20Abi,
    } from "viem";
    import { sepolia } from "viem/chains";
    import dotenv from "dotenv";

    dotenv.config();

    /**
     * Approves a specified amount of USDC for the Permit2 contract using
     * a custom wallet with an EIP-1193 provider (like MetaMask).
     *
     * This function sends an on-chain transaction to call the ERC-20 `approve`
     * method on the USDC contract, allowing the Permit2 contract to spend
     * the specified amount on behalf of the wallet.
     *
     * @async
     * @function approveUSDCWithEIP1193Wallet
     * @param {any} [provider] - EIP-1193 provider.
     * @returns {Promise<object>} The transaction hash and receipt.
     */
    export async function approveUSDCWithEIP1193Wallet(provider) {
      const publicClient = createPublicClient({
        chain: sepolia,
        transport: http(process.env.RPC_URL),
      });

      const walletClient = createWalletClient({
        account: process.env.WALLET_ADDRESS,
        chain: sepolia,
        transport: custom(provider),
      });

      const hash = await walletClient.writeContract({
        address: process.env.USDC_CONTRACT_ADDRESS,
        abi: erc20Abi,
        functionName: "approve",
        args: [
          process.env.PERMIT2_CONTRACT_ADDRESS,
          BigInt(process.env.APPROVAL_AMOUNT),
        ],
      });

      const receipt = await publicClient.waitForTransactionReceipt({ hash });
      return { hash, receipt };
    }

    /* -------- Example usage with EIP-1193 wallet ---------

    // Refer to https://viem.sh/docs/clients/transports/custom and your wallet provider's documentation for the provider object. 
    const {hash, receipt} = await approveUSDCWithEIP1193Wallet({provider: window.ethereum});
    console.log('Hash:', hash);
    console.log('Receipt:', receipt);

    ---------------------------------- */
    ```
  </Tab>
</Tabs>


# How-to: Migrate from Transactions V1 to V2
Source: https://developers.circle.com/cpn/guides/transactions/migrate-from-txn-v1-to-v2

Update your CPN integration from Transactions V1 to V2

Transactions V2 allows for a more straightforward integration with CPN compared
to Transactions V1. It also provides more powerful onchain settlement
primitives, such as auto-acceleration and gas fees that are fixed at quote time.
If you have previously integrated with CPN using the Transactions V1 API, you
can migrate to Transactions V2 without changes to your wallet infrastructure.

Compared to Transactions V1, Transactions V2 has the following differences:

* When creating the CPN quote, you must set the `transactionVersion` parameter
  to `VERSION_2`.
* Gas fees are not charged in native tokens, but in USDC. They are determined at
  quote creation instead of transaction creation in the quote `fees` field. The
  gas fee is collected by Circle's payment settlement smart contract during
  onchain transaction processing.
* There are separate API endpoints for creating and submitting transactions.

Depending on the blockchain, there are additional differences:

<Tabs>
  <Tab title="EVM chains">
    * Before initiating a transaction, the sender wallet must grant the
      [`Permit2` contract](https://docs.uniswap.org/contracts/permit2/overview) a
      USDC allowance.
    * When signing the transaction, you no longer need to compose and sign the raw
      EVM transaction; you only need to sign the EIP-712 typed data provided to you
      in the `messageToBeSigned` field and submit the signature.
    * CPN handles the auto-acceleration of the transaction. You no longer need to
      monitor transaction broadcast status or submit acceleration transactions.
  </Tab>

  <Tab title="Solana">
    * In the signing process, instead of deserializing and signing the
      `messageToBeSigned` field, you would need to use the
      `encodedMessageToBeSigned` field. Please refer to [How-to: Create an Onchain
      Transaction](/cpn/guides/transactions/create-an-onchain-txn) for more
      information on how to sign the transaction in V2.
  </Tab>
</Tabs>

This guide provides information on how to migrate your existing integration from
Transactions V1 to V2 on EVM. On Solana, you would follow a similar process with
some differences in the signing process.

## Prerequisites

Before you begin, ensure that you have:

* Obtained an API key for CPN from Circle
* USDC in your sender wallet
* cURL installed on your development machine
* (EVM chains only) Granted a USDC allowance to the `Permit2` contract. See
  [How-to: Grant USDC Allowance to Permit2](/cpn/guides/transactions/grant-usdc-allowance-to-permit2)
  for more information.

> **Note:** This guide provides API requests in cURL format, along with example
> responses.

## Steps

Use the following steps to create an onchain transaction using Transactions V2.

### Step 1. Create a quote

Use the [create a quote](/api-reference/cpn/cpn-platform/create-quotes) endpoint
to create a quote with the `transactionVersion` parameter set to `VERSION_2`.
When checking limits beforehand, call the
[list routes](/api-reference/cpn/cpn-platform/list-routes) endpoint with
`transactionVersion=VERSION_2` so returned crypto min limits include the
chain-specific fee buffer.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/cpn/quotes \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
    "paymentMethodType": "SPEI",
    "senderCountry": "US",
    "destinationCountry": "MX",
    "sourceAmount": {
        "currency": "USDC"
    },
    "destinationAmount": {
        "amount": "200",
        "currency": "MXN"
    },
    "blockchain": "ETH-SEPOLIA",
    "senderType": "INDIVIDUAL",
    "recipientType": "INDIVIDUAL",
    "transactionVersion": "VERSION_2"
}
'
```

**Response**

```json theme={null}
{
  "data": [
    {
      "id": "2792f4a6-f1bd-4435-b681-1da309122159",
      "paymentMethodType": "SPEI",
      "blockchain": "ETH-SEPOLIA",
      "senderCountry": "US",
      "destinationCountry": "MX",
      "createDate": "2025-09-24T00:01:13.532073875Z",
      "quoteExpireDate": "2025-09-24T00:01:42.502094Z",
      "cryptoFundsSettlementExpireDate": "2025-09-24T01:01:12.502097Z",
      "sourceAmount": {
        "amount": "15.000000",
        "currency": "USDC"
      },
      "destinationAmount": {
        "amount": "252.91",
        "currency": "MXN"
      },
      "fiatSettlementTime": {
        "min": "0",
        "max": "5",
        "unit": "MINUTES"
      },
      "exchangeRate": {
        "rate": "16.860667",
        "pair": "USDC/MXN"
      },
      "fees": {
        "totalAmount": {
          "amount": "1.568971",
          "currency": "USDC"
        },
        "breakdown": [
          {
            "type": "TAX_FEE",
            "amount": {
              "amount": "0.234663",
              "currency": "USDC"
            }
          },
          {
            "type": "BFI_TRANSACTION_FEE",
            "amount": {
              "amount": "0.138037",
              "currency": "USDC"
            }
          },
          {
            "type": "CIRCLE_SERVICE_FEE",
            "amount": {
              "amount": "0.000000",
              "currency": "USDC"
            }
          },
          {
            "type": "BLOCKCHAIN_GAS_FEE",
            "amount": {
              "amount": "1.196271",
              "currency": "USDC"
            }
          }
        ]
      },
      "senderType": "INDIVIDUAL",
      "recipientType": "INDIVIDUAL",
      "certificate": {
        // certificate object
      },
      "quoteOptions": {
        "isFirstParty": false
      },
      "transactionVersion": "VERSION_2"
    }
  ]
}
```

> **Note:** The quote returned from this step must follow the Transactions V2
> workflow, you can't switch from V2 back to V1 without first recreating the
> quote.

### Step 2. Create a V2 transaction

You would then follow the same payment API workflow as before, create a payment
from the [create a payment](/api-reference/cpn/cpn-platform/create-payment)
endpoint. After your payment is in the `CRYPTO_FUNDS_PENDING` state, initiate
the transaction using the
[create a transaction V2](/api-reference/cpn/cpn-platform/create-transaction-v2)
endpoint.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v2/cpn/payments/:paymentId/transactions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey" : "${RANDOM_UUID}"
}
'
```

**Response**

```json theme={null}
{
  "data": {
    "id": "dbc27d23-cd4f-447e-855e-349cb2853d23",
    "status": "CREATED",
    "paymentId": "49d4231e-6c4f-319e-946d-ed8c8bab5abc",
    "expireDate": "2025-09-08T20:02:06.651391Z",
    "blockchain": "ETH-SEPOLIA",
    "senderAddress": "0x1234567890123456789012345678901234567890",
    "destinationAddress": "0x0000000000000000000000000000000000000001",
    "amount": {
      "amount": "15.000000",
      "currency": "USDC"
    },
    "messageType": "PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT",
    "messageToBeSigned": {
      "domain": {
        "name": "Permit2",
        "chainId": "11155111",
        "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
      },
      "message": {
        "permitted": {
          "token": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
          "amount": "14174474"
        },
        "spender": "0xe2B17D0C1736dc7C462ABc4233C91BDb9F27DD1d",
        "nonce": "25668617285137697861288274946631174355105919960416755114569514179393151588120",
        "deadline": "1757362866",
        "witness": {
          "from": "0x1234567890123456789012345678901234567890",
          "to": "0x0000000000000000000000000000000000000001",
          "value": 14174474,
          "validAfter": "1757358106",
          "validBefore": "1757361726",
          "nonce": "0x38bfec2b230187932870d575132e8ae1f83b34c10e3bf6d64c377f0c13245718",
          "beneficiary": "0x4f1c3a0359A7fAd8Fa8E9E872F7C06dAd97C91Fd",
          "maxFee": "0",
          "attester": "0x768919ef04853b5fd444ccff48cea154768a0291",
          "requirePayeeSign": false
        }
      },
      "primaryType": "PermitWitnessTransferFrom",
      "types": {
        "EIP712Domain": [
          {
            "name": "name",
            "type": "string"
          },
          {
            "name": "chainId",
            "type": "uint256"
          },
          {
            "name": "verifyingContract",
            "type": "address"
          }
        ],
        "PermitWitnessTransferFrom": [
          {
            "name": "permitted",
            "type": "TokenPermissions"
          },
          {
            "name": "spender",
            "type": "address"
          },
          {
            "name": "nonce",
            "type": "uint256"
          },
          {
            "name": "deadline",
            "type": "uint256"
          },
          {
            "name": "witness",
            "type": "PaymentIntent"
          }
        ],
        "TokenPermissions": [
          {
            "name": "token",
            "type": "address"
          },
          {
            "name": "amount",
            "type": "uint256"
          }
        ],
        "PaymentIntent": [
          {
            "name": "from",
            "type": "address"
          },
          {
            "name": "to",
            "type": "address"
          },
          {
            "name": "value",
            "type": "uint256"
          },
          {
            "name": "validAfter",
            "type": "uint256"
          },
          {
            "name": "validBefore",
            "type": "uint256"
          },
          {
            "name": "nonce",
            "type": "bytes32"
          },
          {
            "name": "beneficiary",
            "type": "address"
          },
          {
            "name": "maxFee",
            "type": "uint256"
          },
          {
            "name": "requirePayeeSign",
            "type": "bool"
          },
          {
            "name": "attester",
            "type": "address"
          }
        ]
      }
    },
    "metadata": {}
  }
}
```

### Step 3. Sign and submit the transaction

From the response in the previous step, extract the `messageToBeSigned` field.
You must sign this data using [EIP-712](https://eips.ethereum.org/EIPS/eip-712)
typed data signing from your sender wallet. Once signed, you should submit it to
the
[submit transaction V2](/api-reference/cpn/cpn-platform/submit-transaction-v2)
endpoint. The following is an example request:

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v2/cpn/payments/:paymentId/transactions/:transactionId/submit \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-type: application/json' \
  --data '
{
  "signedTransaction": "0x12b5fb72e99f9bb0300d2eb66a6d89dd5a667f43669893cf14bfcc390754dcb61b69f92cba598ec83a184e11c97e3bb9964a2bfd7a09688eee63f586ad9ccae21c"
}
'
```

<Note>
  **Note:** For Solana, follow the steps in [How-to: Create an Onchain
  Transaction](/cpn/guides/transactions/create-an-onchain-txn) to sign the
  transaction. You would submit the signed transaction in the same way as for
  EVM.
</Note>

After the transaction is submitted, CPN is responsible for broadcasting the
transaction to the blockchain. You will be notified by webhooks when events
related to the transaction occur. Unlike Transaction V1, you don't need to
actively monitor the transaction or manually accelerate it. CPN monitors the
transaction and automatically accelerates it if necessary.


# How-to: Set Up a Circle Wallet for CPN Payments
Source: https://developers.circle.com/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments

Configure a Circle-hosted dev-controlled wallet as your operational wallet for CPN onchain payment flows.

Use Circle-hosted [dev-controlled wallets](/wallets/dev-controlled.mdx) as your
operational wallet for CPN onchain payment flows. Circle custody keeps signing
keys secure and surfaces the wallet address and wallet ID through the Wallet
APIs.

Treasury is your responsibility: fund the wallet on the right blockchain,
reconcile balances, and size liquidity for your payment volume. When Circle also
moves your fiat and USDC, pair this guide with
[Set up Circle on/off-ramps for CPN payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments).
If you custody keys yourself, see
[Bring your own wallet for CPN](/cpn/concepts/wallets/bring-your-own-wallet).

## Overview

* Use this guide when you want Circle to host the wallet that signs CPN onchain
  transactions for USDC transfers.
* CPN does not require Circle-hosted wallets. The steps here are optional; they
  support teams that want Circle custody for the sender wallet.
* After your wallet holds USDC on the required blockchain, you can continue with
  [Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi) or
  [Create an onchain transaction](/cpn/guides/transactions/create-an-onchain-txn).

<Note>
  Dev-controlled Programmable Wallets are documented in the [Circle
  Wallets](/wallets) section. This topic frames those capabilities for CPN
  payments only.
</Note>

## Prerequisites

Before you begin:

* You have a [CPN Console](https://cpn.circle.com/signin) account with the
  [Circle Wallet](/wallets/dev-controlled) capability enabled for your
  organization.
* You have an API key for Programmable Wallets. Create and manage keys in
  [CPN Console → Developer → API Keys](https://cpn.circle.com/signin).
* You have sandbox or mainnet access enabled for Programmable Wallets.

<Note>
  Mainnet access for Programmable Wallets is typically granted after your CPN
  eligibility application is approved, when **Circle Wallets** was requested as
  a capability.
</Note>

## Steps

This guide covers generating and registering your entity secret, creating a
wallet set and EOA wallet, configuring notifications, and funding the wallet
with USDC.

### Step 1. Generate and register your entity secret

The entity secret is a 32-byte value that secures your developer-controlled
wallets. Circle never stores the secret in plain text: you must protect it.

Register your entity secret:

<Tabs>
  <Tab title="Using the SDK">
    Follow
    [Register your entity secret](/wallets/dev-controlled/register-entity-secret)
    for Node.js and Python: install the SDK, generate the entity secret, and
    register the ciphertext with Circle. That guide includes tabs for each language.
    Use environment variables or a secrets manager for `apiKey` and `entitySecret`;
    never commit real values.
  </Tab>

  <Tab title="Without the SDK">
    Generate a cryptographically random 32-byte value and store it in a secure
    location (for example in a secrets manager). From a terminal you can use:

    ```bash theme={null}
    openssl rand -hex 32
    ```

    Encrypt the secret with Circle's public key, then register the ciphertext with
    the Programmable Wallets configuration API. Read
    [Entity secret management](/wallets/dev-controlled/entity-secret-management) for
    encryption, ciphertext, and non-SDK options, including the sample repository
    linked from that topic.

    The HTTP API uses `POST /v1/w3s/config/entity/entitySecret` with a body
    containing `entitySecretCiphertext`. Store the recovery file from the response
    if you need to recover access later.
  </Tab>
</Tabs>

### Step 2. Create a wallet set and operational wallet

A wallet set groups wallets under one entity secret. Create a wallet set, then
create at least one externally owned account (EOA) wallet.

Use the API reference for request and response fields:

* [Create wallet set](/api-reference/wallets/developer-controlled-wallets/create-wallet-set)
  (`POST /v1/w3s/developer/walletSets`)
* [Create wallet](/api-reference/wallets/developer-controlled-wallets/create-wallet)
  (`POST /v1/w3s/developer/wallets`)

Example request body for a single sandbox EOA on Sepolia (adjust names and
ciphertext for your environment):

**1. Create wallet set** - example request body:

```json theme={null}
{
  "name": "CPN Operational Wallets",
  "entitySecretCiphertext": "<your_encrypted_entity_secret>"
}
```

**2. Create wallet** - example request body for the second call. Replace
`<your_wallet_set_id>` with the `walletSetId` from the create-wallet-set
response:

```json theme={null}
{
  "idempotencyKey": "<unique_key>",
  "entitySecretCiphertext": "<your_encrypted_entity_secret>",
  "walletSetId": "<your_wallet_set_id>",
  "blockchains": ["ETH-SEPOLIA"],
  "count": 1,
  "accountType": "EOA"
}
```

Save the **wallet ID** and **address** from the create-wallet response. CPN uses
the wallet ID for transaction APIs; funding flows use the address.

Use `ETH-SEPOLIA` for typical Transactions V2 sandbox testing. For Transactions
V1 on EVM testnet, use `EVM-TESTNET` instead. On mainnet, set `blockchains` to
the production identifier that matches your CPN corridor (for example, `ETH` for
Ethereum mainnet). See
[Supported blockchains](/cpn/references/blockchains/supported-blockchains).

### Step 3. Configure webhook notifications for wallet activity

Subscribe to wallet and transaction events so your system is notified when funds
arrive or transfers complete.

1. Open [CPN Console → Developer → Webhooks](https://cpn.circle.com/signin) and
   add or update your subscriber configuration as offered for your organization.
2. For Programmable Wallets subscription details and payload shapes, see
   [Webhook notifications](/wallets/webhook-notifications),
   [Webhook notification flows](/wallets/webhook-notification-flows), and
   [Create subscription](/api-reference/wallets/common/create-subscription)
   (`POST /v2/notifications/subscriptions`). Common event types include
   `transactions.inbound` and `transactions.outbound`.

### Step 4. Fund your wallet with USDC

Your operational wallet must hold USDC before you initiate a CPN payment that
draws from that wallet.

* **Sandbox:** Use the [Circle faucet](https://faucet.circle.com/) to obtain
  testnet USDC. Enter your wallet address and select the matching testnet
  blockchain. For Transactions V1 on EVM, ensure you also have testnet native
  gas tokens (check the faucet for your target blockchain).
* **Mainnet:** Fund the wallet by moving USDC from your Circle business account
  balance (for example after an on-ramp). Follow how to
  [Set Up Circle On/Off-Ramps for CPN Payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments).
  You can exercise the Circle APIs flow in sandbox before switching to
  production endpoints.

Confirm funding with
[List wallet balance](/api-reference/wallets/developer-controlled-wallets/list-wallet-balance)
(`GET /v1/w3s/wallets/{id}/balances`). When your USDC balance is sufficient for
your test or production payment, you are ready to call CPN transaction APIs.

## See also

* [Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi)
  (continue at Part 1: Request a quote).
* [Set up Circle on/off-ramps for CPN payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments)
  (fund your operational wallet via Circle Mint).
* [Set up webhook notifications](/cpn/guides/webhooks/setup-webhook-notifications)
  (CPN payment events)
* [Webhook events](/cpn/references/webhooks/webhook-events)
* [Entity secret management](/wallets/dev-controlled/entity-secret-management)


# Set up Webhook Notifications
Source: https://developers.circle.com/cpn/guides/webhooks/setup-webhook-notifications



During the payment process, CPN sends notifications using webhooks. These
asynchronous notifications inform the entities on the progress of the payment
and any required actions they must take.

This guide demonstrates how to subscribe to CPN notifications as an OFI
integrator. See [Webhook Events](/cpn/references/webhooks/webhook-events) for a
complete list of the notifications that are sent over webhooks.

## Steps

Use the following steps to set up a webhook endpoint and subscribe to
notifications using the CPN API.

### Step 1: Set up a subscriber endpoint

To receive webhook notifications, you must expose a publicly accessible
subscriber endpoint. The endpoint must be able to handle both `HEAD` and `POST`
requests over HTTPS.

<Note>
  **Note:** During OFI integration, Circle works directly with you to configure
  this endpoint.
</Note>

For testing purposes, you can create an endpoint using
[webhook.site](https://webhook.site).

### Step 2: Subscribe to notifications

Set up an endpoint to receive notifications instead of polling for event updates
using the `/v2/subscriptions` endpoint.

```shell Shell theme={null}
curl --request POST \
  --url https://api.circle.com/v2/cpn/notifications/subscriptions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}:' \
  --header 'Content-type: application/json' \
  --data '
{
    "endpoint": "${YOUR_WEBHOOK_ENDPOINT}",
    "name": "Test OFI",
    "enabled": true,
    "notificationTypes": ["*"]
}
'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "id": "1609aa1c-510a-448d-b9b9-3a13566ff922",
    "name": "Test OFI",
    "endpoint": "https://webhook.site/1fde07a9-8974-42bd-a273-943ffdf0e7d6",
    "enabled": true,
    "createDate": "2025-05-08T16:20:02.825689Z",
    "updateDate": "2025-05-08T16:20:02.825689Z",
    "notificationTypes": ["*"],
    "restricted": false
  }
}
```

Webhook notifications are digitally signed with an asymmetric key. You can use
information in the webhook header to verify that the content of the webhook is
legitimate. For more information, see
[How-to: Verify Webhook Signatures](/cpn/guides/webhooks/verify-webhook-signatures).


# Verify Webhook Signatures
Source: https://developers.circle.com/cpn/guides/webhooks/verify-webhook-signatures



Every webhook notification sent by CPN is digitally signed with an asymmetric
key. This guide demonstrates how to use the key and signature to verify that a
webhook notification was sent by Circle. Validating webhooks in this way can
reduce the risk of person-in-the-middle attacks on your subscriber endpoint.

## Steps

Use the following steps to verify the Circle signature on a webhook
notification.

### Step 1: Get the digital signature and ID of the notification

Every webhook notification is digitally signed with an asymmetric key. The
asymmetric key is random for each webhook, so you must perform this full
authentication flow to validate the key. This signature is available in the
header of the message. Each message contains the following headers:

* `X-Circle-Signature`: the digital signature generated by Circle
* `X-Circle-Key-Id`: the public key ID in UUID format

Extract those values from the header of the webhook message.

### Step 2: Get the public key and encryption algorithm

Using the `X-Circle-Key-Id` value, query the
[`/v2/cpn/notifications/publicKey/{keyId}`](/api-reference/cpn/common/get-notification-signature)
endpoint.

```shell Shell theme={null}
curl --request GET \
     --url "https://api.circle.com/v2/cpn/notifications/publicKey/${PUBLIC_KEY_ID}" \
     --header "Accept: application/json" \
     --header "authorization: Bearer ${YOUR_API_KEY}"
```

**Response**

```json JSON theme={null}
{
  "data": {
    "id": "879dc113-5ca4-4ff7-a6b7-54652083fcf8",
    "algorithm": "ECDSA_SHA_256",
    "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAESl76SZPBJemW0mJNN4KTvYkLT8bOT4UGhFhzNk3fJqf6iuPlLQLq533FelXwczJbjg2U1PHTvQTK7qOQnDL2Tg==",
    "createDate": "2023-06-28T21:47:35.107250Z"
  }
}
```

<Note>
  **Note:** To avoid making multiple requests to the public key endpoint, you
  should cache the public key associated with a given public key ID.
</Note>

### Step 3: Verify the signature

Use the public key and the specified algorithm from the response in step 2,
along with the `X-Circle-Signature` value, to verify the integrity of the
webhook's payload.

The following Python code demonstrates how to verify the `X-Circle-Signature`
value:

```python Python theme={null}
import base64
import json

from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec

# Load the public key from the base64 encoded string
public_key_base64 = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAESl76SZPBJemW0mJNN4KTvYkLT8bOT4UGhFhzNk3fJqf6iuPlLQLq533FelXwczJbjg2U1PHTvQTK7qOQnDL2Tg=="
public_key_bytes = base64.b64decode(public_key_base64)
public_key = serialization.load_der_public_key(public_key_bytes)

# Load the signature you want to verify
signature_base64 = "MEQCIBlJPX7t0FDOcozsRK6qIQwik5Fq6mhAtCSSgIB/yQO7AiB9U5lVpdufKvPhk3cz4TH2f5MP7ArnmPRBmhPztpsIFQ=="
signature_bytes = base64.b64decode(signature_base64)

# Load and format the message you want to verify
message = "{\"subscriptionId\":\"00000000-0000-0000-0000-000000000000\",\"notificationId\":\"00000000-0000-0000-0000-000000000000\",\"notificationType\":\"webhooks.test\",\"notification\":{\"hello\":\"world\"},\"timestamp\":\"2024-01-26T18:22:19.779834211Z\",\"version\":2}"
message_bytes = message.encode(encoding="utf-8")

# Verify the signature
try:
    public_key.verify(
        signature_bytes,
        message_bytes,
        ec.ECDSA(hashes.SHA256())
    )
    print("Signature is valid.")
except InvalidSignature:
    print("Signature is invalid.")
```

<Tip>
  **Tip:** Ensure that the webhook payload that you input in the `message` field
  is a properly formatted JSON string. Invalid JSON causes verification failure.
</Tip>


# CPN Managed Payments
Source: https://developers.circle.com/cpn/managed-payments

CPN Managed Payments is a turnkey stablecoin solution in which Circle takes on licensing, compliance, minting, and global settlement.

CPN Managed Payments gives partners stablecoin settlement without needing
in-house custody, compliance, or onchain systems. Circle holds assets, runs
compliance, and does the onchain work. You call APIs for sub-wallets, funding,
withdrawals, and payins or payouts. You stay in fiat at the edge. Payment
platforms and banks can offer stablecoin payments under their brand without
custody or compliance builds in-house. See the
[Managed Payments API](#api-summary).

## Key features

* **Fiat funding and withdrawals:** Send or receive fiat over wire and other
  methods Circle supports.
* **Stablecoin payins and payouts:** Send and receive USDC on
  [supported blockchains](/cpn/references/blockchains/supported-blockchains).
  Payins credit each sub-wallet; send payouts from each sub-wallet or the main
  wallet when enabled.
* **Merchant sub-wallets:** Give each merchant or customer a separate stablecoin
  account for clear bookkeeping and audit trails. Use the Accounts API to list,
  create, and fetch these accounts. Your agreement's onboarding model determines
  whether you or Circle provisions them.
* **Webhook notifications:** Receive webhook events for payment intents,
  payments, address book recipients, payouts, and credit transfers. See
  [Webhook events](/cpn/managed-payments/references/webhook-events) for event
  types and payloads.
* **Line of credit and reporting:** Borrow USDC on credit when your agreement
  allows it. Daily and monthly payout and balance reports are available.
* **Two onboarding models:** Your Managed Payments agreement with Circle sets
  which model you use.
  * **Direct:** Circle works directly with your merchants/customers. You collect
    Know Your Business (KYB) of your merchant and share it with Circle. Circle
    creates sub-wallets for the merchants/customers after KYB approval.
  * **Intermediary:** Circle doesn't have to onboard your underlying merchants
    or customers. You create sub-wallets for each merchant or customer with the
    APIs.

## How it works

<Steps>
  <Step title="Onboard and obtain API access">
    You join through Circle's invitation and sign up with a Managed Payments
    account. Circle assigns role-based permissions to your API keys, controlling
    access to specific capabilities such as sub-wallets, wires, stablecoin payouts,
    reports, and balance views. Circle configures these roles during onboarding.
  </Step>

  <Step title="Create merchant sub-wallets">
    Creating merchant sub-wallets depends on the onboarding process you agree on
    with Circle.

    * **Direct onboarding:** You collect end-merchant Know Your Business (KYB)
      information and share it with Circle through a secure offline channel. Circle
      creates sub-wallets for those merchants on your behalf.
    * **Intermediary model:** Use the
      [accounts API](/api-reference/cpn/managed-payments/accounts/create-account)
      to create the sub-wallets you need for your merchants. Sub-wallets keep
      balances separate for tracking and reporting.
  </Step>

  <Step title="Run payin and payout flows">
    * **Payins:**
      1. [Create a continuous payment intent](/api-reference/cpn/managed-payments/payment-intents/create-payment-intent)
         for third-party payins so each sub-wallet has a stable USDC receive address.
      2. After USDC is confirmed, use
         [Fiat Burns](/api-reference/cpn/managed-payments/withdrawals/create-account-withdrawal)
         to withdraw USDC to fiat in your bank account.
    * **Payouts:**
      1. Use the
         [Wires API](/api-reference/cpn/managed-payments/wires/create-account-wire-account)
         to add bank accounts and wire instructions, then send fiat so Circle credits
         USDC.
      2. Use the
         [Payouts API](/api-reference/cpn/managed-payments/payouts/create-payout)
         to send USDC onchain to payees you register and approve in the
         [Address Book](/api-reference/cpn/managed-payments/address-book/create-address-book-recipient).
    * **Line of credit (optional):** If your agreement supports it, you can borrow
      USDC before fiat settles.
  </Step>
</Steps>

## API summary

| Area                                                                                    | Purpose                                                                                                       |
| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| [Accounts API](/api-reference/cpn/managed-payments/accounts/list-accounts)              | Create sub-account wallets for merchants. List and get stablecoin accounts for self and merchant sub-wallets. |
| [Payins](/api-reference/cpn/managed-payments/payment-intents/create-payment-intent)     | Payment intents and Payments for payin flows.                                                                 |
| [Fiat Burns](/api-reference/cpn/managed-payments/withdrawals/create-account-withdrawal) | Withdraw USDC to fiat in your bank when enabled.                                                              |
| [Payouts](/api-reference/cpn/managed-payments/payouts/create-payout)                    | Onchain USDC sends plus funding, Address Book, and Line of Credit when enabled.                               |

For more details, see the
[Managed Payments API reference](/api-reference/cpn/managed-payments/accounts/list-accounts).

## Get started

Pick a quickstart to walk through a managed payment flow:

<CardGroup>
  <Card title="Receive Stablecoin Payins" icon="arrow-down-long" href="/cpn/managed-payments/quickstarts/receive-stablecoin-payins">
    Payment intents, inbound USDC, and settlement to fiat for your use case.
  </Card>

  <Card title="Send Stablecoin Payouts" icon="paper-plane" href="/cpn/managed-payments/quickstarts/send-stablecoin-payouts">
    Sub-wallets, funding, and USDC payouts for your managed payments use case.
  </Card>
</CardGroup>


# Settlement Flows
Source: https://developers.circle.com/cpn/managed-payments/concepts/settlement-flows

How Managed Payments moves value between fiat and USDC for payin-heavy and payout-heavy setups

When you use Managed Payments, you settle in USDC while your books stay in fiat.
Circle holds assets in regulated custody, runs compliance checks, and moves
funds both onchain and to your bank. Two settlement flows support this model:

* [Payins](#payins-usdc-to-fiat) (USDC-to-fiat): Inbound USDC that Circle
  converts and deposits as fiat in your bank account.
* [Payouts](#payouts-fiat-to-usdc) (fiat-to-USDC): Fiat you send to Circle that
  backs outbound USDC to payees you designate.

You can run one flow, the other, or both depending on your volume and product
design. The sections below walk through how each flow works, when to choose one
over the other, and what APIs you call at each stage.

## Payins (USDC-to-fiat)

A payin settles inbound USDC as fiat in your bank account. Circle manages the
custodial accounts, performs compliance screening, and executes a first-party
burn to move value offchain.

### How a payin moves through the system

1. **Payer sends USDC onchain.** The USDC arrives in a Circle Managed Payments
   account. Many integrations create a continuous payment intent on each
   sub-wallet so every merchant or segment has a stable receive address.
2. **Circle screens and confirms the deposit.** Circle's compliance and policy
   engine evaluates the transaction before it progresses.
3. **USDC is burned.** Circle performs a first-party burn to remove the USDC
   from circulation and convert the value to fiat.
4. **Fiat is credited to your bank.** After the burn completes, Circle initiates
   a withdrawal to your designated bank account for local disbursement.

### Key API calls for payins

| Action                      | Endpoint                                                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Create a payment intent     | [Create payment intent](/api-reference/cpn/managed-payments/payment-intents/create-payment-intent) (Payment Intents API) |
| List payments               | [List payments](/api-reference/cpn/managed-payments/payments/list-payments) (Payments API)                               |
| Burn USDC and withdraw fiat | [Create account withdrawal](/api-reference/cpn/managed-payments/withdrawals/create-account-withdrawal) (Fiat Burns API)  |

### When to use payins

Choose the payin flow when your end users pay in USDC and you need to receive
fiat: for example, a merchant checkout where customers pay with USDC and you
disburse to sellers in local currency. To try it, follow the
[Receive Stablecoin Payins quickstart](/cpn/managed-payments/quickstarts/receive-stablecoin-payins).

## Payouts (fiat-to-USDC)

A payout converts fiat you send to Circle into USDC that payees receive onchain.
You fund your account by wire, Circle mints or allocates USDC, and you initiate
crypto payouts to registered addresses.

### How a payout moves through the system

1. **You wire fiat to Circle.** Wires can credit a specific sub-wallet or, if
   your agreement allows it, a main wallet used for pooled funding. Set up bank
   accounts and wire instructions ahead of time through the
   [Wires API](/api-reference/cpn/managed-payments/wires/create-account-wire-account).
2. **Fiat posts and a deposit record is created.** After the wire settles, you
   can list and retrieve deposit records through the
   [Fiat Deposits API](/api-reference/cpn/managed-payments/deposits/list-account-deposits).
3. **Circle converts fiat to USDC.** USDC may remain in your account briefly
   while payouts are prepared.
4. **You register approved payout addresses.** Circle's policy engine screens
   each address before it is eligible to receive funds.
5. **USDC is sent to payees onchain.** Circle executes the crypto payout to the
   approved addresses.

Sub-wallets per merchant or segment give you built-in audit trails and simplify
reconciliation.

### Key API calls for payouts

| Action                   | Endpoint                                                                                                                           |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Set up wire instructions | [Create account wire account](/api-reference/cpn/managed-payments/wires/create-account-wire-account) (Wires API)                   |
| List fiat deposits       | [List account deposits](/api-reference/cpn/managed-payments/deposits/list-account-deposits) (Fiat Deposits API)                    |
| Register payout address  | [Create address book recipient](/api-reference/cpn/managed-payments/address-book/create-address-book-recipient) (Address Book API) |
| Send USDC payout         | [Create payout](/api-reference/cpn/managed-payments/payouts/create-payout) (Payouts API)                                           |

### Optional line of credit

Some agreements include a line of credit so USDC is available before every wire
clears. This lets you initiate payouts without waiting for each wire to settle.
Eligibility and terms depend on your agreement with Circle.

### When to use payouts

Choose the payout flow when you need to disburse USDC to external recipients:
for example, paying out creators, suppliers, or partners who prefer to receive
stablecoins. To try it, follow the
[Send Stablecoin Payouts quickstart](/cpn/managed-payments/quickstarts/send-stablecoin-payouts).
For details on how sub-wallets and the main wallet interact during payouts, see
[Sub-Wallet Architecture](/cpn/managed-payments/concepts/sub-wallet-architecture).

## Comparing payins and payouts

| Dimension             | Payins (USDC-to-fiat)          | Payouts (fiat-to-USDC)               |
| --------------------- | ------------------------------ | ------------------------------------ |
| **Direction**         | USDC in, fiat out              | Fiat in, USDC out                    |
| **Funding source**    | Payer sends USDC onchain       | You wire fiat to Circle              |
| **Settlement output** | Fiat credited to your bank     | USDC sent to payee addresses onchain |
| **Typical use case**  | Merchant checkout, collections | Creator payouts, supplier payments   |
| **Key APIs**          | Fiat Burns                     | Wires, Fiat Deposits                 |

## Integration considerations

* Circle operates the regulated infrastructure for custody and money movement.
  You integrate through the
  [Managed Payments API](/api-reference/cpn/managed-payments/accounts/list-accounts).
* You can combine both flows in a single integration if your product requires
  bidirectional movement.
* Use the payin, payout, and balance reports Circle provides for reconciliation.
* For a hands-on walkthrough, see
  [Quickstart: Receive Stablecoin Payins](/cpn/managed-payments/quickstarts/receive-stablecoin-payins)
  and
  [Quickstart: Send Stablecoin Payouts](/cpn/managed-payments/quickstarts/send-stablecoin-payouts).
* For sub-wallet setup and balance tracking, see
  [Sub-Wallet Architecture](/cpn/managed-payments/concepts/sub-wallet-architecture).


# Sub-Wallet Architecture
Source: https://developers.circle.com/cpn/managed-payments/concepts/sub-wallet-architecture

Sub-wallets, your main wallet, and how they work together in Managed Payments

A Managed Payments sub-wallet is a separate ledger for a merchant or segment. It
belongs to your Circle Managed Payments Account for your setup.

* Most teams create one sub-wallet per merchant or segment. Then USDC balances
  and activity stay easy to trace in your books and in Circle reports.
* Your setup has a main wallet too. USDC can live in the main wallet only, in
  sub-wallets only, or across both. It depends on how you fund and pay out.

Together these wallets let you split balances for books and reports while still
using shared funding or pooled sends when your setup allows.

## Wallets structure and typical flows

The following figure is a simplified model. Circle enables only the paths that
your setup and agreement support.

```mermaid theme={null}
flowchart TB
  subgraph mp_setup["Managed Payments setup"]
    MW[Main wallet]
    SA[Sub-wallet A]
    SB[Sub-wallet B]
  end

  Wire[Fiat wire] --> MW
  Wire --> SA
  LOC[Line of credit] -.-> MW
  MW -.-> SA

  SA --> Payin[Payment intent receive]
  SB --> Payin
  SA --> Payout[USDC payout]
  SB --> Payout
  MW --> Payout
```

Solid arrows are typical funding, receive, and payout paths, including payouts
funded from the main wallet. Dotted arrows are optional paths your setup may
use, such as a line of credit into the main wallet or moving USDC to a
sub-wallet before payout.

## Accounts API

<Note>
  If you use the **Direct** onboarding model, you can skip this section. In that
  model, Circle creates sub-wallets on your behalf.
</Note>

Use the Stablecoin Accounts API to create and inspect the stablecoin account
that backs each merchant sub-wallet.

* [Create a managed payments intermediary account](/api-reference/cpn/managed-payments/accounts/create-account)
  when you add a merchant sub-wallet in the Intermediary onboarding model.
* [List accounts](/api-reference/cpn/managed-payments/accounts/list-accounts) to
  page through sub-wallets and see each one's balances and metadata.
* [Get an account](/api-reference/cpn/managed-payments/accounts/get-account) to
  load one sub-wallet's stablecoin account by `accountId`, including balances
  and metadata.

Sub-wallet activity in API requests and responses references these account and
wallet IDs. Circle grants role-based API access during onboarding; the endpoints
available to your API keys depend on the roles assigned to your account.

In the Intermediary model, you call the
[create account](/api-reference/cpn/managed-payments/accounts/create-account)
endpoint after each merchant is approved. In the Direct model, Circle provisions
sub-wallets during onboarding. In both cases, you reference the same `accountId`
values for wires, payouts, and payins.

## Funding and pooled balances

Depending on your setup, USDC can be funded and spent across the main wallet and
sub-wallets in several ways:

* Wires can credit one sub-wallet so that merchant's USDC sits in its own
  balance. Use the
  [Wires API](/api-reference/cpn/managed-payments/wires/create-account-wire-account)
  for bank accounts and wire instructions.
* If your setup allows it, you can mint to a shared main wallet instead. That
  pool can back steady, high-volume payout use cases.
* Some setups include a line of credit. USDC may land in the main wallet first;
  payouts can move funds to the correct sub-wallet before they go onchain. Terms
  follow your agreement with Circle.
* Payouts usually debit a sub-wallet balance. If your integration supports it,
  you can fund payouts from the main wallet instead of from each sub-wallet.
  That helps when you send a lot and don't want USDC in every sub-wallet first.
  Use that path only when your setup supports it.

## Payins and payouts

Handle payins, debits, and reconciliation per sub-wallet:

* **Payins (receiving USDC):** Each sub-wallet can have a stable onchain
  address. Create a continuous payment intent so that each merchant or segment
  has a dedicated receive address.
* **Payouts and withdrawals:** Specify the `walletId` or `accountId` of the
  sub-wallet to debit when you create a payout.

| Activity           | API / resource            | Key identifier                      |
| ------------------ | ------------------------- | ----------------------------------- |
| Receive USDC       | Continuous payment intent | `paymentIntentId`, onchain address  |
| Send USDC          | Payouts API               | `walletId` or `accountId`           |
| Match transactions | Settlement reports        | `accountId`, transaction timestamps |


# Quickstart: Receive Stablecoin Payins
Source: https://developers.circle.com/cpn/managed-payments/quickstarts/receive-stablecoin-payins

Managed Payments Stablecoin payins using the default continuous payment intent flow; for transient payment intents, see the Crypto Deposits quickstart

This guide walks you through the basics of accepting USDC on your site or in
your app with Managed Payments stablecoin payins. You create payment intents,
show a deposit address, your customer sends USDC, and Circle links the onchain
payment to your intent. The steps use a continuous payment intent, which is the
default pattern and fits a stable receive address per merchant or sub-wallet.

<Note>
  The alternative [Quickstart: Crypto
  Deposits](/circle-mint/crypto-payments-quickstart) walkthrough covers a
  transient payment intent instead (amount and time window set on create). Use
  that guide when you want a one-time, expiring checkout-style intent.
</Note>

## Prerequisites

Before you start, ensure you have:

* Aligned with Circle on your Managed Payments onboarding model (Direct or
  Intermediary).
* Completed Managed Payments onboarding, depending on your preferred model, with
  Circle and have API credentials for the environment you target. The cURL
  examples use the sandbox host `api-sandbox.circle.com`.
* Roles that allow creating and reading payment intents and payments in your
  setup. Circle assigns roles during onboarding.
* Sub-wallets or any other structure your setup requires so each continuous
  intent ties to the right merchant or segment. See
  [Managed Payments](/cpn/managed-payments) and the
  [Stablecoin Accounts API](/api-reference/cpn/managed-payments/accounts/create-account)
  if you create accounts first.
* (Optional) A webhook receiver or queue to handle payment intent and payment
  events. Follow the
  [notifications quickstart](/circle-mint/circle-apis-notifications-quickstart).
* (Optional) For an end-to-end test, a payer wallet with USDC and native gas on
  the chain you set on the intent (for example Sepolia ETH when the intent uses
  an Ethereum test chain).

## Sequence diagram

Continuous payins use settlement currency and chain on create; you may see
`active` instead of `pending` when the address is ready.

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Site as Your website
    participant Server as Your server
    participant CAPI as Circle APIs
    Customer->>Site: Select pay with<br/>stablecoin onchain
    Site->>Server: Create deposit intent<br/>settlement and chain
    Server->>CAPI: POST v1 paymentIntents
    CAPI-->>Server: Payment intent created
    CAPI-->>Server: Webhook payment intent<br/>address ready
    Server-->>CAPI: Ack
    Server->>Site: Deposit address
    Site->>Customer: Present deposit address
    Customer->>Customer: Send payment from wallet<br/>to deposit address
    CAPI-->>Server: Webhook payment paid
    Server-->>CAPI: Ack
    CAPI-->>Server: Webhook payment intent<br/>complete paid
    Server-->>CAPI: Ack
    Server->>Site: Stablecoin payment<br/>completed
    Site->>Customer: Payment confirmed
```

## Steps

1. Set up payment intent to pay with stablecoin
2. Acquire blockchain address customer will pay to
3. Customer pays
4. Receive payment

## 1. Pay with stablecoin

Once the customer reaches checkout and confirms they would like to pay with USDC
on Ethereum, your system sends Circle a request to
[create a payment intent](/api-reference/cpn/managed-payments/payment-intents/create-payment-intent).
In this **continuous** payment intent you specify the settlement currency and
chain (no fixed charge amount on create).

Create a payment intent:

<CodeGroup>
  ```curl cURL theme={null}
  curl --location --request POST 'https://api-sandbox.circle.com/v1/paymentIntents' \
  --header 'X-Requested-Id: ${GUID}' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "idempotencyKey": "17607606-e383-4874-87c3-7e46a5dc03dd",
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH"
      }
    ]
  }'
  ```

  ```typescript TypeScript theme={null}
  /**
   * See installation instructions at
   * https://developers.circle.com/circle-mint/circle-sdks
   */
  import {
    Circle,
    CircleEnvironments,
    PaymentIntentCreationRequest,
  } from "@circle-fin/circle-sdk";
  import crypto from "crypto";

  const circle = new Circle(
    "<your-api-key>",
    CircleEnvironments.sandbox, // API base url
  );

  async function createContinuousPaymentIntent(): Promise<void> {
    const reqBody: PaymentIntentCreationRequest = {
      settlementCurrency: "USD",
      paymentMethods: [
        {
          type: "blockchain",
          chain: "ETH",
        },
      ],
      idempotencyKey: crypto.randomUUID(),
    };
    const resp = await circle.cryptoPaymentIntents.createPaymentIntent(reqBody);
    console.log(resp.data);
  }

  void createContinuousPaymentIntent();
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH"
      }
    ],
    "timeline": [
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:19.979669Z",
    "merchantWalletId": "1000700366",
    "currency": "USD"
  }
}
```

```json Webhook notification theme={null}
{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "paymentIntent": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH"
      }
    ],
    "timeline": [
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:19.979669Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}
```

## 2. Acquire blockchain address customer will pay to

For security reasons, the API does not return the deposit blockchain address in
the create response. To retrieve the blockchain deposit address, you have two
options:

1. Subscribe to webhook notifications
2. Poll Circle APIs

### Option 1: Webhook notification

To receive webhook notifications, follow the steps in the
[notifications quickstart](/circle-mint/circle-apis-notifications-quickstart).
After you subscribe to notifications, you receive updates for the payment intent
whenever the resource is updated. In this case, when the
`paymentMethods.address` is set, a notification is sent with a new `timeline`
object with a `status` of `active`.

```json Payment intent webhook notification theme={null}
{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "paymentIntent": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:23.405690Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}
```

### Option 2: Poll payment intent endpoint

If you prefer to poll
[get a payment intent](/api-reference/cpn/managed-payments/payment-intents/get-payment-intent),
send `GET` requests until you receive `paymentMethods.address`.

Retrieve payment intent:

<CodeGroup>
  ```curl cURL theme={null}
  curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/{id}' \
  --header 'X-Requested-Id: ${GUID}' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
  ```

  ```typescript TypeScript theme={null}
  /**
   * See installation instructions at
   * https://developers.circle.com/circle-mint/circle-sdks
   */
  import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

  const circle = new Circle(
    "<your-api-key>",
    CircleEnvironments.sandbox, // API base url
  );

  function delay(time: number): Promise<void> {
    return new Promise((resolve) => {
      setTimeout(resolve, time);
    });
  }

  async function getPaymentIntent(paymentIntentId: string) {
    const resp =
      await circle.cryptoPaymentIntents.getPaymentIntent(paymentIntentId);
    return resp.data;
  }

  async function pollPaymentIntent(): Promise<void> {
    const paymentIntentId = "payment-intent-id";
    const pollInterval = 500; // Interval (in ms) by which to poll

    let resp: Awaited<ReturnType<typeof getPaymentIntent>>;
    while (true) {
      resp = await getPaymentIntent(paymentIntentId);
      const depositAddress = resp.data?.paymentMethods[0]?.address;
      if (depositAddress) break;
      await delay(pollInterval);
    }
    console.log(resp);
  }

  void pollPaymentIntent();
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:23.405690Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}
```

## 3. Enable customer payment

Once you receive the deposit address via `paymentMethods.address`, share it with
the customer so they can send funds on the correct chain.

<Note>
  A **continuous** payment intent doesn't define a fixed amount on create; you
  communicate any specific charge (for example an invoice total) from your own
  checkout or UI.
</Note>

You can present the address two ways:

1. as plain text the customer can cut and paste; or
2. as a QR code the customer can scan via an app.

The customer then sends payment from their wallet (custodial or non-custodial).

<Tip>
  When using transient payment intents, you can set a time frame in which the
  customer must send payment by adjusting the `expiresOn` setting.
</Tip>

## 4. Receive payment from Circle

Once Circle obtains payment onchain, Circle creates a Payment resource linked to
the Payment Intent created earlier and updates the status of that Payment
Intent. Your firm will then receive payment via the method specified.

### Option 1: Webhook notifications

```json Payment intent webhook notification theme={null}
{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "paymentIntent": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "5.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      },
      {
        "type": "totalPaymentFees",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:52:18.080633Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}
```

```json Payment webhook notification theme={null}
{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "payments",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "payment": {
    "id": "021ff661-e7d5-332f-bb9c-e43870608f26",
    "type": "payment",
    "status": "pending",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "createDate": "2026-03-23T17:49:54.197Z",
    "updateDate": "2026-03-23T17:49:54.259Z",
    "merchantId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
    "merchantWalletId": "12345",
    "paymentIntentId": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x6dbe810e3314546009bd6e1b29f9031211cda5d2"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
    },
    "transactionHash": "0xfbc0f1c8256af3453fd3be7a1491e3581e072022a29ffc78cf129a662182305e"
  }
}
```

### Option 2: Retrieve payment intent and payment

Retrieve a payment intent:

<CodeGroup>
  ```curl cURL theme={null}
  curl --location --request GET 'https://api-sandbox.circle.com/v1/paymentIntents/{id}' \
  --header 'X-Requested-Id: ${GUID}' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
  ```

  ```typescript TypeScript theme={null}
  /**
   * See installation instructions at
   * https://developers.circle.com/circle-mint/circle-sdks
   */
  import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

  const circle = new Circle(
    "<your-api-key>",
    CircleEnvironments.sandbox, // API base url
  );

  async function getPaymentIntent(): Promise<void> {
    const paymentIntentId = "<payment-intent-id>";
    const resp =
      await circle.cryptoPaymentIntents.getPaymentIntent(paymentIntentId);

    console.log(resp.data);
  }

  void getPaymentIntent();
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "5.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      },
      {
        "type": "totalPaymentFees",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:52:18.080633Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}
```

Retrieve a payment:

<CodeGroup>
  ```curl cURL theme={null}
  curl --location --request GET 'https://api-sandbox.circle.com/v1/payments/{id}' \
  --header 'X-Requested-Id: ${GUID}' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
  ```

  ```typescript TypeScript theme={null}
  /**
   * See installation instructions at
   * https://developers.circle.com/circle-mint/circle-sdks
   */
  import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

  const circle = new Circle(
    "<your-api-key>",
    CircleEnvironments.sandbox, // API base url
  );

  async function getPayment(): Promise<void> {
    const paymentId = "<payment-id>";
    const resp = await circle.payments.getPayment(paymentId);

    console.log(resp.data);
  }

  void getPayment();
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "id": "021ff661-e7d5-332f-bb9c-e43870608f26",
    "type": "payment",
    "status": "paid",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "fees": {
      "amount": "0.00",
      "currency": "USD"
    },
    "createDate": "2026-03-23T17:49:54.197184Z",
    "updateDate": "2026-03-23T17:52:17.910610Z",
    "merchantId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
    "merchantWalletId": "12345",
    "paymentIntentId": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "settlementAmount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x6dbe810e3314546009bd6e1b29f9031211cda5d2"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
    },
    "transactionHash": "0xfbc0f1c8256af3453fd3be7a1491e3581e072022a29ffc78cf129a662182305e"
  }
}
```

<Note>
  For blockchains that require a 'memo' or 'address tag' (XLM, HBAR, etc.), the
  optional `addressTag` field will be present in the `depositAddress` object.
</Note>


# Quickstart: Send Stablecoin Payouts
Source: https://developers.circle.com/cpn/managed-payments/quickstarts/send-stablecoin-payouts

Send USDC payouts with Managed Payments using the address book and optional main-wallet funding

This guide shows how to send a stablecoin payout with Managed Payments. You add
a blockchain recipient to your address book. You wait until the recipient is
active. You create a payout from a sub-wallet or the main wallet. You confirm
that the payout completes.

## Prerequisites

Before you start, ensure you have:

* Managed Payments onboarding done and API keys for the environment you use.
  This guide uses the sandbox host `api-sandbox.circle.com`.
* Roles for address book and stablecoin payouts for your setup. Circle sets
  roles when you onboard.
* A sub-wallet wallet ID for `source` when you don't pay from the main wallet
  alone. Read [Managed Payments](/cpn/managed-payments) and
  [Sub-wallet architecture](/cpn/managed-payments/concepts/sub-wallet-architecture).
* (Optional) A webhook endpoint for address book and payout events. Use the
  [notifications quickstart](/circle-mint/circle-apis-notifications-quickstart).

## Sequence diagram

```mermaid theme={null}
sequenceDiagram
    participant Server as Your server
    participant CAPI as Circle APIs
    Server->>CAPI: POST v1/addressBook/recipients
    CAPI-->>Server: Recipient pending or inactive
    CAPI-->>Server: Webhook or poll recipient active
    Server->>CAPI: POST v1/payouts
    CAPI-->>Server: Payout pending
    CAPI-->>Server: Webhook or poll payout complete
```

## Steps

1. Create an address book recipient
2. Wait until the recipient is active
3. Create a payout
4. Confirm the payout completed

## 1. Create an address book recipient

Outbound sends use destinations in your address book. Create a recipient with
[create an address book recipient](/api-reference/cpn/managed-payments/address-book/create-address-book-recipient).

Don't create a payout until the recipient is **active**. The `status` you get
when you create a recipient depends on your setup. For example, **delayed
withdrawals** can keep a new entry **inactive** until it activates (see the
following note).

<Note>
  **Delayed withdrawals** are off by default for Managed Payments. You can't
  turn them on or off yourself; contact Circle customer support if your setup
  needs a different configuration. When delayed withdrawals are on, new address
  book entries start inactive. Wait until they're **active** before you pay.
</Note>

<CodeGroup>
  ```curl cURL theme={null}
  curl --location --request POST 'https://api-sandbox.circle.com/v1/addressBook/recipients' \
  --header 'Accept: application/json' \
  --header 'X-Request-Id: fb7980ad-fd01-468b-98ff-2d9ecff67f86' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "idempotencyKey": "9352ec9e-5ee6-441f-ab42-186bc71fbdde",
    "chain": "ETH",
    "address": "0x65BFCf1a6289a0b77b4D3F7d12005a05949FD8C3",
    "metadata": {
      "email": "satoshi@circle.com",
      "bns": "testbns",
      "nickname": "test nickname desc"
    }
  }'
  ```

  ```typescript TypeScript theme={null}
  /**
   * See installation instructions at
   * https://developers.circle.com/circle-mint/circle-sdks
   */
  import {
    AddressBookRecipientRequest,
    Chain,
    Circle,
    CircleEnvironments,
  } from "@circle-fin/circle-sdk";
  import crypto from "crypto";

  const circle = new Circle("<your-api-key>", CircleEnvironments.sandbox);

  async function createAddressBookRecipient(): Promise<void> {
    const reqBody: AddressBookRecipientRequest = {
      idempotencyKey: crypto.randomUUID(),
      chain: Chain.Eth,
      address: "0x65BFCf1a6289a0b77b4D3F7d12005a05949FD8C3",
      metadata: {
        email: "satoshi@circle.com",
        bns: "testbns",
        nickname: "test nickname desc",
      },
    };
    const resp =
      await circle.cryptoAddressBook.createAddressBookRecipient(reqBody);
    console.log(resp.data);
  }

  void createAddressBookRecipient();
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "pending",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}
```

## 2. Wait until the recipient is active

You cannot pay an inactive recipient. Use webhooks or polling until `status` is
`active`.

### Option 1: Webhook notification

After you subscribe, you get updates when address book recipients change. This
sample shows an `active` recipient.

```json Address book recipient webhook notification theme={null}
{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "addressBookRecipients",
  "version": 1,
  "customAttributes": {
    "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
  },
  "addressBookRecipient": {
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "active",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}
```

### Option 2: Poll the recipient

Call
[get an address book recipient](/api-reference/cpn/managed-payments/address-book/get-address-book-recipient)
until `data.status` is `active`.

<CodeGroup>
  ```curl cURL theme={null}
  curl --location --request GET 'https://api-sandbox.circle.com/v1/addressBook/recipients/dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe' \
  --header 'Accept: application/json' \
  --header 'X-Request-Id: 55990729-c59f-4cda-9edd-838cefaa1e42' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
  ```

  ```typescript TypeScript theme={null}
  /**
   * See installation instructions at
   * https://developers.circle.com/circle-mint/circle-sdks
   */
  import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

  const circle = new Circle("<your-api-key>", CircleEnvironments.sandbox);

  function delay(ms: number): Promise<void> {
    return new Promise((resolve) => {
      setTimeout(resolve, ms);
    });
  }

  async function pollRecipientActive(recipientId: string): Promise<void> {
    const pollIntervalMs = 500;
    while (true) {
      const resp =
        await circle.cryptoAddressBook.getAddressBookRecipient(recipientId);
      const status = resp.data?.data?.status;
      if (status === "active") {
        console.log(resp.data);
        return;
      }
      await delay(pollIntervalMs);
    }
  }

  void pollRecipientActive("dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe");
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "active",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}
```

## 3. Create a payout

Create the payout with
[create a payout](/api-reference/cpn/managed-payments/payouts/create-payout).
Set `destination` to the address book entry. Set `amount` and optional
`toAmount`. Set `source` when you use a sub-wallet.

If you omit `source`, the API withdraws from the **main wallet**.

<Warning>
  **Receiving currency and Travel Rule:** If you omit `toAmount.currency`, the API
  uses `amount.currency` as the receiving currency.

  The `source.identities` object is required for payouts greater than or equal to
  \$3,000. The object describes the **originator** (your organization), not the
  recipient, for Financial Crimes Enforcement Network (FinCEN)
  [Travel Rule](/circle-mint/howtos/transfer-on-chain#travel-rule-compliance)
  compliance.
</Warning>

<Note>
  **Main wallet funding:** For Managed Payments, `source.useMainWalletFunding`
  defaults to `true`. When it is `true`, the API tops up from the **main wallet**
  if the source wallet lacks funds. Set `source.useMainWalletFunding` to `false`
  to require the full amount on the source wallet only.

  **Insufficient funds:** If a payout fails because funds are not ready yet,
  confirm your wire completed and USDC is available for the source wallet. See the
  [Wires API](/api-reference/cpn/managed-payments/wires/create-account-wire-account)
  and [Settlement flows](/cpn/managed-payments/concepts/settlement-flows).
</Note>

The example uses a sub-wallet as `source`, sets `useMainWalletFunding` on
`source`, and uses an amount that needs `identities` for Travel Rule coverage.
Replace placeholder IDs with your own values.

<CodeGroup>
  ```curl cURL theme={null}
  curl --location --request POST 'https://api-sandbox.circle.com/v1/payouts' \
  --header 'Accept: application/json' \
  --header 'X-Request-Id: ff422eab-52fa-4a6e-bf07-b6b522786468' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "source": {
      "type": "wallet",
      "id": "12345",
      "useMainWalletFunding": true,
      "identities": [
        {
          "type": "individual",
          "name": "Satoshi Nakamoto",
          "addresses": [
            {
              "line1": "100 Money Street",
              "line2": "Suite 1",
              "city": "Boston",
              "district": "MA",
              "postalCode": "01234",
              "country": "US"
            }
          ]
        }
      ]
    },
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe"
    },
    "amount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "toAmount": {
      "currency": "USD"
    }
  }'
  ```

  ```typescript TypeScript theme={null}
  /**
   * See installation instructions at
   * https://developers.circle.com/circle-mint/circle-sdks
   */
  import {
    Circle,
    CircleEnvironments,
    CryptoPayoutCreationRequest,
    CryptoPayoutDestinationType,
    IdentityTypeEnum,
    MoneyCurrencyEnum,
    ToAmountCurrencyEnum,
    TransferSourceWalletLocationTypeEnum,
  } from "@circle-fin/circle-sdk";
  import crypto from "crypto";

  /** Managed Payments: `useMainWalletFunding` on `source` (SDK types may lag the API). */
  type PayoutSourceWallet = NonNullable<CryptoPayoutCreationRequest["source"]> & {
    useMainWalletFunding?: boolean;
  };

  const circle = new Circle("<your-api-key>", CircleEnvironments.sandbox);

  async function createManagedPaymentsPayout(): Promise<void> {
    const sourceWallet: PayoutSourceWallet = {
      type: TransferSourceWalletLocationTypeEnum.Wallet,
      id: "12345",
      useMainWalletFunding: true,
      identities: [
        {
          type: IdentityTypeEnum.Individual,
          name: "Satoshi Nakamoto",
          addresses: [
            {
              line1: "100 Money Street",
              line2: "Suite 1",
              city: "Boston",
              district: "MA",
              postalCode: "01234",
              country: "US",
            },
          ],
        },
      ],
    };

    const reqBody: CryptoPayoutCreationRequest = {
      idempotencyKey: crypto.randomUUID(),
      source: sourceWallet,
      destination: {
        type: CryptoPayoutDestinationType.AddressBook,
        id: "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
      },
      amount: {
        amount: "3000.14",
        currency: MoneyCurrencyEnum.Usd,
      },
      toAmount: {
        currency: ToAmountCurrencyEnum.Usd,
      },
    };

    const resp = await circle.payouts.createPayout(reqBody);
    console.log(resp.data);
  }

  void createManagedPaymentsPayout();
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe"
    },
    "amount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "toAmount": {
      "currency": "USD"
    },
    "status": "pending",
    "updateDate": "2020-04-10T02:13:30.000Z",
    "createDate": "2020-04-10T02:13:30.000Z"
  }
}
```

## 4. Confirm the payout completed

Use webhooks or polling with
[get a payout](/api-reference/cpn/managed-payments/payouts/get-payout) to
confirm the payout finished onchain.

### Option 1: Webhook notification

```json Payout webhook notification theme={null}
{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "payout",
  "version": 1,
  "customAttributes": {
    "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
  },
  "payout": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe"
    },
    "amount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "fees": {
      "amount": "0.00",
      "currency": "USD"
    },
    "networkFees": {
      "amount": "0.30",
      "currency": "USD"
    },
    "status": "complete",
    "createDate": "2020-04-10T02:13:30.000Z",
    "updateDate": "2020-04-10T02:13:30.000Z"
  }
}
```

### Option 2: Poll the payout

<CodeGroup>
  ```curl cURL theme={null}
  curl --location --request GET 'https://api-sandbox.circle.com/v1/payouts/b8627ae8-732b-4d25-b947-1df8f4007a29' \
  --header 'Accept: application/json' \
  --header 'X-Request-Id: d36f3c00-9c98-4610-bfea-83995379995e' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
  ```

  ```typescript TypeScript theme={null}
  /**
   * See installation instructions at
   * https://developers.circle.com/circle-mint/circle-sdks
   */
  import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

  const circle = new Circle("<your-api-key>", CircleEnvironments.sandbox);

  function delay(ms: number): Promise<void> {
    return new Promise((resolve) => {
      setTimeout(resolve, ms);
    });
  }

  async function pollPayoutComplete(payoutId: string): Promise<void> {
    const pollIntervalMs = 500;
    while (true) {
      const resp = await circle.payouts.getPayout(payoutId);
      const status = resp.data?.data?.status;
      if (status === "complete") {
        console.log(resp.data);
        return;
      }
      await delay(pollIntervalMs);
    }
  }

  void pollPayoutComplete("b8627ae8-732b-4d25-b947-1df8f4007a29");
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "id": "2f3bca9a-2d0e-4aef-a511-026eefd3cc6f",
    "destination": {
      "type": "address_book",
      "id": "eaca84eb-69fb-53d3-9dac-f69cb5f1541a"
    },
    "amount": {
      "amount": "500.00",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "500.00",
      "currency": "USD"
    },
    "externalRef": "0x41f8f2cd555e247716f3e9bc97366ac04a848fd2fde76732c894c6843fc6f8db",
    "createDate": "2023-08-14T20:30:19.145913Z",
    "updateDate": "2023-08-14T22:05:55.406292Z",
    "sourceWalletId": "1000594146",
    "fees": {
      "amount": "1.00",
      "currency": "USD"
    },
    "networkFees": {
      "amount": "0.01",
      "currency": "USD"
    },
    "status": "complete"
  }
}
```


# Webhook Events
Source: https://developers.circle.com/cpn/managed-payments/references/webhook-events

Reference for Managed Payments webhook event types, payloads, and the v1 notification subscription system.

<Note>
  Managed Payments uses the v1 Circle APIs notification subscription system,
  which is separate from the CPN Platform v2 webhook system. For CPN Platform
  webhook events, see the [CPN Platform webhook events
  reference](/cpn/references/webhooks/webhook-events).
</Note>

* Subscription endpoint: `POST /v1/notifications/subscriptions`
* Setup:
  [Circle APIs notifications quickstart](/circle-mint/circle-apis-notifications-quickstart)

All Managed Payments webhook payloads use the following v1 envelope structure:

| Envelope field     | Type   | Description                                             |
| ------------------ | ------ | ------------------------------------------------------- |
| `clientId`         | string | Your Circle client identifier.                          |
| `notificationType` | string | Event type identifier. See [Event types](#event-types). |
| `version`          | number | Schema version. Always `1`.                             |
| `customAttributes` | object | Contains `clientId`.                                    |
| `<resourceKey>`    | object | Event-specific data. Key name varies by event type.     |

## Event types

| `notificationType`      | Resource key           | Trigger                                                                 |
| ----------------------- | ---------------------- | ----------------------------------------------------------------------- |
| `paymentIntents`        | `paymentIntent`        | Payment intent created, deposit address ready, or payment received      |
| `payments`              | `payment`              | Payment status changes (for example, `pending` or `paid`)               |
| `addressBookRecipients` | `addressBookRecipient` | Recipient status changes (for example, `pending` or `active`)           |
| `payout`                | `payout`               | Payout status changes (for example, `pending`, `complete`, or `failed`) |
| `creditTransfer`        | `creditTransfer`       | Credit transfer status changes (`requested`, `disbursed`, or `paid`)    |

## Payment intent events

The `paymentIntents` notification fires when a payment intent is created, when a
blockchain deposit address becomes available, or when a payment is received
against the intent.

Status values observed in `timeline[].status`: `created`, `active`

```json Example paymentIntents payload theme={null}
{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "paymentIntent": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:23.405690Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}
```

## Payment events

The `payments` notification fires when a payment status changes.

Status values: `pending`, `paid`

```json Example payments payload theme={null}
{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "payments",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "payment": {
    "id": "021ff661-e7d5-332f-bb9c-e43870608f26",
    "type": "payment",
    "status": "pending",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "createDate": "2026-03-23T17:49:54.197Z",
    "updateDate": "2026-03-23T17:49:54.259Z",
    "merchantId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
    "merchantWalletId": "12345",
    "paymentIntentId": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x6dbe810e3314546009bd6e1b29f9031211cda5d2"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
    },
    "transactionHash": "0xfbc0f1c8256af3453fd3be7a1491e3581e072022a29ffc78cf129a662182305e"
  }
}
```

## Address book recipient events

The `addressBookRecipients` notification fires when a recipient's status
changes.

Status values: `pending`, `active`

```json Example addressBookRecipients payload theme={null}
{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "addressBookRecipients",
  "version": 1,
  "customAttributes": {
    "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
  },
  "addressBookRecipient": {
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "active",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}
```

## Payout events

The `payout` notification fires when a payout status changes.

Status values: `pending`, `complete`, `failed`

```json Example payout payload theme={null}
{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "payout",
  "version": 1,
  "customAttributes": {
    "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
  },
  "payout": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe"
    },
    "amount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "3000.14",
      "currency": "USD"
    },
    "fees": {
      "amount": "0.00",
      "currency": "USD"
    },
    "networkFees": {
      "amount": "0.30",
      "currency": "USD"
    },
    "status": "complete",
    "createDate": "2020-04-10T02:13:30.000Z",
    "updateDate": "2020-04-10T02:13:30.000Z"
  }
}
```

## Credit transfer events

The `creditTransfer` notification fires when a credit transfer status changes. A
credit transfer represents a draw from a line of credit.

Status values: `requested` (disbursement requested), `disbursed` (funds
transferred to wallet), `paid` (fully repaid; fees invoiced at month end)

```json Example creditTransfer payload theme={null}
{
  "clientId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
  "notificationType": "creditTransfer",
  "version": 1,
  "customAttributes": {
    "clientId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd"
  },
  "creditTransfer": {
    "data": {
      "id": "0c206348-1252-4c33-8618-5d85e322a0a3",
      "amount": {
        "amount": "50.00",
        "currency": "USD"
      },
      "status": "disbursed",
      "outstanding": {
        "amount": "50.00",
        "currency": "USD"
      },
      "dueDate": "2026-02-27T19:37:58.954Z",
      "disbursedDate": "2026-02-20T19:37:58.954Z",
      "createDate": "2026-02-20T19:37:58.358590Z",
      "updateDate": "2026-02-20T19:37:59.321362Z"
    }
  }
}
```

### Credit transfer fields

The following table documents every field in the `creditTransfer.data` object.

| Field           | Type                                   | Description                                                                  |
| --------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
| `id`            | string (UUID)                          | Unique identifier for the credit transfer.                                   |
| `amount`        | Amount object (`{ amount, currency }`) | Total amount drawn from the line of credit.                                  |
| `status`        | enum: `requested`, `disbursed`, `paid` | Current status of the credit transfer.                                       |
| `outstanding`   | Amount object (`{ amount, currency }`) | Remaining balance to repay. Omitted when status is `requested`.              |
| `dueDate`       | ISO 8601 timestamp                     | When repayment is due. Omitted when status is `requested`.                   |
| `disbursedDate` | ISO 8601 timestamp                     | When funds were disbursed to the wallet. Omitted when status is `requested`. |
| `paidDate`      | ISO 8601 timestamp                     | When the credit transfer was fully repaid. Omitted unless status is `paid`.  |
| `createDate`    | ISO 8601 timestamp                     | When the credit transfer was created.                                        |
| `updateDate`    | ISO 8601 timestamp                     | When the credit transfer was last updated.                                   |


# Integrate with CPN as an OFI
Source: https://developers.circle.com/cpn/quickstarts/integrate-with-cpn-ofi

Request, lock, and fulfill a USDC payment quote as an OFI using CPN. Covers Transactions V1 and V2 on EVM blockchains and Solana signing.

Complete this quickstart to request, lock, and fulfill your first USDC payment
quote as an OFI using CPN. Examples cover both Transactions V1 and V2 on EVM
blockchains; where the two versions differ, each step provides version-specific
guidance. Solana follows the same overall flow with differences in the signing
process.

<Note>
  This quickstart uses **Circle Wallets** and **Circle On/Off-Ramps** as
  examples; CPN does not require them. If you use your own wallet and USDC, see
  [Bring your own wallet for CPN](/cpn/concepts/wallets/bring-your-own-wallet)
  and [Wallet provider
  compatibility](/cpn/references/blockchains/wallet-provider-compatibility). For
  Circle setup, follow the how-tos under Prerequisites.
</Note>

## Prerequisites

Before you begin this quickstart, ensure you have:

* API keys created in
  [CPN Console → Developer → API Keys](https://cpn.circle.com/signin) with
  access to **CPN** and **Programmable Wallets**. If you fund USDC through
  Circle APIs for this exercise, you also need a key authorized for those
  **Circle APIs** endpoints.
* Completed operational wallet setup for the quickstart:
  * Follow how to
    [Set Up a Circle Wallet for CPN Payments](/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments),
    **or** use your own wallet that meets
    [Wallet provider compatibility](/cpn/references/blockchains/wallet-provider-compatibility).
  * You need the **wallet ID** of an EOA on the correct chain (`EVM-TESTNET` for
    Transactions V1, `ETH-SEPOLIA` for Transactions V2 when using testnet).
* Funded the operational wallet with enough **USDC** (and, for Transactions V1
  on EVM, enough **native gas**). For sandbox you can use the
  [Circle faucet](https://faucet.circle.com) and an
  [EVM testnet ETH faucet](https://cloud.google.com/application/web3/faucet/ethereum).
  For a guided Circle fiat-to-wallet path, follow how to
  [Set Up Circle On/Off-Ramps for CPN Payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments).
* Python installed on your development machine
  * The latest `jwcrypto`, `web3`, `eth_utils`, `hexbytes`, and `eth_abi`
    libraries are installed with the `pip` package manager
* cURL installed on your development machine
* (If using Transactions V2) Granted a USDC allowance to the `Permit2` contract.
  See how to
  [Grant USDC Allowance to Permit2](/cpn/guides/transactions/grant-usdc-allowance-to-permit2)
  for more information.
* (Optional) a
  [configured webhook notification endpoint](/cpn/guides/webhooks/setup-webhook-notifications)

This quickstart provides API requests in cURL format, along with example
responses.

<Note>
  The base URL for all API endpoints is `https://api.circle.com/v1/cpn` for both
  sandbox and production environments. The API determines if a request is for
  testnet or mainnet based on the key used to authenticate the request.
</Note>

## Part 1: Request a quote

Request quotes for a USDC to MX payment with the SPEI payment method. Request
quotes with the [create a quote](/api-reference/cpn/cpn-platform/create-quotes)
endpoint, providing the source currency and destination amount. For Transactions
V2, you must specify `transactionVersion` as `VERSION_2`. The endpoint returns a
list of quotes from various BFIs with the rate, expiration time, USDC settlement
window, and unique ID.

<Note>
  Quotes expire quickly (typically 30–60 seconds). If a quote expires before you
  create the payment, the payment creation endpoint returns an error. Request a
  new quote and restart from Part 1. Save the `id` and `quoteExpireDate` from
  the response so you can check expiration before proceeding.
</Note>

<Tabs>
  <Tab title="Transactions V2">
    ```shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v1/cpn/quotes \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-Type: application/json' \
      --data '
    {
        "paymentMethodType": "SPEI",
        "senderCountry": "US",
        "destinationCountry": "MX",
        "sourceAmount": {
            "currency": "USDC"
        },
        "destinationAmount": {
            "amount": "200",
            "currency": "MXN"
        },
        "blockchain": "ETH-SEPOLIA",
        "senderType": "INDIVIDUAL",
        "recipientType": "INDIVIDUAL",
        "transactionVersion": "VERSION_2"
    }
    '
    ```

    **Response**

    ```json theme={null}
    {
      "data": [
        {
          "id": "2792f4a6-f1bd-4435-b681-1da309122159",
          "paymentMethodType": "SPEI",
          "blockchain": "ETH-SEPOLIA",
          "senderCountry": "US",
          "destinationCountry": "MX",
          "createDate": "2025-09-24T00:01:13.532073875Z",
          "quoteExpireDate": "2025-09-24T00:01:42.502094Z",
          "cryptoFundsSettlementExpireDate": "2025-09-24T01:01:12.502097Z",
          "sourceAmount": {
            "amount": "15.000000",
            "currency": "USDC"
          },
          "destinationAmount": {
            "amount": "252.91",
            "currency": "MXN"
          },
          "fiatSettlementTime": {
            "min": "0",
            "max": "5",
            "unit": "MINUTES"
          },
          "exchangeRate": {
            "rate": "16.860667",
            "pair": "USDC/MXN"
          },
          "fees": {
            "totalAmount": {
              "amount": "1.568971",
              "currency": "USDC"
            },
            "breakdown": [
              {
                "type": "TAX_FEE",
                "amount": {
                  "amount": "0.234663",
                  "currency": "USDC"
                }
              },
              {
                "type": "BFI_TRANSACTION_FEE",
                "amount": {
                  "amount": "0.138037",
                  "currency": "USDC"
                }
              },
              {
                "type": "CIRCLE_SERVICE_FEE",
                "amount": {
                  "amount": "0.000000",
                  "currency": "USDC"
                }
              },
              {
                "type": "BLOCKCHAIN_GAS_FEE",
                "amount": {
                  "amount": "1.196271",
                  "currency": "USDC"
                }
              }
            ]
          },
          "senderType": "INDIVIDUAL",
          "recipientType": "INDIVIDUAL",
          "certificate": {
            // certificate object
          },
          "quoteOptions": {
            "isFirstParty": false
          },
          "transactionVersion": "VERSION_2"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Transactions V1">
    ```shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v1/cpn/quotes \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-Type: application/json' \
      --data '
    {
        "paymentMethodType": "SPEI",
        "senderCountry": "US",
        "destinationCountry": "MX",
        "sourceAmount": {
            "currency": "USDC"
        },
        "destinationAmount": {
            "amount": "200",
            "currency": "MXN"
        },
        "blockchain": "ETH-SEPOLIA",
        "senderType": "INDIVIDUAL",
        "recipientType": "INDIVIDUAL"
    }
    '
    ```

    **Response**

    ```json theme={null}
    {
      "data": [
        {
          "id": "922a06cd-ff1e-4ee4-840e-54006893fd1a",
          "paymentMethodType": "SPEI",
          "blockchain": "ETH-SEPOLIA",
          "senderCountry": "US",
          "destinationCountry": "MX",
          "createDate": "2025-03-28T16:21:47.089081899Z",
          "quoteExpireDate": "2025-03-28T16:22:45.713598Z",
          "cryptoFundsSettlementExpireDate": "2025-03-28T18:21:45.713615Z",
          "sourceAmount": {
            "amount": "10.000000",
            "currency": "USDC"
          },
          "destinationAmount": {
            "amount": "200.23",
            "currency": "MXN"
          },
          "fiatSettlementTime": {
            "min": "1",
            "max": "12",
            "unit": "HOURS"
          },
          "exchangeRate": {
            "rate": "20.040000",
            "pair": "USDC/MXN"
          },
          "fees": {
            "totalAmount": {
              "amount": "0.170000",
              "currency": "USDC"
            },
            "breakdown": [
              {
                "type": "TAX_FEE",
                "amount": {
                  "amount": "0.070000",
                  "currency": "USDC"
                }
              },
              {
                "type": "BFI_TRANSACTION_FEE",
                "amount": {
                  "amount": "0.100000",
                  "currency": "USDC"
                }
              }
            ]
          },
          "senderType": "INDIVIDUAL",
          "recipientType": "INDIVIDUAL",
          "certificate": {
            "id": "201c52fc-8866-44cf-a2e2-3ceae098381c",
            "certPem": "LS0t...",
            "domain": "api.circle.com",
            "jwk": {
              "kty": "EC",
              "crv": "P-256",
              "kid": "263521881931753643998528753619816524468853605762",
              "x": "YdjOeAmlNfWV0xIryFAivcp9of21s0c-JhyGEOINV2Y",
              "y": "n621ve_OV_p3jdocxtNkAk4uaKcYR2XWYUu1NMzBei8"
            }
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Part 2: Create a payment

Use the API to get the requirements for a payment, accept the quote, and create
a payment.

### 2.1. Get payment requirements

Call the
[`/payments/requirements`](/api-reference/cpn/cpn-platform/get-payment-requirements)
endpoint with the quote ID to get the requirements for a payment. The endpoint
returns an object describing the required fields for the compliance check. The
`optional` field for each parameter defines if the parameter must be included in
the response constructed in the next step.

```shell theme={null}
curl -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET "https://api.circle.com/v1/cpn/payments/requirements?quoteId=${QUOTE_ID}"
```

**Response**

```json theme={null}
{
  "data": {
    "travelRule": [
      {
        "name": "ORIGINATOR_FINANCIAL_INSTITUTION_NAME",
        "type": "TEXT",
        "optional": false
      },
      {
        "name": "ORIGINATOR_FINANCIAL_INSTITUTION_ADDRESS",
        "type": "ADDRESS",
        "optional": false
      },
      {
        "name": "ORIGINATOR_FINANCIAL_INSTITUTION_ID",
        "type": "TEXT",
        "optional": true
      },
      {
        "name": "ORIGINATOR_NAME",
        "type": "TEXT",
        "optional": false
      },
      {
        "name": "ORIGINATOR_ACCOUNT_NUMBER",
        "type": "TEXT",
        "optional": false
      },
      {
        "name": "ORIGINATOR_ADDRESS",
        "type": "ADDRESS",
        "optional": false
      },
      {
        "name": "BENEFICIARY_NAME",
        "type": "TEXT",
        "optional": false
      },
      {
        "name": "BENEFICIARY_ADDRESS",
        "type": "ADDRESS",
        "optional": false
      },
      {
        "name": "ORIGINATOR_DATE_OF_BIRTH",
        "type": "TEXT",
        "optional": true
      },
      {
        "name": "ORIGINATOR_NATIONALITY",
        "type": "TEXT",
        "optional": true
      },
      {
        "name": "ORIGINATOR_NATIONAL_IDENTIFICATION_NUMBER",
        "type": "TEXT",
        "optional": true
      },
      {
        "name": "BENEFICIARY_DATE_OF_BIRTH",
        "type": "TEXT",
        "optional": true
      },
      {
        "name": "BENEFICIARY_NATIONALITY",
        "type": "TEXT",
        "optional": true
      },
      {
        "name": "BENEFICIARY_NATIONAL_IDENTIFICATION_NUMBER",
        "type": "TEXT",
        "optional": false
      },
      {
        "name": "BENEFICIARY_PHONE_NUMBER",
        "type": "TEXT",
        "optional": true
      },
      {
        "name": "BENEFICIARY_EMAIL",
        "type": "TEXT",
        "optional": true
      }
    ],
    "beneficiaryAccount": [
      {
        "name": "CLABE",
        "type": "TEXT",
        "optional": false
      }
    ]
  }
}
```

### 2.2. Encrypt the required fields

Construct a JSON object with the information requested in the previous step. For
each schema, the properties that you must include are outlined by the `optional`
field. Encrypt the object with the `jwk` certificate provided in the quote
response.

The correct format for travel rule data and beneficiary account data is a JSON
array of objects where each object contains two properties: `name` and `value`.
You can review an example of each field in how to
[Encrypt Travel Rule Data](/cpn/guides/payments/encrypt-travel-rule-beneficiary-data#step-4-prepare-the-payload).

Create a file called `cpn_encryption.py` and put the following code in it,
replacing the `requirements_response_json` parameter with the contents of the
response from the previous step, and the `certificate_json` parameter with the
`jwk` from the quote response. When you run the script, it outputs the encrypted
beneficiary and travel rule data to the console.

```python Python theme={null}
"""
CPN Requirements V1 Encryption Quickstart

This script demonstrates how to:
1. Parse V1 Requirements response
2. Generate realistic test data matching the fields
3. Encrypt data using JWE for CPN API integration

Usage:
1. Replace certificate_json with your JWK from Quote response
2. Replace requirements_response_json with your Requirements response
3. Run the script to get encrypted data for creating payment API requests
"""

import json
import os
import base64
import random
from typing import Dict, Any, Optional, List
from jwcrypto import jwk, jwe

# ========================================
# Test Data Lists for Realistic Generation
# ========================================

FIRST_NAMES = [
    "James", "John", "Robert", "Michael", "William", "David", "Joseph", "Thomas",
    "Charles", "Mary", "Patricia", "Jennifer", "Linda", "Elizabeth", "Barbara",
    "Susan", "Jessica", "Sarah", "Karen", "Nancy"
]

LAST_NAMES = [
    "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis",
    "Rodriguez", "Martinez", "Hernandez", "Lopez", "Gonzalez", "Wilson",
    "Anderson", "Thomas", "Taylor", "Moore", "Jackson", "Martin"
]

STREET_TYPES = ["St", "Ave", "Blvd", "Rd", "Ln", "Dr", "Way", "Circle", "Court"]
STREET_NAMES = [
    "Main", "Oak", "Maple", "Cedar", "Pine", "Elm", "Washington", "Lake", "Hill",
    "River", "Valley", "Park", "Spring", "Market", "Church", "Bridge", "Highland"
]

CITIES = [
    "New York", "Los Angeles", "Chicago", "Houston", "Phoenix", "Philadelphia",
    "San Antonio", "San Diego", "Dallas", "San Jose", "Austin", "Jacksonville",
    "Fort Worth", "Columbus", "San Francisco", "Charlotte", "Indianapolis",
    "Seattle", "Denver", "Washington"
]

# ========================================
# Helper Functions
# ========================================

def generate_random_name() -> str:
    """Generate a random realistic name."""
    return f"{random.choice(FIRST_NAMES)} {random.choice(LAST_NAMES)}"

def generate_random_address() -> Dict[str, str]:
    """Generate a random realistic address."""
    street_number = str(random.randint(1, 9999))
    street_name = random.choice(STREET_NAMES)
    street_type = random.choice(STREET_TYPES)
    return {
        "street": f"{street_number} {street_name} {street_type}",
        "city": random.choice(CITIES),
        "country": "US",
        "postalCode": f"{random.randint(10000, 99999)}"
    }

def random_string(length: int = 12) -> str:
    """Generate a random string of given length."""
    return base64.b64encode(os.urandom(length)).decode()[:length]

def get_originator_name(case: Optional[str] = None) -> str:
    """Get the originator name based on test case."""
    if case == 'rfi-failed':
        return "Failed"
    return "Alice Johnson"  # Default for success case

# ========================================
# Core Data Generation
# ========================================

def generate_group_data(fields: List[Dict[str, Any]], originator_name: str) -> List[Dict[str, Any]]:
    """
    Generate test data matching Requirements fields as an array of {name, value}.

    Args:
        fields: List of field objects from Requirements
        originator_name: Name to use for originator fields

    Returns:
        List[{"name": str, "value": Any}] for required fields
    """
    items: List[Dict[str, Any]] = []

    for field in fields:
        name = field["name"]
        field_type = field["type"].upper()
        optional = field.get("optional", False)

        if optional:
            continue  # only include required fields

        # Address fields
        if field_type == "ADDRESS" or "ADDRESS" in name.upper():
            items.append({"name": name, "value": generate_random_address()})

        # Text fields
        elif field_type == "TEXT":
            if "NAME" in name.upper():
                if "ORIGINATOR" in name.upper():
                    items.append({"name": name, "value": originator_name})
                else:
                    items.append({"name": name, "value": generate_random_name()})
            elif "CLABE" in name.upper():
                items.append({"name": name, "value": ''.join(str(random.randint(0, 9)) for _ in range(18))})
            elif "ACCOUNT" in name.upper():
                items.append({"name": name, "value": ''.join(str(random.randint(0, 9)) for _ in range(12))})
            elif "DATE" in name.upper() or "BIRTH" in name.upper():
                year = random.randint(1970, 2000)
                month = random.randint(1, 12)
                day = random.randint(1, 28)
                items.append({"name": name, "value": f"{year:04d}-{month:02d}-{day:02d}"})
            elif "EMAIL" in name.upper():
                items.append({"name": name, "value": f"{random_string(8)}@example.com"})
            else:
                items.append({"name": name, "value": random_string(12)})

    return items

# ========================================
# Encryption
# ========================================

def encrypt_data(data: Any, jwk_data: Dict[str, Any]) -> str:
    """
    Encrypt data using JWE with provided JWK.

    Args:
        data: Data to encrypt (will be JSON serialized)
        jwk_data: JWK from certificate

    Returns:
        Encrypted JWE string
    """
    recipient_key = jwk.JWK(**jwk_data)
    jwe_obj = jwe.JWE(
        plaintext=json.dumps(data).encode(),
        protected=json.dumps({"alg": "ECDH-ES+A128KW", "enc": "A128GCM"})
    )
    jwe_obj.add_recipient(recipient_key)
    return jwe_obj.serialize(True)

# ========================================
# Configuration - Replace with your data
# ========================================

# Certificate JWK - copy from Quote response
# e.g. {"kty":"EC","crv":"P-256","kid":"263...5762","x":"Ydj...2Y","y":"n621...i8"}
certificate_json = '''certificate_json'''

# Requirements response - copy from Requirements API
# e.g. {"data": {"travelRule": [...], "beneficiaryAccount": [...]}}
requirements_response_json = '''requirements_response_json'''

# ========================================
# Main Execution
# ========================================

if __name__ == "__main__":
    # Parse configuration
    certificate = json.loads(certificate_json)
    required_fields = json.loads(requirements_response_json)

    # Extract field arrays
    travel_rule_fields = required_fields['data']['travelRule']
    beneficiary_account_fields = required_fields['data']['beneficiaryAccount']

    # Generate test data (array of {name, value})
    test_data = {
        "travelRuleData": generate_group_data(travel_rule_fields, get_originator_name()),
        "beneficiaryAccountData": generate_group_data(beneficiary_account_fields, get_originator_name())
    }

    # Create encrypted data (encrypt arrays directly)
    travel_rule_encrypted = encrypt_data(test_data["travelRuleData"], certificate)
    beneficiary_account_encrypted = encrypt_data(test_data["beneficiaryAccountData"], certificate)

    # Output encrypted data ready for API
    print(f"Travel Rule encryptedData: {travel_rule_encrypted}\n")
    print(f"Beneficiary Account encryptedData: {beneficiary_account_encrypted}")
```

### 2.3. Create a payment

After the quote is accepted, create a payment by calling the
[`/payments`](/api-reference/cpn/cpn-platform/create-payment) endpoint. You need
to provide the quote ID and encrypted sender and receiver information. The
endpoint returns a unique payment ID and the initial status of the payment.

<Note>
  You must create the payment before the quote expires. If the quote has
  expired, request a new quote and restart from Part 1. Once the payment is
  created, save the payment `id` and `expireDate`. You must complete the onchain
  transaction before the payment expires.
</Note>

```bash Shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/cpn/payments \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-type: application/json' \
  --data '
{
  "idempotencyKey" : "${randomUUID}",
  "quoteId" : "${cpn_ofi_quote_id}",
  "beneficiaryAccountData" : "${encrypted_beneficiary_data}",
  "travelRuleData" : "${encrypted_travel_rule_data}",
  "senderAddress" : "${YOUR_WALLET_ADDRESS}",
  "blockchain" : "ETH-SEPOLIA",
  "reasonForPayment" : "PMT001",
  "customerRefId" : "123c7442-e843-4afa-bfad-35f50636d35b",
  "refCode" : "7b479c5a-3684-4423-9fc6-f7c890c0e816",
  "useCase" : "B2B"
}
'
```

**Response**

```json JSON theme={null}
{
  "data": {
    "id": "07dbe320-6bcb-475b-8d21-17b57263cd3e",
    "quoteId": "922a06cd-ff1e-4ee4-840e-54006893fd1a",
    "blockchain": "ETH-SEPOLIA",
    "paymentMethodType": "SPEI",
    "sourceAmount": {
      "amount": "10.000000",
      "currency": "USDC"
    },
    "destinationAmount": {
      "amount": "200.23",
      "currency": "MXN"
    },
    "status": "CRYPTO_FUNDS_PENDING",
    "refCode": "7b479c5a-3684-4423-9fc6-f7c890c0e816",
    "customerRefId": "123c7442-e843-4afa-bfad-35f50636d35b",
    "useCase": "B2B_INVOICE_PAYMENT",
    "expireDate": "2025-03-31T20:59:21.211547Z",
    "createDate": "2025-03-31T18:59:30.183044Z",
    "fees": {
      "totalAmount": {
        "amount": "0.170000",
        "currency": "USDC"
      },
      "breakdown": [
        {
          "type": "TAX_FEE",
          "amount": {
            "amount": "0.070000",
            "currency": "USDC"
          }
        },
        {
          "type": "BFI_TRANSACTION_FEE",
          "amount": {
            "amount": "0.100000",
            "currency": "USDC"
          }
        }
      ]
    },
    "fiatSettlementTime": {
      "min": "1",
      "max": "12",
      "unit": "HOURS"
    },
    "rfis": [],
    "onChainTransactions": []
  }
}
```

## Part 3: Create a transaction

Use the API to create a blockchain transaction to transfer USDC. Sign the
transaction locally, and use the API to broadcast it to the blockchain.

<Note>
  This quickstart uses Circle Wallets (or your equivalent operational wallet) as
  the originator wallet. Use the wallet ID from the
  [prerequisites](#prerequisites) section, including any funding you completed
  via the Circle Wallet or Circle On/Off-Ramps how-tos.
</Note>

### 3.1. Initiate the onchain transaction

Initiate the onchain funds transfer by calling the
[`/payments/{paymentId}/transactions`](/api-reference/cpn/cpn-platform/create-transaction)
endpoint with the payment ID from the previous step, and other
transaction-related parameters. Note that if you are using Transactions V2, you
should use the
[create transaction V2](/api-reference/cpn/cpn-platform/create-transaction-v2)
endpoint. The endpoint returns an unsigned onchain transaction object and a
transaction ID.

<Tabs>
  <Tab title="Transactions V2">
    ```shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v2/cpn/payments/:paymentId/transactions \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "idempotencyKey" : "${RANDOM_UUID}"
    }
    '
    ```

    **Response**

    ```json theme={null}
    {
      "data": {
        "id": "dbc27d23-cd4f-447e-855e-349cb2853d23",
        "status": "CREATED",
        "paymentId": "49d4231e-6c4f-319e-946d-ed8c8bab5abc",
        "expireDate": "2025-09-08T20:02:06.651391Z",
        "blockchain": "ETH-SEPOLIA",
        "senderAddress": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
        "destinationAddress": "0xc75c3e371d617b3e60db1b6f3fa2f0689562e5a7",
        "amount": {
          "amount": "15.000000",
          "currency": "USDC"
        },
        "messageType": "PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT",
        "messageToBeSigned": {
          "domain": {
            "name": "Permit2",
            "chainId": "11155111",
            "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
          },
          "message": {
            "permitted": {
              "token": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
              "amount": "14174474"
            },
            "spender": "0xe2B17D0C1736dc7C462ABc4233C91BDb9F27DD1d",
            "nonce": "25668617285137697861288274946631174355105919960416755114569514179393151588120",
            "deadline": "1757362866",
            "witness": {
              "from": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
              "to": "0xc75c3e371d617b3e60db1b6f3fa2f0689562e5a7",
              "value": 14174474,
              "validAfter": "1757358106",
              "validBefore": "1757361726",
              "nonce": "0x38bfec2b230187932870d575132e8ae1f83b34c10e3bf6d64c377f0c13245718",
              "beneficiary": "0x4f1c3a0359A7fAd8Fa8E9E872F7C06dAd97C91Fd",
              "maxFee": "0",
              "attester": "0x768919ef04853b5fd444ccff48cea154768a0291",
              "requirePayeeSign": false
            }
          },
          "primaryType": "PermitWitnessTransferFrom",
          "types": {
            "EIP712Domain": [
              {
                "name": "name",
                "type": "string"
              },
              {
                "name": "chainId",
                "type": "uint256"
              },
              {
                "name": "verifyingContract",
                "type": "address"
              }
            ],
            "PermitWitnessTransferFrom": [
              {
                "name": "permitted",
                "type": "TokenPermissions"
              },
              {
                "name": "spender",
                "type": "address"
              },
              {
                "name": "nonce",
                "type": "uint256"
              },
              {
                "name": "deadline",
                "type": "uint256"
              },
              {
                "name": "witness",
                "type": "PaymentIntent"
              }
            ],
            "TokenPermissions": [
              {
                "name": "token",
                "type": "address"
              },
              {
                "name": "amount",
                "type": "uint256"
              }
            ],
            "PaymentIntent": [
              {
                "name": "from",
                "type": "address"
              },
              {
                "name": "to",
                "type": "address"
              },
              {
                "name": "value",
                "type": "uint256"
              },
              {
                "name": "validAfter",
                "type": "uint256"
              },
              {
                "name": "validBefore",
                "type": "uint256"
              },
              {
                "name": "nonce",
                "type": "bytes32"
              },
              {
                "name": "beneficiary",
                "type": "address"
              },
              {
                "name": "maxFee",
                "type": "uint256"
              },
              {
                "name": "requirePayeeSign",
                "type": "bool"
              },
              {
                "name": "attester",
                "type": "address"
              }
            ]
          }
        },
        "metadata": {}
      }
    }
    ```
  </Tab>

  <Tab title="Transactions V1">
    ```shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v1/cpn/payments/:paymentId/transactions \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "idempotencyKey" : "${RANDOM_UUID}",
      "senderAccountType": "EOA",
    }
    '
    ```

    **Response**

    ```json theme={null}
    {
      "data": {
        "id": "8e0cc03f-799c-4971-ba41-6b790b4f9548",
        "status": "CREATED",
        "paymentId": "0a6973af-3089-4265-812b-0f68a426a4d8",
        "expireDate": "2025-04-01T17:28:25.198159Z",
        "senderAddress": "0x140f52a9D27764a51032ebDff7E6352D1640cbfd",
        "senderAccountType": "EOA",
        "blockchain": "ETH-SEPOLIA",
        "amount": {
          "amount": "10.000000",
          "currency": "USDC"
        },
        "destinationAddress": "0x6e87cdf0b9d2d96232f5c605526cb0e89db7387a",
        "estimatedFee": {
          "type": "EIP1559",
          "payload": {
            "gasLimit": "150000",
            "maxFeePerGas": "4829089726",
            "maxPriorityFeePerGas": "2000000000"
          }
        },
        "messageType": "EIP3009",
        "messageToBeSigned": {
          "domain": {
            "chainId": "11155111",
            "name": "USDC",
            "verifyingContract": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
            "version": "2"
          },
          "message": {
            "from": "0x140f52a9D27764a51032ebDff7E6352D1640cbfd",
            "nonce": "0x75cc053bfcdedd359bfdaaa560fc0c7d3899097dcf6396e65b029df3b1e05a0e",
            "to": "0x6e87cdf0b9d2d96232f5c605526cb0e89db7387a",
            "validAfter": "1743519573",
            "validBefore": "1743527605",
            "value": "10000000"
          },
          "primaryType": "TransferWithAuthorization",
          "types": {
            "EIP712Domain": [
              {
                "name": "name",
                "type": "string"
              },
              {
                "name": "version",
                "type": "string"
              },
              {
                "name": "chainId",
                "type": "uint256"
              },
              {
                "name": "verifyingContract",
                "type": "address"
              }
            ],
            "TransferWithAuthorization": [
              {
                "name": "from",
                "type": "address"
              },
              {
                "name": "to",
                "type": "address"
              },
              {
                "name": "value",
                "type": "uint256"
              },
              {
                "name": "validAfter",
                "type": "uint256"
              },
              {
                "name": "validBefore",
                "type": "uint256"
              },
              {
                "name": "nonce",
                "type": "bytes32"
              }
            ]
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 3.2 Sign the onchain transaction

<Note>
  The following steps are for EVM blockchains. For Solana, you would follow a
  similar process with some differences in the signing. Refer to how to [Create
  an Onchain Transaction](/cpn/guides/transactions/create-an-onchain-txn) for
  more information.
</Note>

<Tabs>
  <Tab title="Transactions V2">
    Using the
    [`/sign/typedData`](/api-reference/wallets/developer-controlled-wallets/sign-typed-data)
    endpoint, input the `messageToBeSigned` object from the previous step along with
    your entity secret and wallet ID. The transaction parameter should be
    [stringified](https://jsonformatter.org/json-stringify-online) from the
    `messageToBeSigned` field from the transaction response.

    ```bash Shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v1/w3s/developer/sign/typedData \
      --header 'Accept: application/json' \
      --header 'authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "entitySecretCiphertext": "qXnnGgbsU5lBUGiW9kp2/ltuvSSWW4qJ4/9VKuQT7wd6+ge2y7xqYnEc0pHbqLuj+YBDaPMfRUl1X+K1hbyiPTRVjCqHD5x3DyLtj8eTG/GmIimYfXOveXIJjsT95T8bI9uJ9kxygYAQbNev6wX993OYTYZ8D2PfVLUV3BicTSiClqhgSLW1Nh0qJ+TK0p2rOHs2HZkGA/WTv4SQv+uq//wEbUWFmrrD/ToTSuv3tMQvluCMYDF9xO/F6EoQwmP/XJCpPihGZuvrweTnhHbNWe5suvSSKpB+8Yo6f24ttNtCwvHrLBVaF6U9EZrCRpCydHJuuVBf5j7AD0JPC2DPFAG2p/Upq/KdzF1r8GJ4j2SsFLyzQEAw3ZAl623UiB/F3Szu2T/fYeF0rkfNt6tYKqmCmhvlzvn8BBkgIXsdcoEmNsf4x7b7UwPk9EloTibF4MhkGIW7jDHWWXlL3gKpGzMug+A2bIYdwUtqQ+u65pDi4+o+tuEH8MtM9Mmt3YaP2Zr40wj/uMnRv53hc+Apzsvh6UIsmliK2ldPyfXg77eDEzU7E228al/jIi2YQacQLNAAV870v3iKFB0PeWiUNtVlUdnqXmZkMA/bmg4TOo05ROGJWkfPVFWUNoocyEvCfEasj0ZflfbO8W2Q0M9BqhqjU/WHEBrYnF65ytY0A+8=",
      "data": "{\"domain\":{\"chainId\":\"11155111\",\"name\":\"USDC\",\"verifyingContract\":\"0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238\",\"version\":\"2\"},\"message\":{\"from\":\"0x39fd73b03a01c6230b5e0d946e1960d79db44fd8\",\"nonce\":\"0x854f1f66cb7cb0e266e17a3715c24c8dae1eb540c4eb00a7a1b39f4bfa9bcf09\",\"to\":\"0x6734b39043f1029f8d5f1b6948d5417b75a72cf8\",\"validAfter\":\"1743522751\",\"validBefore\":\"1743530842\",\"value\":\"10000000\"},\"primaryType\":\"TransferWithAuthorization\",\"types\":{\"EIP712Domain\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"version\",\"type\":\"string\"},{\"name\":\"chainId\",\"type\":\"uint256\"},{\"name\":\"verifyingContract\",\"type\":\"address\"}],\"TransferWithAuthorization\":[{\"name\":\"from\",\"type\":\"address\"},{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"value\",\"type\":\"uint256\"},{\"name\":\"validAfter\",\"type\":\"uint256\"},{\"name\":\"validBefore\",\"type\":\"uint256\"},{\"name\":\"nonce\",\"type\":\"bytes32\"}]}}",
      "walletId": "${YOUR_CIRCLE_WALLET_ID}"
    }
    '
    ```

    **Response**

    ```json JSON theme={null}
    {
      "signature": "0x905d70de3f1d9e86b982f6aee2755807fcd50a11cd9035bf47845c856be920fc3b7af8d06bf953bfdecdcea4cc9250aeaeb178b50116774d6bfab37bcc3757621c"
    }
    ```
  </Tab>

  <Tab title="Transactions V1">
    Using the
    [`/sign/typedData`](/api-reference/wallets/developer-controlled-wallets/sign-typed-data)
    endpoint, input the `messageToBeSigned` object from the previous step along with
    your entity secret and wallet ID. The transaction parameter should be
    [stringified](https://jsonformatter.org/json-stringify-online) from the
    `messageToBeSigned` field from the transaction response.

    ```bash Shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v1/w3s/developer/sign/typedData \
      --header 'Accept: application/json' \
      --header 'authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "entitySecretCiphertext": "qXnnGgbsU5lBUGiW9kp2/ltuvSSWW4qJ4/9VKuQT7wd6+ge2y7xqYnEc0pHbqLuj+YBDaPMfRUl1X+K1hbyiPTRVjCqHD5x3DyLtj8eTG/GmIimYfXOveXIJjsT95T8bI9uJ9kxygYAQbNev6wX993OYTYZ8D2PfVLUV3BicTSiClqhgSLW1Nh0qJ+TK0p2rOHs2HZkGA/WTv4SQv+uq//wEbUWFmrrD/ToTSuv3tMQvluCMYDF9xO/F6EoQwmP/XJCpPihGZuvrweTnhHbNWe5suvSSKpB+8Yo6f24ttNtCwvHrLBVaF6U9EZrCRpCydHJuuVBf5j7AD0JPC2DPFAG2p/Upq/KdzF1r8GJ4j2SsFLyzQEAw3ZAl623UiB/F3Szu2T/fYeF0rkfNt6tYKqmCmhvlzvn8BBkgIXsdcoEmNsf4x7b7UwPk9EloTibF4MhkGIW7jDHWWXlL3gKpGzMug+A2bIYdwUtqQ+u65pDi4+o+tuEH8MtM9Mmt3YaP2Zr40wj/uMnRv53hc+Apzsvh6UIsmliK2ldPyfXg77eDEzU7E228al/jIi2YQacQLNAAV870v3iKFB0PeWiUNtVlUdnqXmZkMA/bmg4TOo05ROGJWkfPVFWUNoocyEvCfEasj0ZflfbO8W2Q0M9BqhqjU/WHEBrYnF65ytY0A+8=",
      "data": "{\"domain\":{\"chainId\":\"11155111\",\"name\":\"USDC\",\"verifyingContract\":\"0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238\",\"version\":\"2\"},\"message\":{\"from\":\"0x39fd73b03a01c6230b5e0d946e1960d79db44fd8\",\"nonce\":\"0x854f1f66cb7cb0e266e17a3715c24c8dae1eb540c4eb00a7a1b39f4bfa9bcf09\",\"to\":\"0x6734b39043f1029f8d5f1b6948d5417b75a72cf8\",\"validAfter\":\"1743522751\",\"validBefore\":\"1743530842\",\"value\":\"10000000\"},\"primaryType\":\"TransferWithAuthorization\",\"types\":{\"EIP712Domain\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"version\",\"type\":\"string\"},{\"name\":\"chainId\",\"type\":\"uint256\"},{\"name\":\"verifyingContract\",\"type\":\"address\"}],\"TransferWithAuthorization\":[{\"name\":\"from\",\"type\":\"address\"},{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"value\",\"type\":\"uint256\"},{\"name\":\"validAfter\",\"type\":\"uint256\"},{\"name\":\"validBefore\",\"type\":\"uint256\"},{\"name\":\"nonce\",\"type\":\"bytes32\"}]}}",
      "walletId": "${YOUR_CIRCLE_WALLET_ID}"
    }
    '
    ```

    **Response**

    ```json JSON theme={null}
    {
      "signature": "0x905d70de3f1d9e86b982f6aee2755807fcd50a11cd9035bf47845c856be920fc3b7af8d06bf953bfdecdcea4cc9250aeaeb178b50116774d6bfab37bcc3757621c"
    }
    ```

    Create a file called `cpn_signature.py` and add the following code to it,
    replacing `circle_signature` with the signature returned from the endpoint, and
    replacing the message object values with the corresponding values from the
    response in
    [step 3.1](/cpn/quickstarts/integrate-with-cpn-ofi#3-1-initiate-the-onchain-transaction).

    ```python Python theme={null}
    from web3 import Web3
    from eth_utils import keccak, to_hex
    from hexbytes import HexBytes
    from eth_abi import encode

    def get_function_selector(signature: str) -> str:
        """Return 4-byte function selector from signature."""
        hash_bytes = keccak(text=signature)
        return to_hex(hash_bytes[:4])

    def encode_transfer_with_authorization(
        from_address: str,
        to_address: str,
        value: int,
        valid_after: int,
        valid_before: int,
        nonce: str,
        v: int,
        r: str,
        s: str
    ) -> str:
        """Encode callData for transferWithAuthorization (EIP-3009 USDC)."""
        types = [
            "address", "address", "uint256", "uint256", "uint256",
            "bytes32", "uint8", "bytes32", "bytes32"
        ]
        args = [
            Web3.to_checksum_address(from_address),
            Web3.to_checksum_address(to_address),
            value,
            valid_after,
            valid_before,
            HexBytes(nonce),
            v,
            HexBytes(r),
            HexBytes(s)
        ]
        encoded_args = encode(types, args)
        selector = get_function_selector(f"transferWithAuthorization({','.join(types)})")
        return selector + encoded_args.hex()

    # === INPUT DATA ===

    circle_signature = your_signature
    message = {
        "from": your_from_address,
        "to": your_to_address,
        "value": 10_000_000,  # 10 USDC (6 decimals)
        "validAfter": your_valid_after,
        "validBefore": your_valid_before,
        "nonce": your_nonce
    }

    # === SPLIT SIGNATURE ===

    sig_bytes = Web3.to_bytes(hexstr=circle_signature)
    r = Web3.to_hex(sig_bytes[0:32])
    s = Web3.to_hex(sig_bytes[32:64])
    v = sig_bytes[64]
    if v < 27:
        v += 27  # Normalize v for Ethereum

    # === ENCODE CALL DATA ===

    call_data = encode_transfer_with_authorization(
        from_address=message["from"],
        to_address=message["to"],
        value=message["value"],
        valid_after=message["validAfter"],
        valid_before=message["validBefore"],
        nonce=message["nonce"],
        v=v,
        r=r,
        s=s
    )

    print(f"✅ Final Call Data:\n{call_data}")
    ```

    Next, you must create and sign the raw transaction using the
    [`/sign-transaction`](/api-reference/wallets/developer-controlled-wallets/sign-transaction)
    endpoint. Include the call data from the script as the `data` field and the
    wallet ID from your Circle Wallet.

    The raw transaction to be signed can be composed like the following example:

    ```json JSON theme={null}
    {
      "nonce": 1, // The nonce of the sender address, obtained via eth_getTransactionCount RPC call
      "to": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238", // The target contract address, in this case, the USDC contract address
      "gas": "150000", // The gas limit for the transaction, from `data.estimatedFee.payload.gasLimit` in the step 3.1 response.
      "maxFeePerGas": "70000000000", // The max fee per gas, from `data.estimatedFee.payload.maxFeePerGas` in the step 3.1 response.
      "maxPriorityFeePerGas": "3000000000", // The max priority fee per gas, from `data.estimatedFee.payload.maxPriorityFeePerGas` in the step 3.1 response.
      "chainId": 11155111, // The chain ID, for Ethereum Sepolia testnet, the chain ID is 11155111
      // The call data, obtained from the script in step 3.2
      "data": "0xe3ee160e00000000000000000000000039fd73b03a01c6230b5e0d946e1960d79db44fd80000000000000000000000003eebc158f254838e2f6275b892e6a0621e3ea321000000000000000000000000000000000000000000000000000000000098968000000000000000000000000000000000000000000000000000000000680bc9e000000000000000000000000000000000000000000000000000000000680be8863a30a084fe9ef623cf95ea778067b98b69accf602b8f240f55073339f4c2f2b2000000000000000000000000000000000000000000000000000000000000001bd6960c1cc4c28482a3c96ea35e5c0cfe84f4e466f734de02023b15101c9735a04830dbfeeccd565705c1e8b92b3dd038d720130f5a3101bf43160be49e0f1651"
    }
    ```

    Use the following endpoint to sign the transaction:

    ```bash Shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v1/w3s/developer/sign/transaction \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "entitySecretCiphertext": "h8R0RizKx0KWX2wpZgfcUoSSFms0Qj/6pkGH3JSKaYJPhSNRl2GpPWba9ZilCRivI42Di9MRAxI5jsGjay1tyQcrasq3o0aC4jNvK6RH7f8DOnoeNQjmL4pFlLzp/R+NduNI/w/JH5rk84JhsAkOy5yXkMmGf9IkQbh4+381VojV3P8FCuVzsJDTI5KDWzzwMR3eExmQN8QmKlIIyxlAm1JSxhS5Y/9GqqMY+jtcSkxzkX965GzkGyODRo0gxPuUZCiES1lHSe9tkLJWs5AgvJ/2MVpaiDmcIXZJ3JNBw2EuAMp6uRiv3OiODrThgP44YSpvTPavfxDtAnxyw7ZrPSUeN8wX8RBsTpqxZaJvy4aJTCgnDjfvqfPcsg90UqhXYI0VBVU5489s89HHKw76AYp4Hz52Iu4FtsA6r2PidN4Cccp7Ges7gOde6vG36mOG0ODcxMwKyWcAkNdZYEPBQ1DK0c1s5dbNYImBHZ+EnfY0TlHroFOKYhMihrhkXTjCTL+HiSboJtoVGvOphmsyvoQMg0fzprJUVhOraH/soQkd61eulETFN6vJq8R5ODFeeBDlOkZny1Om2ZUd8tdobZDlVGiSZFUR4rPlntoUN5g/hPp8lB+25UN2KaIUiX3OR01EvRedA6Xr+kqzVsmgKmkNW1aFuOJFXEAXlMjR2fU=",
      "transaction": "{\"nonce\":1,\"to\":\"0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238\",\"gas\":\"150000\",\"maxFeePerGas\":\"70000000000\",\"maxPriorityFeePerGas\":\"3000000000\",\"chainId\":11155111,\"data\":\"0xe3ee160e00000000000000000000000039fd73b03a01c6230b5e0d946e1960d79db44fd80000000000000000000000003eebc158f254838e2f6275b892e6a0621e3ea321000000000000000000000000000000000000000000000000000000000098968000000000000000000000000000000000000000000000000000000000680bc9e000000000000000000000000000000000000000000000000000000000680be8863a30a084fe9ef623cf95ea778067b98b69accf602b8f240f55073339f4c2f2b2000000000000000000000000000000000000000000000000000000000000001bd6960c1cc4c28482a3c96ea35e5c0cfe84f4e466f734de02023b15101c9735a04830dbfeeccd565705c1e8b92b3dd038d720130f5a3101bf43160be49e0f1651\"}",
      "walletId": "${YOUR_CIRCLE_WALLET_ID}"
    }
    '
    ```

    **Response**

    ```json JSON theme={null}
    {
      "signature": "0xe59d32312a920b6c63ad4c7344bb76d8e7cae2615f79f707649e325abea00a247cddec90138bb6790e68e01998fdf77efc9496a91b3b4b42e59fd0e8ad89d0bc00",
      "signedTransaction": "0x02f9019583aa36a70184b2d05e0085104c533c00830249f0941c7d4b196cb0c7b01d743fbc6116a902379c723880b90124e3ee160e00000000000000000000000039fd73b03a01c6230b5e0d946e1960d79db44fd80000000000000000000000003eebc158f254838e2f6275b892e6a0621e3ea321000000000000000000000000000000000000000000000000000000000098968000000000000000000000000000000000000000000000000000000000680bc9e000000000000000000000000000000000000000000000000000000000680be8863a30a084fe9ef623cf95ea778067b98b69accf602b8f240f55073339f4c2f2b2000000000000000000000000000000000000000000000000000000000000001bd6960c1cc4c28482a3c96ea35e5c0cfe84f4e466f734de02023b15101c9735a04830dbfeeccd565705c1e8b92b3dd038d720130f5a3101bf43160be49e0f1651c080a0e59d32312a920b6c63ad4c7344bb76d8e7cae2615f79f707649e325abea00a24a07cddec90138bb6790e68e01998fdf77efc9496a91b3b4b42e59fd0e8ad89d0bc",
      "txHash": "0xc1d5963f87e4a9035eae4e31fe7842a8bc1cd0ebf941d541c0b7ff37b4d1f5df"
    }
    ```
  </Tab>
</Tabs>

### 3.3. Submit the signed transaction

<Tabs>
  <Tab title="Transactions V2">
    Use the
    [`/v2/cpn/payments/{paymentId}/transactions/{transactionId}/submit`](/api-reference/cpn/cpn-platform/submit-transaction-v2)
    endpoint to submit the transaction to be broadcast to the blockchain.
    You should submit the EIP-712 typed data signature you obtained from the `/sign/typedData` endpoint in
    [step 3.2.](#3-2-sign-the-onchain-transaction) as `signedTransaction`.

    ```bash Shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v2/cpn/payments/:paymentId/transactions/:transactionId/submit \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-type: application/json' \
      --data '
    {
      "signedTransaction": "0x12b5fb72e99f9bb0300d2eb66a6d89dd5a667f43669893cf14bfcc390754dcb61b69f92cba598ec83a184e11c97e3bb9964a2bfd7a09688eee63f586ad9ccae21c"
    }
    '
    ```

    **Response**

    ```json JSON theme={null}
    {
      "data": {
        "id": "5cae9e1c-f3e3-44e5-ac36-d78f4ff9c56e",
        "status": "PENDING",
        "paymentId": "2b2b314a-0c06-39bb-b111-506f56599a17",
        "expireDate": "2025-11-12T00:08:42.000875Z",
        "blockchain": "ETH-SEPOLIA",
        "senderAddress": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
        "destinationAddress": "0xded12af48fb343b446bcbe739c5211636896362b",
        "amount": {
          "amount": "11.948672",
          "currency": "USDC"
        },
        "messageType": "PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT",
        "messageToBeSigned": {
          "domain": {
            "name": "Permit2",
            "chainId": "11155111",
            "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
          },
          "message": {
            "permitted": {
              "token": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
              "amount": "11948672"
            },
            "spender": "0x8ea7239f185CC32AB1Ff698f1b1A3aAB615D6d2c",
            "nonce": "55519981872451242578307489093459806523820915276389791540432104685160022674073",
            "deadline": "1762907262",
            "witness": {
              "from": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
              "to": "0xded12af48fb343b446bcbe739c5211636896362b",
              "value": 11048874,
              "validAfter": "1762901905",
              "validBefore": "1762906122",
              "nonce": "0x7abf323679377bff4d064e663e44b7064985eab99693dec4a9e8a9f941a80a99",
              "beneficiary": "0x8049E74C07A6BAdc8ddeB7C3530Ab9Af30037211",
              "maxFee": "899798",
              "attester": "0xcf9e077c75ce6bd22f48163e559d20b10708ae85",
              "requirePayeeSign": false
            }
          },
          "primaryType": "PermitWitnessTransferFrom",
          "types": {
            "EIP712Domain": [
              {
                "name": "name",
                "type": "string"
              },
              {
                "name": "chainId",
                "type": "uint256"
              },
              {
                "name": "verifyingContract",
                "type": "address"
              }
            ],
            "PermitWitnessTransferFrom": [
              {
                "name": "permitted",
                "type": "TokenPermissions"
              },
              {
                "name": "spender",
                "type": "address"
              },
              {
                "name": "nonce",
                "type": "uint256"
              },
              {
                "name": "deadline",
                "type": "uint256"
              },
              {
                "name": "witness",
                "type": "PaymentIntent"
              }
            ],
            "TokenPermissions": [
              {
                "name": "token",
                "type": "address"
              },
              {
                "name": "amount",
                "type": "uint256"
              }
            ],
            "PaymentIntent": [
              {
                "name": "from",
                "type": "address"
              },
              {
                "name": "to",
                "type": "address"
              },
              {
                "name": "value",
                "type": "uint256"
              },
              {
                "name": "validAfter",
                "type": "uint256"
              },
              {
                "name": "validBefore",
                "type": "uint256"
              },
              {
                "name": "nonce",
                "type": "bytes32"
              },
              {
                "name": "beneficiary",
                "type": "address"
              },
              {
                "name": "maxFee",
                "type": "uint256"
              },
              {
                "name": "requirePayeeSign",
                "type": "bool"
              },
              {
                "name": "attester",
                "type": "address"
              }
            ]
          }
        },
        "encodedMessageToBeSigned": "0xabc6f65eb8b2c264ae486b7244e9ca887cd0f8bd29422f651042665c14974ef3",
        "metadata": {},
        "version": "VERSION_2"
      }
    }
    ```

    <Note>
      `transactionHash` will be provided after transaction is in `COMPLETED` status.
      You can monitor for the transactions webhook events to get the
      `transactionHash`.
    </Note>
  </Tab>

  <Tab title="Transactions V1">
    Use the
    [`/v1/cpn/payments/{paymentId}/transactions/{transactionId}/submit`](/api-reference/cpn/cpn-platform/submit-transaction)
    endpoint to submit the transaction to be broadcast to the blockchain.
    You should submit the `signedTransaction` you obtained from the
    `/sign/transaction` endpoint in [step 3.2](#3-2-sign-the-onchain-transaction).

    ```shell theme={null}
    curl --request POST \
      --url https://api.circle.com/v1/cpn/payments/:paymentId/transactions/:transactionId/submit \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer ${YOUR_API_KEY}' \
      --header 'Content-type: application/json' \
      --data '
    {
      "signedTransaction": "0x02f9019583aa36a70184b2d05e0085104c533c00830249f0941c7d4b196cb0c7b01d743fbc6116a902379c723880b90124e3ee160e00000000000000000000000039fd73b03a01c6230b5e0d946e1960d79db44fd80000000000000000000000003eebc158f254838e2f6275b892e6a0621e3ea321000000000000000000000000000000000000000000000000000000000098968000000000000000000000000000000000000000000000000000000000680bc9e000000000000000000000000000000000000000000000000000000000680be8863a30a084fe9ef623cf95ea778067b98b69accf602b8f240f55073339f4c2f2b2000000000000000000000000000000000000000000000000000000000000001bd6960c1cc4c28482a3c96ea35e5c0cfe84f4e466f734de02023b15101c9735a04830dbfeeccd565705c1e8b92b3dd038d720130f5a3101bf43160be49e0f1651c080a0e59d32312a920b6c63ad4c7344bb76d8e7cae2615f79f707649e325abea00a24a07cddec90138bb6790e68e01998fdf77efc9496a91b3b4b42e59fd0e8ad89d0bc"
    }
    '
    ```

    **Response**

    ```json theme={null}
    {
      "data": {
        "id": "1f3ccc13-69e3-4811-9648-755bc9aa26f4",
        "status": "PENDING",
        "paymentId": "fed8687a-d911-3682-a6f2-b2474a1016ba",
        "expireDate": "2025-04-25T19:54:46.230217Z",
        "senderAddress": "0x39fd73b03a01c6230b5e0d946e1960d79db44fd8",
        "senderAccountType": "EOA",
        "blockchain": "ETH-SEPOLIA",
        "amount": {
          "amount": "10.000000",
          "currency": "USDC"
        },
        "destinationAddress": "0x3eebc158f254838e2f6275b892e6a0621e3ea321",
        "estimatedFee": {
          "type": "EIP1559",
          "payload": {
            "gasLimit": "150000",
            "maxFeePerGas": "27514930294",
            "maxPriorityFeePerGas": "2000000000"
          }
        },
        "messageType": "EIP3009",
        "messageToBeSigned": {
          "domain": {
            "chainId": "11155111",
            "name": "USDC",
            "verifyingContract": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
            "version": "2"
          },
          "message": {
            "from": "0x39fd73b03a01c6230b5e0d946e1960d79db44fd8",
            "nonce": "0x3a30a084fe9ef623cf95ea778067b98b69accf602b8f240f55073339f4c2f2b2",
            "to": "0x3eebc158f254838e2f6275b892e6a0621e3ea321",
            "validAfter": "1745603040",
            "validBefore": "1745610886",
            "value": "10000000"
          },
          "primaryType": "TransferWithAuthorization",
          "types": {
            "EIP712Domain": [
              {
                "name": "name",
                "type": "string"
              },
              {
                "name": "version",
                "type": "string"
              },
              {
                "name": "chainId",
                "type": "uint256"
              },
              {
                "name": "verifyingContract",
                "type": "address"
              }
            ],
            "TransferWithAuthorization": [
              {
                "name": "from",
                "type": "address"
              },
              {
                "name": "to",
                "type": "address"
              },
              {
                "name": "value",
                "type": "uint256"
              },
              {
                "name": "validAfter",
                "type": "uint256"
              },
              {
                "name": "validBefore",
                "type": "uint256"
              },
              {
                "name": "nonce",
                "type": "bytes32"
              }
            ]
          }
        },
        "signedTransaction": "0x02f9019583aa36a70184b2d05e0085104c533c00830249f0941c7d4b196cb0c7b01d743fbc6116a902379c723880b90124e3ee160e00000000000000000000000039fd73b03a01c6230b5e0d946e1960d79db44fd80000000000000000000000003eebc158f254838e2f6275b892e6a0621e3ea321000000000000000000000000000000000000000000000000000000000098968000000000000000000000000000000000000000000000000000000000680bc9e000000000000000000000000000000000000000000000000000000000680be8863a30a084fe9ef623cf95ea778067b98b69accf602b8f240f55073339f4c2f2b2000000000000000000000000000000000000000000000000000000000000001bd6960c1cc4c28482a3c96ea35e5c0cfe84f4e466f734de02023b15101c9735a04830dbfeeccd565705c1e8b92b3dd038d720130f5a3101bf43160be49e0f1651c080a0e59d32312a920b6c63ad4c7344bb76d8e7cae2615f79f707649e325abea00a24a07cddec90138bb6790e68e01998fdf77efc9496a91b3b4b42e59fd0e8ad89d0bc",
        "transactionHash": "0xc1d5963f87e4a9035eae4e31fe7842a8bc1cd0ebf941d541c0b7ff37b4d1f5df"
      }
    }
    ```
  </Tab>
</Tabs>

Once the onchain transaction is confirmed by the BFI, the BFI initiates a fiat
payout to the recipient. As the fiat payout progresses, the OFI is notified by
[webhook notifications](/cpn/guides/webhooks/setup-webhook-notifications).


# Payment Smart Contract Addresses
Source: https://developers.circle.com/cpn/references/blockchains/contract-addresses

Payment smart contract addresses for CPN

The following sections provide the addresses for the CPN payment smart contracts
on supported blockchains.

## Mainnet

| Blockchain  | Settlement Contract Address                                                                                                |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| Ethereum    | [`0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868`](https://etherscan.io/address/0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868)    |
| Polygon PoS | [`0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868`](https://polygonscan.com/address/0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868) |

## Testnet

| Blockchain       | Settlement Contract Address                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Arc Testnet      | [`0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868`](https://testnet.arcscan.app/address/0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868)  |
| Ethereum Sepolia | [`0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868`](https://sepolia.etherscan.io/address/0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868) |
| Polygon PoS Amoy | [`0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868`](https://amoy.polygonscan.com/address/0x355e0a2a4B7563e0E00C90deD9Aa914c119Ee868) |


# Supported Blockchains
Source: https://developers.circle.com/cpn/references/blockchains/supported-blockchains



CPN is chain-agnostic and built for multichain flexibility. OFIs can select the
blockchains they operate on, based on their internal risk, compliance,
operational, and security requirements.

The following sections list the blockchains that CPN supports.

## Testnet

| Blockchain       | Transactions V1 | Transactions V2 |
| ---------------- | --------------- | --------------- |
| Ethereum Sepolia | ✅               | ✅               |
| Polygon Amoy     | ✅               | ✅               |
| Solana Devnet    | ✅               | ✅               |

## Mainnet

| Blockchain | Transactions V1 | Transactions V2 |
| ---------- | --------------- | --------------- |
| Ethereum   | ✅               | ✅               |
| Polygon    | ✅               | ✅               |
| Solana     | ✅               | ✅               |


# Wallet Provider Compatibility
Source: https://developers.circle.com/cpn/references/blockchains/wallet-provider-compatibility



CPN allows you to bring your own wallet provider when integrating with the
network. Circle Wallets is an option for your integration, but not a
requirement. When bringing your own wallet provider, you should make sure that
they support the features and signing methods that are required to interact with
CPN.

## Requirements

The following features and signing methods are required for a wallet provider to
be able to integrate with CPN:

* **Custodial wallet support:** The provider must be able to sign transactions
  for wallets without requiring user interaction.
* **Ethereum virtual machine (EVM) raw transaction signing:** For Transactions
  V1, the provider must be able to sign raw EVM transactions without
  broadcasting them to the blockchain. This is not required for Transactions V2.
* **EIP-712 signing:** The provider must support EIP-712 typed data. This is a
  requirement for both Transactions V1 and V2. The resulting signature can be
  used in one of the following ways:
  * The signature can be verified by recovering the signer's address with the
    hash of the typed data (on behalf of an EOA).
  * The signature can be validated by the `isValidSignature` method defined in
    EIP-1271 with the hash of the typed data (on behalf of an SCA).

<Note>
  **Note:** USDC implements EIP-3009 with the EIP-7598 extension, enabling both
  EOAs and SCAs to authorize transfers via the EIP-3009 mechanism.
</Note>

* SCA wallet interface: When using an SCA wallet as the sender wallet, the
  wallet contract must implement the following two interfaces:
  * EIP-165 Standard Interface Detection: The SCA wallet must correctly
    implement the EIP-165 interface detection standard. The `supportsInterface`
    function must return `true` for the EIP-1271 interface ID.
  * EIP-1271 Standard Signature Validation for Contracts: The SCA wallet must
    correctly implement the EIP-1271 interface, which defines the
    `isValidSignature` function.

* **Solana signing:** The provider must support signing raw Solana transaction
  using `Ed25519`, without broadcasting them to the blockchain. For Transactions
  V2, the provider must support
  [partial signing](https://solana.com/developers/cookbook/transactions/offline-transactions#partial-sign-transaction)
  of the transaction.

* **Solana memo field:** The provider must support a memo field for Solana
  transactions.

| Blockchain | Transactions V1                                                   | Transactions V2                              |
| ---------- | ----------------------------------------------------------------- | -------------------------------------------- |
| EVM        | EIP-712 typed data signing<br /><br />Raw EVM transaction signing | EIP-712 typed data signing                   |
| Solana     | Solana transaction signing                                        | Solana transaction signing (partial signing) |


# RFI Levels
Source: https://developers.circle.com/cpn/references/compliance/rfi-levels



Requests for information (RFI) can have one of three levels, which indicate the
required information that must be passed to satisfy the RFI. The levels vary
depending on if the sender is an individual or a business.

## Individual

The following sections outline the requirements for each level if the sender is
an individual (natural person).

### Level 1

Level 1 requires the following information:

| Field                            | Description                                                    |
| -------------------------------- | -------------------------------------------------------------- |
| `ADDRESS`                        | Individual's full address                                      |
| `NAME`                           | Individual's full name                                         |
| `DATE_OF_BIRTH`                  | Individual's date of birth                                     |
| `NATIONAL_IDENTIFICATION_NUMBER` | Unique government-issued ID (tax ID, national ID, or other)    |
| `SOURCE_OF_FUNDS`                | Source of funds for transactions                               |
| `METHOD_OF_VERIFICATION`         | The method of verification (electronic, by document, or other) |

### Level 2

Level 2 requires all of the information required for level 1, plus the following
information:

| Field         | Description                         |
| ------------- | ----------------------------------- |
| `NATIONALITY` | Nationality of the individual       |
| `EMAIL`       | Contact email address               |
| `PHONE`       | Primary phone number                |
| `OCCUPATION`  | Employment or professional activity |

### Level 3

Level 3 requires all the information required for levels 1 and 2, plus the
following information:

| Field              | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `ID_DOC_TYPE`      | Type of ID provided (passport, national ID, or others) |
| `ID_DOCUMENT`      | Copy of the provided ID                                |
| `PROOF_OF_ADDRESS` | Utility bill, bank statement, or lease agreement       |
| `ADDITIONAL_DOCS`  | Any additional documents for enhanced due diligence    |

## Business

The following sections outline the requirements for each level if the sender is
a business.

### Level 1

Level 1 requires the following information:

| Field                            | Description                                                |
| -------------------------------- | ---------------------------------------------------------- |
| `NAME`                           | Legal registered name of the business                      |
| `TRADE_NAME`                     | Doing Business As (DBA) or trade name                      |
| `NATIONAL_IDENTIFICATION_NUMBER` | Business identification number (tax ID)                    |
| `DATE_OF_FORMATION`              | Date of company formation                                  |
| `COUNTRY_OF_FORMATION`           | Country where the entity was formed                        |
| `ENTITY_TYPE`                    | Business structure (LLC, corporation, partnership, others) |
| `INDUSTRY_TYPE`                  | Classification of business activity                        |
| `ADDRESS`                        | Registered place of business                               |
| `METHOD_OF_VERIFICATION`         | The method of verification                                 |
| `SOURCE_OF_FUNDS`                | Business funding sources                                   |

### Level 2

Level 2 requires all of the information required for level 1, plus the following
information:

| Field                             | Description                                                                                                           |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `AUTHORIZED_SIGNATORIES`          | List of individuals with signature authorization                                                                      |
| `BENEFICIARY_OWNERSHIP`           | Whether any individuals or entities have significant ownership (directly or indirectly own >= 25%) of the company     |
| `BENEFICIARY_OWNERS`              | List of individuals with significant ownership (directly or indirectly owning >= 25%) of the company                  |
| `INTERMEDIARY_BENEFICIARY_OWNERS` | List of intermediary beneficiary owners with significant ownership (directly or indirectly own >= 25%) of the company |
| `WEBSITE`                         | Business website URL                                                                                                  |
| `EMAIL`                           | Business contact email                                                                                                |
| `PHONE`                           | Business contact phone number                                                                                         |

### Level 3

Level 3 requires all the information required for levels 1 and 2, plus the
following information:

| Field                                  | Description                                            |
| -------------------------------------- | ------------------------------------------------------ |
| `FORMATION_DOCUMENT`                   | Articles of incorporation or certificate of formation  |
| `PROOF_OF_ADDRESS`                     | Utility bill, lease agreement, or bank statement       |
| `ORG_STRUCTURE`                        | Document of the organization structure of the business |
| `INVOICE`                              | Underlying invoice for the payment                     |
| `BENEFICIAL_OWNERS_IDENTITY_DOCUMENTS` | Beneficial owners ID documents                         |


# CPN Supported Countries
Source: https://developers.circle.com/cpn/references/compliance/supported-countries

Countries supported by the Circle Payments Network

The following table shows countries where Circle Payments Network is allowed to
operate. The country code is used in the
[`senderCountry` parameter](/api-reference/cpn/cpn-platform/create-quotes#body-sender-country)
in the CPN API. Note that the not all countries are currently supported by CPN.
Consult the preceding link for the full list of supported countries in the API
reference.

| Country                                      | Country Code | Supported? |
| -------------------------------------------- | ------------ | ---------- |
| Afghanistan                                  | AF           | ❌          |
| Albania                                      | AL           | ✅          |
| Algeria                                      | DZ           | ✅          |
| American Samoa                               | AS           | ✅          |
| Andorra                                      | AD           | ✅          |
| Angola                                       | AO           | ✅          |
| Anguilla                                     | AI           | ✅          |
| Antigua and Barbuda                          | AG           | ✅          |
| Argentina                                    | AR           | ✅          |
| Armenia                                      | AM           | ✅          |
| Aruba                                        | AW           | ✅          |
| Australia                                    | AU           | ✅          |
| Austria                                      | AT           | ✅          |
| Azerbaijan                                   | AZ           | ✅          |
| Bahamas                                      | BS           | ✅          |
| Bahrain                                      | BH           | ✅          |
| Bangladesh                                   | BD           | ✅          |
| Barbados                                     | BB           | ✅          |
| Belarus                                      | BY           | ❌          |
| Belgium                                      | BE           | ✅          |
| Belize                                       | BZ           | ✅          |
| Benin                                        | BJ           | ✅          |
| Bermuda                                      | BM           | ✅          |
| Bhutan                                       | BT           | ✅          |
| Bolivia                                      | BO           | ✅          |
| Bonaire                                      | BQ           | ✅          |
| Bosnia and Herzegovina                       | BA           | ✅          |
| Botswana                                     | BW           | ✅          |
| Bouvet Island                                | BV           | ✅          |
| Brazil                                       | BR           | ✅          |
| British Indian Ocean Territory               | IO           | ✅          |
| Brunei Darussalam                            | BN           | ✅          |
| Bulgaria                                     | BG           | ✅          |
| Burkina Faso                                 | BF           | ✅          |
| Burundi                                      | BI           | ✅          |
| Cabo Verde                                   | CV           | ✅          |
| Cambodia                                     | KH           | ✅          |
| Cameroon                                     | CM           | ✅          |
| Canada                                       | CA           | ✅          |
| Cayman Islands                               | KY           | ✅          |
| Central African Republic                     | CF           | ❌          |
| Chad                                         | TD           | ✅          |
| Chile                                        | CL           | ✅          |
| China                                        | CN           | ✅          |
| Christmas Island                             | CX           | ✅          |
| Cocos (Keeling) Islands                      | CC           | ✅          |
| Colombia                                     | CO           | ✅          |
| Comoros                                      | KM           | ✅          |
| Congo                                        | CG           | ✅          |
| Congo, Democratic Republic of the            | CD           | ❌          |
| Cook Islands                                 | CK           | ✅          |
| Costa Rica                                   | CR           | ✅          |
| Croatia                                      | HR           | ✅          |
| Cuba                                         | CU           | ❌          |
| Curacao                                      | CW           | ✅          |
| Cyprus                                       | CY           | ✅          |
| Czechia                                      | CZ           | ✅          |
| Cote d'Ivoire                                | CI           | ✅          |
| Denmark                                      | DK           | ✅          |
| Djibouti                                     | DJ           | ✅          |
| Dominica                                     | DM           | ✅          |
| Dominican Republic                           | DO           | ✅          |
| Ecuador                                      | EC           | ✅          |
| Egypt                                        | EG           | ✅          |
| El Salvador                                  | SV           | ✅          |
| Equatorial Guinea                            | GQ           | ✅          |
| Eritrea                                      | ER           | ✅          |
| Estonia                                      | EE           | ✅          |
| Eswatini                                     | SZ           | ✅          |
| Ethiopia                                     | ET           | ✅          |
| Falkland Islands (Malvinas)                  | FK           | ✅          |
| Faroe Islands                                | FO           | ✅          |
| Fiji                                         | FJ           | ✅          |
| Finland                                      | FI           | ✅          |
| France                                       | FR           | ✅          |
| French Guiana                                | GF           | ✅          |
| French Polynesia                             | PF           | ✅          |
| French Southern Territories                  | TF           | ✅          |
| Gabon                                        | GA           | ✅          |
| Gambia                                       | GM           | ✅          |
| Georgia                                      | GE           | ✅          |
| Germany                                      | DE           | ✅          |
| Ghana                                        | GH           | ✅          |
| Gibraltar                                    | GI           | ✅          |
| Greece                                       | GR           | ✅          |
| Greenland                                    | GL           | ✅          |
| Grenada                                      | GD           | ✅          |
| Guadeloupe                                   | GP           | ✅          |
| Guam                                         | GU           | ✅          |
| Guatemala                                    | GT           | ✅          |
| Guernsey                                     | GG           | ✅          |
| Guinea                                       | GN           | ✅          |
| Guinea-Bissau                                | GW           | ❌          |
| Guyana                                       | GY           | ✅          |
| Haiti                                        | HT           | ✅          |
| Heard Island and McDonald Islands            | HM           | ✅          |
| Honduras                                     | HN           | ✅          |
| Hong Kong                                    | HK           | ✅          |
| Hungary                                      | HU           | ✅          |
| Iceland                                      | IS           | ✅          |
| India                                        | IN           | ✅          |
| Indonesia                                    | ID           | ✅          |
| Iran                                         | IR           | ❌          |
| Iraq                                         | IQ           | ❌          |
| Ireland                                      | IE           | ✅          |
| Isle of Man                                  | IM           | ✅          |
| Israel                                       | IL           | ✅          |
| Italy                                        | IT           | ✅          |
| Jamaica                                      | JM           | ✅          |
| Japan                                        | JP           | ✅          |
| Jersey                                       | JE           | ✅          |
| Jordan                                       | JO           | ✅          |
| Kazakhstan                                   | KZ           | ✅          |
| Kenya                                        | KE           | ✅          |
| Kiribati                                     | KI           | ✅          |
| Korea, Democratic People's Republic of       | KP           | ❌          |
| Korea, Republic of                           | KR           | ✅          |
| Kuwait                                       | KW           | ✅          |
| Kyrgyzstan                                   | KG           | ✅          |
| Laos                                         | LA           | ❌          |
| Latvia                                       | LV           | ✅          |
| Lebanon                                      | LB           | ✅          |
| Lesotho                                      | LS           | ✅          |
| Liberia                                      | LR           | ✅          |
| Libya                                        | LY           | ❌          |
| Liechtenstein                                | LI           | ✅          |
| Lithuania                                    | LT           | ✅          |
| Luxembourg                                   | LU           | ✅          |
| Macao                                        | MO           | ✅          |
| Madagascar                                   | MG           | ✅          |
| Malawi                                       | MW           | ✅          |
| Malaysia                                     | MY           | ✅          |
| Maldives                                     | MV           | ✅          |
| Mali                                         | ML           | ❌          |
| Malta                                        | MT           | ✅          |
| Marshall Islands                             | MH           | ✅          |
| Martinique                                   | MQ           | ✅          |
| Mauritania                                   | MR           | ✅          |
| Mauritius                                    | MU           | ✅          |
| Mayotte                                      | YT           | ✅          |
| Mexico                                       | MX           | ✅          |
| Micronesia                                   | FM           | ✅          |
| Moldova                                      | MD           | ✅          |
| Monaco                                       | MC           | ✅          |
| Mongolia                                     | MN           | ✅          |
| Montenegro                                   | ME           | ✅          |
| Montserrat                                   | MS           | ✅          |
| Morocco                                      | MA           | ✅          |
| Mozambique                                   | MZ           | ✅          |
| Myanmar                                      | MM           | ❌          |
| Namibia                                      | NA           | ✅          |
| Nauru                                        | NR           | ✅          |
| Nepal                                        | NP           | ✅          |
| Netherlands                                  | NL           | ✅          |
| New Caledonia                                | NC           | ✅          |
| New Zealand                                  | NZ           | ✅          |
| Nicaragua                                    | NI           | ✅          |
| Niger                                        | NE           | ✅          |
| Nigeria                                      | NG           | ✅          |
| Niue                                         | NU           | ✅          |
| Norfolk Island                               | NF           | ✅          |
| Northern Mariana Islands                     | MP           | ✅          |
| Norway                                       | NO           | ✅          |
| Oman                                         | OM           | ✅          |
| Pakistan                                     | PK           | ✅          |
| Palau                                        | PW           | ✅          |
| Palestine, State of                          | PS           | ✅          |
| Panama                                       | PA           | ✅          |
| Papua New Guinea                             | PG           | ✅          |
| Paraguay                                     | PY           | ✅          |
| Peru                                         | PE           | ✅          |
| Philippines                                  | PH           | ✅          |
| Pitcairn                                     | PN           | ✅          |
| Poland                                       | PL           | ✅          |
| Portugal                                     | PT           | ✅          |
| Puerto Rico                                  | PR           | ✅          |
| Qatar                                        | QA           | ✅          |
| Republic of North Macedonia                  | MK           | ✅          |
| Romania                                      | RO           | ✅          |
| Russia                                       | RU           | ❌          |
| Rwanda                                       | RW           | ✅          |
| Reunion                                      | RE           | ✅          |
| Saint Barthélemy                             | BL           | ✅          |
| Saint Helena, Ascension and Tristan da Cunha | SH           | ✅          |
| Saint Kitts and Nevis                        | KN           | ✅          |
| Saint Lucia                                  | LC           | ✅          |
| Saint Martin (French part)                   | MF           | ✅          |
| Saint Pierre and Miquelon                    | PM           | ✅          |
| Saint Vincent and the Grenadines             | VC           | ✅          |
| Samoa                                        | WS           | ✅          |
| San Marino                                   | SM           | ✅          |
| Sao Tome and Principe                        | ST           | ✅          |
| Saudi Arabia                                 | SA           | ✅          |
| Senegal                                      | SN           | ✅          |
| Serbia                                       | RS           | ✅          |
| Seychelles                                   | SC           | ✅          |
| Sierra Leone                                 | SL           | ✅          |
| Singapore                                    | SG           | ✅          |
| Sint Maarten (Dutch part)                    | SX           | ✅          |
| Slovakia                                     | SK           | ✅          |
| Slovenia                                     | SI           | ✅          |
| Solomon Islands                              | SB           | ✅          |
| Somalia                                      | SO           | ❌          |
| South Africa                                 | ZA           | ✅          |
| South Georgia and the South Sandwich Islands | GS           | ✅          |
| South Sudan                                  | SS           | ❌          |
| Spain                                        | ES           | ✅          |
| Sri Lanka                                    | LK           | ✅          |
| Sudan                                        | SD           | ❌          |
| Suriname                                     | SR           | ✅          |
| Svalbard and Jan Mayen                       | SJ           | ✅          |
| Sweden                                       | SE           | ✅          |
| Switzerland                                  | CH           | ✅          |
| Syrian Arab Republic                         | SY           | ❌          |
| Taiwan                                       | TW           | ✅          |
| Tajikistan                                   | TJ           | ✅          |
| Tanzania, United Republic of                 | TZ           | ✅          |
| Thailand                                     | TH           | ✅          |
| Timor-Leste                                  | TL           | ✅          |
| Togo                                         | TG           | ✅          |
| Tokelau                                      | TK           | ✅          |
| Tonga                                        | TO           | ✅          |
| Trinidad and Tobago                          | TT           | ✅          |
| Tunisia                                      | TN           | ✅          |
| Turkey                                       | TR           | ✅          |
| Turkmenistan                                 | TM           | ✅          |
| Turks and Caicos Islands                     | TC           | ✅          |
| Tuvalu                                       | TV           | ✅          |
| Uganda                                       | UG           | ✅          |
| Ukraine                                      | UA           | ❌          |
| United Arab Emirates                         | AE           | ✅          |
| United Kingdom                               | GB           | ✅          |
| United States of America                     | US           | ✅          |
| United States Minor Outlying Islands         | UM           | ✅          |
| Uruguay                                      | UY           | ✅          |
| Uzbekistan                                   | UZ           | ✅          |
| Vanuatu                                      | VU           | ✅          |
| Venezuela                                    | VE           | ❌          |
| Vietnam                                      | VN           | ✅          |
| Virgin Islands, British                      | VG           | ✅          |
| Virgin Islands, U.S.                         | VI           | ✅          |
| Wallis and Futuna                            | WF           | ✅          |
| Western Sahara                               | EH           | ✅          |
| Yemen                                        | YE           | ❌          |
| Zambia                                       | ZM           | ✅          |
| Zimbabwe                                     | ZW           | ✅          |
| Aland Islands                                | AX           | ✅          |


# Travel Rule Requirements
Source: https://developers.circle.com/cpn/references/compliance/travel-rule-requirements



Travel rule information is required during payment creation to provide
appropriate regulatory information to the BFI. The following sections outline
the required data that must be securely transmitted to the BFI when a payment is
created. See [JSON Schema](/cpn/concepts/api/json-schema) for more information
on how to validate your API response to the travel rule requirements.

<Note>
  **Note:** Depending on the geography of the payment route, additional travel
  rule information may be required to initiate the payment. This additional data
  are specified in the data object returned by the [payment creation
  endpoint](/api-reference/cpn/cpn-platform/create-payment).
</Note>

## OFI

| Field                                      | Description            |
| ------------------------------------------ | ---------------------- |
| `ORIGINATOR_FINANCIAL_INSTITUTION_NAME`    | OFI's business name    |
| `ORIGINATOR_FINANCIAL_INSTITUTION_ADDRESS` | OFI's business address |

## Individual

| Field                                        | Description                                                                                                             |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `ORIGINATOR_NAME`                            | Sender's full name                                                                                                      |
| `ORIGINATOR_ACCOUNT_NUMBER`                  | Sender's account number reference (originator's wallet address or account number for an OFI virtual or funding account) |
| `ORIGINATOR_ADDRESS`                         | Sender's address                                                                                                        |
| `ORIGINATOR_DATE_OF_BIRTH`                   | Sender's date of birth                                                                                                  |
| `ORIGINATOR_NATIONALITY`                     | Sender's nationality                                                                                                    |
| `ORIGINATOR_NATIONAL_IDENTIFICATION_NUMBER`  | Sender's national ID or passport number                                                                                 |
| `BENEFICIARY_NAME`                           | Recipient's full name                                                                                                   |
| `BENEFICIARY_ADDRESS`                        | Recipient's address                                                                                                     |
| `BENEFICIARY_DATE_OF_BIRTH`                  | Recipient's date of birth                                                                                               |
| `BENEFICIARY_NATIONALITY`                    | Recipient's nationality                                                                                                 |
| `BENEFICIARY_NATIONAL_IDENTIFICATION_NUMBER` | Recipient's national ID or passport number                                                                              |

## Business

| Field                                        | Description                                                                                                             |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `ORIGINATOR_NAME`                            | Sender's legal registered business name                                                                                 |
| `ORIGINATOR_ACCOUNT_NUMBER`                  | Sender's account number reference (originator's wallet address or account number for an OFI virtual or funding account) |
| `ORIGINATOR_ADDRESS`                         | Sender's registered place of business                                                                                   |
| `ORIGINATOR_DATE_OF_FORMATION`               | Sender's date of company formation                                                                                      |
| `ORIGINATOR_COUNTRY_OF_FORMATION`            | Sender's country where the entity was formed                                                                            |
| `ORIGINATOR_NATIONAL_IDENTIFICATION_NUMBER`  | Sender's business registration or tax ID                                                                                |
| `BENEFICIARY_NAME`                           | Recipient's legal registered business name                                                                              |
| `BENEFICIARY_ADDRESS`                        | Recipient's registered place of business                                                                                |
| `BENEFICIARY_DATE_OF_FORMATION`              | Recipient's date of company formation                                                                                   |
| `BENEFICIARY_COUNTRY_OF_FORMATION`           | Recipient's country where the entity was formed                                                                         |
| `BENEFICIARY_NATIONAL_IDENTIFICATION_NUMBER` | Recipient's business registration or tax ID                                                                             |


# Validating Brazilian Tax ID and Bank Account Numbers
Source: https://developers.circle.com/cpn/references/compliance/validating-brazil-tax-account-id



When providing beneficiary account data during payment creation or during RFIs,
OFIs may need to submit tax IDs or bank account numbers that follow a specific
format. You can often validate these numbers by calculating their check digits.
This topic describes how to checksum various account and tax ID numbers.

## CNPJ

The CNPJ number is a 14 digit number in the following format:

* First 8 digits: base number
* Digits 9-12: branch number
* Last 2 digits: check digits

CNPJ numbers are never all the same digit.

The check digits are calculated in a specific way that you can replicate to
validate the number.

### First check digit

You can calculate the first check digit (digit 13) of a CNPJ number as follows:

1. Multiply the first 12 digits by the following weights, according to their
   position: `5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2`
2. Sum the products
3. Calculate the remainder of the sum divided by `11`
4. If the remainder is less than `2`, the check digit is `0`
5. Otherwise, the check digit is `11 - {remainder}`

### Second check digit

You can calculate the second check digit (digit 14) of a CNPJ number as follows:

1. Multiply the first 13 digits by the following weights, according to their
   position: `6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2`
2. Sum the products
3. Calculate the remainder of the sum divided by `11`
4. If the remainder is less than `2`, the check digit is `0`
5. Otherwise, the check digit is `11 - {remainder}`

### Example

The following is an example of validating the CNPJ number `11.444.777/0001-61`:

**First digit**

* Weighting and sum:
  `((1*5 + 1*4 + 4*3 + 4*2 + 4*9 + 7*8 + 7*7 + 7*6 + 0*5 + 0*4 + 0*3 + 1*2) = 162)`
* Remainder and check digit: `(11 - (184 % 11) = 1)` (matches 13th digit)

**Second digit**

* Weighting and sum:
  `((1*6 + 1*5 + 4*4 + 4*3 + 4*2 + 7*9 + 7*8 + 7*7 + 0*6 + 0*5 + 0*4 + 1*3 + 6*2) = 184)`
* Remainder and check digit: `(11 - (184 % 11) = 1)` (matches 14th digit)

## CPF

The CPF number is an 11 digit number that is not all the same digit. The 10th
and 11th digits are check digits. The check digits are calculated in a specific
way that you can replicate to validate the number.

### First check digit

You can calculate the first check digit (digit 10) of a CPF number as follows:

1. Multiply the first 9 digits by the following weights, according to their
   position: `10, 9, 8, 7, 6, 5, 4, 3, 2`
2. Sum the products
3. Calculate the remainder of the sum divided by `11`
4. If the remainder is less than `2`, the check digit is `0`
5. Otherwise, the check digit is `11 - {remainder}`

### Second check digit

You can calculate the second check digit (digit 11) of a CPF number as follows:

1. Multiply the first 10 digits by the following weights, according to their
   position: `11, 10, 9, 8, 7, 6, 5, 4, 3, 2`
2. Sum the products
3. Calculate the remainder of the sum divided by `11`
4. If the remainder is less than 2, the check digit is `0`
5. Otherwise, the check digit is `11 - {remainder}`

### Example

The following is an example of validating the CPF number `529.982.247-25`:

**First digit**

* Weighting and sum:
  `((5*10 + 2*9 + 9*8 + 9*7 + 8*6 + 2*5 + 2*4 + 4*3 + 7*2) = 295)`
* Remainder and check digit: `(11 - (295 % 11) = 2)` (matches 10th digit)

**Second digit**

* Weighting and sum:
  `((5*11 + 2*10 + 9*9 + 9*8 + 8*7 + 2*6 + 2*5 + 4*4 + 7*3 + 2*2) = 347)`
* Remainder and check digit: `(11 - (347 % 11) = 5)` (matches 11th digit)


# Error Codes
Source: https://developers.circle.com/cpn/references/errors/error-codes



When an error is encountered, CPN returns an error code and a message. The
sections below show an explanation of each error code returned by the API, and
steps to resolve (where possible).

## Common

| Status code | Error code | Detail                  | Description                                                                                                                                                                                                         |
| ----------- | ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `500`       | `-1`       | `UNKNOWN_ERROR`         | A generic response for errors that aren't properly handled.                                                                                                                                                         |
| `400`       | `2`        | `API_PARAMETER_INVALID` | API request was missing parameters or had incorrect parameter types.                                                                                                                                                |
| `403`       | `3`        | `FORBIDDEN`             | The client is recognized but does not have permission to access the resource.<br /><br />**Resolution:** Verify the IP allowlist for the API key has the correct permissions through your Circle representative.    |
| `401`       | `4`        | `UNAUTHORIZED`          | The client did not provide valid authentication credentials to access the resource.<br /><br />**Resolution:** Verify your API key was passed as a `Bearer` token in the `Authorization` header of the API request. |
| `404`       | `2`        | `RESOURCE_NOT_FOUND`    | The requested resource could not be found.                                                                                                                                                                          |
| `400`       | `2900000`  | `INVALID_TENANCY_ENV`   | The parameter and the environment of the API call doesn't match (for example, a testnet chain in the production environment).<br /><br />**Resolution:** Update the request body to use the correct parameters.     |

## Quote

| Status code | Error code | Detail                 | Description                                                                                                                                                                                                                                                                                                                                            |
| ----------- | ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`       | `290100`   | `AMOUNT_OUTSIDE_LIMIT` | The provided amount does not fall in the supported range. It either exceeds the `cryptoLimit` or `fiatLimit`.<br /><br />**Resolution:** Make a request to the [configuration endpoint](/api-reference/cpn/cpn-platform/get-payment-configurations-overview) to determine supported combinations and try your request again with different parameters. |
| `400`       | `290101`   | `BFI_NOT_AVAILABLE`    | Only one BFI services the requested route and that service is unavailable.<br /><br />**Resolution:** Retry your request at a later time.                                                                                                                                                                                                              |
| `400`       | `290102`   | `ROUTE_NOT_SUPPORTED`  | The route includes unsupported countries.<br /><br />**Resolution:** Make a request to the [configuration endpoint](/api-reference/cpn/cpn-platform/get-payment-configurations-overview) to determine supported combinations and try your request again with different parameters.                                                                     |

## Payment

| Status code | Error code | Detail                              | Description                                                                                                                                                                                                   |
| ----------- | ---------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | `290200`   | `QUOTE_NOT_FOUND`                   | The provided quote ID can't be found.<br /><br />**Resolution:** Verify the quote ID is correct and make a new API request.                                                                                   |
| `400`       | `290201`   | `QUOTE_ALREADY_IN_USE`              | The provide quote ID has been used to create another payment.<br /><br />**Resolution:** Request a new quote and use it to create your payment.                                                               |
| `400`       | `290202`   | `QUOTE_EXPIRED`                     | The quote used to request payment creation is expired.<br /><br />**Resolution:** Request a new quote and use it to create your payment.                                                                      |
| `400`       | `290203`   | `INVALID_SENDER_ADDRESS_BLOCKCHAIN` | The blockchain associated with `senderAddress` does not match the requested blockchain from the quote.<br /><br />**Resolution:** Use the same blockchain in the payment request body as the `senderAddress`. |
| `400`       | `290204`   | `SANCTIONED_SENDER_WALLET_ADDRESS`  | The provided wallet address is on sanctioned lists.                                                                                                                                                           |
| `400`       | `290205`   | `PENDING_RFI_VERIFICATION`          | An RFI was requested for the sender or recipient so the payment can't be created.<br /><br />**Resolution:** Complete the RFI for the requested information before creating another payment.                  |
| `400`       | `290206`   | `RFI_REJECTED`                      | The given sender or receiver has a rejected RFI with the given BFI and the payment can't be completed.                                                                                                        |
| `400`       | `290207`   | `REQUIRED_PARAMETER_MISSING`        | A required parameter is missing in the request data.<br /><br />**Resolution:** Check the error in the response and make a new request with the missing parameter.                                            |
| `400`       | `290208`   | `COMPLIANCE_INFORMATION_REJECTED`   | The compliance information provided was rejected.                                                                                                                                                             |

## Transaction

| Status code | Error code | Detail                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------- | ---------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | `290300`   | `ACTIVE_TRANSACTION_ALREADY_EXISTS`                 | The payment already has an associated active or complete transaction.<br /><br />**Resolution:** For payments with an existing active transaction, sign and submit the transaction instead of attempting to create a new one.                                                                                                                                                                                                                      |
| `400`       | `290301`   | `BLOCKCHAIN_UNSUPPORTED`                            | The sender address blockchain is not supported by CPN for creating transactions.<br /><br />**Resolution:** Use the blockchain indicated in the quote.                                                                                                                                                                                                                                                                                             |
| `400`       | `290302`   | `BLOCKCHAIN_UNSUPPORTED_FOR_V2`                     | The blockchain is not support for Transactions V2.<br /><br />**Resolution:** See [supported blockchains](/cpn/references/blockchains/supported-blockchains) for the complete list of supported blockchains.                                                                                                                                                                                                                                       |
| `400`       | `290303`   | `INVALID_TRANSACTION_STATUS_FOR_SUBMISSION`         | The transaction provided is not in a submittable status.<br /><br />**Resolution:** Only submit a transaction when it is in the `CREATED` state.                                                                                                                                                                                                                                                                                                   |
| `400`       | `290304`   | `INVALID_PAYMENT_STATUS`                            | The transaction can't be submitted due to an invalid payment state.<br /><br />**Resolution:** Only submit a transaction when the payment is in the `CRYPTO_FUNDS_PENDING` state.                                                                                                                                                                                                                                                                  |
| `400`       | `290305`   | `PAYMENT_NOT_FOUND`                                 | The payment ID provided in the request was not found.                                                                                                                                                                                                                                                                                                                                                                                              |
| `400`       | `290306`   | `TRANSACTION_NOT_FOUND`                             | The transaction provided by the resource ID in the path was not found.                                                                                                                                                                                                                                                                                                                                                                             |
| `400`       | `290307`   | `SIGNED_TRANSACTION_SUBMITTED`                      | A signed transaction for the payment has already been submitted.<br /><br />**Resolution:** Wait for the transaction to reach a terminal state.                                                                                                                                                                                                                                                                                                    |
| `400`       | `290308`   | `PAYMENT_EXPIRED`                                   | The payment is expired.<br /><br />**Resolution:** Request a new quote, then create a new payment and submit the transaction in the appropriate time frame.                                                                                                                                                                                                                                                                                        |
| `400`       | `290309`   | `SIGNED_TRANSACTION_EXPIRED`                        | The signed transaction is expired. Solana requires that you submit signed transactions in 150 blocks (\~1 min) of signing them.<br /><br />**Resolution:** Create a new transaction for the same payment and sign and submit it in the appropriate time frame.                                                                                                                                                                                     |
| `400`       | `290310`   | `NONCE_TOO_LOW`                                     | The nonce for the signed transaction is lower than the current wallet nonce.<br /><br />**Resolution:** Resubmit the signed transaction with the current wallet nonce.                                                                                                                                                                                                                                                                             |
| `400`       | `290311`   | `SIGNED_TRANSACTION_PAYLOAD_MISMATCH`               | The signed transaction payload does not match the CPN payment. For EVM chains, the EIP-3009 typed data must match the value in the `messageToBeSigned` field returned from the [create transaction endpoint](/api-reference/cpn/cpn-platform/create-transaction). For Solana, the signed transaction object must match the value from the `messageToBeSigned` field.<br /><br />**Resolution:** Resubmit the transaction with the correct payload. |
| `400`       | `290312`   | `INSUFFICIENT_TOKEN_BALANCE`                        | The sender's wallet does not have enough USDC to complete the transfer.<br /><br />**Resolution:** Add USDC to the wallet and resubmit the signed transaction.                                                                                                                                                                                                                                                                                     |
| `400`       | `290313`   | `INSUFFICIENT_GAS_BALANCE`                          | The sender's wallet does not have enough native tokens to cover the gas cost of the transaction.<br /><br />**Resolution:** Add native tokens to the wallet and resubmit the signed transaction.                                                                                                                                                                                                                                                   |
| `400`       | `290314`   | `PAYMENT_ID_MISMATCH`                               | The payment ID provided in the signed data does not match the expected value.                                                                                                                                                                                                                                                                                                                                                                      |
| `400`       | `290315`   | `GAS_PRICE_TOO_LOW`                                 | The gas price in the signed transaction is below network thresholds. The fee must exceed the estimated high fee to ensure prompt confirmation.<br /><br />**Resolution:** Sign the transaction with a higher gas price and resubmit.                                                                                                                                                                                                               |
| `400`       | `290316`   | `NONCE_MISMATCH`                                    | When resubmitting the transaction, the wallet address or nonce does not match the original submission.<br /><br />Sign the transaction with the same wallet and nonce as the previous transaction and resubmit.                                                                                                                                                                                                                                    |
| `500`       | `290317`   | `FULL_NODE_SERVICE_UNAVAILABLE`                     | The full node used by CPN is unavailable or returning an unexpected error during transaction validation.<br /><br />**Resolution:** Submit the signed transaction at a later time.                                                                                                                                                                                                                                                                 |
| `400`       | `290318`   | `PAYMENT_REF_ID_ONCHAIN`                            | The payment ref ID has already been used onchain. The signed transaction may have been rebroadcast prior to submission to CPN.<br /><br />**Resolution:** Contact Circle customer support to reconcile the transaction.                                                                                                                                                                                                                            |
| `400`       | `290319`   | `OUT_OF_GAS`                                        | For EVM chains, the gas limit in the signed transaction is insufficient to cover the execution costs. For Solana, the allocated compute budget falls short of the transaction's requirements, preventing execution.<br /><br />**Resolution:** For EVM chains, increase the gas limit. For Solana, increase the compute budget. Create a new transaction for the same payment and sign and submit it.                                              |
| `400`       | `290320`   | `NONCE_ALREADY_USED`                                | The nonce has already been used by the same sender in another signed transaction submission.<br /><br />**Resolution:** Resubmit the signed transaction using the next available nonce.                                                                                                                                                                                                                                                            |
| `400`       | `290321`   | `INVALID_TRANSACTION_SIGNATURE`                     | The transaction signature is invalid.<br /><br />**Resolution:** Review the guidelines for signing a transaction and try again with updated signing functions.                                                                                                                                                                                                                                                                                     |
| `400`       | `290322`   | `SANCTIONED_WALLET_ADDRESS`                         | The wallet address used is on a sanction list.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `400`       | `290324`   | `CROSS_CHAIN_UNSUPPORTED`                           | The crosschain transfer is not supported by CPN.<br /><br />**Resolution:** Make a request to the [configuration endpoint](/api-reference/cpn/cpn-platform/get-payment-configurations-overview) to determine supported combinations and try your request again with different parameters.                                                                                                                                                          |
| `400`       | `290325`   | `COMPLETED_TRANSACTION_EXISTS`                      | A completed transaction already exists. No need to accelerate.                                                                                                                                                                                                                                                                                                                                                                                     |
| `400`       | `290327`   | `INVALID_SIGNED_TX`                                 | The signed transaction can't be decoded or is otherwise invalid.<br /><br />**Resolution:** Review the guidelines for signing a transaction and try again with updated signing functions.                                                                                                                                                                                                                                                          |
| `400`       | `290328`   | `ONCHAIN_ACCOUNT_NOT_FOUND`                         | The Solana account specified in the transaction is not found.<br /><br />**Resolution:** Ensure the Solana account has been initialized before using it as the sender address for the transaction.                                                                                                                                                                                                                                                 |
| `400`       | `290329`   | `TRANSACTION_EXPIRED`                               | The transaction is expired.<br /><br />**Resolution:** Create a new transaction and submit it in the appropriate time frame.                                                                                                                                                                                                                                                                                                                       |
| `400`       | `290330`   | `CREATED_PENDING_TRANSACTION_EXIST_AT_ACCELERATION` | The existing transaction is not signed or submitted yet before the current attempt to accelerate it.<br /><br />**Resolution:** Sign the existing transaction or wait for the signed transaction to be broadcast.                                                                                                                                                                                                                                  |
| `400`       | `290331`   | `NO_TRANSACTION_TO_ACCELERATE`                      | No broadcast transaction to be accelerated.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `400`       | `290332`   | `ONCHAIN_ACCOUNT_INVALID`                           | An invalid Solana address was used to create the transaction.<br /><br />**Resolution:** Verify the sender account provided in the request is a valid Solana address capable of signing and sending transactions. Don't use system accounts or program accounts. Resubmit the request using a valid Solana account.                                                                                                                                |
| `400`       | `290333`   | `BROADCASTING_IN_PROGRESS`                          | A submitted transaction is already in a non-terminal state.<br /><br />**Resolution:** Wait for the result.                                                                                                                                                                                                                                                                                                                                        |
| `400`       | `290334`   | `NONCE_TOO_HIGH`                                    | The transaction nonce exceeds the permitted range relative to the current nonce.<br /><br />**Resolution:** Check your wallets latest nonce and make sure the nonce selected for your transaction does not exceed that value by more than 32. If you are sending multiple concurrent transactions for multiple payments, try waiting for the previous few transactions to settle.                                                                  |
| `400`       | `290336`   | `INCOMPATIBLE_QUOTE`                                | The quote is incompatible with the specified transaction. Quotes created with V1 transactions must proceed with V1 transaction endpoints, similarly with quotes created with V2 transactions.<br /><br />**Resolution:** Make sure the `transactionVersion` specified in the [endpoint response](/api-reference/cpn/cpn-platform/create-quotes) is consistent with the transaction flow you are using.                                             |
| `400`       | `290337`   | `PAYMENT_MISSING_BLOCKCHAIN_ADDRESS`                | The payment is missing the sender blockchain address.<br /><br />**Resolution:** Make sure you [create the payment](/api-reference/cpn/cpn-platform/create-payment) with `blockchain` and `senderAddress`.                                                                                                                                                                                                                                         |
| `400`       | `290340`   | `INSUFFICIENT_ALLOWANCE_TO_PERMIT2`                 | The ERC-20 allowance granted to the `Permit2` contract is insufficient to cover the total required token amount for the payment, including both the payment amount and associated fees.<br /><br />**Resolution:** With your sender wallet, approve the `Permit2` contract to spend the required amount of USDC for the payment.                                                                                                                   |
| `400`       | `290341`   | `PERMIT2_NONCE_ALREADY_USED`                        | The `Permit2` nonce included in the typed data for the sender has already been used.<br /><br />**Resolution:** Create a new transaction for the same payment with the same sender address, then sign and submit it.                                                                                                                                                                                                                               |

## RFI

| Status code | Error code | Detail                       | Description                                                                                                                                                                                                                           |
| ----------- | ---------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | `290400`   | `RFI_EXPIRED`                | The RFI has expired; you can't submit data to an expired resource.<br /><br />**Resolution:** Create a new payment for the user and complete a new RFI.                                                                               |
| `400`       | `290401`   | `RFI_NOT_SUBMITTABLE`        | Requirement data submissions are limited to RFIs with the `INFORMATION_REQUIRED` status. Submission for an RFI in any other status results in this error code.                                                                        |
| `400`       | `290402`   | `RFI_FILE_NOT_FOUND`         | The uploaded filename does not match the file input name specified in the request for information.<br /><br />**Resolution:** Ensure the correct files are uploaded and that the file names exactly match those specified in the RFI. |
| `400`       | `290403`   | `RFI_FILE_INVALID_CONTENT`   | The server was unable to read the content of the uploaded file.<br /><br />**Resolution:** Ensure the uploaded file contains content in a compatible format that can be processed by the CPN server.                                  |
| `400`       | `290404`   | `RFI_FILE_CONTENT_TOO_LARGE` | The size of the uploaded file exceeds the maximum allowed size. <br /><br />**Resolution:** Ensure that the uploaded file does not exceed the 10 MB.                                                                                  |
| `400`       | `290405`   | `RFI_UNSUPPORTED_FILE_TYPE`  | The MIME type of the uploaded file is not supported.<br /><br />**Resolution:** Ensure that the uploaded file has a MIME type accepted by the file upload endpoint.                                                                   |

## Encryption

| Status code | Error code | Detail                             | Description                                                                                                                                                                                                               |
| ----------- | ---------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | `290500`   | `ENCRYPTED_BLOB_DECRYPTION_ERROR`  | The decryption process failed.<br /><br />**Resolution:** Ensure the correct public key was used to encrypt the payload.                                                                                                  |
| `400`       | `290502`   | `INVALID_JWE_FORMAT`               | The JWE compact payload is not formatted correctly or is missing required components.<br /><br />**Resolution:** Ensure you're using a standard library for encrypting the payload and sending in the JWE compact format. |
| `400`       | `290503`   | `UNSUPPORTED_ENCRYPTION_ALGORITHM` | The JWE compact payload was not encrypted with a supported algorithm.<br /><br />**Resolution:** Ensure your encryption function is correctly implementing the appropriate algorithms and resubmit.                       |

## Support ticket

| Status code | Error code | Detail                                      | Description                                                                                                      |
| ----------- | ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `400`       | `290600`   | `TICKET_REFERENCE_REQUIRED`                 | Ticket reference ID is required for escalation.                                                                  |
| `404`       | `290601`   | `ORIGINAL_TICKET_NOT_FOUND`                 | The original ticket was not found with the provided reference ID.                                                |
| `400`       | `290602`   | `INVALID_SUPPORT_TICKET_ISSUE_TYPE`         | Issue type is not allowed for this origin.<br /><br />**Resolution:** Ensure the correct issue type is provided. |
| `404`       | `290603`   | `PAYMENT_NOT_FOUND_FOR_TICKET`              | The payment ID provided was not found.                                                                           |
| `500`       | `290604`   | `SUPPORT_TICKET_SALESFORCE_CREATION_FAILED` | Failed to create a ticket in Circle Salesforce.<br /><br />**Resolution:** Try again at a later time.            |
| `500`       | `290605`   | `SUPPORT_TICKET_BFI_CREATION_FAILED`        | Failed to create a BFI support ticket.<br /><br />**Resolution:** Try again at a later time.                     |


# Payment and Transaction Failure Reasons
Source: https://developers.circle.com/cpn/references/errors/payment-and-transaction-failure-reasons



When payments or transactions fail, you'll receive an object containing the
failure reason. Depending on when the failure occurs, this information is
returned in the synchronous (API) or asynchronous (webhook) response. The
following sections outline the reasons that each of these components might fail.

## Payments

When a payment fails in CPN there are no further actions you can take with that
payment ID. You should restart the payment workflow by requesting a new quote
and accepting it to create a new payment.

The payment failure notification includes a failure reason (listed below) and a
[failure code](/cpn/references/errors/payment-failure-codes) containing more
specific information about the failure. The failure code provides information
about how to resolve the issue and create a new payment.

| Failure reason              | Description                                                                   |
| --------------------------- | ----------------------------------------------------------------------------- |
| `TRAVEL_RULE_FAILED`        | The travel rule information included with the payment was rejected            |
| `BANK_VERIFICATION_FAILED`  | The bank information included with the payment was rejected                   |
| `RFI_VERIFICATION_FAILED`   | The payment failed due to issues related to RFI handling or verification      |
| `EXISTING_RFI_PENDING`      | An RFI exists on the customer in a non-terminal state                         |
| `ONCHAIN_SETTLEMENT_FAILED` | The payment couldn't be processed due to an issue with the onchain settlement |
| `FIAT_SETTLEMENT_FAILED`    | The payment couldn't be completed due to routing or bank settlement issues    |
| `COMPLIANCE_CHECK_FAILED`   | The payment was rejected due a compliance check failure                       |
| `CANCELLED`                 | The payment is canceled by the originator                                     |
| `PAYMENT_EXPIRED`           | The payment is expired and not able to provide further action.                |
| `OTHER`                     | General payment failure not covered by other reasons                          |

## Transactions

If an onchain transaction fails or becomes stuck, you can create a new
transaction or attempt to replace or accelerate the transaction. You may
continue to troubleshoot onchain transactions until the payment expires. Note
that only one transaction can be associated with a given payment, so you must
wait until the current transaction fails or attempt to replace it if you need to
update the transaction.

| Failure reason               | Description                                                                                                                                                                                                                                                                                                 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CPN_PAYMENT_EXPIRED`        | The payment corresponding to this transaction is expired.<br /><br />**Resolution**: Create a new payment and ensure the onchain transaction is completed in its valid time frame.                                                                                                                          |
| `SIGNED_TRANSACTION_EXPIRED` | (Solana only) The signed transaction is expired. Solana requires you to submit a signed transaction in 150 blocks (\~1 min).<br /><br />**Resolution:** Initiate a new transaction and submit it in the appropriate time frame.                                                                             |
| `NONCE_TOO_LOW`              | The nonce of the signed transaction is lower than the current wallet nonce.<br /><br />**Resolution:** Submit a new transaction using the latest nonce value for the wallet.                                                                                                                                |
| `INSUFFICIENT_GAS_BALANCE`   | Not enough native tokens were available in the wallet to cover the gas fee for the transaction.<br /><br />**Resolution:** Fund the wallet with the appropriate amount of native tokens and initiate a new transaction.                                                                                     |
| `GAS_PRICE_TOO_LOW`          | The specified gas fee is too low, which may prevent the transaction from being included in a block.<br /><br />**Resolution:** Create a new transaction with a higher gas fee.                                                                                                                              |
| `INSUFFICIENT_TOKEN_BALANCE` | The wallet does not have enough USDC in it for the transfer amount.<br /><br />**Resolution:** Fund the wallet with the appropriate amount of USDC for the payment, then initiate a new transaction.                                                                                                        |
| `OUT_OF_GAS`                 | For EVM chains, the gas limit for the signed transaction is insufficient to cover the execution cost. For Solana, the allocated compute budget falls short of the transaction's requirements, preventing successful execution.<br /><br />**Resolution:** Create a new transaction with a higher gas limit. |
| `TX_REPLACEMENT_FAILED`      | The transaction replacement failed because another transaction with the same nonce (and higher fee) is already the mempool or was mined first.<br /><br />If the replacement fails, the original transaction submitted to the blockchain is still executed.                                                 |
| `SOL_TX_ALREADY_IN_CACHE`    | (Solana only) The transaction has already been broadcast and is present in the network's cache.<br /><br />**Resolution:** Wait for the current transaction's confirmation or failure before proceeding.                                                                                                    |
| `TX_ALREADY_CONFIRMED`       | The transaction was confirmed onchain before the current broadcast attempt.<br /><br />**Resolution:** If this was unexpected, open a support ticket for further investigation.                                                                                                                             |
| `FAILED_ONCHAIN`             | The transaction failed execution on the blockchain.<br /><br />**Resolution:** Review the onchain error, correct any issues, and submit a new transaction.                                                                                                                                                  |
| `SOL_BLOCKHASH_EXPIRED`      | (Solana only) The Solana blockhash assigned to the transaction has expired.<br /><br />**Resolution:** Initiate a new transaction.                                                                                                                                                                          |
| `TRANSACTION_EXPIRED`        | The transaction is expired and you aren't able to perform any further actions.<br /><br />**Resolution:** Initiate a new transaction.                                                                                                                                                                       |


# Payment Failure Codes
Source: https://developers.circle.com/cpn/references/errors/payment-failure-codes



When a payment fails, CPN provides a
[failure reason](/cpn/references/errors/payment-and-transaction-failure-reasons)
and a failure code. Depending on when the failure occurs, this information is
returned in the synchronous (API) or asynchronous (webhook) response. This
failure code can help you understand why the payment failed, and take
appropriate steps to resolve the issue. The following sections outline the
specific failure codes for failed payments.

## General

These codes apply when the failure reason is `OTHER`.

| Failure code | Description   |
| ------------ | ------------- |
| `PM00001`    | General error |

## Travel rule

These codes apply when the failure reason is `TRAVEL_RULE_FAILED`.

| Failure code | Description                                                                                                |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `PM01000`    | A general travel rule failure occurred during travel rule verification                                     |
| `PM01001`    | The originator address is missing data or doesn't meet required formatting or jurisdictional standards     |
| `PM01002`    | The beneficiary address is missing data or doesn't meet required formatting or jurisdictional standards    |
| `PM01003`    | The national ID or passport number provided for the originator is invalid, missing, or fails verification  |
| `PM01004`    | The national ID or passport number provided for the beneficiary is invalid, missing, or fails verification |

## Bank verification

These codes apply when the failure reason is `BANK_VERIFICATION_FAILED`.

| Failure code | Description                                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PM02000`    | General bank detail validation failure                                                                                                           |
| `PM02001`    | The beneficiary bank account details (SWIFT BIC, account alias, account number) are invalid, malformed, or not recognized by the bank or network |
| `PM02002`    | The beneficiary bank account details provided don't match the registered beneficiary in the bank's records                                       |
| `PM02003`    | The receiving bank isn't supported                                                                                                               |
| `PM02004`    | The specified account type (checking, savings) isn't supported                                                                                   |

## RFI verification

These codes apply when the failure reason is `RFI_VERIFICATION_FAILED`.

| Failure code | Description                                          |
| ------------ | ---------------------------------------------------- |
| `PM03000`    | General RFI verification failure                     |
| `PM03001`    | Missing or improperly formatted RFI documents        |
| `PM03002`    | Conflicting data in the RFI submission               |
| `PM03003`    | Expired or outdated RFI documents                    |
| `PM03004`    | Rejected after manual compliance review              |
| `PM03005`    | RFI response or review not completed in allowed time |

## Existing RFI pending

These codes apply when the failure reason is `EXISTING_RFI_PENDING`.

| Failure code | Description                                           |
| ------------ | ----------------------------------------------------- |
| `PM04000`    | An RFI exists on the customer in a non-terminal state |

## Onchain settlement

These codes apply when the failure reason is `ONCHAIN_SETTLEMENT_FAILED`.

| Failure code | Description                                                                     |
| ------------ | ------------------------------------------------------------------------------- |
| `PM05000`    | General onchain settlement failure                                              |
| `PM05001`    | Received funds are invalid (wrong asset, insufficient amount, wrong blockchain) |

## Fiat settlement

These codes apply when the failure reason is `FIAT_SETTLEMENT_FAILED`.

| Failure code | Description                                 |
| ------------ | ------------------------------------------- |
| `PM06000`    | General fiat settlement or payout failure   |
| `PM06001`    | Rejected by the receiving bank              |
| `PM06002`    | Rejected by the sending bank                |
| `PM06003`    | Destination account invalid or unregistered |
| `PM06004`    | Destination account blocked                 |

## Compliance check

These codes apply when the failure reason is `COMPLIANCE_CHECK_FAILED`.

| Failure code | Description                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------ |
| `PM07000`    | General compliance check failure                                                                             |
| `PM07001`    | Originator blocked or ineligible                                                                             |
| `PM07002`    | Beneficiary blocked or ineligible                                                                            |
| `PM07003`    | OFI compliance check failed.<br /><br />You may need to complete KYB before proceeding with further payments |
| `PM07004`    | The beneficiary bank account failed compliance checks                                                        |

## Canceled

These codes apply when the failure reason is `CANCELLED`.

| Failure code | Description                           |
| ------------ | ------------------------------------- |
| `PM08000`    | Funds were canceled by the originator |

## Payment expired

These codes apply when the failure reason is `PAYMENT_EXPIRED`.

| Failure code | Description                                           |
| ------------ | ----------------------------------------------------- |
| `PM09000`    | Crypto funds not received in the expected time window |


# Payment Reason Codes
Source: https://developers.circle.com/cpn/references/errors/payment-reason-codes



When you
[create a payment with the CPN API](/api-reference/cpn/cpn-platform/create-payment),
you should include a `reasonForPayment` code in the API request. Each code
provides a specific payment reason.

The following table outlines each code and the reason it represents.

| Reason code | Description                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `PMT001`    | Invoice payment                                                                                        |
| `PMT002`    | Payment for services                                                                                   |
| `PMT003`    | Payment for software                                                                                   |
| `PMT004`    | Payment for imported goods                                                                             |
| `PMT005`    | Travel services                                                                                        |
| `PMT006`    | Transfer to own account                                                                                |
| `PMT007`    | Repayment of loans                                                                                     |
| `PMT008`    | Payroll                                                                                                |
| `PMT009`    | Payment of property rental                                                                             |
| `PMT010`    | Information service charges                                                                            |
| `PMT011`    | Advertising and public relations related expenses                                                      |
| `PMT012`    | Royalty fees, trademark fees, patent fees, and copyright fees                                          |
| `PMT013`    | Fees for brokers, front end fee, commitment fee, guarantee fee, and custodian fee                      |
| `PMT014`    | Fees for advisors, technical assistance, and academic knowledge including remuneration for specialists |
| `PMT015`    | Representative office expenses                                                                         |
| `PMT016`    | Tax payment                                                                                            |
| `PMT017`    | Transportation fees for goods                                                                          |
| `PMT018`    | Construction costs/expenses                                                                            |
| `PMT019`    | Insurance premium                                                                                      |
| `PMT020`    | General goods trades (offline)                                                                         |
| `PMT021`    | Insurance claims payment                                                                               |
| `PMT022`    | Remittance payments to friends or family                                                               |
| `PMT023`    | Education-related student expenses                                                                     |
| `PMT024`    | Medical treatment                                                                                      |
| `PMT025`    | Donations                                                                                              |
| `PMT026`    | Mutual fund investment                                                                                 |
| `PMT027`    | Currency exchange                                                                                      |
| `PMT028`    | Advance payments for goods                                                                             |
| `PMT029`    | Merchant settlement                                                                                    |
| `PMT030`    | Repatriation fund settlement                                                                           |


# Supported Payment Methods
Source: https://developers.circle.com/cpn/references/payments/supported-payment-methods



CPN supports multiple payment methods for transferring funds to recipients in
different countries. The available payment methods depend on the destination
country and are determined by the payment rails available in that region.

You can discover available payment methods for specific routes using the
[configurations overview endpoint](/api-reference/cpn/cpn-platform/get-payment-configurations-overview)
or the [list routes endpoint](/api-reference/cpn/cpn-platform/list-routes).

<Note>
  **Note:** Payment method availability may vary based on your account
  configuration and the specific payment route. Always use the [list routes
  endpoint](/api-reference/cpn/cpn-platform/list-routes) to verify available
  payment methods for your specific use case.
</Note>

## Settlement times

Payment methods have different settlement characteristics:

* **Instant payments** (for example `PIX`, `SPEI`, `IMPS`): Typically settle in
  seconds to minutes
* **Batched payments** (for example `WIRE`, `CHATS`): May take 1-2 business days
  depending on the route

Actual settlement times are provided in the quote response via the
`fiatSettlementTime` field.

## Payment methods by region

The following sections detail payment methods available for specific destination
countries and regions.

### Argentina

| Payment Method | Currency | Description                              | Approximate Processing Time |
| -------------- | -------- | ---------------------------------------- | --------------------------- |
| `WIRE`         | USD      | Wire transfer for international payments | 1-2 business days           |

### Brazil

| Payment Method | Currency | Description                                                           | Approximate Processing Time |
| -------------- | -------- | --------------------------------------------------------------------- | --------------------------- |
| `PIX`          | BRL      | Brazil's instant payment system that enables real-time transfers 24/7 | 5 minutes                   |
| `WIRE`         | USD      | Wire transfer for international payments                              | 1-2 business days           |

### Chile

| Payment Method | Currency | Description                              | Approximate Processing Time |
| -------------- | -------- | ---------------------------------------- | --------------------------- |
| `WIRE`         | USD      | Wire transfer for international payments | 1-2 business days           |

### China

| Payment Method | Currency | Description                                                                   | Approximate Processing Time |
| -------------- | -------- | ----------------------------------------------------------------------------- | --------------------------- |
| `CIPS`         | CNY      | China's Cross-Border Interbank Payment System for international RMB transfers | 1-2 business days           |
| `WIRE`         | CNY, USD | Wire transfer for international payments                                      | 1-2 business days           |

### Colombia

| Payment Method  | Currency | Description                                                                        | Approximate Processing Time |
| --------------- | -------- | ---------------------------------------------------------------------------------- | --------------------------- |
| `BANK-TRANSFER` | COP      | Bank transfer for domestic payments in Colombia, processed through the ACH network | 1-2 business days           |
| `NEQUI`         | COP      | Colombia's digital wallet and instant payment system                               | 5 minutes                   |
| `WIRE`          | USD      | Wire transfer for international payments                                           | 1-2 business days           |

### European Union

| Payment Method | Currency | Description                                                    | Approximate Processing Time |
| -------------- | -------- | -------------------------------------------------------------- | --------------------------- |
| `WIRE`         | USD      | Wire transfer for international payments to European countries | 1-2 business days           |

<Note>
  **Note:** SEPA payments will attempt instant SEPA first, which delivers in
  minutes. If instant SEPA is not available for the transaction, it will fall
  back to regular SEPA, which takes 1 business day.
</Note>

<Note>
  **Note:** WIRE is available for the following countries: Andorra, Austria,
  Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland,
  France, Germany, Greece, Hungary, Ireland, Italy, Latvia, Liechtenstein,
  Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania,
  Slovakia, Slovenia, Spain, Sweden, Switzerland, and United Kingdom.
</Note>

### Hong Kong

| Payment Method | Currency | Description                                                                  | Approximate Processing Time |
| -------------- | -------- | ---------------------------------------------------------------------------- | --------------------------- |
| `CHATS`        | HKD, USD | Hong Kong's Clearing House Automated Transfer System for interbank transfers | Same day                    |
| `FPS`          | HKD      | Hong Kong's Faster Payment System for real-time payments                     | 5 minutes                   |
| `WIRE`         | HKD, USD | Wire transfer for international payments                                     | 1-2 business days           |

### India

| Payment Method | Currency | Description                                                              | Approximate Processing Time |
| -------------- | -------- | ------------------------------------------------------------------------ | --------------------------- |
| `IMPS`         | INR      | India's Immediate Payment Service for instant interbank transfers        | 5 minutes                   |
| `NEFT`         | INR      | India's National Electronic Funds Transfer for scheduled batch transfers | Same day                    |
| `RTGS`         | INR      | India's Real Time Gross Settlement for high-value transfers              | 5 minutes                   |

### Japan

| Payment Method | Currency | Description                              | Approximate Processing Time |
| -------------- | -------- | ---------------------------------------- | --------------------------- |
| `WIRE`         | USD      | Wire transfer for international payments | 1-2 business days           |

### Kenya

| Payment Method | Currency | Description                              | Approximate Processing Time |
| -------------- | -------- | ---------------------------------------- | --------------------------- |
| `WIRE`         | USD      | Wire transfer for international payments | 1-2 business days           |

### Mexico

| Payment Method | Currency | Description                                                              | Approximate Processing Time |
| -------------- | -------- | ------------------------------------------------------------------------ | --------------------------- |
| `SPEI`         | MXN      | Mexico's electronic interbank payment system operated by Banco de México | 5 minutes                   |
| `WIRE`         | USD      | Wire transfer for international payments                                 | 1-2 business days           |

### Nigeria

| Payment Method  | Currency | Description                                                                                                     | Approximate Processing Time |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `BANK-TRANSFER` | NGN      | Nigeria's NIBSS (Nigeria Inter-Bank Settlement System) instant payment system for real-time interbank transfers | 5 minutes                   |
| `WIRE`          | USD      | Wire transfer for international payments                                                                        | 1-2 business days           |

### Singapore

| Payment Method  | Currency | Description                                                                                                                                           | Approximate Processing Time |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `BANK-TRANSFER` | SGD      | Bank transfer for domestic payments in Singapore, may be processed through FAST (Fast And Secure Transfers) or MEPS RTGS (Real-Time Gross Settlement) | 30 minutes                  |
| `WIRE`          | USD      | Wire transfer for international payments                                                                                                              | 1-2 business days           |

### South Africa

| Payment Method | Currency | Description                              | Approximate Processing Time |
| -------------- | -------- | ---------------------------------------- | --------------------------- |
| `WIRE`         | USD      | Wire transfer for international payments | 1-2 business days           |

### South Korea

| Payment Method | Currency | Description                              | Approximate Processing Time |
| -------------- | -------- | ---------------------------------------- | --------------------------- |
| `WIRE`         | USD      | Wire transfer for international payments | 1-2 business days           |

### Taiwan

| Payment Method | Currency | Description                              | Approximate Processing Time |
| -------------- | -------- | ---------------------------------------- | --------------------------- |
| `WIRE`         | USD      | Wire transfer for international payments | 1-2 business days           |

### United States

| Payment Method | Currency | Description                                                       | Approximate Processing Time |
| -------------- | -------- | ----------------------------------------------------------------- | --------------------------- |
| `FEDWIRE`      | USD      | US Federal Reserve's wire transfer system for same-day settlement | Same day                    |

## Payment method characteristics

### Limits

Each payment method has minimum and maximum transfer limits that vary by:

* Destination country
* Destination currency
* Payment method type

Use the [list routes endpoint](/api-reference/cpn/cpn-platform/list-routes) to
retrieve specific limits for your payment route. When using V2 transactions,
pass `transactionVersion=VERSION_2` so returned crypto min limits include a
chain-specific buffer for fees (for example, gas fee), paid in USDC from the
source amount.


# Postman API Suite
Source: https://developers.circle.com/cpn/references/postman

Use Circle's Postman collection to send API requests and try CPN APIs.

Circle's Postman collection provides template requests to help you learn about
the Circle Payments Network APIs. These requests run on Postman, an API platform
for learning, building, and using APIs. The Postman CPN workspace includes a
collection that matches the organization of the
[API References](/api-reference/cpn/cpn-platform/get-payment-configurations-overview).

## Run in Postman

To use the Postman collection, click the **Run in Postman** link below. You can
fork the collection to your workspace, view the collection in the public
workspace, or import the collection into Postman.

* **Fork**: Creates a copy of the collection while maintaining a link to the
  parent.
* **View**: Allows you to quickly try out the API without importing anything
  into your Postman suite.
* **Import**: Creates a copy of the collection but does not maintain a link to
  Circle's copy.

| Collection | Link                                                                                                                                                                                                                                                                                                             |
| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CPN        | [Run in Postman](https://app.getpostman.com/run-collection/18225688-f1682adb-ab23-4e2d-b21d-a3562d879e5f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D18225688-f1682adb-ab23-4e2d-b21d-a3562d879e5f%26entityType%3Dcollection%26workspaceId%3D5d277774-3b09-4e2b-91f5-4253c25a48d0k) |

<Info>
  **Authorization**

  To authorize your session, use Circle's Postman variable `apiKey` and add your
  API key to the `environment` or `collection` variables. See Postman's
  [using variables](https://learning.postman.com/docs/sending-requests/variables/)
  for details.

  You can get an API key for CPN from the
  [CPN Console](https://cpn.circle.com/signin). Contact your Circle representative
  to get access to CPN.
</Info>


# Magic Values for Testing
Source: https://developers.circle.com/cpn/references/testing/magic-values



You can use specific values when you create a payment on testnet to get the CPN
API to return certain statuses. These magic values can be useful to test how
your integration handles specific states and situations of payments. Magic
values can be used in the sandbox environment.

The following sections outline the magic values you can pass to the sandbox API
and the effect that they have on the response from the API.

<Note>
  **Note:** All of the magic values listed in the following sections are case
  sensitive. The specified field must be set to the exact value in the table in
  order for them to work.
</Note>

## Create payment

You can test payments by providing magic values on the `ORIGINATOR_NAME` field
when making requests to the
[create a payment endpoint](/api-reference/cpn/cpn-platform/create-payment). The
following table outlines the magic values and their effects on the payment
response:

| Magic value                          | Response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Failed`                             | Synchronous payment failure. Payment is returned with the `FAILED` status in the synchronous response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `AsyncFailed`                        | Asynchronous payment failure. Payment is returned with the `CREATED` status in the synchronous response, followed by a webhook that updates the payment to the `FAILED` status.                                                                                                                                                                                                                                                                                                                                                                                               |
| `AsyncSuccess`                       | Asynchronous payment success. Payment is returned with the `CREATED` status in the synchronous response, followed by a webhook that updates the payment to the `CRYPTO_FUNDS_PENDING` status.                                                                                                                                                                                                                                                                                                                                                                                 |
| `CreateRfi`                          | Payment is returned with an active level 1 RFI in the synchronous response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `CreateRfiL2`                        | Payment is returned with an active level 2 RFI in the synchronous response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `CreateRfiL3`                        | Payment is returned with an active level 3 RFI in the synchronous response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `AsyncRfi`                           | Payment is returned with the `CREATED` status in the synchronous response, followed by a webhook that creates an RFI on the payment.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `Delayed`                            | Payment is returned with the `CRYPTO_FUNDS_PENDING` status in the synchronous response. After an onchain transaction is received and after the `FIAT_PAYMENT_INITIATED` notification occurs, the fiat settlement time on the payment increases and a payment delayed webhook notifications is sent. The `COMPLETED` webhook is delayed by a few seconds.                                                                                                                                                                                                                      |
| `Expired`                            | Payment is returned with the `CRYPTO_FUNDS_PENDING` status in the synchronous response. After a few seconds the payment status is updated to `FAILED` with the reason `PAYMENT_EXPIRED`.                                                                                                                                                                                                                                                                                                                                                                                      |
| `FailThenRefundWithCompleted`        | Payment is returned with the `CRYPTO_FUNDS_PENDING` status in the synchronous response. After an onchain transaction is received and after the `FIAT_PAYMENT_INITATED` notification occurs, the payment is moved to a `FAILED` state and a refund with the `COMPLETED` status is added to the payment.<br /><br />Using this magic value just fails the payment and sends the refund notification. It does not send the funds from the onchain transaction back. The `txHash` returned in the sandbox environment is a randomly generated transaction hash.                   |
| `FailThenRefundCreatedThenFailed`    | Payment is returned with the `CRYPTO_FUNDS_PENDING` status in the synchronous response. After an onchain transaction is received, a `FIAT_PAYMENT_INITIATED` notification occurs, and the payment is moved to a `FAILED` state. A refund with the `CREATED` status is added to the payment, followed by a webhook that updates the refund to the `FAILED` state.<br /><br />This magic value simulates a scenario where the payment fails and an attempt to issue a refund is made, but the refund also fails, for example due to a downstream system error.                  |
| `FailThenRefundCreatedThenCompleted` | Payment is returned with the `CRYPTO_FUNDS_PENDING` status in the synchronous response. After an onchain transaction is received, a `FIAT_PAYMENT_INITIATED` notification occurs, and the payment is moved to a `FAILED` state. A refund with the `CREATED` status is added to the payment, followed by a webhook that updates the refund to the `COMPLETED` state.<br /><br />This value simulates a successful refund process after a failed payment. The original onchain funds are still not returned to the sender. The `txHash` used for testnet is randomly generated. |

## Submit RFI

You can test RFIs by providing magic values on the `NAME` field when making
requests to the [submit RFI data](/api-reference/cpn/cpn-platform/submit-rfi)
endpoint. The following table outlines the magic values and their effects on the
RFI response:

| Magic value | Response                                        |
| ----------- | ----------------------------------------------- |
| `InReview`  | Stuck RFI. RFI stays in the `IN_REVIEW` status. |
| `Rejected`  | RFI is rejected.                                |

<Note>
  **Note:** Any value in the `NAME` field besides the values in the table
  results in an approved RFI.
</Note>


# Webhook Events
Source: https://developers.circle.com/cpn/references/webhooks/webhook-events

Reference for CPN webhooks for OFIs: payment, RFI, transaction, and refund notification types and payloads.

Components of CPN send webhook notifications when events occur, typically for a
change in state. These webhook notifications are sent to the OFI so that they
can track and manage payments in CPN. The webhooks described in this topic are
specific to OFIs only.

All webhook notifications follow the same payload structure. The
`notificationType` field indicates the event type, and the `notification` field
contains the event-specific data object. The `notification` object schema
matches the `data` field returned by the corresponding API endpoint (see the
[API reference](/api-reference/cpn/cpn-platform/) for details).

```json JSON theme={null}
{
  "subscriptionId": "cd198ca6-9fc4-41d6-b6b1-8e2a9c975352",
  "notificationId": "0761b030-0c75-472a-b471-74d90a7e796c",
  // Event type, determines the structure of the notification object
  "notificationType": "cpn.payment.cryptoFundsPending",
  // Event-specific data object, structure varies by notificationType
  // See corresponding section below for the object schema (Payment, RFI, Transaction, or Refund)
  "notification": {
    // Object matching the event type
  },
  "timestamp": "2024-09-30T17:48:05.420577158Z",
  "version": 2
}
```

The following sections describe the webhook events by component.

## Payment events

The `notification` object has the same schema as the `data` field returned by
[Get Payment](/api-reference/cpn/cpn-platform/get-payment).

| Event name                         | Description                                                                                                                                  | Trigger when                                                                                                                                                                    |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpn.payment.cryptoFundsPending`   | The payment has been created and is waiting for funds to be deposited                                                                        | The payment is ready to accept crypto funds                                                                                                                                     |
| `cpn.payment.fiatPaymentInitiated` | The BFI has initiated the fiat payment to the receiver's bank account                                                                        | The onchain transaction is confirmed by the BFI and the BFI initiated the fiat payment                                                                                          |
| `cpn.payment.completed`            | The payment is fully processed                                                                                                               | The fiat payment has been sent.<br /><br />Depending on the payment method, the receiver may or may not have received the transfer. At this point, the CPN payment is complete. |
| `cpn.payment.failed`               | The payment failed due to errors in processing, insufficient funds, or compliance rejection                                                  | The payment can't proceed due to an issue                                                                                                                                       |
| `cpn.payment.delayed`              | There is a delay to the estimate of payment settlement time. No status has changed but an updated settlement time is included in the payload | The BFI has an internal issue such that fiat settlement takes longer to process than originally stated                                                                          |
| `cpn.payment.inManualReview`       | A manual review has been placed on the payment. The payment status itself remains `CREATED`.                                                 | A payment is created but placed under manual review                                                                                                                             |

## RFI events

The `notification` object has the same schema as the `data` field returned by
[Get RFI](/api-reference/cpn/cpn-platform/get-rfi).

| Event name                    | Description                                                                | Trigger when                                                      |
| ----------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `cpn.rfi.informationRequired` | Additional compliance information is needed before the payment can proceed | The BFI requests more information to proceed with the payment     |
| `cpn.rfi.inReview`            | The submitted RFI response is under review by the BFI                      | The OFI submits the required information through the API endpoint |
| `cpn.rfi.approved`            | The RFI has been reviewed and approved, the payment can proceed            | The BFI approves the submitted information                        |
| `cpn.rfi.rejected`            | The RFI has been reviewed and rejected, the payment is failed              | The BFI rejects the submitted information                         |

## Transaction events

The `notification` object has the same schema as the `data` field returned by
[Get Transaction](/api-reference/cpn/cpn-platform/get-transaction).

| Event name                    | Description                                                                                | Trigger when                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| `cpn.transaction.broadcasted` | The signed transaction is sent to the blockchain for confirmation                          | The signed transaction has been broadcast        |
| `cpn.transaction.completed`   | The transaction was successfully included in a block                                       | The blockchain confirms the transaction          |
| `cpn.transaction.failed`      | The transaction failed due to issues such as incorrect parameters or insufficient gas fees | The blockchain failed to confirm the transaction |

## Refund events

The `notification` object has the same schema as the `data` field returned by
[Get Refund](/api-reference/cpn/cpn-platform/get-refund).

| Event name             | Description                                         | Trigger when                                                                     |
| ---------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------- |
| `cpn.refund.created`   | The BFI created a refund for the associated payment | The BFI initiated the refund.<br /><br />**Note:** Not all BFIs send this event. |
| `cpn.refund.failed`    | The refund could not be processed                   | The BFI encountered an error processing the refund                               |
| `cpn.refund.completed` | The refund is complete                              | The BFI confirms that the refund was successfully returned to the refund address |

## Webhooks from other Circle products

The event types in the previous sections are delivered through **CPN**
subscriptions. When you also use **Programmable Wallets** or **Circle APIs** for
liquidity and treasury, you may configure additional webhook subscriptions for
those products. Payload shape and `notificationType` values differ from CPN
webhooks.

| Product area            | Subscription endpoint                                                                                                  | Reference                                                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| CPN payments            | [Create subscription](/api-reference/cpn/common/create-subscription) (`POST /v2/cpn/notifications/subscriptions`)      | This page and [Set up webhook notifications](/cpn/guides/webhooks/setup-webhook-notifications)                                  |
| Programmable Wallets    | [Create subscription](/api-reference/wallets/common/create-subscription) (`POST /v2/notifications/subscriptions`)      | [Webhook notification flows](/wallets/webhook-notification-flows) (for example `transactions.inbound`, `transactions.outbound`) |
| Circle APIs (liquidity) | [Create subscription](/api-reference/circle-mint/general/create-subscription) (`POST /v1/notifications/subscriptions`) | [Notifications data models](/circle-mint/notifications-data-models)                                                             |

CPN and other Circle products each enforce their own API keys and notification
contracts. Plan separate subscriber endpoints or routing logic if you need all
event types in one service.


# Crosschain Transfers
Source: https://developers.circle.com/crosschain-transfers

Move USDC seamlessly across blockchains with native burn-and-mint protocols and unified balances.

<Tip>
  **Use dedicated SDKs for crosschain transfers**

  [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit) and
  [Unified Balance Kit](https://www.npmjs.com/package/@circle-fin/unified-balance-kit)
  let you move USDC across blockchains without low-level protocol work. Both
  support multiple blockchains and wallet providers.
</Tip>

## What you can build

Move USDC across chains securely and efficiently with tools designed for speed,
capital efficiency, and composability:

* **Protocol-level integration**: Build with [CCTP](/cctp), Circle's
  permissionless protocol that burns and mints native USDC across supported
  blockchains.
* **Chain-free UX**: A single [Gateway](/gateway) balance that works seamlessly
  across chains, enabling instant access to liquidity and a simplified
  experience for users.
* **Agentic commerce**: Use Gateway [Nanopayments](/gateway/nanopayments) to
  enable gas-free USDC payments down to \$0.000001, purpose-built for AI agents,
  usage-based billing, and high-frequency sub-cent transactions.

## Choose your approach

Each product is designed for different crosschain use cases. Pick the approach
that matches your application needs.

<CardGroup>
  <Card title="CCTP" icon="arrow-up-arrow-down" href="/cctp">
    Permissionless burn-and-mint protocol for native USDC transfers with fast
    and standard options.
  </Card>

  <Card title="Gateway" icon="dungeon" href="/gateway">
    Unified USDC balance instantly accessible across supported chains. No manual
    bridging required.
  </Card>
</CardGroup>

## When to use each product

Understanding which tool fits your use case helps you build the right crosschain
experience:

<AccordionGroup>
  <Accordion title="Use CCTP for direct protocol access" icon="arrow-up-arrow-down">
    CCTP is best when you need fine-grained control over crosschain transfers or
    want to build custom composable flows. It's a permissionless protocol that
    enables native USDC transfers through burn-and-mint mechanics. Use CCTP when
    you need to integrate crosschain transfers at the smart contract level,
    require Fast Transfer for speed-sensitive use cases, or want to trigger
    automated actions post-transfer using Hooks.
  </Accordion>

  <Accordion title="Use Gateway for unified balance" icon="dungeon">
    Gateway is designed for applications where users need instant access to their
    USDC across multiple chains without manual bridging. It's perfect for
    multichain apps, DEXs with chain abstraction, or any platform where users
    should see and spend one unified balance regardless of which chain they're on.
    Gateway eliminates the need for liquidity management across chains.
  </Accordion>

  <Accordion title="Use Nanopayments for agentic and sub-cent payments" icon="robot">
    Nanopayments extends Gateway with batched settlement to enable gas-free
    USDC payments at sub-cent scale. Use it when your application involves AI
    agents paying for resources, per-request billing, machine-to-machine
    commerce, or any scenario where per-transaction gas costs would exceed the
    payment value.
  </Accordion>
</AccordionGroup>

## Dive deeper

* Explore the [CCTP technical guide](/cctp/technical-guide) to understand Fast
  Transfer and Standard Transfer options.
* Read the Gateway quickstarts ([EVM](/gateway/quickstarts/unified-balance-evm),
  [Solana](/gateway/quickstarts/unified-balance-solana)) to create and use a
  unified USDC balance.
* Explore [Nanopayments](/gateway/nanopayments) to build agentic commerce with
  gas-free, sub-cent USDC payments.
* Learn about [CCTP supported blockchains](/cctp/cctp-supported-blockchains) and
  [Gateway supported blockchains](/gateway/references/supported-blockchains).


# Circle Gateway
Source: https://developers.circle.com/gateway



Circle Gateway enables a unified USDC balance across multiple blockchains.
Deposit USDC to non-custodial Gateway Wallet contracts on any supported source
blockchain, then mint USDC instantly (\<500 ms) on any destination blockchain
using a single API call.

Gateway is fully permissionless, and you can start integrating with it
immediately with no sign-up needed. Check out the quickstart guides for
[EVM](/gateway/quickstarts/unified-balance-evm) and
[Solana](/gateway/quickstarts/unified-balance-solana).

<Tip>
  **Use
  [Unified Balance Kit](https://www.npmjs.com/package/@circle-fin/unified-balance-kit)
  to simplify Gateway integrations.**

  Unified Balance Kit handles deposit, transfer, and spend flows so you can build
  Gateway-powered features in just a few lines of code.
</Tip>

## Key features

<CardGroup>
  <Card title="Unified crosschain balance" icon="layer-group">
    Hold USDC across multiple blockchains and access it as a single balance on
    any supported destination blockchain
  </Card>

  <Card title="Instant transfers" icon="bolt">
    Transfer USDC in under 500 ms after your balance is established, with no
    waiting for source blockchain finality
  </Card>

  <Card title="Non-custodial" icon="key">
    Retain full ownership of deposited USDC with signature-based authorization
    and a 7-day trustless withdrawal option
  </Card>
</CardGroup>

## What you can build

Gateway enables applications that require instant access to USDC across
blockchains. Here are some common use cases:

<AccordionGroup>
  <Accordion title="Chain abstraction" icon="wand-magic-sparkles">
    Build applications where users interact with USDC without worrying about which
    blockchain it's on. Users deposit once and access their balance instantly on any
    supported blockchain.
  </Accordion>

  <Accordion title="Crosschain liquidity" icon="arrow-right-arrow-left">
    Provide instant liquidity across blockchains without maintaining separate
    balances on each chain. Consolidate USDC holdings and access them where needed.
  </Accordion>

  <Accordion title="Payment routing" icon="route">
    Route payments to any supported blockchain instantly. Accept USDC on one
    blockchain and settle on another without delays.
  </Accordion>

  <Accordion title="Treasury management" icon="vault">
    Reduce working capital requirements by consolidating USDC across blockchains
    into a unified balance that's accessible anywhere.
  </Accordion>

  <Accordion title="Agentic commerce" icon="robot">
    Power AI agents and machine-to-machine systems with gasless, sub-cent USDC
    payments. See [Agent Nanopayments](/agent-stack/agent-nanopayments) for the
    agent-builder workflow.
  </Accordion>
</AccordionGroup>

## Get started

<CardGroup>
  <Card title="Create and transfer a unified balance" icon="rocket" href="/gateway/quickstarts/unified-balance">
    Build a script to deposit USDC on multiple blockchains and transfer it
    instantly to a destination blockchain
  </Card>

  <Card title="Set up webhooks" icon="bell" href="/gateway/webhooks">
    Receive real-time notifications for Gateway events on your registered wallet
    addresses
  </Card>

  <Card title="Supported blockchains" icon="link" href="/gateway/references/supported-blockchains">
    View the blockchains where you can deposit and mint USDC with Gateway
  </Card>
</CardGroup>

## Related products

CCTP and Gateway offer different approaches to crosschain transfers. This table
compares the two approaches.

| Attribute                 | CCTP                                                                               | Gateway                                                            |
| ------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Use case**              | Transfer USDC from one blockchain to another                                       | Hold a unified USDC balance accessible on any supported blockchain |
| **Transfer speed**        | Fast Transfer: \~8-20 seconds<br />Standard Transfer: 15-19 minutes (Ethereum/L2s) | Instant (\<500 ms) after balance is established                    |
| **Balance model**         | Point-to-point transfers                                                           | Unified crosschain balance                                         |
| **Custody**               | Non-custodial                                                                      | Non-custodial with 7-day trustless withdrawal option               |
| **Supported blockchains** | [View list](/cctp/concepts/supported-chains-and-domains)                           | [View list](/gateway/references/supported-blockchains)             |


# How-to: Create a Unified USDC Balance
Source: https://developers.circle.com/gateway/howtos/create-unified-usdc-balance



Circle Gateway allows you to establish a unified USDC balance consisting of USDC
stored on multiple source chains. Once established, you can transfer this
balance instantly to any destination chain.

This guide demonstrates how to establish a unified USDC balance by depositing
USDC into the [Gateway Wallet contract](/gateway/references/contract-addresses).
You can perform this action on multiple chains to establish a chain-abstracted
balance.

Select a tab below for EVM or Solana-specific instructions.

<Tabs>
  <Tab title="EVM">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared an EVM testnet wallet with the private key available
      * Added Arc testnet network to your wallet
        ([network details](https://docs.arc.io/arc/references/connect-to-arc#wallet-setup))
    * Funded your testnet wallet with USDC and native tokens
    * Created a TypeScript project and have `viem` installed
    * You've set up a `.env` file with the following variables:

      ```text .env theme={null}
      EVM_PRIVATE_KEY={YOUR_PRIVATE_KEY}
      ```

    ## Steps

    Follow these steps to establish a unified USDC balance on Arc Testnet. You can
    adapt this example for any
    [supported EVM chain](/gateway/references/supported-blockchains#testnet).

    ### Step 1. Approve the Gateway Wallet to transfer USDC from your address

    Create a new file called `deposit.ts` in the root of your project, and add the
    following code to it. This code calls the `approve()` method on the USDC
    contract to allow the Gateway Wallet contract to transfer USDC from your wallet.

    ```ts deposit.ts theme={null}
    import {
      createPublicClient,
      createWalletClient,
      getContract,
      http,
      erc20Abi,
      formatUnits,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet } from "viem/chains";

    /* Constants */
    const GATEWAY_WALLET_ADDRESS = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
    const USDC_ADDRESS = "0x3600000000000000000000000000000000000000";
    const DEPOSIT_AMOUNT = 10_000_000n; // 10 USDC (6 decimals)

    const gatewayWalletAbi = [
      {
        type: "function",
        name: "deposit",
        inputs: [
          { name: "token", type: "address" },
          { name: "value", type: "uint256" },
        ],
        outputs: [],
        stateMutability: "nonpayable",
      },
    ] as const;

    if (!process.env.EVM_PRIVATE_KEY) throw new Error("EVM_PRIVATE_KEY not set");
    const account = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );

    // Set up clients
    const publicClient = createPublicClient({
      chain: arcTestnet,
      transport: http(),
    });

    const walletClient = createWalletClient({
      account,
      chain: arcTestnet,
      transport: http(),
    });

    // Get contract instances
    const usdc = getContract({
      address: USDC_ADDRESS,
      abi: erc20Abi,
      client: walletClient,
    });

    const gatewayWallet = getContract({
      address: GATEWAY_WALLET_ADDRESS,
      abi: gatewayWalletAbi,
      client: walletClient,
    });

    // Approve Gateway Wallet to spend USDC
    console.log(`Approving ${formatUnits(DEPOSIT_AMOUNT, 6)} USDC...`);

    const approvalTx = await usdc.write.approve(
      [gatewayWallet.address, DEPOSIT_AMOUNT],
      { account },
    );
    await publicClient.waitForTransactionReceipt({ hash: approvalTx });
    console.log(`Approved: ${approvalTx}`);
    ```

    ### Step 2. Call the deposit method on the Gateway Wallet contract

    Add the following code to the `deposit.ts` file to call the
    [`deposit()`](/gateway/references/contract-interfaces-and-events#deposit) method
    on the Gateway Wallet contract. Note that you must use the `deposit()` method
    and not the standard transfer on the USDC contract.

    <Warning>
      **Warning:** Directly transferring USDC to the Gateway Wallet contract with a
      standard ERC-20 transfer will result in loss of that USDC. You must use one of
      the deposit methods on the wallet contract to get a unified USDC balance.
    </Warning>

    ```ts deposit.ts theme={null}
    console.log(
      `Depositing ${formatUnits(DEPOSIT_AMOUNT, 6)} USDC to Gateway Wallet...`,
    );

    const depositTx = await gatewayWallet.write.deposit(
      [usdc.address, DEPOSIT_AMOUNT],
      { account },
    );
    await publicClient.waitForTransactionReceipt({ hash: depositTx });
    console.log(`Deposit tx: ${depositTx}`);
    ```

    ### Step 3. Run the script

    Run the script with the following command:

    ```shell theme={null}
    npx tsx --env-file=.env deposit.ts
    ```

    ### Step 4. Wait for the required number of block confirmations

    Wait for the
    [required number of block confirmations](/gateway/references/supported-blockchains#required-block-confirmations).
    Once the deposit transaction is final, your unified balance reflects the amount
    from Arc Testnet. If you have balances on other chains, the total balance is the
    sum of all the USDC from deposit transactions across all supported chains that
    have reached finality.
  </Tab>

  <Tab title="Solana">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared a Solana Devnet wallet with the keypair exported as a JSON array
    * Funded your testnet wallet with USDC and native tokens
    * Created a TypeScript project and have the following dependencies installed:
      * `@solana/web3.js`
      * `@solana/spl-token`
      * `@coral-xyz/anchor`
      * `bn.js`
    * You've set up a `.env` file with the following variable:

      ```text .env theme={null}
      SOLANA_PRIVATE_KEYPAIR={YOUR_SOLANA_KEYPAIR_ARRAY}
      ```

    <Note>
      To generate a new Solana key pair, run:

      ```shell theme={null}
      solana-keygen new -o keypair.json --no-bip39-passphrase
      ```

      Copy the byte array from the JSON file to your `.env` file.

      If your wallet exports a private key hash instead, you can use `bs58` to convert
      it:

      ```ts TypeScript theme={null}
      const bytes = bs58.decode({ YOUR_PRIVATE_KEY_HASH });
      console.log(JSON.stringify(Array.from(bytes)));
      ```
    </Note>

    ## Steps

    Follow these steps to establish a unified USDC balance on Solana. The high level
    steps are the same for EVM chains, consult the EVM example for adding additional
    USDC to your unified balance from EVM chains.

    ### Step 1. Set up your Solana client

    Create a new file called `deposit.ts` in the root of your project and add the
    following code. This code sets up the Solana connection and wallet client.

    ```ts deposit.ts theme={null}
    import {
      Wallet,
      AnchorProvider,
      setProvider,
      Program,
      utils,
    } from "@coral-xyz/anchor";
    import { Connection, Keypair, PublicKey, SystemProgram } from "@solana/web3.js";
    import {
      getAssociatedTokenAddressSync,
      TOKEN_PROGRAM_ID,
    } from "@solana/spl-token";
    import BN from "bn.js";

    /* Constants */
    const GATEWAY_WALLET_ADDRESS = "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
    const USDC_ADDRESS = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
    const RPC_ENDPOINT = "https://api.devnet.solana.com";
    const DEPOSIT_AMOUNT = new BN(10_000_000); // 10 USDC (6 decimals)

    /* Gateway Wallet IDL (partial, for deposit only) */
    const gatewayWalletIdl = {
      address: GATEWAY_WALLET_ADDRESS,
      metadata: {
        name: "gatewayWallet",
        version: "0.1.0",
        spec: "0.1.0",
      },
      instructions: [
        {
          name: "deposit",
          discriminator: [22, 0],
          accounts: [
            { name: "payer", writable: true, signer: true },
            { name: "owner", signer: true },
            { name: "gatewayWallet" },
            { name: "ownerTokenAccount", writable: true },
            { name: "custodyTokenAccount", writable: true },
            { name: "deposit", writable: true },
            { name: "depositorDenylist" },
            { name: "tokenProgram" },
            { name: "systemProgram" },
            { name: "eventAuthority" },
            { name: "program" },
          ],
          args: [{ name: "amount", type: "u64" }],
        },
      ],
    };

    // Get keypair from environment
    if (!process.env.SOLANA_PRIVATE_KEYPAIR)
      throw new Error("SOLANA_PRIVATE_KEYPAIR not set");
    const keypair = Keypair.fromSecretKey(
      Uint8Array.from(JSON.parse(process.env.SOLANA_PRIVATE_KEYPAIR)),
    );

    // Set up connection and public keys
    const connection = new Connection(RPC_ENDPOINT, "confirmed");
    const usdcMint = new PublicKey(USDC_ADDRESS);
    const programId = new PublicKey(GATEWAY_WALLET_ADDRESS);
    const owner = keypair.publicKey;
    ```

    ### Step 2. Set up Anchor provider and program and derive PDAs

    Add the following code to `deposit.ts` to initialize the Anchor client and
    derive the Program Derived Addresses (PDAs) required by the Gateway Wallet.

    ```ts deposit.ts theme={null}
    // Set up Anchor provider and program
    const anchorWallet = new Wallet(keypair);
    const provider = new AnchorProvider(
      connection,
      anchorWallet,
      AnchorProvider.defaultOptions(),
    );
    setProvider(provider);
    const program = new Program(gatewayWalletIdl, provider);

    // Derive PDAs
    const pdas = {
      wallet: PublicKey.findProgramAddressSync(
        [Buffer.from(utils.bytes.utf8.encode("gateway_wallet"))],
        programId,
      )[0],
      custody: PublicKey.findProgramAddressSync(
        [
          Buffer.from(utils.bytes.utf8.encode("gateway_wallet_custody")),
          usdcMint.toBuffer(),
        ],
        programId,
      )[0],
      deposit: PublicKey.findProgramAddressSync(
        [Buffer.from("gateway_deposit"), usdcMint.toBuffer(), owner.toBuffer()],
        programId,
      )[0],
      denylist: PublicKey.findProgramAddressSync(
        [Buffer.from("denylist"), owner.toBuffer()],
        programId,
      )[0],
    };
    ```

    ### Step 3. Call the deposit instruction on the Gateway Wallet program

    Add the following code to `deposit.ts` to call the deposit instruction on the
    Gateway Wallet program. Note that you must use the Gateway Wallet's deposit
    instruction and not a standard SPL token transfer.

    <Warning>
      Directly transferring USDC to the Gateway Wallet program with a standard SPL
      token transfer will result in loss of that USDC. You must use the deposit
      instruction on the wallet program to get a unified USDC balance.
    </Warning>

    ```ts deposit.ts theme={null}
    // Deposit USDC into Gateway Wallet
    console.log(
      `Depositing ${Number(DEPOSIT_AMOUNT.toString()) / 1_000_000} USDC to Gateway Wallet...`,
    );

    const tx = await program.methods
      .deposit(DEPOSIT_AMOUNT)
      .accountsPartial({
        payer: owner,
        owner: owner,
        gatewayWallet: pdas.wallet,
        ownerTokenAccount: getAssociatedTokenAddressSync(usdcMint, owner),
        custodyTokenAccount: pdas.custody,
        deposit: pdas.deposit,
        depositorDenylist: pdas.denylist,
        tokenProgram: TOKEN_PROGRAM_ID,
        systemProgram: SystemProgram.programId,
      })
      .signers([keypair])
      .rpc();

    // Wait for confirmation
    const latest = await connection.getLatestBlockhash();
    await connection.confirmTransaction(
      {
        signature: tx,
        blockhash: latest.blockhash,
        lastValidBlockHeight: latest.lastValidBlockHeight,
      },
      "confirmed",
    );
    console.log(`Deposit tx: ${tx}`);
    ```

    ### Step 4. Run the script

    Run the script with the following command:

    ```shell theme={null}
    npx tsx --env-file=.env deposit.ts
    ```

    ### Step 5. Wait for finality

    Wait for the deposit transaction to reach finality. On Solana Devnet, finality
    is typically reached in a few seconds. Once the deposit transaction is final,
    your unified balance reflects the amount from Solana. If you have balances on
    other chains, the total balance is the sum of all the USDC from deposit
    transactions across all supported chains that have reached finality.
  </Tab>
</Tabs>


# How-to: Transfer with the Forwarding Service
Source: https://developers.circle.com/gateway/howtos/forwarding-service

Transfer USDC crosschain using the Forwarding Service to automatically handle destination chain minting

Transfer your unified USDC balance to a destination chain without needing a
wallet or gas on that chain. The
[Forwarding Service](/gateway/references/forwarding-service) handles the
destination chain mint automatically.

This guide demonstrates how to estimate fees, create a burn intent, submit it
with forwarding enabled, and poll for transfer completion.

Select a tab below for EVM or Solana destination instructions.

<Tabs>
  <Tab title="EVM">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared an EVM testnet wallet with the private key available
      * Added the
        [supported Testnets](/gateway/references/supported-blockchains#testnet) of
        your choice to your wallet (this guide uses Arc Testnet and Base Sepolia)
    * Funded your testnet wallet with native tokens on the source chain (this guide
      uses Arc Testnet). With the Forwarding Service, you do **not** need native
      tokens on the destination chain.
    * [Deposited 10 USDC into the Gateway Wallet](/gateway/howtos/create-unified-usdc-balance)
      contract on Arc Testnet
    * Created a TypeScript project and have `viem` installed
    * You've set up a `.env` file with the following variables:

      ```text .env theme={null}
      EVM_PRIVATE_KEY={YOUR_PRIVATE_KEY}
      ```

    ## Steps

    Follow these steps to transfer a unified USDC balance using the Forwarding
    Service. This example transfers 10 USDC from Arc Testnet to Base Sepolia. You
    can adapt it for another
    [supported chain](/gateway/references/supported-blockchains).

    ### Step 1. Create the transfer spec and estimate fees

    Create a new file called `transfer.ts` in the root of your project and add the
    following code to it. This code creates a
    [transfer spec](/gateway/references/technical-guide#burn-intent) for 10 USDC on
    Arc Testnet, then calls the
    [`/estimate`](/api-reference/gateway/all/estimate-transfer) endpoint with
    `enableForwarder=true` to determine the `maxFee` and `maxBlockHeight` values.
    Using the estimate endpoint ensures the `maxFee` covers the gas fee, transfer
    fee, and forwarding fee.

    ```ts transfer.ts expandable theme={null}
    import { randomBytes } from "node:crypto";
    import { pad, zeroAddress, formatUnits } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { arcTestnet, baseSepolia } from "viem/chains";

    /* Constants */
    const GATEWAY_API_BASE = "https://gateway-api-testnet.circle.com";
    const GATEWAY_WALLET_ADDRESS = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
    const GATEWAY_MINTER_ADDRESS = "0x0022222ABE238Cc2C7Bb1f21003F0a260052475B";

    const TRANSFER_VALUE = 10_000000n; // 10 USDC (6 decimals)
    const POLL_INTERVAL_MS = 5_000;
    const POLL_TIMEOUT_MS = 300_000; // 5 minutes

    const sourceChain = {
      name: "arcTestnet",
      chain: arcTestnet,
      usdcAddress: "0x3600000000000000000000000000000000000000",
      domainId: 26,
    };

    const destinationChain = {
      name: "baseSepolia",
      chain: baseSepolia,
      usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      domainId: 6,
    };

    const domain = { name: "GatewayWallet", version: "1" };

    const EIP712Domain = [
      { name: "name", type: "string" },
      { name: "version", type: "string" },
    ] as const;

    const TransferSpec = [
      { name: "version", type: "uint32" },
      { name: "sourceDomain", type: "uint32" },
      { name: "destinationDomain", type: "uint32" },
      { name: "sourceContract", type: "bytes32" },
      { name: "destinationContract", type: "bytes32" },
      { name: "sourceToken", type: "bytes32" },
      { name: "destinationToken", type: "bytes32" },
      { name: "sourceDepositor", type: "bytes32" },
      { name: "destinationRecipient", type: "bytes32" },
      { name: "sourceSigner", type: "bytes32" },
      { name: "destinationCaller", type: "bytes32" },
      { name: "value", type: "uint256" },
      { name: "salt", type: "bytes32" },
      { name: "hookData", type: "bytes" },
    ] as const;

    const BurnIntent = [
      { name: "maxBlockHeight", type: "uint256" },
      { name: "maxFee", type: "uint256" },
      { name: "spec", type: "TransferSpec" },
    ] as const;

    if (!process.env.EVM_PRIVATE_KEY) throw new Error("EVM_PRIVATE_KEY not set");
    const account = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );

    console.log(`Using account: ${account.address}`);
    console.log(`Transfer: ${sourceChain.name} → ${destinationChain.name}`);
    console.log(`Amount: ${formatUnits(TRANSFER_VALUE, 6)} USDC`);
    console.log(`Forwarding: enabled\n`);

    // Create the transfer spec
    const spec = {
      version: 1,
      sourceDomain: sourceChain.domainId,
      destinationDomain: destinationChain.domainId,
      sourceContract: GATEWAY_WALLET_ADDRESS,
      destinationContract: GATEWAY_MINTER_ADDRESS,
      sourceToken: sourceChain.usdcAddress,
      destinationToken: destinationChain.usdcAddress,
      sourceDepositor: account.address,
      destinationRecipient: account.address,
      sourceSigner: account.address,
      destinationCaller: zeroAddress,
      value: TRANSFER_VALUE,
      salt: "0x" + randomBytes(32).toString("hex"),
      hookData: "0x",
    };

    const specBytes32 = {
      ...spec,
      sourceContract: pad(spec.sourceContract.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      destinationContract: pad(
        spec.destinationContract.toLowerCase() as `0x${string}`,
        { size: 32 },
      ),
      sourceToken: pad(spec.sourceToken.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      destinationToken: pad(spec.destinationToken.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      sourceDepositor: pad(spec.sourceDepositor.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      destinationRecipient: pad(
        spec.destinationRecipient.toLowerCase() as `0x${string}`,
        { size: 32 },
      ),
      sourceSigner: pad(spec.sourceSigner.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      destinationCaller: pad(
        spec.destinationCaller.toLowerCase() as `0x${string}`,
        { size: 32 },
      ),
    };

    // Estimate fees
    console.log("Estimating fees...");
    const estimateResponse = await fetch(
      `${GATEWAY_API_BASE}/v1/estimate?enableForwarder=true`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify([{ spec: specBytes32 }], (_key, value) =>
          typeof value === "bigint" ? value.toString() : value,
        ),
      },
    );

    if (!estimateResponse.ok) {
      const text = await estimateResponse.text();
      throw new Error(`Estimate API error: ${estimateResponse.status} ${text}`);
    }

    const estimateResult = await estimateResponse.json();
    const estimated = estimateResult.body[0].burnIntent;
    const maxFee = BigInt(estimated.maxFee);
    const maxBlockHeight = BigInt(estimated.maxBlockHeight);
    const { fees } = estimateResult;

    if (fees.forwardingFee) {
      console.log(`  Forwarding fee: ${fees.forwardingFee} ${fees.token}`);
    }
    console.log(`  Estimated maxFee: ${formatUnits(maxFee, 6)} ${fees.token}`);
    ```

    <Note>
      **Note:** For production apps, verifying the balance on each chain before
      creating burn intents is best practice. For this how-to, it's assumed that the
      balance is created per the [prerequisites](#prerequisites). For a complete
      end-to-end example that includes checking and error handling, see the Gateway
      quickstarts ([EVM](/gateway/quickstarts/unified-balance-evm)).
    </Note>

    ### Step 2. Sign and submit the burn intent to the Gateway API

    Add the following code to `transfer.ts`. This code constructs the
    [EIP-712 typed data](/gateway/references/technical-guide#burn-intent), signs the
    burn intent using the estimated `maxFee` and `maxBlockHeight`, and submits it to
    the [`/transfer`](/api-reference/gateway/all/create-transfer-attestation)
    endpoint with `enableForwarder=true`.

    <Info>
      In forwarded flows, the `POST /v1/transfer` response may omit top-level
      `attestation` and `signature` fields. Use the returned `transferId` to poll
      `GET /v1/transfer/{id}` for the full transfer record.
    </Info>

    ```ts transfer.ts theme={null}
    const typedData = {
      types: { EIP712Domain, TransferSpec, BurnIntent },
      domain,
      primaryType: "BurnIntent" as const,
      message: { maxBlockHeight, maxFee, spec: specBytes32 },
    };

    const signature = await account.signTypedData(
      typedData as Parameters<typeof account.signTypedData>[0],
    );
    console.log("\nSigned burn intent.");

    console.log("Submitting to Gateway API...");
    const response = await fetch(
      `${GATEWAY_API_BASE}/v1/transfer?enableForwarder=true`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(
          [{ burnIntent: typedData.message, signature }],
          (_key, value) => (typeof value === "bigint" ? value.toString() : value),
        ),
      },
    );

    if (!response.ok) {
      const text = await response.text();
      throw new Error(`Gateway API error: ${response.status} ${text}`);
    }

    const json = await response.json();
    const transferId = json.transferId;
    if (!transferId) throw new Error("Missing transferId in response");
    console.log(`Transfer ID: ${transferId}`);
    ```

    ### Step 3. Poll for transfer completion

    Add the following code to `transfer.ts`. Because the Forwarding Service handles
    the destination chain mint, you don't need to call the minter contract. Instead,
    poll the [`/transfer/{id}`](/api-reference/gateway/all/get-transfer-by-id)
    endpoint until the status reaches `confirmed` or `finalized`.

    ```ts transfer.ts theme={null}
    console.log(`\nPolling for transfer completion...`);
    const pollStart = Date.now();
    let completed = false;

    while (Date.now() - pollStart < POLL_TIMEOUT_MS) {
      const pollRes = await fetch(`${GATEWAY_API_BASE}/v1/transfer/${transferId}`);

      if (!pollRes.ok) {
        console.error(`Poll error: ${pollRes.status}`);
        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
        continue;
      }

      const details = await pollRes.json();
      console.log(`  Status: ${details.status}`);

      if (details.status === "finalized" || details.status === "confirmed") {
        completed = true;
        break;
      }

      if (details.status === "failed") {
        const reason = details.forwardingDetails?.failureReason ?? "unknown";
        throw new Error(`Transfer failed: ${reason}`);
      }

      if (details.status === "expired") {
        throw new Error("Transfer attestation expired before forwarding");
      }

      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
    }

    if (!completed) {
      throw new Error("Polling timed out waiting for transfer completion");
    }

    console.log(
      `\nTransfer complete. ${formatUnits(TRANSFER_VALUE, 6)} USDC forwarded to ${destinationChain.name}.`,
    );
    ```

    ### Step 4. Run the script

    Run the script with the following command:

    ```shell theme={null}
    npx tsx --env-file=.env transfer.ts
    ```
  </Tab>

  <Tab title="Solana">
    When the destination is Solana, you need to ensure that `destinationRecipient`
    is an initialized USDC token account. If the recipient wallet address does not
    already have a USDC token account, you can request
    [automatic ATA creation](/gateway/references/forwarding-service#automatic-ata-creation-for-solana)
    using the Forwarding Service.

    This guide demonstrates how to forward from an EVM source blockchain to a Solana
    destination with automatic Associated Token Account (ATA) creation.

    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared an EVM testnet wallet with the private key available
      * Added the
        [supported Testnets](/gateway/references/supported-blockchains#testnet) of
        your choice to your wallet (this guide uses Arc Testnet)
    * Funded your testnet wallet with native tokens on the source chain (this guide
      uses Arc Testnet). With the Forwarding Service, you do **not** need native
      tokens on the destination chain.
    * [Deposited 10 USDC into the Gateway Wallet](/gateway/howtos/create-unified-usdc-balance)
      contract on Arc Testnet
    * Created a TypeScript project and have `viem`, `@solana/web3.js`, and
      `@solana/spl-token` installed
    * You've set up a `.env` file with the following variables:

      ```text .env theme={null}
      EVM_PRIVATE_KEY={YOUR_PRIVATE_KEY}
      SOLANA_RECIPIENT_WALLET={RECIPIENT_SOLANA_WALLET_ADDRESS}
      ```

    ## Steps

    Follow these steps to transfer a unified USDC balance to a Solana destination
    using the Forwarding Service with automatic ATA creation. This example transfers
    10 USDC from Arc Testnet to Solana Devnet.

    ### Step 1. Create the transfer spec and estimate fees

    Create a new file called `transfer-solana.ts` in the root of your project and
    add the following code to it. This code derives the recipient's ATA, creates a
    transfer spec targeting Solana Devnet, and calls the
    [`/estimate`](/api-reference/gateway/all/estimate-transfer) endpoint with
    `enableForwarder=true` and `recipientSetupOptions` for automatic ATA creation.

    <Note>
      The forwarding fee for Solana destinations includes the rent cost for ATA
      creation when `recipientSetupOptions` is provided. If the recipient already
      has an initialized USDC token account, omit `recipientSetupOptions` to avoid
      the additional rent fee.
    </Note>

    ```ts transfer-solana.ts expandable highlight={4-5,15-20,28-33,66-67,73-82,86-87,101,151-154} theme={null}
    import { randomBytes } from "node:crypto";
    import { pad, zeroAddress, formatUnits } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { PublicKey } from "@solana/web3.js";
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";

    /* Constants */
    const GATEWAY_API_BASE = "https://gateway-api-testnet.circle.com";
    const GATEWAY_WALLET_ADDRESS = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";

    const TRANSFER_VALUE = 10_000000n; // 10 USDC (6 decimals)
    const POLL_INTERVAL_MS = 5_000;
    const POLL_TIMEOUT_MS = 300_000; // 5 minutes

    const SOLANA_USDC_MINT = new PublicKey(
      "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
    );
    const SOLANA_GATEWAY_MINTER_ADDRESS = new PublicKey(
      "GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr",
    );

    const sourceChain = {
      name: "arcTestnet",
      usdcAddress: "0x3600000000000000000000000000000000000000",
      domainId: 26,
    };

    const destinationChain = {
      name: "solanaDevnet",
      minterAddress:
        "0x" + Buffer.from(SOLANA_GATEWAY_MINTER_ADDRESS.toBytes()).toString("hex"),
      usdcAddress: "0x" + Buffer.from(SOLANA_USDC_MINT.toBytes()).toString("hex"),
      domainId: 5,
    };

    const domain = { name: "GatewayWallet", version: "1" };

    const EIP712Domain = [
      { name: "name", type: "string" },
      { name: "version", type: "string" },
    ] as const;

    const TransferSpec = [
      { name: "version", type: "uint32" },
      { name: "sourceDomain", type: "uint32" },
      { name: "destinationDomain", type: "uint32" },
      { name: "sourceContract", type: "bytes32" },
      { name: "destinationContract", type: "bytes32" },
      { name: "sourceToken", type: "bytes32" },
      { name: "destinationToken", type: "bytes32" },
      { name: "sourceDepositor", type: "bytes32" },
      { name: "destinationRecipient", type: "bytes32" },
      { name: "sourceSigner", type: "bytes32" },
      { name: "destinationCaller", type: "bytes32" },
      { name: "value", type: "uint256" },
      { name: "salt", type: "bytes32" },
      { name: "hookData", type: "bytes" },
    ] as const;

    const BurnIntent = [
      { name: "maxBlockHeight", type: "uint256" },
      { name: "maxFee", type: "uint256" },
      { name: "spec", type: "TransferSpec" },
    ] as const;

    if (!process.env.EVM_PRIVATE_KEY) throw new Error("EVM_PRIVATE_KEY not set");
    if (!process.env.SOLANA_RECIPIENT_WALLET)
      throw new Error("SOLANA_RECIPIENT_WALLET not set");

    const account = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );

    // Derive the recipient's USDC ATA from their wallet address
    const recipientWallet = new PublicKey(process.env.SOLANA_RECIPIENT_WALLET);
    const recipientAta = getAssociatedTokenAddressSync(
      SOLANA_USDC_MINT,
      recipientWallet,
    );
    const recipientAtaHex =
      "0x" + Buffer.from(recipientAta.toBytes()).toString("hex");
    const recipientWalletHex =
      "0x" + Buffer.from(recipientWallet.toBytes()).toString("hex");

    console.log(`Using account: ${account.address}`);
    console.log(`Transfer: ${sourceChain.name} → ${destinationChain.name}`);
    console.log(`Recipient wallet: ${recipientWallet.toBase58()}`);
    console.log(`Recipient ATA: ${recipientAta.toBase58()}`);
    console.log(`Amount: ${formatUnits(TRANSFER_VALUE, 6)} USDC`);
    console.log(`Forwarding: enabled\n`);

    // Create the transfer spec
    const spec = {
      version: 1,
      sourceDomain: sourceChain.domainId,
      destinationDomain: destinationChain.domainId,
      sourceContract: GATEWAY_WALLET_ADDRESS,
      destinationContract: destinationChain.minterAddress,
      sourceToken: sourceChain.usdcAddress,
      destinationToken: destinationChain.usdcAddress,
      sourceDepositor: account.address,
      destinationRecipient: recipientAtaHex,
      sourceSigner: account.address,
      destinationCaller: zeroAddress,
      value: TRANSFER_VALUE,
      salt: "0x" + randomBytes(32).toString("hex"),
      hookData: "0x",
    };

    const specBytes32 = {
      ...spec,
      sourceContract: pad(spec.sourceContract.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      destinationContract: pad(
        spec.destinationContract.toLowerCase() as `0x${string}`,
        { size: 32 },
      ),
      sourceToken: pad(spec.sourceToken.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      destinationToken: pad(spec.destinationToken.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      sourceDepositor: pad(spec.sourceDepositor.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      destinationRecipient: pad(
        spec.destinationRecipient.toLowerCase() as `0x${string}`,
        { size: 32 },
      ),
      sourceSigner: pad(spec.sourceSigner.toLowerCase() as `0x${string}`, {
        size: 32,
      }),
      destinationCaller: pad(
        spec.destinationCaller.toLowerCase() as `0x${string}`,
        { size: 32 },
      ),
    };

    // Estimate fees with recipientSetupOptions for automatic ATA creation
    console.log("Estimating fees...");
    const estimateResponse = await fetch(
      `${GATEWAY_API_BASE}/v1/estimate?enableForwarder=true`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(
          [
            {
              spec: specBytes32,
              recipientSetupOptions: {
                includeRecipientSetup: true,
                recipientOwnerAddress: recipientWalletHex,
              },
            },
          ],
          (_key, value) => (typeof value === "bigint" ? value.toString() : value),
        ),
      },
    );

    if (!estimateResponse.ok) {
      const text = await estimateResponse.text();
      throw new Error(`Estimate API error: ${estimateResponse.status} ${text}`);
    }

    const estimateResult = await estimateResponse.json();
    const estimated = estimateResult.body[0].burnIntent;
    const maxFee = BigInt(estimated.maxFee);
    const maxBlockHeight = BigInt(estimated.maxBlockHeight);
    const { fees } = estimateResult;

    if (fees.forwardingFee) {
      console.log(`  Forwarding fee: ${fees.forwardingFee} ${fees.token}`);
    }
    console.log(`  Estimated maxFee: ${formatUnits(maxFee, 6)} ${fees.token}`);
    ```

    ### Step 2. Sign and submit the burn intent to the Gateway API

    Add the following code to `transfer-solana.ts`. The signing step is the same as
    the EVM flow, but the request body includes `recipientSetupOptions` so the
    Forwarding Service creates the ATA on Solana.

    The `recipientOwnerAddress` is the recipient's Solana wallet address in bytes32
    hex format. The API validates that the `destinationRecipient` in the transfer
    spec matches the canonical ATA derived from this address and the USDC token
    mint. If they don't match, the request is rejected.

    <Info>
      In forwarded flows, the `POST /v1/transfer` response may omit top-level
      `attestation` and `signature` fields. Use the returned `transferId` to poll
      `GET /v1/transfer/{id}` for the full transfer record.
    </Info>

    ```ts transfer-solana.ts highlight={24-27} theme={null}
    const typedData = {
      types: { EIP712Domain, TransferSpec, BurnIntent },
      domain,
      primaryType: "BurnIntent" as const,
      message: { maxBlockHeight, maxFee, spec: specBytes32 },
    };

    const signature = await account.signTypedData(
      typedData as Parameters<typeof account.signTypedData>[0],
    );
    console.log("\nSigned burn intent.");

    console.log("Submitting to Gateway API...");
    const response = await fetch(
      `${GATEWAY_API_BASE}/v1/transfer?enableForwarder=true`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(
          [
            {
              burnIntent: {
                ...typedData.message,
                recipientSetupOptions: {
                  includeRecipientSetup: true,
                  recipientOwnerAddress: recipientWalletHex,
                },
              },
              signature,
            },
          ],
          (_key, value) => (typeof value === "bigint" ? value.toString() : value),
        ),
      },
    );

    if (!response.ok) {
      const text = await response.text();
      throw new Error(`Gateway API error: ${response.status} ${text}`);
    }

    const json = await response.json();
    const transferId = json.transferId;
    if (!transferId) throw new Error("Missing transferId in response");
    console.log(`Transfer ID: ${transferId}`);
    ```

    ### Step 3. Poll for transfer completion

    Add the following code to `transfer-solana.ts`. Because the Forwarding Service
    handles the destination chain mint, you don't need to call the minter contract.
    Instead, poll the
    [`/transfer/{id}`](/api-reference/gateway/all/get-transfer-by-id) endpoint until
    the status reaches `confirmed` or `finalized`.

    ```ts transfer-solana.ts theme={null}
    console.log(`\nPolling for transfer completion...`);
    const pollStart = Date.now();
    let completed = false;

    while (Date.now() - pollStart < POLL_TIMEOUT_MS) {
      const pollRes = await fetch(`${GATEWAY_API_BASE}/v1/transfer/${transferId}`);

      if (!pollRes.ok) {
        console.error(`Poll error: ${pollRes.status}`);
        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
        continue;
      }

      const details = await pollRes.json();
      console.log(`  Status: ${details.status}`);

      if (details.status === "finalized" || details.status === "confirmed") {
        completed = true;
        break;
      }

      if (details.status === "failed") {
        const reason = details.forwardingDetails?.failureReason ?? "unknown";
        throw new Error(`Transfer failed: ${reason}`);
      }

      if (details.status === "expired") {
        throw new Error("Transfer attestation expired before forwarding");
      }

      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
    }

    if (!completed) {
      throw new Error("Polling timed out waiting for transfer completion");
    }

    console.log(
      `\nTransfer complete. ${formatUnits(TRANSFER_VALUE, 6)} USDC forwarded to ${destinationChain.name}.`,
    );
    ```

    ### Step 4. Run the script

    Run the script with the following command:

    ```shell theme={null}
    npx tsx --env-file=.env transfer-solana.ts
    ```
  </Tab>
</Tabs>


# How-to: Manage Delegates for Smart Contract Wallets
Source: https://developers.circle.com/gateway/howtos/manage-delegates



When using
[Smart Contract Account (SCA) wallets](/wallets/account-types#smart-contract-accounts-sca)
with Gateway, you need to authorize an Externally Owned Account (EOA) to sign
burn intents on behalf of the SCA. This is necessary because Gateway requires
ECDSA signatures for static verification, which SCAs cannot provide directly.

This guide demonstrates how to add and remove delegates for Gateway transfers
from SCA wallets using Circle
[Developer-controlled wallets](/wallets/dev-controlled).

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)
* Created a [Circle Developer Console](https://console.circle.com) account
* Obtained an API key and
  [registered your Entity Secret](/wallets/dev-controlled/register-entity-secret)
* Created an SCA wallet and an EOA wallet via Circle Developer-Controlled
  Wallets
  * The SCA wallet holds your Gateway USDC deposits
  * The EOA wallet will sign burn intents on behalf of the SCA
* Deposited USDC into the Gateway Wallet from your SCA wallet
* Created a TypeScript project with the
  [Developer-Controlled Wallets SDK](/sdks/developer-controlled-wallets-nodejs-sdk)
  installed
* Set up a `.env` file with the following variables:

  ```text .env theme={null}
  CIRCLE_API_KEY={YOUR_API_KEY}
  CIRCLE_ENTITY_SECRET={YOUR_ENTITY_SECRET}
  DEPOSITOR_ADDRESS={YOUR_SCA_WALLET_ADDRESS}
  DELEGATE_WALLET_ADDRESS={YOUR_EOA_DELEGATE_ADDRESS}
  ```

## Add a Delegate

Follow these steps to authorize an EOA delegate to sign burn intents on behalf
of your SCA wallet.

### Step 1. Create the add delegate script

Create a new file called `add-delegate.ts` in the root of your project and add
the following code. This calls the
[`addDelegate()`](/gateway/references/contract-interfaces-and-events#adddelegate)
method on the Gateway Wallet contract on Arc Testnet.

```ts add-delegate.ts theme={null}
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const GATEWAY_WALLET = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
const USDC_ADDRESS = "0x3600000000000000000000000000000000000000"; // Arc Testnet
const BLOCKCHAIN = "ARC-TESTNET";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
});

async function waitForTx(txId: string) {
  while (true) {
    const { data } = await client.getTransaction({ id: txId });
    const state = data?.transaction?.state;
    if (["COMPLETE", "CONFIRMED"].includes(state!)) return;
    if (["FAILED", "DENIED", "CANCELLED"].includes(state!))
      throw new Error(`Failed: ${state}`);
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

async function main() {
  console.log(`\n=== Processing ${BLOCKCHAIN} ===`);
  console.log(`Adding delegate: ${process.env.DELEGATE_WALLET_ADDRESS}`);

  const tx = await client.createContractExecutionTransaction({
    walletAddress: process.env.DEPOSITOR_ADDRESS!,
    blockchain: BLOCKCHAIN,
    contractAddress: GATEWAY_WALLET,
    abiFunctionSignature: "addDelegate(address,address)",
    abiParameters: [USDC_ADDRESS, process.env.DELEGATE_WALLET_ADDRESS!],
    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
  });

  await waitForTx(tx.data?.id!);
  console.log(`Done on ${BLOCKCHAIN}`);
}

main().catch((error) => {
  console.error("\nError:", error);
  process.exit(1);
});
```

### Step 2. Run the script

Run the script with the following command:

```shell theme={null}
npx tsx --env-file=.env add-delegate.ts
```

The script output shows "Done on \<SELECTED\_BLOCKCHAIN>" when the delegate is
successfully authorized. You can now use the delegate to sign burn intents on
behalf of your SCA wallet when making Gateway transfers.

### Step 3. Repeat for other chains

To add the delegate on additional chains where the SCA holds Gateway deposits,
repeat Steps 1-2 with different `BLOCKCHAIN` and `USDC_ADDRESS` values for your
target chains. Check the
[USDC contract addresses](/stablecoins/usdc-contract-addresses) for the correct
values.

<Note>
  The delegate authorization remains valid until explicitly removed with the
  [`removeDelegate()`](/gateway/references/contract-interfaces-and-events#removedelegate)
  method.
</Note>

## Remove a Delegate

Follow these steps to revoke a delegate's authorization to sign burn intents on
behalf of your SCA wallet. After removing a delegate, note that:

* The delegate can no longer create new burn intents for the SCA wallet
* Burn intents that were already signed by the delegate remain valid and can
  still be executed on-chain
* This ensures that burns may be executed safely even in the event of a
  revocation
* The Gateway API reflects revocations as soon as they're finalized on-chain

This behavior is by design to prevent race conditions where a valid burn intent
becomes unusable mid-flight.

### Step 1. Create the remove delegate script

Create a new file called `remove-delegate.ts` in the root of your project and
add the following code. This is nearly identical to the add delegate script, but
calls
[`removeDelegate()`](/gateway/references/contract-interfaces-and-events#removedelegate)
instead.

```ts remove-delegate.ts theme={null}
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const GATEWAY_WALLET = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
const USDC_ADDRESS = "0x3600000000000000000000000000000000000000"; // Arc Testnet
const BLOCKCHAIN = "ARC-TESTNET";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
});

async function waitForTx(txId: string) {
  while (true) {
    const { data } = await client.getTransaction({ id: txId });
    const state = data?.transaction?.state;
    if (["COMPLETE", "CONFIRMED"].includes(state!)) return;
    if (["FAILED", "DENIED", "CANCELLED"].includes(state!))
      throw new Error(`Failed: ${state}`);
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

async function main() {
  console.log(`\n=== Processing ${BLOCKCHAIN} ===`);
  console.log(`Removing delegate: ${process.env.DELEGATE_WALLET_ADDRESS}`);

  const tx = await client.createContractExecutionTransaction({
    walletAddress: process.env.DEPOSITOR_ADDRESS!,
    blockchain: BLOCKCHAIN,
    contractAddress: GATEWAY_WALLET,
    abiFunctionSignature: "removeDelegate(address,address)",
    abiParameters: [USDC_ADDRESS, process.env.DELEGATE_WALLET_ADDRESS!],
    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
  });

  await waitForTx(tx.data?.id!);
  console.log(`Done on ${BLOCKCHAIN}`);
}

main().catch((error) => {
  console.error("\nError:", error);
  process.exit(1);
});
```

### Step 2. Run the script

Run the script with the following command:

```shell theme={null}
npx tsx --env-file=.env remove-delegate.ts
```


# How-to: Transfer a Unified USDC Balance Instantly
Source: https://developers.circle.com/gateway/howtos/transfer-unified-usdc-balance



Once you have established a unified USDC balance, you can transfer it instantly
to any supported destination chain.

This guide demonstrates how to transfer your unified balance.

Select a tab below for EVM or Solana-specific instructions.

<Tabs>
  <Tab title="EVM">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared an EVM testnet wallet with the private key available
      * Added the
        [supported Testnets](/gateway/references/supported-blockchains#testnet) of
        your choice to your wallet (this guide uses Arc Testnet, Avalanche Fuji and
        Sei Testnet)
    * Funded your testnet wallet with native tokens on the destination chain (this
      guide uses Sei Testnet)
    * [Deposited 10 USDC into the Gateway Wallet](/gateway/howtos/create-unified-usdc-balance)
      contracts on Arc Testnet and Avalanche Fuji (creating a unified balance of 20
      USDC)
    * Created a TypeScript project and have `viem` installed
    * You've set up a `.env` file with the following variables:

      ```text .env theme={null}
      EVM_PRIVATE_KEY={YOUR_PRIVATE_KEY}
      ```

    ## Steps

    Follow these steps to transfer a unified USDC balance. This example uses a
    unified balance split between Arc Testnet and Avalanche Fuji. You can adapt it
    for any chains where you hold a unified balance.

    ### Step 1. Create and sign burn intents for the source chains

    Create a new file called `transfer.ts` in the root of your project and add the
    following code to it. This code creates and signs
    [burn intents](/gateway/references/technical-guide#burn-intent) for 5 USDC on
    Arc Testnet and 5 USDC on Avalanche Fuji.

    ```ts transfer.ts expandable theme={null}
    import { randomBytes } from "node:crypto";
    import {
      http,
      maxUint256,
      zeroAddress,
      pad,
      createPublicClient,
      getContract,
      createWalletClient,
      formatUnits,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { avalancheFuji, arcTestnet, seiTestnet } from "viem/chains";

    /* Constants */
    const GATEWAY_WALLET_ADDRESS = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
    const GATEWAY_MINTER_ADDRESS = "0x0022222ABE238Cc2C7Bb1f21003F0a260052475B";

    const TRANSFER_VALUE = 5_000000n; // 5 USDC (6 decimals)
    const MAX_FEE = 2_010000n;

    // Source chains configuration
    const sourceChains = [
      {
        name: "arcTestnet",
        chain: arcTestnet,
        usdcAddress: "0x3600000000000000000000000000000000000000",
        domainId: 26,
      },
      {
        name: "avalancheFuji",
        chain: avalancheFuji,
        usdcAddress: "0x5425890298aed601595a70ab815c96711a31bc65",
        domainId: 1,
      },
    ];

    // Destination chain configuration
    const destinationChain = {
      name: "seiTestnet",
      chain: seiTestnet,
      usdcAddress: "0x4fCF1784B31630811181f670Aea7A7bEF803eaED",
      domainId: 16,
    };

    const domain = { name: "GatewayWallet", version: "1" };

    const EIP712Domain = [
      { name: "name", type: "string" },
      { name: "version", type: "string" },
    ] as const;

    const TransferSpec = [
      { name: "version", type: "uint32" },
      { name: "sourceDomain", type: "uint32" },
      { name: "destinationDomain", type: "uint32" },
      { name: "sourceContract", type: "bytes32" },
      { name: "destinationContract", type: "bytes32" },
      { name: "sourceToken", type: "bytes32" },
      { name: "destinationToken", type: "bytes32" },
      { name: "sourceDepositor", type: "bytes32" },
      { name: "destinationRecipient", type: "bytes32" },
      { name: "sourceSigner", type: "bytes32" },
      { name: "destinationCaller", type: "bytes32" },
      { name: "value", type: "uint256" },
      { name: "salt", type: "bytes32" },
      { name: "hookData", type: "bytes" },
    ] as const;

    const BurnIntent = [
      { name: "maxBlockHeight", type: "uint256" },
      { name: "maxFee", type: "uint256" },
      { name: "spec", type: "TransferSpec" },
    ] as const;

    const gatewayMinterAbi = [
      {
        type: "function",
        name: "gatewayMint",
        inputs: [
          { name: "attestationPayload", type: "bytes" },
          { name: "signature", type: "bytes" },
        ],
        outputs: [],
        stateMutability: "nonpayable",
      },
    ] as const;

    // Get account from environment
    if (!process.env.EVM_PRIVATE_KEY) throw new Error("EVM_PRIVATE_KEY not set");
    const account = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );

    console.log(`Using account: ${account.address}`);
    console.log(`Transferring from: ${sourceChains.map((c) => c.name).join(", ")}`);
    console.log(`Transferring to: ${destinationChain.name}\n`);

    // Create and sign burn intents for each source chain
    const requests = [];

    for (const sourceChain of sourceChains) {
      console.log(
        `Creating burn intent from ${sourceChain.name} → ${destinationChain.name}...`,
      );

      const burnIntent = {
        maxBlockHeight: maxUint256,
        maxFee: MAX_FEE,
        spec: {
          version: 1,
          sourceDomain: sourceChain.domainId,
          destinationDomain: destinationChain.domainId,
          sourceContract: GATEWAY_WALLET_ADDRESS,
          destinationContract: GATEWAY_MINTER_ADDRESS,
          sourceToken: sourceChain.usdcAddress,
          destinationToken: destinationChain.usdcAddress,
          sourceDepositor: account.address,
          destinationRecipient: account.address,
          sourceSigner: account.address,
          destinationCaller: zeroAddress,
          value: TRANSFER_VALUE,
          salt: "0x" + randomBytes(32).toString("hex"),
          hookData: "0x",
        },
      };

      const typedData = {
        types: { EIP712Domain, TransferSpec, BurnIntent },
        domain,
        primaryType: "BurnIntent" as const,
        message: {
          ...burnIntent,
          spec: {
            ...burnIntent.spec,
            sourceContract: pad(
              burnIntent.spec.sourceContract.toLowerCase() as `0x${string}`,
              { size: 32 },
            ),
            destinationContract: pad(
              burnIntent.spec.destinationContract.toLowerCase() as `0x${string}`,
              { size: 32 },
            ),
            sourceToken: pad(
              burnIntent.spec.sourceToken.toLowerCase() as `0x${string}`,
              { size: 32 },
            ),
            destinationToken: pad(
              burnIntent.spec.destinationToken.toLowerCase() as `0x${string}`,
              { size: 32 },
            ),
            sourceDepositor: pad(
              burnIntent.spec.sourceDepositor.toLowerCase() as `0x${string}`,
              { size: 32 },
            ),
            destinationRecipient: pad(
              burnIntent.spec.destinationRecipient.toLowerCase() as `0x${string}`,
              { size: 32 },
            ),
            sourceSigner: pad(
              burnIntent.spec.sourceSigner.toLowerCase() as `0x${string}`,
              { size: 32 },
            ),
            destinationCaller: pad(
              burnIntent.spec.destinationCaller.toLowerCase() as `0x${string}`,
              { size: 32 },
            ),
          },
        },
      };

      const signature = await account.signTypedData(
        typedData as Parameters<typeof account.signTypedData>[0],
      );
      requests.push({ burnIntent: typedData.message, signature });
    }

    console.log("Signed burn intents.\n");
    ```

    <Note>
      **Note:** For production apps, verifying the balance on each chain before
      creating burn intents is best practice. For this how-to, it's assumed that the
      balances are created per the [prerequisites](#prerequisites). For a complete
      end-to-end example that includes checking and error handling, see the Gateway
      quickstarts ([EVM](/gateway/quickstarts/unified-balance-evm),
      [Solana](/gateway/quickstarts/unified-balance-solana)).
    </Note>

    ### Step 2. Submit the burn intents to the Gateway API to obtain an attestation

    Add the following code to `transfer.ts`. This code constructs a Gateway API
    request to the
    [`/transfer`](/api-reference/gateway/all/create-transfer-attestation) endpoint
    and obtains the attestation from that endpoint.

    ```ts transfer.ts theme={null}
    console.log("Submitting to Gateway API...");
    const response = await fetch(
      "https://gateway-api-testnet.circle.com/v1/transfer",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(requests, (_key, value) =>
          typeof value === "bigint" ? value.toString() : value,
        ),
      },
    );

    if (!response.ok) {
      console.error("Gateway API error status:", response.status);
      console.error(await response.text());
      throw new Error("Gateway API request failed");
    }

    const json = await response.json();
    console.log("Gateway API response:", JSON.stringify(json, null, 2));

    const { attestation, signature } = json;
    ```

    ### Step 3. Transfer USDC to the destination chain

    Add the following code to `transfer.ts`. This code performs a call to the
    [Gateway Minter contract](/gateway/references/contract-interfaces-and-events#gatewayminter)
    on Sei Testnet to instantly mint the USDC to your account on that chain.

    ```ts transfer.ts theme={null}
    console.log(`\nMinting funds on ${destinationChain.chain.name}...`);

    const publicClient = createPublicClient({
      chain: destinationChain.chain,
      transport: http(),
    });

    const walletClient = createWalletClient({
      account,
      chain: destinationChain.chain,
      transport: http(),
    });

    const gatewayMinter = getContract({
      address: GATEWAY_MINTER_ADDRESS,
      abi: gatewayMinterAbi,
      client: walletClient,
    });

    const mintTx = await gatewayMinter.write.gatewayMint([attestation, signature], {
      account,
    });
    await publicClient.waitForTransactionReceipt({ hash: mintTx });

    const totalMinted = BigInt(requests.length) * TRANSFER_VALUE;
    console.log(`\nMinted ${formatUnits(totalMinted, 6)} USDC`);
    console.log(`Mint transaction hash:`, mintTx);
    ```

    ### Step 4. Run the script

    Run the script with the following command:

    ```shell theme={null}
    npx tsx --env-file=.env transfer.ts
    ```
  </Tab>

  <Tab title="Solana">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared Solana Devnet wallets (sender and recipient) and have the private key
      pairs exported as JSON arrays
    * Funded your testnet wallet with USDC and native tokens
    * [Deposited 10 USDC into the Gateway Wallet](/gateway/howtos/create-unified-usdc-balance)
      contract on Solana Devnet
    * Created a TypeScript project and have the following dependencies installed:
      * `@solana/web3.js`
      * `@solana/spl-token`
      * `@coral-xyz/anchor`
      * `@solana/buffer-layout`
      * `bn.js`
      * `bs58`
    * You've set up a `.env` file with the following variable:

      ```text .env theme={null}
      SOLANA_PRIVATE_KEYPAIR={YOUR_SOLANA_KEYPAIR_ARRAY}
      RECIPIENT_KEYPAIR={YOUR_RECIPIENT_KEYPAIR_ARRAY}
      ```

    <Note>
      To generate a new Solana key pair, run:

      ```shell theme={null}
      solana-keygen new -o keypair.json --no-bip39-passphrase
      ```

      Copy the byte array from the JSON file to your `.env` file.

      If your wallet exports a private key hash instead, you can use `bs58` to convert
      it:

      ```ts TypeScript theme={null}
      const bytes = bs58.decode({ YOUR_PRIVATE_KEY_HASH });
      console.log(JSON.stringify(Array.from(bytes)));
      ```
    </Note>

    ## Steps

    Follow these steps to transfer a unified USDC balance from Solana to another
    Solana account. You can adapt this example for crosschain transfers.

    ### Step 1. Set up your Solana client and helpers

    Create a new file called `transfer.ts` in the root of your project and add the
    following code. This code imports required dependencies and defines constants
    for the Solana connection, Gateway addresses, and transfer parameters.

    ```ts transfer.ts theme={null}
    import { randomBytes } from "node:crypto";
    import * as crypto from "crypto";
    import {
      Wallet,
      AnchorProvider,
      setProvider,
      Program,
      utils,
    } from "@coral-xyz/anchor";
    import {
      Connection,
      Keypair,
      PublicKey,
      SystemProgram,
      Transaction,
      sendAndConfirmTransaction,
    } from "@solana/web3.js";
    import {
      TOKEN_PROGRAM_ID,
      getAssociatedTokenAddressSync,
      createAssociatedTokenAccountIdempotentInstruction,
    } from "@solana/spl-token";
    import {
      u32be,
      nu64be,
      struct,
      seq,
      blob,
      offset,
      Layout,
    } from "@solana/buffer-layout";
    import bs58 from "bs58";

    /* Constants */
    const RPC_ENDPOINT = "https://api.devnet.solana.com";
    const GATEWAY_WALLET_ADDRESS = "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
    const GATEWAY_MINTER_ADDRESS = "GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr";
    const USDC_ADDRESS = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
    const SOLANA_ZERO_ADDRESS = "11111111111111111111111111111111";

    const SOLANA_DOMAIN = 5;
    const TRANSFER_AMOUNT = 2; // 2 USDC
    const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
    const MAX_FEE = 2_010000n;
    const MAX_UINT64 = 2n ** 64n - 1n;

    const TRANSFER_SPEC_MAGIC = 0xca85def7;
    const BURN_INTENT_MAGIC = 0x070afbc2;
    ```

    ### Step 2. Set up buffer layouts and IDL

    Add the following code to `transfer.ts` to define custom layout classes for
    serialization, structures for encoding burn intents and decoding attestations,
    and the Gateway Minter IDL. Solana doesn't support EIP-712 typed data, so burn
    intents must be encoded manually using buffer layouts.

    ```ts transfer.ts expandable theme={null}
    // Custom layout for Solana PublicKey (32 bytes)
    class PublicKeyLayout extends Layout<PublicKey> {
      constructor(property: string) {
        super(32, property);
      }
      decode(b: Buffer, offset = 0): PublicKey {
        return new PublicKey(b.subarray(offset, offset + 32));
      }
      encode(src: PublicKey, b: Buffer, offset = 0): number {
        const pubkeyBuffer = src.toBuffer();
        pubkeyBuffer.copy(b, offset);
        return 32;
      }
    }

    const publicKey = (property: string) => new PublicKeyLayout(property);

    // Custom layout for 256-bit unsigned integers
    class UInt256BE extends Layout<bigint> {
      constructor(property: string) {
        super(32, property);
      }
      decode(b: Buffer, offset = 0) {
        const buffer = b.subarray(offset, offset + 32);
        return buffer.readBigUInt64BE(24);
      }
      encode(src: bigint, b: Buffer, offset = 0) {
        const buffer = Buffer.alloc(32);
        buffer.writeBigUInt64BE(BigInt(src), 24);
        buffer.copy(b, offset);
        return 32;
      }
    }

    const uint256be = (property: string) => new UInt256BE(property);

    // Type 'as any' used due to @solana/buffer-layout's incomplete TypeScript definitions (archived Jan 2025)
    const BurnIntentLayout = struct([
      u32be("magic"),
      uint256be("maxBlockHeight"),
      uint256be("maxFee"),
      u32be("transferSpecLength"),
      struct(
        [
          u32be("magic"),
          u32be("version"),
          u32be("sourceDomain"),
          u32be("destinationDomain"),
          publicKey("sourceContract"),
          publicKey("destinationContract"),
          publicKey("sourceToken"),
          publicKey("destinationToken"),
          publicKey("sourceDepositor"),
          publicKey("destinationRecipient"),
          publicKey("sourceSigner"),
          publicKey("destinationCaller"),
          uint256be("value"),
          blob(32, "salt"),
          u32be("hookDataLength"),
          blob(offset(u32be(), -4), "hookData"),
        ] as any,
        "spec",
      ),
    ] as any);

    const MintAttestationElementLayout = struct([
      publicKey("destinationToken"),
      publicKey("destinationRecipient"),
      nu64be("value"),
      blob(32, "transferSpecHash"),
      u32be("hookDataLength"),
      blob(offset(u32be(), -4), "hookData"),
    ] as any);

    const MintAttestationSetLayout = struct([
      u32be("magic"),
      u32be("version"),
      u32be("destinationDomain"),
      publicKey("destinationContract"),
      publicKey("destinationCaller"),
      nu64be("maxBlockHeight"),
      u32be("numAttestations"),
      seq(MintAttestationElementLayout, offset(u32be(), -4), "attestations"),
    ] as any);

    // Sample-local IDL subset for this example.
    const gatewayMinterIdl = {
      address: GATEWAY_MINTER_ADDRESS,
      metadata: { name: "gatewayMinter", version: "0.1.0", spec: "0.1.0" },
      instructions: [
        {
          name: "gatewayMint",
          discriminator: [12, 0],
          accounts: [
            { name: "payer", writable: true, signer: true },
            { name: "destinationCaller", signer: true },
            { name: "gatewayMinter" },
            { name: "systemProgram" },
            { name: "tokenProgram" },
            { name: "eventAuthority" },
            { name: "program" },
          ],
          args: [
            { name: "params", type: { defined: { name: "gatewayMintParams" } } },
          ],
        },
      ],
      types: [
        {
          name: "gatewayMintParams",
          type: {
            kind: "struct",
            fields: [
              { name: "attestation", type: "bytes" },
              { name: "signature", type: "bytes" },
            ],
          },
        },
      ],
    };
    ```

    ### Step 3. Define helper functions

    Add the following code to `transfer.ts` to define helper functions for creating,
    encoding, and signing burn intents, converting addresses between formats,
    decoding attestations from the Gateway API, and finding Program Derived
    Addresses (PDAs). The signing process uses Ed25519 with a specific prefix
    required by the Gateway Wallet program.

    ```ts transfer.ts expandable theme={null}
    function createBurnIntent(params: {
      sourceDepositor: string;
      destinationRecipient: string;
      sourceSigner: string;
    }) {
      const { sourceDepositor, destinationRecipient, sourceSigner } = params;

      return {
        maxBlockHeight: MAX_UINT64,
        maxFee: MAX_FEE,
        spec: {
          version: 1,
          sourceDomain: SOLANA_DOMAIN,
          destinationDomain: SOLANA_DOMAIN,
          sourceContract: addressToBytes32(GATEWAY_WALLET_ADDRESS),
          destinationContract: addressToBytes32(GATEWAY_MINTER_ADDRESS),
          sourceToken: addressToBytes32(USDC_ADDRESS),
          destinationToken: addressToBytes32(USDC_ADDRESS),
          sourceDepositor: addressToBytes32(sourceDepositor),
          destinationRecipient: addressToBytes32(destinationRecipient),
          sourceSigner: addressToBytes32(sourceSigner),
          destinationCaller: addressToBytes32(SOLANA_ZERO_ADDRESS),
          value: TRANSFER_VALUE,
          salt: "0x" + randomBytes(32).toString("hex"),
          hookData: "0x",
        },
      };
    }

    function encodeBurnIntent(bi: any): Buffer {
      const hookData = Buffer.from((bi.spec.hookData || "0x").slice(2), "hex");
      const prepared = {
        magic: BURN_INTENT_MAGIC,
        maxBlockHeight: bi.maxBlockHeight,
        maxFee: bi.maxFee,
        transferSpecLength: 340 + hookData.length,
        spec: {
          magic: TRANSFER_SPEC_MAGIC,
          version: bi.spec.version,
          sourceDomain: bi.spec.sourceDomain,
          destinationDomain: bi.spec.destinationDomain,
          sourceContract: hexToPublicKey(bi.spec.sourceContract),
          destinationContract: hexToPublicKey(bi.spec.destinationContract),
          sourceToken: hexToPublicKey(bi.spec.sourceToken),
          destinationToken: hexToPublicKey(bi.spec.destinationToken),
          sourceDepositor: hexToPublicKey(bi.spec.sourceDepositor),
          destinationRecipient: hexToPublicKey(bi.spec.destinationRecipient),
          sourceSigner: hexToPublicKey(bi.spec.sourceSigner),
          destinationCaller: hexToPublicKey(bi.spec.destinationCaller),
          value: bi.spec.value,
          salt: Buffer.from(bi.spec.salt.slice(2), "hex"),
          hookDataLength: hookData.length,
          hookData,
        },
      };
      const buffer = Buffer.alloc(72 + 340 + hookData.length);
      const bytesWritten = BurnIntentLayout.encode(prepared, buffer);
      return buffer.subarray(0, bytesWritten);
    }

    function signBurnIntent(keypair: Keypair, payload: any): string {
      const encoded = encodeBurnIntent(payload);
      const prefixed = Buffer.concat([
        Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
        encoded,
      ]);
      const privateKey = crypto.createPrivateKey({
        key: Buffer.concat([
          Buffer.from("302e020100300506032b657004220420", "hex"),
          Buffer.from(keypair.secretKey.slice(0, 32)),
        ]),
        format: "der",
        type: "pkcs8",
      });
      return `0x${crypto.sign(null, prefixed, privateKey).toString("hex")}`;
    }

    function addressToBytes32(address: string): string {
      const decoded = Buffer.from(bs58.decode(address));
      return `0x${decoded.toString("hex")}`;
    }

    function hexToPublicKey(hex: string): PublicKey {
      return new PublicKey(Buffer.from(hex.slice(2), "hex"));
    }

    function decodeAttestationSet(attestation: string) {
      const buffer = Buffer.from(attestation.slice(2), "hex");
      return MintAttestationSetLayout.decode(buffer) as {
        attestations: Array<{
          destinationToken: PublicKey;
          destinationRecipient: PublicKey;
          transferSpecHash: Uint8Array;
        }>;
      };
    }

    function findCustodyPda(
      mint: PublicKey,
      minterProgramId: PublicKey,
    ): PublicKey {
      return PublicKey.findProgramAddressSync(
        [Buffer.from("gateway_minter_custody"), mint.toBuffer()],
        minterProgramId,
      )[0];
    }

    function findTransferSpecHashPda(
      transferSpecHash: Uint8Array | Buffer,
      minterProgramId: PublicKey,
    ): PublicKey {
      return PublicKey.findProgramAddressSync(
        [Buffer.from("used_transfer_spec_hash"), Buffer.from(transferSpecHash)],
        minterProgramId,
      )[0];
    }
    ```

    ### Step 4. Set up the environment and create the burn intent

    Add the following code to `transfer.ts` to load keypairs from environment
    variables, create a Solana connection, set up the recipient's Associated Token
    Account, and create and sign the burn intent.

    <Info>
      For transfers to Solana, the `destinationRecipient` must be an initialized
      USDC Token Account. If the intended recipient is a standard wallet address,
      consider setting the `destinationRecipient` to its Associated Token Account
      (ATA) not the recipient wallet address. See the [Solana Technical
      Guide](/gateway/references/solana#reducedmintattestation) and [Solana Programs
      and Interfaces](/gateway/references/solana-programs#gatewaymint) for
      high-level Solana guidance and `gatewayMint` account requirements. Use the
      onchain IDLs linked from [Solana Programs and
      Interfaces](/gateway/references/solana-programs#account-structures) as the
      canonical static instruction and account definitions.
    </Info>

    ```ts transfer.ts theme={null}
    if (!process.env.SOLANA_PRIVATE_KEYPAIR)
      throw new Error("SOLANA_PRIVATE_KEYPAIR not set");
    if (!process.env.RECIPIENT_KEYPAIR)
      throw new Error("RECIPIENT_KEYPAIR not set");

    const senderKeypair = Keypair.fromSecretKey(
      Uint8Array.from(JSON.parse(process.env.SOLANA_PRIVATE_KEYPAIR)),
    );
    const recipientKeypair = Keypair.fromSecretKey(
      Uint8Array.from(JSON.parse(process.env.RECIPIENT_KEYPAIR)),
    );
    const connection = new Connection(RPC_ENDPOINT, "confirmed");
    const usdcMint = new PublicKey(USDC_ADDRESS);

    console.log(`Using account: ${senderKeypair.publicKey.toBase58()}`);
    console.log(`Transferring from: Solana Devnet → Solana Devnet\n`);

    // Create recipient's Associated Token Account
    const recipientAta = getAssociatedTokenAddressSync(
      usdcMint,
      recipientKeypair.publicKey,
    );

    console.log("Creating recipient's Associated Token Account...");
    const createAtaIx = createAssociatedTokenAccountIdempotentInstruction(
      senderKeypair.publicKey,
      recipientAta,
      recipientKeypair.publicKey,
      usdcMint,
    );
    const tx = new Transaction().add(createAtaIx);
    await sendAndConfirmTransaction(connection, tx, [senderKeypair]);
    console.log(`Recipient ATA: ${recipientAta.toBase58()}\n`);

    // Create and sign burn intent
    console.log(`Creating burn intent from Solana Devnet → Solana Devnet...`);
    const burnIntent = createBurnIntent({
      sourceDepositor: senderKeypair.publicKey.toBase58(),
      destinationRecipient: recipientAta.toBase58(),
      sourceSigner: senderKeypair.publicKey.toBase58(),
    });

    const burnIntentSignature = signBurnIntent(senderKeypair, burnIntent);
    const request = [{ burnIntent, signature: burnIntentSignature }];
    console.log("Signed burn intent.\n");
    ```

    ### Step 5. Submit to Gateway API and decode the attestation

    Add the following code to `transfer.ts` to submit the burn intent to the Gateway
    API, obtain an attestation, and decode the attestation set for use in the mint
    operation.

    ```ts transfer.ts theme={null}
    console.log("Submitting to Gateway API...");
    const response = await fetch(
      "https://gateway-api-testnet.circle.com/v1/transfer",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(request, (_key, value) =>
          typeof value === "bigint" ? value.toString() : value,
        ),
      },
    );

    const json = await response.json();
    if (json.success === false) {
      throw new Error(`Gateway API error: ${json.message}`);
    }
    console.log("Gateway API response:", JSON.stringify(json, null, 2));

    const { attestation, signature: mintSignature } = json;
    const decoded = decodeAttestationSet(attestation);
    ```

    ### Step 6. Mint USDC on the destination chain

    Add the following code to `transfer.ts` to set up the Anchor program, prepare
    the required accounts, and call the Gateway Minter to mint USDC on Solana Devnet
    using the attestation from the previous step.

    <Info>
      The ordered remaining-account list and PDA derivations are documented in
      [Solana Programs and
      Interfaces](/gateway/references/solana-programs#gatewaymint). For static
      instruction definitions, use the onchain IDLs linked from that page.
    </Info>

    ```ts transfer.ts theme={null}
    const minterProgramId = new PublicKey(GATEWAY_MINTER_ADDRESS);
    const anchorWallet = new Wallet(senderKeypair);
    const provider = new AnchorProvider(
      connection,
      anchorWallet,
      AnchorProvider.defaultOptions(),
    );
    setProvider(provider);
    const minterProgram = new Program(gatewayMinterIdl, provider);

    const [minterPda] = PublicKey.findProgramAddressSync(
      [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
      minterProgramId,
    );

    // Mint on Solana
    const remainingAccounts = decoded.attestations.flatMap((e) => [
      {
        pubkey: findCustodyPda(e.destinationToken, minterProgramId),
        isWritable: true,
        isSigner: false,
      },
      { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
      {
        pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
        isWritable: true,
        isSigner: false,
      },
    ]);

    const attestationBytes = Buffer.from(attestation.slice(2), "hex");
    const signatureBytes = Buffer.from(mintSignature.slice(2), "hex");

    console.log("\nMinting funds on Solana Devnet...");
    const mintTx = await minterProgram.methods
      .gatewayMint({ attestation: attestationBytes, signature: signatureBytes })
      .accountsPartial({
        gatewayMinter: minterPda,
        destinationCaller: senderKeypair.publicKey,
        payer: senderKeypair.publicKey,
        systemProgram: SystemProgram.programId,
        tokenProgram: TOKEN_PROGRAM_ID,
      })
      .remainingAccounts(remainingAccounts)
      .signers([senderKeypair])
      .rpc();

    // Wait for confirmation
    const latest = await connection.getLatestBlockhash();
    await connection.confirmTransaction(
      {
        signature: mintTx,
        blockhash: latest.blockhash,
        lastValidBlockHeight: latest.lastValidBlockHeight,
      },
      "confirmed",
    );

    console.log(`\nMinted ${Number(TRANSFER_VALUE) / 1_000_000} USDC`);
    console.log(`Mint transaction hash:`, mintTx);
    ```

    ### Step 7. Run the script

    Run the script with the following command:

    ```shell theme={null}
    npx tsx --env-file=.env transfer.ts
    ```
  </Tab>
</Tabs>


# Nanopayments
Source: https://developers.circle.com/gateway/nanopayments

Gas-free USDC nanopayments down to $0.000001, powered by Circle Gateway batched settlement

Circle Gateway enables gas-free USDC nanopayments by batching thousands of
payments into a single onchain transaction. Instead of settling each payment
individually, buyers sign offchain authorizations and Gateway settles net
positions in bulk, eliminating per-transaction gas costs and making sub-cent
payments economically viable. Nanopayments power agentic commerce by giving
developers and AI agents a financial rail purpose-built for high-frequency
agentic payments at scale.

## Key features

<CardGroup>
  <Card title="Gas-free transfers" icon="gas-pump">
    Buyers sign payment authorizations offchain at zero gas cost. Gateway
    settles in bulk, so neither party pays per-transaction fees.
  </Card>

  <Card title="Sub-cent minimums" icon="coins">
    Send as little as \$0.000001 USDC per payment. Batched settlement keeps fees
    from exceeding the payment itself.
  </Card>

  <Card title="Crosschain liquidity" icon="arrow-right-arrow-left">
    Sellers receive payments in their Gateway balance and can withdraw to any
    supported blockchain.
  </Card>
</CardGroup>

## What you can build

<AccordionGroup>
  <Accordion title="Agentic payments" icon="robot">
    Enable AI agents to pay autonomously for compute, data, memory, and services.
    Agents transact at high frequency and extreme granularity, executing thousands
    of sub-cent payments per minute without gas friction. For the agent-builder
    workflow, see [Agent Nanopayments](/agent-stack/agent-nanopayments).
  </Accordion>

  <Accordion title="Usage-based billing" icon="chart-line">
    Charge per API call, per second of compute, or per dataset access. With
    transaction costs near zero, fine-grained billing models become practical for
    the first time.
  </Accordion>

  <Accordion title="Machine-to-machine marketplaces" icon="network-wired">
    Build decentralized marketplaces where services, models, and data is priced and
    traded in real time at sub-cent granularity.
  </Accordion>

  <Accordion title="Streaming value" icon="wave-sine">
    Implement pay-per-second content, micro-rewards, and continuous value flows
    where traditional payment rails are too expensive to operate.
  </Accordion>
</AccordionGroup>

## How it works

Nanopayments enables the [x402 protocol](/gateway/nanopayments/concepts/x402),
an open standard built on the HTTP `402 Payment Required` status code, by using
Circle Gateway's
[batched settlement](/gateway/nanopayments/concepts/batched-settlement)
infrastructure. Instead of settling each x402 payment individually onchain,
Gateway aggregates signed payment authorizations and settles net positions in
bulk. This is what makes sub-cent x402 payments economically viable.

The end-to-end flow is:

1. A buyer deposits USDC into a Gateway Wallet contract (one-time onchain
   transaction).
2. A buyer requests a paid resource from a seller's API.
3. The seller responds with `402 Payment Required` and payment details.
4. The buyer signs an EIP-3009 payment authorization (offchain, zero gas).
5. The buyer retries the request with the signed authorization attached.
6. The seller verifies the signature and serves the resource immediately.
7. Gateway collects authorizations and settles them in batches onchain,
   crediting the seller's Gateway balance.

## Get started

<CardGroup>
  <Card title="Quickstart: Buy side" icon="cart-shopping" href="/gateway/nanopayments/quickstarts/buyer">
    Deposit USDC, pay for an x402-protected resource without gas fees, and check
    your balance
  </Card>

  <Card title="Quickstart: Sell side" icon="store" href="/gateway/nanopayments/quickstarts/seller">
    Add payment middleware to your Express API and start accepting gasless USDC
    payments
  </Card>

  <Card title="What is x402?" icon="circle-info" href="/gateway/nanopayments/concepts/x402">
    Learn about the open payment protocol that powers Nanopayments
  </Card>

  <Card title="How batched settlement works" icon="layer-group" href="/gateway/nanopayments/concepts/batched-settlement">
    Understand how Gateway aggregates payments and settles them onchain
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/gateway/all/settle-x402payment">
    Explore the API endpoints for Nanopayments
  </Card>
</CardGroup>


# How Batched Settlement Works
Source: https://developers.circle.com/gateway/nanopayments/concepts/batched-settlement

How Circle Gateway aggregates payment authorizations and settles them onchain in a single transaction

Circle Gateway enables nanopayments by batching many individual payment
authorizations into a single onchain transaction. Instead of settling each
payment separately (and paying gas each time), Gateway collects signed
authorizations offchain, computes net balance changes, and applies them in bulk.

This document explains the batching lifecycle, the security model that keeps it
non-custodial, and how balances move through the system.

## The economics of batching

Settling a USDC transfer onchain costs gas. Even on low-fee blockchains, gas
costs can exceed the value of a sub-cent payment. Batching solves this by
amortizing gas across thousands of payments:

| Approach              | Gas cost per payment              | Viable minimum payment            |
| --------------------- | --------------------------------- | --------------------------------- |
| Individual settlement | Full gas per transaction          | \~\$0.01+ (depends on blockchain) |
| Batched settlement    | Gas / number of payments in batch | \$0.000001                        |

By settling net positions rather than individual transfers, Gateway reduces both
the number of onchain transactions and the total gas consumed.

## Payment lifecycle

A nanopayment moves through five stages from initiation to settlement:

```mermaid theme={null}
sequenceDiagram
    participant Buyer
    participant Seller
    participant Gateway as Circle Gateway

    Buyer->>Gateway: 1. Deposit USDC (one-time onchain tx)

    Buyer->>Seller: 2. Request resource
    Seller-->>Buyer: 402 Payment Required

    Note left of Buyer: Signs EIP-3009 authorization (offchain, zero gas)

    Buyer->>Seller: 3. Retry with signed authorization
    Seller->>Gateway: 4. Submit authorization
    Seller-->>Buyer: 200 OK + resource

    Note right of Gateway: Collects authorizations

    Gateway->>Gateway: 5. Batch settle (single onchain tx)
    Gateway-->>Seller: Funds credited to balance
```

<Steps>
  <Step title="Deposit">
    The buyer deposits USDC from their wallet into a Gateway Wallet contract.
    This is a one-time onchain transaction that establishes the buyer's Gateway
    balance. Once deposited, the buyer can make gasless payments from this
    balance.
  </Step>

  <Step title="Request and negotiate">
    The buyer requests a paid resource. The seller responds with `402 Payment
            Required`, including payment details. This follows the standard [x402
    protocol flow](/gateway/nanopayments/concepts/x402).
  </Step>

  <Step title="Sign authorization">
    The buyer signs an [EIP-3009](/gateway/nanopayments/howtos/eip-3009-signing)
    `TransferWithAuthorization` message authorizing Gateway to transfer USDC
    from their balance to the seller. This signature is created offchain and
    costs zero gas. The buyer retries the request with the signed authorization
    attached.
  </Step>

  <Step title="Settle and serve">
    The seller (or a facilitator) submits the signed authorization to Gateway.
    Gateway verifies the signature, locks the buyer's funds, and credits the
    seller's pending balance. The seller serves the resource immediately,
    without waiting for onchain settlement. Neither the buyer nor the seller
    pays gas for this step.
  </Step>

  <Step title="Batch and onchain settlement">
    Gateway periodically collects pending authorizations, computes net balance
    changes across all participants, and submits a single onchain transaction
    that applies the changes. After onchain confirmation, pending balances
    become available. The seller can then withdraw funds to any supported
    blockchain.
  </Step>
</Steps>

## Security model

Gateway's batching system is non-custodial. Gateway never has arbitrary control
over user funds. The security model relies on three components:

### Trusted execution environment (TEE)

A Trusted Execution Environment (TEE) is an isolated hardware enclave that runs
code in a secure, tamper-proof environment. Gateway uses an AWS Nitro Enclave
to:

* Verify every EIP-3009 signature before including it in a batch
* Compute net balance changes across all payments in the batch
* Sign the batch result with the enclave's private key

The enclave's signing key is protected by AWS Key Management Service (KMS) with
attestation-based access policies. Only the audited enclave image can access the
key. Even Circle operators cannot extract it outside the enclave.

### Onchain verification

The Gateway Wallet smart contract verifies the TEE's signature before executing
any batch. If the signature is invalid or comes from an unauthorized signer, the
contract reverts. This ensures that only correctly computed batches are applied
onchain.

### Cryptographic attestations

AWS Nitro Enclaves produce cryptographic attestation documents that prove the
enclave is running a specific, audited code image. These attestations can be
independently verified, providing transparency into the batching process.

## Balance states

Gateway tracks funds through multiple states as they move through the batching
pipeline:

| State       | Description                                                                      |
| ----------- | -------------------------------------------------------------------------------- |
| `available` | Spendable balance. Set after deposit or after receiving a settled batch payment. |

### Example: Alice sends 10 USDC to Bob

| Event                   | Alice (sender)   | Bob (receiver)  |
| ----------------------- | ---------------- | --------------- |
| Initial state           | `available: 100` | `available: 0`  |
| Authorization submitted | `available: 90`  | `available: 0`  |
| Batch settled onchain   | `available: 90`  | `available: 10` |

When Alice submits her authorization, Gateway locks her funds internally. Once
the batch settles onchain, Bob's available balance increases.

## Withdrawal

After settlement, sellers (and buyers) can withdraw their Gateway balance to any
supported blockchain. Same-chain withdrawals are instant. Crosschain withdrawals
use Gateway's standard minting infrastructure and are also near instant.


# What is x402?
Source: https://developers.circle.com/gateway/nanopayments/concepts/x402

An overview of the x402 open payment standard and how Nanopayments provides a gasless payment method for x402-protected resources

x402 is an open, neutral standard for internet-native payments built on the HTTP
`402 Payment Required` status code. It defines how a server communicates that
payment is required to access a resource, and how a client can provide proof of
payment. x402 is not a payment system itself—it is a negotiation protocol that
is agnostic to how payments are constructed, verified, or settled.

This document explains the x402 protocol, its core concepts, and how
Nanopayments provides a gasless payment method that works with x402.

## The problem with internet payments

Traditional payment systems were not designed for programmatic, high-frequency
transactions. Credit cards carry high fixed fees, require account creation, and
involve slow settlement. Standard onchain payments require gas for every
transaction, making sub-cent payments uneconomical. Neither approach works well
for AI agents, per-request billing, or machine-to-machine commerce.

x402 addresses this by making payment negotiation a native part of HTTP. A
server declares that payment is required, a client provides a payment payload,
and the exchange happens in a single request-response cycle. The actual payment
method is flexible—any scheme that can produce a verifiable payment payload can
work with x402.

## How x402 works

The x402 protocol uses three HTTP headers to negotiate payment between a client
and a server:

| Header              | Direction        | Purpose                                                                |
| ------------------- | ---------------- | ---------------------------------------------------------------------- |
| `PAYMENT-REQUIRED`  | Server to client | Payment requirements (accepted schemes, price, network, destination)   |
| `PAYMENT-SIGNATURE` | Client to server | Signed payment payload proving the client has authorized payment       |
| `PAYMENT-RESPONSE`  | Server to client | Confirmation that the payment was verified, returned with the resource |

The typical flow is:

```mermaid theme={null}
sequenceDiagram
    participant Client as Client (Buyer)
    participant Server as Server (Seller)

    Client->>Server: 1. GET /resource
    Server-->>Client: 2. 402 Payment Required + PAYMENT-REQUIRED header

    Note left of Client: Signs payment payload

    Client->>Server: 3. GET /resource + PAYMENT-SIGNATURE header

    Note right of Server: Verifies payment

    Server-->>Client: 4. 200 OK + resource + PAYMENT-RESPONSE header
```

1. The client requests a paid resource.
2. The server responds with `402 Payment Required`, including payment details
   such as the accepted payment schemes, price, network, and destination
   address.
3. The client selects a payment option, constructs and signs a payment payload,
   and retries the request with the `PAYMENT-SIGNATURE` header.
4. The server verifies the payment (directly or through a facilitator) and
   returns the resource along with a confirmation in the `PAYMENT-RESPONSE`
   header.

x402 defines this negotiation flow. How the payment payload is constructed, how
it is verified, and how funds ultimately move are determined by the payment
method and facilitator, not by x402 itself.

## Core concepts

### Buyers and sellers

* **Buyer (client)**: The entity requesting a paid resource. This can be a
  human-operated application, an AI agent, or any programmatic HTTP client.
  Buyers construct payment payloads using whatever payment method the server
  accepts.
* **Seller (server)**: The resource provider that requires payment. Sellers
  declare their accepted payment methods in the `402` response, verify incoming
  payment payloads, and serve the resource when payment is valid. Any
  HTTP-accessible API or service can act as a seller.

### Facilitators

A facilitator is an optional service that handles payment verification and
settlement on behalf of sellers. By using a facilitator, sellers avoid needing
to verify payment payloads or interact with blockchain infrastructure
themselves.

Different facilitators can support different payment methods. A seller connects
to a facilitator and automatically gains access to the payment methods that
facilitator supports.

### Payment schemes

x402 is designed to support multiple payment schemes. A payment scheme defines
how payment payloads are constructed, signed, and verified. The `402` response
from a server lists the schemes it accepts, and the client picks one it can
fulfill.

Nanopayments uses the `exact` scheme with a custom EIP-3009
`TransferWithAuthorization` signature against the `GatewayWalletBatched` domain,
enabling gasless payments from the buyer's Gateway balance.

## How Nanopayments fits in

x402 defines the negotiation—a server says "pay me" and a client responds with a
payment payload. But x402 does not prescribe how those payments are funded,
verified, or settled. That is where Nanopayments comes in.

Nanopayments is a payment method for x402 that uses Circle Gateway's
[batched settlement](/gateway/nanopayments/concepts/batched-settlement)
infrastructure:

* Buyers fund their payments from a Gateway Wallet balance (deposited once
  onchain).
* When a server requests payment via `402`, the buyer signs an offchain EIP-3009
  authorization (zero gas) and includes it in the `PAYMENT-SIGNATURE` header.
* The server (or its facilitator) submits the authorization to Gateway for
  verification and settlement.
* Gateway collects authorizations and settles net positions in bulk onchain,
  paying gas once per batch instead of once per payment.

From x402's perspective, Nanopayments is just another payment method. Clients
and servers use the same `402` negotiation flow—the difference is that the
underlying payment is gasless and settled through batching.

## Learn more

* [How batched settlement works](/gateway/nanopayments/concepts/batched-settlement):
  the mechanics of Gateway's batching system
* [x402.org](https://www.x402.org/): the official x402 website
* [x402 documentation](https://docs.x402.org/): the full protocol specification
* [x402 GitHub repository](https://github.com/coinbase/x402): the open source
  reference implementation


# How-to: Sign EIP-3009 Payment Authorizations
Source: https://developers.circle.com/gateway/nanopayments/howtos/eip-3009-signing

Manually construct and sign EIP-3009 TransferWithAuthorization messages for Circle Gateway batched payments

## Overview

* Construct and sign EIP-3009 `TransferWithAuthorization` messages that
  authorize Circle Gateway to transfer USDC from your Gateway balance.
* Use this when integrating payment signing into a custom workflow, building a
  non-JavaScript client, or understanding the signing mechanism that the SDK
  handles automatically.

## Prerequisites

Before you begin, ensure you have:

* An EVM wallet with a private key for signing.
* Deposited USDC in a Gateway Wallet contract (see the
  [buyer quickstart](/gateway/nanopayments/quickstarts/buyer)).
* Familiarity with [EIP-712](https://eips.ethereum.org/EIPS/eip-712) typed data
  signing.
* Installed the [viem](https://viem.sh/) library (`npm install viem`).

## Steps

### Step 1. Construct the EIP-712 domain

Gateway uses a custom EIP-712 domain named `GatewayWalletBatched`. This is
specific to Gateway's batching feature and is not the standard USDC domain.

```ts sign.ts theme={null}
const domain = {
  name: "GatewayWalletBatched",
  version: "1",
  chainId: 5042002, // Arc Testnet — replace with your target chain's EVM chain ID
  verifyingContract: "0x0077777d7EBA4688BDeF3E311b846F25870A19B9", // GatewayWallet on Arc Testnet
};
```

The `verifyingContract` is the GatewayWallet contract address for the blockchain
you are transacting on. Find the address for your target chain in the
[EVM contract addresses](/gateway/references/contract-addresses) reference. You
can also retrieve it programmatically using `getVerifyingContract()` from the
SDK or from the `402` response's `accepts` array (in the
`extra.verifyingContract` field).

<Warning>
  The `chainId` must be the standard EVM chain ID for your target network (for
  example, `5042002` for Arc Testnet), not the Gateway domain identifier. Using
  the wrong chain ID causes the signature to fail silently.
</Warning>

### Step 2. Define the typed data

The `TransferWithAuthorization` type follows the
[EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) specification:

```ts sign.ts theme={null}
const types = {
  TransferWithAuthorization: [
    { name: "from", type: "address" },
    { name: "to", type: "address" },
    { name: "value", type: "uint256" },
    { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" },
    { name: "nonce", type: "bytes32" },
  ],
};
```

Populate the message fields.

USDC uses 6 decimal places: `$1.00` = `1000000`, `$0.01` = `10000`, `$0.001` =
`1000`. Always convert dollar amounts to base units before signing.

```ts sign.ts theme={null}
import { randomBytes } from "crypto";

const message = {
  from: "0xYOUR_ADDRESS", // Your wallet address (the payer)
  to: "0xSELLER_ADDRESS", // The seller's wallet address
  value: 10000n, // Amount in USDC base units (0.01 USDC = 10000)
  validAfter: 0n, // Signature is valid immediately
  validBefore: BigInt(Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 5), // Valid for 5 days
  nonce: `0x${randomBytes(32).toString("hex")}`, // Unique random nonce
};
```

<Warning>
  The `validBefore` timestamp must be at least 3 days in the future. Gateway
  rejects signatures with shorter validity periods to ensure there is enough time
  to include them in a settlement batch.
</Warning>

### Step 3. Sign the typed data

Use the `viem` library's `signTypedData` to produce the EIP-712 signature:

```ts sign.ts theme={null}
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

const signature = await account.signTypedData({
  domain,
  types,
  primaryType: "TransferWithAuthorization",
  message,
});

console.log("Signature:", signature);
```

### Step 4. Assemble and send the payment payload

Encode the payment payload as base64 JSON and attach it to your HTTP request in
the `Payment-Signature` header. The server-side facilitator settles this payment
through the [Settle x402 Payment](/api-reference/gateway/all/settle-x402payment)
API endpoint:

```ts sign.ts theme={null}
const paymentPayload = {
  x402Version: 2,
  payload: {
    authorization: {
      from: message.from,
      to: message.to,
      value: message.value.toString(),
      validAfter: message.validAfter.toString(),
      validBefore: message.validBefore.toString(),
      nonce: message.nonce,
    },
    signature,
  },
  resource: "...", // from 402 response
  accepted: {}, // the payment option chosen
};

const encoded = Buffer.from(JSON.stringify(paymentPayload)).toString("base64");

const response = await fetch("http://localhost:3000/premium-data", {
  headers: {
    "Payment-Signature": encoded,
  },
});

console.log("Status:", response.status);
console.log("Body:", await response.json());
```

### Step 5. Use `BatchEvmScheme` for the x402 protocol (alternative)

If you are integrating with an existing x402 client (such as `@x402/core`), use
the `BatchEvmScheme` class instead of constructing the payload manually. It
handles domain construction, nonce generation, and payload encoding:

```ts sign-x402.ts theme={null}
import { BatchEvmScheme } from "@circle-fin/x402-batching/client";

const batchScheme = new BatchEvmScheme({
  address: account.address,
  signTypedData: async (params) => account.signTypedData(params),
});

// Get requirements from a 402 response
const res = await fetch(url);
const header = res.headers.get("PAYMENT-REQUIRED");
const { accepts } = JSON.parse(Buffer.from(header, "base64").toString());
const gatewayOption = accepts.find(
  (opt) => opt.extra?.name === "GatewayWalletBatched",
);

// Create the payment payload
const payload = await batchScheme.createPaymentPayload(2, gatewayOption);

// Retry with the payload
const finalResponse = await fetch(url, {
  headers: {
    "Payment-Signature": Buffer.from(
      JSON.stringify({ ...payload, accepted: gatewayOption }),
    ).toString("base64"),
  },
});
```

## Troubleshoot `invalid_signature`

Gateway returns `invalid_signature` for any EIP-712 domain or field mismatch
without specifying which field is wrong. If your signature is rejected, check
every item in this list:

* **Domain name** must be exactly `"GatewayWalletBatched"`. Common mistakes
  include `"GatewayWallet"`, `"Gateway"`, and `"USDC"`.
* **`verifyingContract`** must be the GatewayWallet contract address, not the
  USDC token address or GatewayMinter. See
  [EVM contract addresses](/gateway/references/contract-addresses) for the
  correct address on each chain.
* **`chainId`** must be the standard EVM chain ID (for example, `5042002` for
  Arc Testnet). Do not use the Gateway domain identifier.
* **`nonce`** must be a unique random 32-byte value for every payment. Reusing a
  nonce causes the same `invalid_signature` error.
* **`validBefore`** must be at least 3 days in the future. Shorter validity
  periods are rejected with `authorization_validity_too_short`.
* **`value`** must be in USDC base units (6 decimals). Passing a dollar amount
  instead of base units causes an amount mismatch.
* **`from`** must match the address derived from the private key that signed the
  message.

For the full list of error codes, see the
[error reference](/gateway/nanopayments/references/sdk#gateway-api-error-codes).

<Note>
  The EIP-712 domain for payment authorizations (`GatewayWalletBatched`) is
  different from the domain used for Gateway withdrawal and crosschain transfer
  operations (`GatewayWallet`). If you are building manual signing for both
  payments and withdrawals, use the correct domain for each operation. The SDK's
  `client.withdraw()` and `client.pay()` methods handle this automatically.
</Note>


# How-to: Integrate Nanopayments into Your Existing Facilitator
Source: https://developers.circle.com/gateway/nanopayments/howtos/facilitator-integration

Add nanopayments gas-free settlement to your x402 facilitator service

## Overview

* Add nanopayments as a settlement provider to your x402 facilitator so that
  sellers connected to your facilitator automatically gain access to gas-free,
  batched payments.
* Use this guide if you operate an x402 facilitator service and want to offer
  Gateway settlement alongside your existing onchain settlement methods.

<Note>
  This guide is for infrastructure providers and payment processors running x402
  facilitators.
</Note>

## Prerequisites

Before you begin, ensure you have:

* An existing x402 facilitator service using `@x402/core`.
* [Node.js](https://nodejs.org/) v18+ installed.
* Familiarity with the [x402 protocol](/gateway/nanopayments/concepts/x402) and
  how facilitators verify and settle payments.

## Steps

### Step 1. Install the SDK

Install `@circle-fin/x402-batching` alongside its required peer dependencies:

```shell theme={null}
npm install @circle-fin/x402-batching @x402/core viem
```

### Step 2. Initialize the `BatchFacilitatorClient`

The `BatchFacilitatorClient` handles all communication with Circle Gateway,
including verification via the
[Verify x402 Payment](/api-reference/gateway/all/verify-x402payment) API
endpoint, settlement via the
[Settle x402 Payment](/api-reference/gateway/all/settle-x402payment) API
endpoint, and supported-network discovery via the
[Get Supported x402 Payment Kinds](/api-reference/gateway/all/get-supported-x402payment-kinds)
API endpoint.

```ts theme={null}
import { BatchFacilitatorClient } from "@circle-fin/x402-batching/server";

const gatewayClient = new BatchFacilitatorClient();
```

### Step 3. Route payments by type

Your facilitator acts as a router. Use `isBatchPayment()` to detect Gateway
payments and delegate them to the `BatchFacilitatorClient`. Route all other
payments to your existing onchain logic.

Gateway payments are identified by the `extra` metadata field:
`extra.name === "GatewayWalletBatched"`.

```ts theme={null}
import { isBatchPayment } from "@circle-fin/x402-batching/server";

async function handleVerify(
  payload: PaymentPayload,
  requirements: PaymentRequirements,
) {
  if (isBatchPayment(requirements)) {
    return gatewayClient.verify(payload, requirements);
  }
  return existingOnChainHandler.verify(payload, requirements);
}

async function handleSettle(
  payload: PaymentPayload,
  requirements: PaymentRequirements,
) {
  if (isBatchPayment(requirements)) {
    return gatewayClient.settle(payload, requirements);
  }
  return existingOnChainHandler.settle(payload, requirements);
}

async function handleSupported() {
  const gateway = await gatewayClient.getSupported();
  const existing = await existingOnChainHandler.getSupported();

  return {
    kinds: [...existing.kinds, ...gateway.kinds],
    extensions: [...existing.extensions, ...gateway.extensions],
    signers: { ...existing.signers, ...gateway.signers },
  };
}
```

<Note>
  Gateway's `settle()` endpoint is optimized for low latency and guarantees
  settlement. Use `settle()` directly rather than calling `verify()` followed by
  `settle()` in production flows.
</Note>

### Step 4. Wire up HTTP endpoints

Expose your routing logic through standard x402 facilitator endpoints:

```ts theme={null}
app.post("/v1/x402/verify", async (req, res) => {
  const { paymentPayload, paymentRequirements } = req.body;
  const response = await handleVerify(paymentPayload, paymentRequirements);
  res.json(response);
});

app.post("/v1/x402/settle", async (req, res) => {
  const { paymentPayload, paymentRequirements } = req.body;
  const response = await handleSettle(paymentPayload, paymentRequirements);
  res.json(response);
});
```

### Step 5. Connect sellers to your facilitator

Once your facilitator supports Gateway, sellers connect to it and automatically
gain access to both standard and gas-free payment options.

#### Using `x402ResourceServer`

Sellers using `x402ResourceServer` connect to your facilitator with
`HTTPFacilitatorClient`:

```ts theme={null}
import { x402ResourceServer } from "@x402/core/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const server = new x402ResourceServer([
  new HTTPFacilitatorClient({ url: "https://your-facilitator-service.com" }),
]);

await server.initialize();
```

#### Using `createGatewayMiddleware`

Sellers using the Gateway middleware can route verification and settlement
through your facilitator by setting `facilitatorUrl`:

```ts theme={null}
import { createGatewayMiddleware } from "@circle-fin/x402-batching/server";

const gateway = createGatewayMiddleware({
  sellerAddress: "0xSELLER_ADDRESS",
  facilitatorUrl: "https://your-facilitator-service.com",
});
```

### Alternative: Gas-free-only facilitator

If you are building a new facilitator that only needs to support gas-free
payments (without standard onchain settlement), use `BatchFacilitatorClient`
directly with `x402ResourceServer`:

```shell theme={null}
npm install @x402/core @x402/express @x402/evm
```

```ts theme={null}
import { x402ResourceServer } from "@x402/core/server";
import { BatchFacilitatorClient } from "@circle-fin/x402-batching/server";

const server = new x402ResourceServer([new BatchFacilitatorClient()]);

await server.initialize();
```

#### Using `GatewayEvmScheme` with `x402ResourceServer`

When using `x402ResourceServer` with `BatchFacilitatorClient`, register
`GatewayEvmScheme` to ensure payment requirements include the metadata that
Gateway clients need for EIP-712 signing. `GatewayEvmScheme` extends the
standard `ExactEvmScheme` to:

* Preserve `extra` metadata (`verifyingContract`, `name`, `version`) in payment
  requirements
* Set `maxTimeoutSeconds` to 604900 (7 days plus a small buffer) for batched
  settlement
* Register USDC money parsers for all Gateway-supported networks

```ts theme={null}
import { x402ResourceServer } from "@x402/express";
import {
  BatchFacilitatorClient,
  GatewayEvmScheme,
} from "@circle-fin/x402-batching/server";

const circleClient = new BatchFacilitatorClient();
const server = new x402ResourceServer([circleClient]);
server.register("eip155:*", new GatewayEvmScheme());
await server.initialize();
```

<Note>
  The base `ExactEvmScheme` discards the `extra` field from supported kinds when
  building payment requirements. Gateway clients require `extra.verifyingContract`
  to construct valid EIP-712 signatures. `GatewayEvmScheme` preserves this data.
</Note>

## See also

* [SDK reference](/gateway/nanopayments/references/sdk) for
  `BatchFacilitatorClient` and `GatewayEvmScheme` API details
* [Seller quickstart](/gateway/nanopayments/quickstarts/seller) for setting up a
  seller with `createGatewayMiddleware`
* [How batched settlement works](/gateway/nanopayments/concepts/batched-settlement)
  for background on the batching lifecycle


# How-to: Add Nanopayments to an x402 Buyer
Source: https://developers.circle.com/gateway/nanopayments/howtos/x402-buyer

Add gas-free nanopayments to your x402 client alongside standard onchain payments

## Overview

* Add nanopayments to an existing x402 client so it can pay gas-free when a
  server supports it, while still falling back to standard onchain payments when
  it does not.
* Gas-free payments require a one-time USDC deposit into a Gateway Wallet
  contract. After depositing, all subsequent payments are offchain signatures
  with zero gas cost.
* Your existing onchain payment flows continue to work unchanged. The client
  automatically selects the right payment method based on what the server
  offers.

## Prerequisites

Before you begin, ensure you have:

* An existing x402 client using `@x402/core`.
* [Node.js](https://nodejs.org/) v18+ installed.
* An EVM wallet private key for signing.
* Testnet USDC from the [Circle Faucet](https://faucet.circle.com) (for Gateway
  deposits).

## Steps

### Step 1. Install the SDK

```shell theme={null}
npm install @circle-fin/x402-batching
```

If you plan to use `CompositeEvmScheme` (recommended for supporting both payment
methods), also install:

```shell theme={null}
npm install @x402/evm
```

### Step 2. Choose your integration approach

Pick the option that best fits your setup.

#### Option A: Support both Gateway and standard payments (recommended)

Use `CompositeEvmScheme` to route automatically based on the server's payment
requirements. When the server offers a Gateway option, the client uses
`BatchEvmScheme` for a gas-free payment. When only standard onchain options are
available, it falls back to `ExactEvmScheme`:

```ts theme={null}
import { ExactEvmScheme } from "@x402/evm/exact/client";
import {
  CompositeEvmScheme,
  BatchEvmScheme,
} from "@circle-fin/x402-batching/client";

const composite = new CompositeEvmScheme(
  new BatchEvmScheme(signer),
  new ExactEvmScheme(signer),
);

client.register("eip155:*", composite);
```

No per-request routing code is needed. `CompositeEvmScheme` checks each payment
option's `extra.name` field and delegates to the correct scheme automatically.

#### Option B: Add Gateway support to an existing client

If you already have scheme registrations and want to add Gateway support with
minimal changes while keeping standard onchain payments available:

```ts theme={null}
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { registerBatchScheme } from "@circle-fin/x402-batching/client";

registerBatchScheme(client, {
  signer: account,
  fallbackScheme: new ExactEvmScheme(account),
});
```

#### Option C: Gateway only

If you only need gas-free payments and don't need standard onchain support, use
`GatewayClient` directly. See the
[buyer quickstart](/gateway/nanopayments/quickstarts/buyer) for a full
walkthrough.

### Step 3. Deposit USDC into Gateway

Before making gas-free payments, deposit USDC from your wallet into the Gateway
Wallet contract. This is a one-time onchain transaction:

```ts theme={null}
import { GatewayClient } from "@circle-fin/x402-batching/client";

const gatewayClient = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

const balances = await gatewayClient.getBalances();
if (balances.gateway.available < 1_000_000n) {
  await gatewayClient.deposit("1");
}
```

`getBalances()` calls the
[Get Token Balances](/api-reference/gateway/all/get-token-balances) API
endpoint. After the deposit confirms, your Gateway balance is available for
gas-free payments to any server that supports nanopayments. See the discussion
at [Fast deposits](/gateway/references/supported-blockchains#fast-deposits)
about increasing deposit speeds.

### Step 4. Check support before paying

Before attempting a gas-free payment, check whether the target server supports
Gateway. The `supports()` method requests the target URL, checks for a `402`
response, and inspects the `PAYMENT-REQUIRED` header for a compatible Gateway
batching option:

```ts theme={null}
const support = await gatewayClient.supports(
  "https://api.example.com/resource",
);

if (!support.supported) {
  console.log("Server does not support Gateway -- falling back to onchain");
}
```

If you are using `CompositeEvmScheme`, this check is optional since the scheme
handles fallback automatically.

### Step 5. Understand deposit finality

When you deposit USDC into Gateway, the API waits for block confirmations before
your balance becomes available. Wait times vary by blockchain:

| Blockchain                                                                                                | Deposit time |
| --------------------------------------------------------------------------------------------------------- | ------------ |
| Arc Testnet                                                                                               | \~0.5 sec    |
| Avalanche Fuji                                                                                            | \~8 sec      |
| HyperEVM Testnet, Sei Atlantic                                                                            | \~5 sec      |
| Polygon PoS Amoy, Sonic Testnet                                                                           | \~8 sec      |
| Arbitrum Sepolia, Base Sepolia, Ethereum Sepolia, Optimism Sepolia, Unichain Sepolia, World Chain Sepolia | \~13-19 min  |

<Tip>
  To avoid long deposit wait times, see the discussion at
  [Fast deposits](/gateway/references/supported-blockchains#fast-deposits) about
  third party services that offer fast deposits. Alternatively, use
  [Bridge Kit](https://developers.circle.com/circle-mint/docs/bridgekit-quickstart)
  to bridge your USDC to a fast-finality blockchain before depositing into Gateway
  so your `GatewayClient` can deposit and pay from that chain.

  ```ts theme={null}
  import { BridgeKit } from "@circle-fin/bridge-kit";

  const bridge = new BridgeKit();

  const transfer = await bridge.transfer({
    sourceChain: "base-sepolia",
    destinationChain: "arc-testnet",
    amount: "10",
    token: "USDC",
  });
  await bridge.waitForCompletion(transfer.id);

  const client = new GatewayClient({
    chain: "arcTestnet",
    privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  });
  await client.deposit("10");
  ```
</Tip>

### Step 6. Withdraw funds (optional)

Withdraw USDC from Gateway back to your wallet at any time. Withdrawals are
instant for both same-blockchain and crosschain destinations. The `withdraw()`
method calls the
[Create Transfer Attestation](/api-reference/gateway/all/create-transfer-attestation)
API endpoint:

```ts theme={null}
await gatewayClient.withdraw("5");

await gatewayClient.withdraw("5", { chain: "baseSepolia" });
```

### Step 7. Monitor transfers (optional)

After paying for resources, you can look up individual transfers using the
[Get x402 Transfer by ID](/api-reference/gateway/all/get-x402transfer-by-id) API
endpoint, or search across transfer history using the
[Search x402 Transfers](/api-reference/gateway/all/search-x402transfers) API
endpoint:

```ts theme={null}
const { transfers, pagination } = await gatewayClient.searchTransfers({
  status: "received",
  pageSize: 20,
});

const transferUUID = transfers[0]?.id;

if (transferUUID) {
  try {
    const transfer = await gatewayClient.getTransferById(transferUUID);

    console.log({
      id: transfer.id,
      status: transfer.status,
      amount: transfer.amount,
    });
  } catch (error) {
    console.error("Could not load transfer", error);
  }
}

if (pagination?.pageAfter) {
  const nextPage = await gatewayClient.searchTransfers({
    status: "received",
    pageSize: 20,
    pageAfter: pagination.pageAfter,
  });
}
```

`searchTransfers` supports filtering by sender, recipient, network, status,
token, and date range. When `network` is omitted, the client defaults to the
client's configured blockchain. See the
[SDK reference](/gateway/nanopayments/references/sdk) for the full list of
parameters.

## See also

* [Use nanopayments with x402](/gateway/nanopayments/howtos/x402-integration)
  for a summary of all integration paths
* [x402 seller integration](/gateway/nanopayments/howtos/x402-seller) for the
  server-side counterpart
* [SDK reference](/gateway/nanopayments/references/sdk) for
  `CompositeEvmScheme`, `BatchEvmScheme`, and `registerBatchScheme` API details


# How-to: Use Nanopayments with x402
Source: https://developers.circle.com/gateway/nanopayments/howtos/x402-integration

Add gas-free nanopayments alongside your existing x402 onchain payment flows

Nanopayments integrates with existing x402 setups at every layer of the stack.
It is **additive**: it introduces gas-free payments as a new option alongside
standard onchain x402 payments, without replacing them. Sellers automatically
accept both methods, and buyers choose whichever they have funded.

## Install the SDK

```shell theme={null}
npm install @circle-fin/x402-batching
```

## Integration paths

Choose the guides that match your role in the x402 ecosystem.

<CardGroup>
  <Card title="Buyer (client-side)" icon="cart-shopping" href="/gateway/nanopayments/howtos/x402-buyer">
    Add nanopayments to your x402 client so it can pay gas-free when servers
    support it
  </Card>

  <Card title="Seller (server-side)" icon="store" href="/gateway/nanopayments/howtos/x402-seller">
    Add gas-free nanopayments to your existing x402 server alongside your
    current payment flows
  </Card>

  <Card title="Facilitator" icon="server" href="/gateway/nanopayments/howtos/facilitator-integration">
    Route Gateway payments alongside onchain payments in your facilitator
    service
  </Card>
</CardGroup>

### Seller (server-side)

Add `BatchFacilitatorClient` and `GatewayEvmScheme` to your existing server.
Your `402` responses then include both standard and Gateway payment options:

```ts theme={null}
import { x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import {
  BatchFacilitatorClient,
  GatewayEvmScheme,
} from "@circle-fin/x402-batching/server";

const server = new x402ResourceServer([
  new HTTPFacilitatorClient({ url: "https://facilitator.example.com" }),
  new BatchFacilitatorClient(),
]);
server.register("eip155:*", new GatewayEvmScheme());
await server.initialize();
```

See [Full seller integration guide](/gateway/nanopayments/howtos/x402-seller).

### Buyer (client-side)

Use `CompositeEvmScheme` to handle both Gateway and standard payments
automatically. The client picks the right scheme based on what the server
offers:

```ts theme={null}
import { ExactEvmScheme } from "@x402/evm/exact/client";
import {
  CompositeEvmScheme,
  BatchEvmScheme,
} from "@circle-fin/x402-batching/client";

const composite = new CompositeEvmScheme(
  new BatchEvmScheme(signer),
  new ExactEvmScheme(signer),
);

client.register("eip155:*", composite);
```

See [Full buyer integration guide](/gateway/nanopayments/howtos/x402-buyer).

### Facilitator

Use `isBatchPayment()` to route Gateway payments to `BatchFacilitatorClient`
while your existing handler covers standard payments:

```ts theme={null}
import {
  BatchFacilitatorClient,
  isBatchPayment,
} from "@circle-fin/x402-batching/server";

const gatewayClient = new BatchFacilitatorClient();

async function handleSettle(payload, requirements) {
  if (isBatchPayment(requirements)) {
    return gatewayClient.settle(payload, requirements);
  }
  return existingOnChainHandler.settle(payload, requirements);
}
```

See
[Full facilitator integration guide](/gateway/nanopayments/howtos/facilitator-integration).

## How routing works

When both payment methods are available, routing is automatic at every layer:

| Layer       | What happens                                                                                                                                                                                                                              |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Server      | The `402` response lists both standard and Gateway options in the `accepts` array.                                                                                                                                                        |
| Client      | `CompositeEvmScheme` checks each option's `extra.name`. If `"GatewayWalletBatched"` is present, it uses `BatchEvmScheme`. Otherwise it uses `ExactEvmScheme`.                                                                             |
| Facilitator | `isBatchPayment()` checks the same `extra.name` field and routes [verify](/api-reference/gateway/all/verify-x402payment)/[settle](/api-reference/gateway/all/settle-x402payment) calls to either Gateway or the existing onchain handler. |

No manual routing code is needed in sellers or buyers. The SDK handles it based
on the payment requirements.


# How-to: Add Nanopayments to an x402 Seller
Source: https://developers.circle.com/gateway/nanopayments/howtos/x402-seller

Add gas-free nanopayments to your x402 resource server alongside standard onchain payments

## Overview

* Add nanopayments to an existing `x402ResourceServer` so it offers gas-free
  payments alongside your current payment flows.
* Your existing payment setup continues to work unchanged. The server includes
  nanopayment options in its `402` responses in addition to the options your
  facilitator already supports, and buyers choose whichever method they have
  funded.

## Prerequisites

Before you begin, ensure you have:

* An existing x402 seller using `@x402/express` or `@x402/core` with
  `x402ResourceServer`.
* [Node.js](https://nodejs.org/) v18+ installed.

## Steps

### Step 1. Install the SDK

```shell theme={null}
npm install @circle-fin/x402-batching @x402/evm
```

### Step 2. Add `BatchFacilitatorClient` to your server

Add `BatchFacilitatorClient` alongside your existing `HTTPFacilitatorClient`.
Each facilitator handles a different payment type -- your existing facilitator
continues to handle standard onchain payments, and `BatchFacilitatorClient`
handles Gateway payments:

```ts theme={null}
import { x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import {
  BatchFacilitatorClient,
  GatewayEvmScheme,
} from "@circle-fin/x402-batching/server";

const server = new x402ResourceServer([
  new HTTPFacilitatorClient({ url: "https://facilitator.example.com" }),
  new BatchFacilitatorClient(),
]);
```

### Step 3. Register `GatewayEvmScheme`

Replace `ExactEvmScheme` with `GatewayEvmScheme`. `GatewayEvmScheme` extends
`ExactEvmScheme`, so standard onchain payments continue to work. It also
preserves the `extra` metadata (such as `verifyingContract`) that Gateway
clients need for EIP-712 signing:

```ts theme={null}
server.register("eip155:*", new GatewayEvmScheme());
await server.initialize();
```

After initialization, the server's `402` responses include Gateway nanopayment
options in the `accepts` array alongside any options your existing facilitator
supports.

<Tip>
  If you don't have an existing onchain payment setup or are a new seller, you can
  add onchain payment support by connecting to an existing x402 facilitator using
  `HTTPFacilitatorClient`. See the [x402 documentation](https://docs.x402.org/)
  for a list of available facilitators.
</Tip>

### Step 4. Route through a custom facilitator (optional)

If you run your own x402 facilitator that supports Gateway (see
[facilitator integration](/gateway/nanopayments/howtos/facilitator-integration)),
you can route payments through it instead of connecting to Circle Gateway
directly. Use `facilitatorUrl` with `createGatewayMiddleware`:

```ts theme={null}
import { createGatewayMiddleware } from "@circle-fin/x402-batching/server";

const gateway = createGatewayMiddleware({
  sellerAddress: "0xSELLER_ADDRESS",
  facilitatorUrl: "https://your-facilitator.com",
});
```

### Step 5. Check your balance and withdraw

After buyers pay for your resources, funds accumulate in your Gateway balance.
Use `GatewayClient` to check your earnings via the
[Get Token Balances](/api-reference/gateway/all/get-token-balances) API endpoint
and withdraw via the
[Create Transfer Attestation](/api-reference/gateway/all/create-transfer-attestation)
API endpoint:

```ts theme={null}
import { GatewayClient } from "@circle-fin/x402-batching/client";

const client = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

const balances = await client.getBalances();
console.log(`Available: ${balances.gateway.formattedAvailable} USDC`);
console.log(`Total: ${balances.gateway.formattedTotal} USDC`);
```

Withdraw to your wallet on the same blockchain or to a different one:

```ts theme={null}
await client.withdraw("50");

await client.withdraw("50", { chain: "baseSepolia" });
```

<Note>
  Gateway handles settlement automatically. When you call `settle()` in the
  middleware, the payment is submitted for batched processing. Your Gateway
  `available` balance increases after the batch settles onchain.
</Note>

### Step 6. Verify the integration

The server's `402` responses should now include Gateway options alongside
standard options. Check the `accepts` array for entries with:

```ts theme={null}
extra.name === "GatewayWalletBatched";
```

If both standard and Gateway entries are present, the server is correctly
offering both payment methods.

## See also

* [Use nanopayments with x402](/gateway/nanopayments/howtos/x402-integration)
  for a summary of all integration paths
* [x402 buyer integration](/gateway/nanopayments/howtos/x402-buyer) for the
  client-side counterpart
* [SDK reference](/gateway/nanopayments/references/sdk) for `GatewayEvmScheme`
  and `BatchFacilitatorClient` API details


# Quickstart: Pay for Resources with Nanopayments
Source: https://developers.circle.com/gateway/nanopayments/quickstarts/buyer

Deposit USDC into Gateway and make gasless payments to x402-protected APIs

In this quickstart, you will deposit USDC into a Gateway Wallet, pay for an
x402-protected resource without gas fees, and check your balance. By the end,
you'll have a working client that can make gasless payments to any
x402-compatible API that supports Circle Gateway.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v22+](https://nodejs.org/)
* An
  [EOA (externally owned account)](/wallets/account-types#externally-owned-accounts-eoa)
  wallet private key for signing transactions and payment authorizations.
* Obtained testnet USDC from the [Circle Faucet](https://faucet.circle.com).
* Testnet ETH (or native gas token) for the one-time deposit transaction.

<Warning>
  Nanopayments require an EOA wallet. Smart contract account (SCA) wallets are not
  supported because Gateway verifies payment signatures offchain using
  `ecrecover`, which is incompatible with EIP-1271 contract signatures.
</Warning>

## Step 1. Set up your project

### 1.1. Create the project and install dependencies

```shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir nanopayments-buyer
cd nanopayments-buyer
npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.pay="tsx --env-file=.env pay.ts"

# Install runtime dependencies
npm install @circle-fin/x402-batching viem tsx typescript

# Install dev dependencies
npm install --save-dev @types/node
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.3. Set environment variables

Open `.env` in your editor and add:

```text theme={null}
PRIVATE_KEY=YOUR_PRIVATE_KEY
```

* `PRIVATE_KEY` is the private key for the EOA you use to deposit USDC and sign
  nanopayment authorizations.

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

The `npm run pay` command loads variables from `.env` using Node.js native
env-file support.

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>

## Step 2: Initialize the client

Create a new file `pay.ts` and initialize the `GatewayClient` with your chain
and private key:

```ts pay.ts theme={null}
import { GatewayClient } from "@circle-fin/x402-batching/client";

const client = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});
```

The `chain` parameter determines which blockchain the client connects to for
deposits and withdrawals. See the
[SDK reference](/gateway/nanopayments/references/sdk) for all supported chain
names.

## Step 3: Deposit USDC into Gateway

Before you can make gasless payments, deposit USDC from your wallet into the
Gateway Wallet contract. This is a one-time onchain transaction:

```ts pay.ts theme={null}
const balances = await client.getBalances();
console.log(`Gateway balance: ${balances.gateway.formattedAvailable} USDC`);

// 1 USDC = 1_000_000 base units (6 decimals)
if (balances.gateway.available < 1_000_000n) {
  console.log("Depositing 1 USDC...");
  const deposit = await client.deposit("1");
  console.log(`Deposit tx: ${deposit.depositTxHash}`);
}
```

`getBalances()` calls the
[Get Token Balances](/api-reference/gateway/all/get-token-balances) API
endpoint. The deposit itself is an onchain transaction and does not use the
Gateway API.

After the deposit confirms, your Gateway balance can be used for gasless
payments to any supported seller. See the discussion at
[Fast deposits](/gateway/references/supported-blockchains#fast-deposits) about
increasing deposit speeds.

## Step 4: Pay for a resource

Add the payment logic to `pay.ts`. Call `client.pay()` with the URL of an
x402-protected resource. The client handles the full payment flow automatically:

1. Sends the initial request to the URL.
2. Receives the `402 Payment Required` response with payment details.
3. Signs an EIP-3009 authorization offchain (zero gas).
4. Retries the request with the `PAYMENT-SIGNATURE` header.

```ts pay.ts theme={null}
const url = "http://localhost:3000/premium-data";

const { data, status } = await client.pay(url);

console.log(`Status: ${status}`);
console.log("Response:", data);
```

Under the hood, `pay()` negotiates the `402` flow and submits the payment
through the [Settle x402 Payment](/api-reference/gateway/all/settle-x402payment)
API endpoint.

<Tip>
  Don't have a seller URL to test with? Set up a local test API in two minutes
  using the [seller quickstart](/gateway/nanopayments/quickstarts/seller).
</Tip>

## Step 5: Check your balance

Add balance checking after the payment using the
[Get Token Balances](/api-reference/gateway/all/get-token-balances) API
endpoint:

```ts pay.ts theme={null}
const updated = await client.getBalances();
console.log(`Wallet USDC: ${updated.wallet.formatted}`);
console.log(`Gateway available: ${updated.gateway.formattedAvailable}`);
```

## Step 6: Run the script

Run the complete script:

```shell theme={null}
npm run pay
```

You should see the deposit transaction (if needed), the response from the paid
resource, and your updated balance.

## Step 7: Withdraw funds (optional)

You can withdraw USDC from Gateway back to your wallet at any time. Same-chain
withdrawals are instant:

```ts pay.ts theme={null}
const result = await client.withdraw("5");
console.log(`Withdrew ${result.formattedAmount} USDC`);
console.log(`Tx: ${result.mintTxHash}`);
```

To withdraw to a different blockchain:

```ts pay.ts theme={null}
const crossChain = await client.withdraw("5", { chain: "baseSepolia" });
console.log(`Withdrew to ${crossChain.destinationChain}`);
```

<Note>
  Crosschain withdrawals require native gas tokens on the destination blockchain
  to cover the minting transaction.
</Note>

## Check support before paying

Before attempting a payment, you can verify that the target URL supports Gateway
batching. The `supports()` method requests the target URL, checks for a `402`
response, and inspects the `PAYMENT-REQUIRED` header for a compatible Gateway
batching option:

```ts theme={null}
const support = await client.supports(url);

if (!support.supported) {
  console.error("This URL does not support Gateway payments");
} else {
  const { data } = await client.pay(url);
}
```

This is useful when building clients that interact with APIs where Gateway
support is not guaranteed.


# Quickstart: Accept Payments with Nanopayments
Source: https://developers.circle.com/gateway/nanopayments/quickstarts/seller

Add gasless USDC payment support to your Express API using Circle Gateway

In this quickstart, you will add Circle Gateway payment middleware to an Express
API so that it accepts gasless USDC payments via the x402 protocol. By the end,
your API will return `402 Payment Required` for unpaid requests and serve
resources when a valid payment signature is provided.

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v22+](https://nodejs.org/)
* An EVM wallet address where you want to receive USDC payments

## Step 1: Set up your project

### 1.1. Create the project and install dependencies

```shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir nanopayments-seller
cd nanopayments-seller

npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="tsx server.ts"

# Install runtime dependencies
npm install @circle-fin/x402-batching @x402/core @x402/evm viem express tsx typescript

# Install dev dependencies
npm install --save-dev @types/node @types/express
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

## Step 2: Create the server

Create a new file `server.ts` with an Express app and the Gateway middleware:

```ts server.ts theme={null}
import express from "express";
import { createGatewayMiddleware } from "@circle-fin/x402-batching/server";
import { formatUnits } from "viem";

// Extended Express Request type to include payment information
type PaidRequest = express.Request & {
  payment?: {
    verified: boolean;
    payer: string;
    amount: string;
    network: string;
    transaction?: string;
  };
};

const app = express();

const gateway = createGatewayMiddleware({
  sellerAddress: "0xYOUR_WALLET_ADDRESS",
  facilitatorUrl: "https://gateway-api-testnet.circle.com",
});
```

Replace `0xYOUR_WALLET_ADDRESS` with a valid EVM address where you want to
receive payments. This quickstart uses Arc Testnet, so it points to the testnet
Gateway API. The middleware still accepts payments from
[all supported networks](/gateway/nanopayments/supported-networks).

## Step 3: Protect a route

Use `gateway.require()` to protect any route with a price. When a request
arrives without a valid payment, the middleware returns `402 Payment Required`
with the payment details. When a valid payment signature is attached, the
middleware settles it with Gateway using the
[Settle x402 Payment](/api-reference/gateway/all/settle-x402payment) API
endpoint and calls `next()`:

```ts server.ts theme={null}
app.get("/premium-data", gateway.require("$0.01"), (req: PaidRequest, res) => {
  const { payer, amount, network } = req.payment!;
  const formattedAmount = formatUnits(BigInt(amount), 6);
  console.log(`Paid ${formattedAmount} USDC by ${payer} on ${network}`);

  res.json({
    secret: "The treasure is hidden under the doormat.",
    paid_by: payer,
  });
});

app.listen(3000, () => {
  console.log("Server listening at http://localhost:3000");
});
```

## Step 4: Test the server

### 4.1. Start the server

```shell theme={null}
npm start
```

### 4.2. Send an unpaid request

In a separate terminal, use `curl` to verify the server returns a `402`
response:

```shell theme={null}
curl -i http://localhost:3000/premium-data
```

You should see a `402 Payment Required` response with a `PAYMENT-REQUIRED`
header. The header contains the payment options.

### 4.3. Pay with a buyer client

Use the [buyer quickstart](/gateway/nanopayments/quickstarts/buyer) client to
make a gasless payment to your server:

```ts theme={null}
import { GatewayClient } from "@circle-fin/x402-batching/client";

const client = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

const { data, status } = await client.pay("http://localhost:3000/premium-data");
console.log(`Status: ${status}`);
console.log("Data:", data);
```

If the payment succeeds, you'll see the JSON response from your protected
endpoint.

## Advanced: Use `BatchFacilitatorClient` directly

If you are not using Express, or need custom logic like dynamic pricing, use the
`BatchFacilitatorClient` directly. The `settle()` method calls the
[Settle x402 Payment](/api-reference/gateway/all/settle-x402payment) API
endpoint:

```ts server.ts expandable theme={null}
import { BatchFacilitatorClient } from "@circle-fin/x402-batching/server";

const facilitator = new BatchFacilitatorClient({
  url: "https://gateway-api-testnet.circle.com",
});

const requirements = {
  scheme: "exact",
  network: "eip155:5042002", // CAIP-2 identifier for Arc Testnet (chain ID 5042002)
  asset: "0x...", // USDC contract address on Arc Testnet — see supported chains reference
  amount: "10000", // 0.01 USDC
  maxTimeoutSeconds: 604900,
  payTo: "0xYOUR_ADDRESS", // seller address that receives the payment
  extra: {
    name: "GatewayWalletBatched",
    version: "1",
    verifyingContract: "0x...", // Gateway Wallet contract on Arc Testnet — see supported chains reference
  },
};

async function handleRequest(paymentSignature?: string) {
  if (!paymentSignature) {
    const paymentRequired = {
      x402Version: 2,
      resource: {
        url: "/premium-data",
        description: "Paid resource",
        mimeType: "application/json",
      },
      accepts: [requirements],
    };

    return {
      status: 402,
      headers: {
        "PAYMENT-REQUIRED": Buffer.from(
          JSON.stringify(paymentRequired),
        ).toString("base64"),
      },
      body: {},
    };
  }

  const payload = JSON.parse(
    Buffer.from(paymentSignature, "base64").toString("utf8"),
  );

  const settlement = await facilitator.settle(payload, requirements);

  if (!settlement.success) {
    return {
      status: 402,
      body: { error: "Settlement failed" },
    };
  }

  return {
    status: 200,
    body: { data: "Your paid content" },
  };
}
```

<Note>
  Gateway's `settle()` endpoint is optimized for low latency and guarantees
  settlement. Use `settle()` directly rather than calling `verify()` followed by
  `settle()` in production flows.
</Note>

## Limit accepted networks (optional)

By default, the middleware accepts payments from any Gateway-supported
blockchain, discovered through the
[Get Supported x402 Payment Kinds](/api-reference/gateway/all/get-supported-x402payment-kinds)
API endpoint. This maximizes your reach since any buyer with a Gateway balance
on one of those accepted networks can pay you.

If you need to restrict payments to specific networks:

```ts theme={null}
const gateway = createGatewayMiddleware({
  sellerAddress: "0x...",
  networks: ["eip155:5042002"], // Only accept Arc Testnet
});
```

<Note>
  Payment signatures must have at least 7 days plus a small buffer of validity.
  The `validBefore` timestamp in the buyer's EIP-3009 authorization must be at
  least 7 days in the future, or Gateway will reject it.
</Note>


# SDK Reference
Source: https://developers.circle.com/gateway/nanopayments/references/sdk

API reference for the @circle-fin/x402-batching SDK

This page documents the public API of the `@circle-fin/x402-batching` package,
which provides buyer and seller integrations for Circle Gateway nanopayments.

```shell theme={null}
npm install @circle-fin/x402-batching
```

## Buyer APIs

### `GatewayClient`

```ts theme={null}
import { GatewayClient } from "@circle-fin/x402-batching/client";
```

The primary client for buyers. Handles deposits, gasless payments, withdrawals,
and balance queries.

#### Constructor

```ts theme={null}
new GatewayClient(config: GatewayClientConfig)
```

| Parameter           | Type                 | Required | Description                                                             |
| ------------------- | -------------------- | -------- | ----------------------------------------------------------------------- |
| `config.chain`      | `SupportedChainName` | Yes      | Blockchain to connect to (for example, `'arcTestnet'`, `'baseSepolia'`) |
| `config.privateKey` | `Hex`                | Yes      | Private key for signing (`'0x...'`)                                     |
| `config.rpcUrl`     | `string`             | No       | Custom RPC URL (overrides the default for the chain)                    |

#### Properties

| Property       | Type           | Description                  |
| -------------- | -------------- | ---------------------------- |
| `address`      | `Address`      | The account's wallet address |
| `chainName`    | `string`       | Human-readable chain name    |
| `domain`       | `number`       | Gateway domain identifier    |
| `publicClient` | `PublicClient` | viem public client instance  |
| `walletClient` | `WalletClient` | viem wallet client instance  |

#### `deposit(amount, options?)`

Deposits USDC from your wallet into the Gateway Wallet contract. This is an
onchain transaction that requires gas.

| Parameter               | Type     | Required | Description                                    |
| ----------------------- | -------- | -------- | ---------------------------------------------- |
| `amount`                | `string` | Yes      | Amount in decimal USDC (for example, `'10.5'`) |
| `options.approveAmount` | `string` | No       | ERC-20 approval amount (defaults to `amount`)  |

Returns `Promise<DepositResult>`:

```ts theme={null}
interface DepositResult {
  approvalTxHash?: Hex;
  depositTxHash: Hex;
  amount: bigint;
  formattedAmount: string;
}
```

#### `pay<T>(url, options?)`

Pays for an x402-protected resource. Handles the full `402` negotiation flow
automatically: sends the request, receives payment requirements, signs the
authorization, and retries with the payment header.

| Parameter | Type          | Required | Description                                    |
| --------- | ------------- | -------- | ---------------------------------------------- |
| `url`     | `string`      | Yes      | URL of the x402-protected resource             |
| `options` | `RequestInit` | No       | Standard fetch options (method, body, headers) |

Returns `Promise<PayResult<T>>`:

```ts theme={null}
interface PayResult<T> {
  data: T;
  amount: bigint;
  formattedAmount: string;
  transaction: string;
  status: number;
}
```

#### `withdraw(amount, options?)`

Withdraws USDC from Gateway to your wallet. Supports same-chain (instant) and
crosschain withdrawals.

| Parameter           | Type                 | Required | Description                                     |
| ------------------- | -------------------- | -------- | ----------------------------------------------- |
| `amount`            | `string`             | Yes      | Amount in decimal USDC                          |
| `options.chain`     | `SupportedChainName` | No       | Destination blockchain (defaults to same chain) |
| `options.recipient` | `Address`            | No       | Recipient address (defaults to your address)    |

Returns `Promise<WithdrawResult>`:

```ts theme={null}
interface WithdrawResult {
  mintTxHash: Hex;
  amount: bigint;
  formattedAmount: string;
  sourceChain: string;
  destinationChain: string;
  recipient: Address;
}
```

#### `getBalances(address?)`

Returns both the wallet's USDC balance and the Gateway balance.

| Parameter | Type      | Required | Description                                         |
| --------- | --------- | -------- | --------------------------------------------------- |
| `address` | `Address` | No       | Address to query (defaults to the client's address) |

Returns `Promise<Balances>`:

```ts theme={null}
interface Balances {
  wallet: { balance: bigint; formatted: string };
  gateway: GatewayBalance;
}

interface GatewayBalance {
  total: bigint;
  available: bigint;
  withdrawing: bigint;
  withdrawable: bigint;
  formattedTotal: string;
  formattedAvailable: string;
}
```

#### `supports(url)`

Checks whether a URL supports Gateway batching before attempting payment.

| Parameter | Type     | Required | Description  |
| --------- | -------- | -------- | ------------ |
| `url`     | `string` | Yes      | URL to check |

Returns `Promise<SupportsResult>`:

```ts theme={null}
interface SupportsResult {
  supported: boolean;
  requirements?: Record<string, unknown>;
  error?: string;
}
```

#### `getTransferById(id)`

Fetches a single x402 transfer by its UUID.

| Parameter | Type     | Required | Description                   |
| --------- | -------- | -------- | ----------------------------- |
| `id`      | `string` | Yes      | UUID of the transfer to fetch |

Returns `Promise<TransferResponse>`:

```ts theme={null}
type TransferStatus =
  | "received"
  | "batched"
  | "confirmed"
  | "completed"
  | "failed";

interface TransferResponse {
  id: string;
  status: TransferStatus;
  token: "USDC";
  sendingNetwork: string;
  recipientNetwork: string;
  fromAddress: string;
  toAddress: string;
  amount: string;
  createdAt: string;
  updatedAt: string;
}
```

#### `searchTransfers(params?)`

Searches x402 transfers with optional filters and paginated results. When
`network` is omitted, the client defaults to its own blockchain.

| Parameter           | Type             | Required | Description                                                     |
| ------------------- | ---------------- | -------- | --------------------------------------------------------------- |
| `params.from`       | `Hex`            | No       | Filter by sender address                                        |
| `params.to`         | `Hex`            | No       | Filter by recipient address                                     |
| `params.network`    | `string`         | No       | CAIP-2 network ID (defaults to the client's blockchain)         |
| `params.status`     | `TransferStatus` | No       | Filter by transfer status                                       |
| `params.token`      | `'USDC'`         | No       | Filter by token type                                            |
| `params.startDate`  | `string`         | No       | ISO-8601 date; include transfers created on or after this date  |
| `params.endDate`    | `string`         | No       | ISO-8601 date; include transfers created on or before this date |
| `params.pageSize`   | `number`         | No       | Number of results per page                                      |
| `params.pageAfter`  | `string`         | No       | Cursor for the next page                                        |
| `params.pageBefore` | `string`         | No       | Cursor for the previous page                                    |

Returns `Promise<SearchTransfersResponse>`:

```ts theme={null}
interface SearchTransfersResponse {
  transfers: TransferResponse[];
  pagination?: CursorPagination;
}

interface CursorPagination {
  self?: string;
  first?: string;
  prev?: string;
  next?: string;
  pageAfter?: string;
  pageBefore?: string;
}
```

`self`, `first`, `prev`, and `next` are full pagination URLs parsed from the
HTTP `Link` header. `pageAfter` and `pageBefore` are the cursor values extracted
from those URLs, which you can pass back into `searchTransfers()` when
requesting the next or previous page.

Use `pagination.pageAfter` or `pagination.pageBefore` to request adjacent pages.

***

### `BatchEvmScheme`

```ts theme={null}
import { BatchEvmScheme } from "@circle-fin/x402-batching/client";
```

A `SchemeNetworkClient` implementation for Circle Gateway batched payments. Use
this when integrating with an existing `x402Client` instance or building a
custom payment flow.

#### Constructor

```ts theme={null}
new BatchEvmScheme(signer: BatchEvmSigner)
```

| Parameter | Type             | Required | Description                                        |
| --------- | ---------------- | -------- | -------------------------------------------------- |
| `signer`  | `BatchEvmSigner` | Yes      | Object with `address` and `signTypedData` function |

#### `createPaymentPayload(x402Version, paymentRequirements)`

Creates a signed payment payload by constructing and signing an EIP-3009
`TransferWithAuthorization` message.

| Parameter             | Type                  | Required | Description                          |
| --------------------- | --------------------- | -------- | ------------------------------------ |
| `x402Version`         | `number`              | Yes      | x402 protocol version (use `2`)      |
| `paymentRequirements` | `PaymentRequirements` | Yes      | Requirements from the `402` response |

Returns `Promise<PaymentPayload>`.

***

### `CompositeEvmScheme`

```ts theme={null}
import { CompositeEvmScheme } from "@circle-fin/x402-batching/client";
```

Routes payment requests between Gateway batched payments and standard onchain
payments. Use this when your client needs to support both payment methods
simultaneously.

#### Constructor

```ts theme={null}
new CompositeEvmScheme(batchScheme: BatchEvmScheme, fallbackScheme: SchemeNetworkClient)
```

| Parameter        | Type                  | Required | Description                                                       |
| ---------------- | --------------------- | -------- | ----------------------------------------------------------------- |
| `batchScheme`    | `BatchEvmScheme`      | Yes      | Handles Gateway batched payments                                  |
| `fallbackScheme` | `SchemeNetworkClient` | Yes      | Handles standard onchain payments (must use the `'exact'` scheme) |

#### Behavior

* If the payment requirements include `extra.name === "GatewayWalletBatched"`,
  delegates to `batchScheme`.
* Otherwise, delegates to `fallbackScheme`.

#### Usage

```ts theme={null}
import { ExactEvmScheme } from "@x402/evm/exact/client";
import {
  CompositeEvmScheme,
  BatchEvmScheme,
} from "@circle-fin/x402-batching/client";

const composite = new CompositeEvmScheme(
  new BatchEvmScheme(signer),
  new ExactEvmScheme(signer),
);

client.register("eip155:*", composite);
```

***

### `registerBatchScheme`

```ts theme={null}
import { registerBatchScheme } from "@circle-fin/x402-batching/client";
```

Helper that registers a `BatchEvmScheme` with an `x402Client`. If you need to
support both Gateway and standard onchain `exact` payments, pass a
`fallbackScheme` so one registration handles both paths:

```ts theme={null}
import { ExactEvmScheme } from "@x402/evm/exact/client";

registerBatchScheme(client, {
  signer: account,
  fallbackScheme: new ExactEvmScheme(account),
});
```

***

## Seller APIs

### `createGatewayMiddleware`

```ts theme={null}
import { createGatewayMiddleware } from "@circle-fin/x402-batching/server";
```

Creates Express-compatible middleware that handles x402 payment negotiation,
verification, and settlement.

#### Configuration

```ts theme={null}
createGatewayMiddleware(config: GatewayMiddlewareConfig)
```

| Parameter               | Type                 | Required | Description                                                                                                   |
| ----------------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `config.sellerAddress`  | `string`             | Yes      | Your wallet address for receiving payments                                                                    |
| `config.networks`       | `string \| string[]` | No       | Networks to accept (defaults to all supported)                                                                |
| `config.facilitatorUrl` | `string`             | No       | Custom facilitator URL for verify/settle. Routes through this facilitator instead of Circle Gateway directly. |
| `config.description`    | `string`             | No       | Resource description included in `402` responses                                                              |

#### `require(price)`

Returns Express middleware that requires payment for the route.

| Parameter | Type     | Description                                       |
| --------- | -------- | ------------------------------------------------- |
| `price`   | `string` | Price in USD (for example, `'$0.01'` or `'0.01'`) |

The middleware attaches payment information to `req.payment`:

```ts theme={null}
interface PaymentInfo {
  verified: boolean;
  payer: string;
  amount: string;
  network: string;
  transaction?: string;
}
```

***

### `BatchFacilitatorClient`

```ts theme={null}
import { BatchFacilitatorClient } from "@circle-fin/x402-batching/server";
```

A `FacilitatorClient` implementation that communicates with Circle Gateway's
x402 endpoints. Use this for custom server frameworks or when you need
fine-grained control over verification and settlement.

#### Constructor

```ts theme={null}
new BatchFacilitatorClient(config?: BatchFacilitatorConfig)
```

#### `verify(payload, requirements)`

Verifies a payment signature through the Gateway API.

| Parameter      | Type                  | Description                           |
| -------------- | --------------------- | ------------------------------------- |
| `payload`      | `PaymentPayload`      | The payment payload from the client   |
| `requirements` | `PaymentRequirements` | The payment requirements you declared |

Returns `Promise<VerifyResponse>`:

```ts theme={null}
interface VerifyResponse {
  isValid: boolean;
  invalidReason?: string;
  payer?: string;
}
```

#### `settle(payload, requirements)`

Submits a payment for batched settlement through the Gateway API. This is the
recommended method for production flows because it has low latency and
guarantees settlement.

| Parameter      | Type                  | Description                           |
| -------------- | --------------------- | ------------------------------------- |
| `payload`      | `PaymentPayload`      | The payment payload from the client   |
| `requirements` | `PaymentRequirements` | The payment requirements you declared |

Returns `Promise<SettleResponse>`:

```ts theme={null}
interface SettleResponse {
  success: boolean;
  errorReason?: string;
  payer?: string;
  transaction: string;
}
```

#### `getSupported()`

Fetches the payment kinds (networks and contract addresses) supported by
Gateway.

Returns `Promise<SupportedResponse>`:

```ts theme={null}
interface SupportedResponse {
  kinds: Array<{
    x402Version: number;
    scheme: string;
    network: string;
    extra?: { verifyingContract?: string };
  }>;
}
```

***

### `GatewayEvmScheme`

```ts theme={null}
import { GatewayEvmScheme } from "@circle-fin/x402-batching/server";
```

Server-side EVM scheme that extends `ExactEvmScheme` with Gateway-specific
behavior. Required when using `x402ResourceServer` with
`BatchFacilitatorClient`.

#### Constructor

```ts theme={null}
new GatewayEvmScheme();
```

No parameters required. On construction, it automatically registers USDC money
parsers for all Gateway-supported networks.

#### Key behaviors

* **`enhancePaymentRequirements()`**: Merges `extra` metadata
  (`verifyingContract`, `name`, `version`) from supported kinds into payment
  requirements. Sets `maxTimeoutSeconds` to `604900` (7 days plus a small
  buffer) for batched settlement.
* **USDC money parsers**: Automatically converts dollar amounts to USDC atomic
  units (6 decimals) for all supported networks using the USDC addresses from
  `CHAIN_CONFIGS`.

<Note>
  The base `ExactEvmScheme` discards the `extra` field from supported kinds when
  building payment requirements. Gateway clients require `extra.verifyingContract`
  to construct valid EIP-712 signatures. `GatewayEvmScheme` preserves this data.
</Note>

#### Usage

```ts theme={null}
import { x402ResourceServer } from "@x402/express";
import {
  BatchFacilitatorClient,
  GatewayEvmScheme,
} from "@circle-fin/x402-batching/server";

const server = new x402ResourceServer([new BatchFacilitatorClient()]);
server.register("eip155:*", new GatewayEvmScheme());
await server.initialize();
```

***

## Utilities

### `supportsBatching`

```ts theme={null}
import { supportsBatching } from "@circle-fin/x402-batching";
```

Checks whether a `PaymentRequirements` object supports Gateway batched
settlement. Returns `true` if the requirements include the
`GatewayWalletBatched` scheme.

### `isBatchPayment`

```ts theme={null}
import { isBatchPayment } from "@circle-fin/x402-batching/server";
```

Server-side alias for `supportsBatching`. Use this in facilitator routing logic
to determine whether a payment should be routed to Gateway.

### `getVerifyingContract`

```ts theme={null}
import { getVerifyingContract } from "@circle-fin/x402-batching";
```

Extracts the Gateway Wallet contract address from a `PaymentRequirements`
object.

***

## Constants

```ts theme={null}
import {
  CIRCLE_BATCHING_NAME,
  CIRCLE_BATCHING_VERSION,
  CIRCLE_BATCHING_SCHEME,
} from "@circle-fin/x402-batching";
```

| Constant                  | Value                    | Description                                           |
| ------------------------- | ------------------------ | ----------------------------------------------------- |
| `CIRCLE_BATCHING_NAME`    | `'GatewayWalletBatched'` | EIP-712 domain name used for batch payment signatures |
| `CIRCLE_BATCHING_VERSION` | `'1'`                    | EIP-712 domain version                                |
| `CIRCLE_BATCHING_SCHEME`  | `'exact'`                | x402 payment scheme identifier                        |

***

## Chain configuration

```ts theme={null}
import {
  CHAIN_CONFIGS,
  GATEWAY_DOMAINS,
} from "@circle-fin/x402-batching/client";
```

* `CHAIN_CONFIGS`: Full configuration (USDC address, Gateway Wallet address, RPC
  URL) for all supported blockchains, keyed by `SupportedChainName`.
* `GATEWAY_DOMAINS`: Gateway domain IDs for EIP-712 signing, keyed by chain
  name.

Use these constants to retrieve the correct addresses programmatically instead
of hardcoding them:

```ts theme={null}
import {
  CHAIN_CONFIGS,
  GATEWAY_DOMAINS,
} from "@circle-fin/x402-batching/client";

// Retrieve chain configuration for Arc Testnet
const config = CHAIN_CONFIGS["arcTestnet"];
// config.gatewayWallet → "0x0077777d7EBA4688BDeF3E311b846F25870A19B9"
// config.usdc → "0x3600000000000000000000000000000000000000"

const domainId = GATEWAY_DOMAINS["arcTestnet"]; // → 26
```

For reference, the Gateway Wallet and USDC contract addresses for each chain are
listed in the [EVM contract addresses](/gateway/references/contract-addresses)
and [USDC contract addresses](/stablecoins/usdc-contract-addresses) pages.

***

## Error reference

### Gateway API error codes

These are the `errorReason` (settle) and `invalidReason` (verify) values
returned by the Gateway API:

| Error code                         | Cause                                                  | Recovery                                                     |
| ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| `unsupported_scheme`               | Scheme is not `exact`                                  | Only the `exact` scheme is supported                         |
| `unsupported_network`              | Network not supported for batching                     | Use a supported network                                      |
| `unsupported_asset`                | Token address not recognized on this blockchain        | Use the correct USDC address for the network                 |
| `invalid_payload`                  | Malformed payment payload                              | Check EIP-712 signature fields                               |
| `address_mismatch`                 | Authorization `to` address does not match `payTo`      | Ensure the payment is addressed to the correct seller        |
| `amount_mismatch`                  | Authorization `value` does not match required `amount` | Ensure the signed amount matches the price                   |
| `invalid_signature`                | EIP-3009 signature verification failed                 | Re-sign the payment and check the signing key matches `from` |
| `authorization_not_yet_valid`      | Authorization `validAfter` is in the future            | Wait until the authorization becomes valid                   |
| `authorization_expired`            | Authorization `validBefore` has passed                 | Create a new payment with a future expiry                    |
| `authorization_validity_too_short` | Validity window is shorter than 3 days                 | Set `validBefore` to at least 3 days in the future           |
| `self_transfer`                    | `from` and `to` are the same address                   | Buyer and seller must be different addresses                 |
| `insufficient_balance`             | Buyer's Gateway balance is too low                     | Deposit more USDC before paying                              |
| `nonce_already_used`               | Payment nonce was already submitted                    | Create a new payment (each payment needs a unique nonce)     |
| `unsupported_domain`               | Gateway domain not configured for this blockchain      | Check network configuration                                  |
| `wallet_not_found`                 | Gateway Wallet contract not found on this blockchain   | Verify contract addresses for the network                    |
| `unexpected_error`                 | Infrastructure error (HTTP 500)                        | Retry the request and contact support if the error persists  |

### `GatewayClient` errors

All errors are thrown as standard `Error` objects with descriptive messages.

| Error message                                          | Cause                                                  | Recovery                                                            |
| ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------- |
| `Unsupported chain: {chain}`                           | Invalid `SupportedChainName` passed to the constructor | Use a valid chain name from the chain configuration table           |
| `Request failed with status {N}`                       | Non-402, non-2xx response from the server              | Check server status and URL                                         |
| `Missing PAYMENT-REQUIRED header in 402 response`      | Server returned 402 without the required header        | Verify the server uses x402 v2                                      |
| `No payment options in 402 response`                   | Empty `accepts` array in the 402 response              | The server may not have configured payment options                  |
| `No Gateway batching option available`                 | Server does not support Gateway batching               | Use `supports()` to check first; the server may only accept onchain |
| `Payment failed: {reason}`                             | Server rejected the payment                            | Check the Gateway API error code in the message                     |
| `Insufficient USDC balance`                            | Wallet USDC balance is less than the deposit amount    | Get more USDC from the faucet or transfer from another wallet       |
| `Approval transaction failed: {txHash}`                | USDC approval transaction reverted onchain             | Check gas, wallet balance, and network status                       |
| `Deposit transaction failed: {txHash}`                 | Deposit transaction reverted onchain                   | Check gas and contract state                                        |
| `Insufficient available balance`                       | Gateway balance is too low for the withdrawal          | Deposit more or reduce the amount                                   |
| `Unsupported destination chain: {chain}`               | Invalid chain name for crosschain withdrawal           | Use a valid `SupportedChainName`                                    |
| `Gateway getTransferById failed ({status}): {details}` | Cannot fetch transfer by ID                            | Verify the transfer UUID and API connectivity                       |
| `Gateway searchTransfers failed ({status}): {details}` | Transfer search endpoint returned an error             | Validate filters and check API connectivity                         |

### Middleware errors

| Error message                   | Cause                                      | Recovery                                                             |
| ------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
| `Invalid price: {price}`        | Price string could not be parsed           | Use format `'$0.01'` or `'0.01'`                                     |
| `No payment networks available` | No supported networks found (503 response) | Check Gateway API connectivity                                       |
| `Payment verification failed`   | Verify returned `isValid: false`           | Check the Gateway API error code in the response body `reason` field |
| `Payment settlement failed`     | Settle returned `success: false`           | Check the Gateway API error code in the response body `reason` field |

### `BatchFacilitatorClient` errors

| Error message                                              | Cause                                           | Recovery                                                    |
| ---------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
| `Circle Gateway verify failed ({status}): {details}`       | Verify endpoint returned an unexpected response | Check payload format and API status                         |
| `Circle Gateway settle failed ({status}): {details}`       | Settle endpoint returned an unexpected response | Retry the request and contact support if the error persists |
| `Circle Gateway settle returned empty response ({status})` | Empty body from settle endpoint                 | Retry the request                                           |
| `Circle Gateway getSupported failed ({status}): {details}` | Cannot fetch supported networks                 | Check API connectivity and URL                              |

### `BatchEvmScheme` errors

| Error message                                            | Cause                                                            | Recovery                                                  |
| -------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------- |
| `BatchEvmScheme: unsupported network format "{network}"` | Network string is not in `eip155:<chainId>` format               | Use CAIP-2 format (for example, `eip155:5042002`)         |
| `BatchEvmScheme can only handle Circle batching options` | Payment requirements missing `extra.name="GatewayWalletBatched"` | Use this scheme only for Gateway payments                 |
| `Circle batching option missing extra.verifyingContract` | Payment requirements missing the Gateway Wallet address          | Ensure the server includes `verifyingContract` in `extra` |


# Supported Networks
Source: https://developers.circle.com/gateway/nanopayments/supported-networks

Blockchains supported by nanopayments for deposits, gas-free payments, and withdrawals

Nanopayments supports gas-free USDC payments on all EVM blockchains listed in
the [Gateway supported blockchains](/gateway/references/supported-blockchains)
table where the **Nanopayments** column is marked **Yes**.

Use the `SupportedChainName` value from the table when initializing
`GatewayClient` or configuring the SDK:

```typescript theme={null}
const client = new GatewayClient({
  chain: "base", // SupportedChainName from the supported blockchains table
  privateKey: "0x...",
});
```

<Note>
  When using `GatewayClient`, deposits and payments are scoped to the blockchain
  you configure on the client. If you want to pay on Base, initialize the client
  for Base and deposit there. To avoid long deposit wait times, use Arc App Kit's
  [Bridge Kit](https://docs.arc.io/app-kit/bridge) to bridge your USDC to a
  fast-finality blockchain before depositing. The
  [Fast deposits](/gateway/references/supported-blockchains#fast-deposits) section
  offers third-party alternatives for faster deposits.
</Note>

## Contract addresses

If you are constructing EIP-712 signatures manually (without the SDK), you need
the contract addresses for your target chain:

* **GatewayWallet address** (used as `verifyingContract` in the EIP-712 domain):
  [EVM contract addresses](/gateway/references/contract-addresses)
* **USDC token address** (used as the `asset` in payment requirements):
  [USDC contract addresses](/stablecoins/usdc-contract-addresses)

The SDK's `CHAIN_CONFIGS` constant provides these values programmatically. See
the [SDK reference](/gateway/nanopayments/references/sdk#chain-configuration)
for details.

## Testnet faucets

To test nanopayments, you need testnet USDC and native gas tokens:

* [Circle Faucet](https://faucet.circle.com) — testnet USDC for supported
  testnet blockchains
* For native gas tokens (required for onchain deposit transactions), use the
  blockchain-specific faucets listed on each testnet's documentation site


# Quickstart: Gasless Gateway Deposits with Eco
Source: https://developers.circle.com/gateway/quickstarts/eco-gasless-deposits

Deposit testnet USDC into Circle Gateway without paying source-chain gas by using Eco's gasless deposit flow.

Use Eco's gasless deposit flow to move 1 testnet USDC from Base Sepolia into
Circle Gateway without holding ETH on the source blockchain. This quickstart
shows a TypeScript script that requests an Eco deposit address, signs an
EIP-3009 authorization, submits the deposit, and checks your Gateway balance on
Polygon PoS Amoy.

<Note>
  Eco is a third-party fast-deposit service. Circle names Eco as an option for
  faster Gateway deposits in current docs, but Circle does not operate or audit
  Eco's service. Review Eco's docs and test the flow before you use it in
  production.
</Note>

This quickstart uses Base Sepolia as the source blockchain and Polygon PoS Amoy
(Gateway domain ID `7`) as the destination. You sign an EIP-3009
`TransferWithAuthorization` payload locally, and Eco submits the transfer
onchain. You still need USDC in your wallet, but you do not need ETH on Base
Sepolia for the deposit. For other deposit methods and Eco-specific routing
details, see the
[Eco Gateway Deposits guide](https://eco.com/docs/getting-started/programmable-addresses/gateway-deposits).

## Prerequisites

Before you begin, ensure you have:

* Installed [Node.js v22+](https://nodejs.org/)
* Obtained a private key for a Base Sepolia EOA
* Funded your wallet with testnet USDC from the
  [Circle Faucet](https://faucet.circle.com/) (select **Base Sepolia**)

**Base Sepolia network details**

| Property      | Value                                           |
| ------------- | ----------------------------------------------- |
| Chain ID      | `84532`                                         |
| USDC contract | `0x036CbD53842c5426634e7929541eC2318f3dCF7e`    |
| Faucet        | [faucet.circle.com](https://faucet.circle.com/) |

<Note>You do not need ETH on Base Sepolia for this gasless deposit flow.</Note>

## Step 1. Set up your project

### 1.1. Create the project and install dependencies

```shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir eco-gasless-deposit
cd eco-gasless-deposit
npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="tsx --env-file=.env eco-deposit.ts"

# Install runtime dependencies
npm install viem

# Install dev dependencies
npm install --save-dev @types/node tsx typescript
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.3. Set environment variables

Open `.env` in your editor and add:

```text theme={null}
PRIVATE_KEY=0xYOUR_BASE_SEPOLIA_PRIVATE_KEY
```

* `PRIVATE_KEY` is the private key for the Base Sepolia EOA that holds the
  testnet USDC you want to deposit.
* Include the `0x` prefix. MetaMask often copies the private key as bare hex,
  but this script expects a hex string with the prefix.

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

The `npm run start` command loads variables from `.env` using Node.js native
env-file support.

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>

<Note>
  Steps 2 through 6 show individual parts of the flow. Each snippet highlights
  one stage and is not independently runnable. Use the full script in [Full
  deposit script](#full-deposit-script) to run the quickstart end to end.
</Note>

## Step 2. Request an Eco deposit address

Request a deterministic Eco deposit address for Gateway on Polygon PoS Amoy.

```typescript theme={null}
const response = await fetch(
  "https://deposit-addresses-preproduction.eco.com/api/v1/depositAddresses/gateway/polygon",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      chainId: 84532, // Base Sepolia
      depositor: yourWalletAddress,
      evmDestinationAddress: yourWalletAddress,
    }),
  },
);

if (!response.ok) {
  throw new Error(`Failed to get deposit address: ${await response.text()}`);
}

const { data } = await response.json();
const depositAddress = data.evmDepositAddress;
```

The returned `depositAddress` is a reusable address for this depositor and
destination combination.

## Step 3. Generate EIP-3009 authorization

Create the authorization parameters. EIP-3009 uses a `TransferWithAuthorization`
signed message to let a third party (Eco) submit the transfer on your behalf.
For a deeper explanation of the signing flow, see
[EIP-3009 signing](/gateway/nanopayments/howtos/eip-3009-signing).

```typescript theme={null}
import { randomBytes } from "node:crypto";

const nonce = `0x${randomBytes(32).toString("hex")}`;
const validAfter = 0n;
const validBefore = BigInt(Math.floor(Date.now() / 1000) + 3600); // 1 hour
const amount = 1000000n; // 1 USDC (6 decimals)
```

Sign the `TransferWithAuthorization` payload:

```typescript theme={null}
const signature = await walletClient.signTypedData({
  account,
  domain: {
    name: "USDC",
    version: "2",
    chainId: 84532,
    verifyingContract: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  },
  types: {
    TransferWithAuthorization: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" },
      { name: "validBefore", type: "uint256" },
      { name: "nonce", type: "bytes32" },
    ],
  },
  primaryType: "TransferWithAuthorization",
  message: {
    from: yourWalletAddress,
    to: depositAddress,
    value: amount,
    validAfter,
    validBefore,
    nonce,
  },
});
```

<Note>
  For this Base Sepolia flow, the EIP-712 domain name is `USDC`, not `USD Coin`.
</Note>

## Step 4. Submit the gasless deposit to Eco

Submit the signed authorization:

```typescript theme={null}
const response = await fetch(
  "https://deposit-addresses-preproduction.eco.com/api/v1/gasless/transferWithAuthorization",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      chainId: 84532,
      from: yourWalletAddress,
      to: depositAddress,
      value: amount.toString(),
      validAfter: validAfter.toString(),
      validBefore: validBefore.toString(),
      nonce,
      signature,
    }),
  },
);

if (!response.ok) {
  throw new Error(`Failed to submit transfer: ${await response.text()}`);
}

const { data } = await response.json();
const jobId = data.id;
```

Eco returns a `jobId` you can poll until the deposit completes or fails.

## Step 5. Wait for the deposit to complete

Poll the job status endpoint:

```typescript theme={null}
let status = "PENDING";
let attempts = 0;
const maxAttempts = 30;

while (status === "PENDING" && attempts < maxAttempts) {
  await new Promise((resolve) => setTimeout(resolve, 2000));

  const response = await fetch(
    `https://deposit-addresses-preproduction.eco.com/api/v1/gasless/jobs/${jobId}`,
  );

  if (!response.ok) {
    throw new Error(`Failed to poll status: ${await response.text()}`);
  }

  const { data } = await response.json();
  status = data.status;
  attempts++;

  console.log(`Status: ${status} (${attempts * 2}s elapsed)`);
}

if (status !== "COMPLETED") {
  throw new Error("Deposit failed or timed out");
}
```

## Step 6. Check your Gateway balance

After the job completes, query the Gateway balances endpoint:

```typescript theme={null}
const response = await fetch(
  "https://gateway-api-testnet.circle.com/v1/balances",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      token: "USDC",
      sources: [{ domain: 7, depositor: yourWalletAddress }], // Polygon PoS Amoy
    }),
  },
);

if (!response.ok) {
  throw new Error(`Failed to fetch balance: ${await response.text()}`);
}

const { balances } = await response.json();
const polygonBalance = balances.find((b) => b.domain === 7);

if (!polygonBalance) {
  throw new Error("No Polygon PoS Amoy Gateway balance returned");
}

console.log(`Gateway balance: ${polygonBalance.balance} USDC`);
```

The current Gateway balances API returns `balance` as a decimal USDC string for
this flow.

## Full deposit script

This script requests the Eco deposit address, signs the EIP-3009 payload,
submits the gasless deposit, waits for completion, and prints the resulting
Gateway balance. Save it as `eco-deposit.ts`.

```typescript filename="eco-deposit.ts" expandable theme={null}
import { randomBytes } from "node:crypto";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";

const USDC_BASE_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
const BASE_SEPOLIA_CHAIN_ID = 84532;
const POLYGON_AMOY_DOMAIN = 7;
const ECO_BASE_URL = "https://deposit-addresses-preproduction.eco.com/api/v1";
const GATEWAY_API_URL = "https://gateway-api-testnet.circle.com/v1/balances";
const DEPOSIT_AMOUNT = 1000000n; // 1 USDC

async function requestDepositAddress(depositor: `0x${string}`) {
  const response = await fetch(
    `${ECO_BASE_URL}/depositAddresses/gateway/polygon`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        chainId: BASE_SEPOLIA_CHAIN_ID,
        depositor,
        evmDestinationAddress: depositor,
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Failed to get deposit address: ${await response.text()}`);
  }

  const { data } = await response.json();
  return data.evmDepositAddress as `0x${string}`;
}

async function signTransferAuthorization(
  walletClient: ReturnType<typeof createWalletClient>,
  account: ReturnType<typeof privateKeyToAccount>,
  from: `0x${string}`,
  to: `0x${string}`,
) {
  const nonce = `0x${randomBytes(32).toString("hex")}` as `0x${string}`;
  const validAfter = 0n;
  const validBefore = BigInt(Math.floor(Date.now() / 1000) + 3600);

  const signature = await walletClient.signTypedData({
    account,
    domain: {
      name: "USDC",
      version: "2",
      chainId: BASE_SEPOLIA_CHAIN_ID,
      verifyingContract: USDC_BASE_SEPOLIA as `0x${string}`,
    },
    types: {
      TransferWithAuthorization: [
        { name: "from", type: "address" },
        { name: "to", type: "address" },
        { name: "value", type: "uint256" },
        { name: "validAfter", type: "uint256" },
        { name: "validBefore", type: "uint256" },
        { name: "nonce", type: "bytes32" },
      ],
    },
    primaryType: "TransferWithAuthorization",
    message: {
      from,
      to,
      value: DEPOSIT_AMOUNT,
      validAfter,
      validBefore,
      nonce,
    },
  });

  return {
    nonce,
    validAfter,
    validBefore,
    signature,
  };
}

async function submitGaslessDeposit(params: {
  from: `0x${string}`;
  to: `0x${string}`;
  nonce: `0x${string}`;
  validAfter: bigint;
  validBefore: bigint;
  signature: `0x${string}`;
}) {
  const response = await fetch(
    `${ECO_BASE_URL}/gasless/transferWithAuthorization`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        chainId: BASE_SEPOLIA_CHAIN_ID,
        from: params.from,
        to: params.to,
        value: DEPOSIT_AMOUNT.toString(),
        validAfter: params.validAfter.toString(),
        validBefore: params.validBefore.toString(),
        nonce: params.nonce,
        signature: params.signature,
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Failed to submit transfer: ${await response.text()}`);
  }

  const { data } = await response.json();
  return data.id as string;
}

async function waitForCompletion(jobId: string) {
  let status = "PENDING";
  let attempts = 0;
  const maxAttempts = 30;

  while (status === "PENDING" && attempts < maxAttempts) {
    await new Promise((resolve) => setTimeout(resolve, 2000));

    const response = await fetch(`${ECO_BASE_URL}/gasless/jobs/${jobId}`);

    if (!response.ok) {
      throw new Error(`Failed to poll status: ${await response.text()}`);
    }

    const { data } = await response.json();
    status = data.status as string;
    attempts++;

    console.log(`Status: ${status} (${attempts * 2}s elapsed)`);
  }

  if (status !== "COMPLETED") {
    throw new Error("Deposit failed or timed out");
  }
}

async function checkGatewayBalance(depositor: `0x${string}`) {
  const response = await fetch(GATEWAY_API_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      token: "USDC",
      sources: [{ domain: POLYGON_AMOY_DOMAIN, depositor }],
    }),
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch balance: ${await response.text()}`);
  }

  const { balances } = await response.json();
  const polygonBalance = balances.find(
    (balance: { domain: number; balance: string }) =>
      balance.domain === POLYGON_AMOY_DOMAIN,
  );

  if (!polygonBalance) {
    throw new Error("No Polygon PoS Amoy Gateway balance returned");
  }

  return polygonBalance.balance as string;
}

async function main() {
  const rawPrivateKey = process.env.PRIVATE_KEY?.trim();
  if (!rawPrivateKey) {
    throw new Error("Missing PRIVATE_KEY in .env");
  }

  const privateKey = (
    rawPrivateKey.startsWith("0x") ? rawPrivateKey : `0x${rawPrivateKey}`
  ) as `0x${string}`;

  const account = privateKeyToAccount(privateKey);
  const walletClient = createWalletClient({
    account,
    chain: baseSepolia,
    transport: http(),
  });

  console.log(`\nWallet: ${account.address}`);
  console.log(`Amount: ${Number(DEPOSIT_AMOUNT) / 1e6} USDC\n`);

  console.log("Step 1: Requesting deposit address...");
  const depositAddress = await requestDepositAddress(account.address);
  console.log(`Deposit address: ${depositAddress}\n`);

  console.log("Step 2: Signing authorization...");
  const authorization = await signTransferAuthorization(
    walletClient,
    account,
    account.address,
    depositAddress,
  );
  console.log("Signature generated\n");

  console.log("Step 3: Submitting to Eco...");
  const jobId = await submitGaslessDeposit({
    from: account.address,
    to: depositAddress,
    ...authorization,
  });
  console.log(`Job ID: ${jobId}\n`);

  console.log("Step 4: Waiting for completion...");
  await waitForCompletion(jobId);
  console.log("\nDeposit successful\n");

  console.log("Step 5: Checking Gateway balance...");
  const gatewayBalance = await checkGatewayBalance(account.address);
  console.log(`Gateway balance: ${gatewayBalance} USDC\n`);
}

main().catch((error) => {
  if (error instanceof Error) {
    console.error("Error:", error.message);
    return;
  }

  console.error("Error:", error);
});
```

Run the script:

```bash theme={null}
npm run start
```

For withdrawal and crosschain transfer capabilities, see the
[Gateway documentation](https://developers.circle.com/gateway). To use your
Gateway balance for Gateway-based USDC flows, explore the
[Arc Nanopayments Demo](https://github.com/circlefin/arc-nanopayments).


# Quickstart: Create and Transfer a Unified USDC Balance on EVM
Source: https://developers.circle.com/gateway/quickstarts/unified-balance-evm

Create and transfer a unified USDC balance on EVM using Circle Gateway.

This guide walks you through the process of creating Unified Crosschain USDC
Balances on
[supported EVM chains](/gateway/references/supported-blockchains#testnet) using
Circle Gateway, and performing transfers from EVM to EVM and from Solana to EVM.

<Tip>
  **Use
  [Unified Balance Kit](https://www.npmjs.com/package/@circle-fin/unified-balance-kit)
  to simplify this integration.**

  This quickstart uses a manual Gateway integration. It is for learning or for
  developers who need direct control.

  To simplify, use Unified Balance Kit to deposit and spend USDC in just a few
  lines of code.
</Tip>

Select a tab below for the Circle Wallets or self-managed wallet path.

<Tabs>
  <Tab title="Circle Wallets">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Obtained a
      [Circle API Key](/w3s/circle-developer-account#creating-an-api-key-for-developer-services)
      and [Entity Secret](/wallets/dev-controlled/register-entity-secret) from the
      [Circle Console](/w3s/circle-developer-account).
    * [Created Developer-Controlled Wallets](/wallets/dev-controlled/create-your-first-wallet)
      for the chains you want to test.
    * Funded your wallets with testnet tokens:
      * Get testnet USDC from the [Circle Faucet](https://faucet.circle.com/).
      * Get test native tokens from the
        [Console Faucet](https://console.circle.com/faucet).

    If you want to try the Solana to EVM transfer, ensure that you've:

    * Created a Solana Devnet Developer-Controlled Wallet to act as the source
      depositor
    * Created an EVM Developer-Controlled Wallet on the destination chain to submit
      the mint transaction
    * Completed the
      [deposit flow](/gateway/quickstarts/unified-balance-solana#step-3-deposit-into-a-unified-crosschain-balance-circle-wallets)
      from the
      [Solana quickstart](/gateway/quickstarts/unified-balance-solana#circle-wallets)
      first

    ### Add testnet funds to your wallet

    To interact with Gateway, you need test USDC and native tokens in your wallet on
    each chain you deposit from. You also need native gas tokens on the destination
    chain to call the Gateway Minter contract.

    Use the [Circle Faucet](https://faucet.circle.com/) to get test USDC. If you
    have a [Circle Developer Console](https://console.circle.com) account, you can
    use the [Console Faucet](https://console.circle.com/faucet) to get testnet
    native tokens. In addition, the following faucets can also be used to fund your
    wallet with testnet native tokens:

    <Tabs>
      <Tab title="Arc">
        **Faucet:** [Arc Testnet](https://faucet.circle.com) (USDC + native tokens)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `arcTestnet`                                 |
        | USDC address | `0x3600000000000000000000000000000000000000` |
        | Domain ID    | `26`                                         |
      </Tab>

      <Tab title="Avalanche">
        **Faucet:** [Avalanche Fuji](https://core.app/tools/testnet-faucet)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `avalancheFuji`                              |
        | USDC address | `0x5425890298aed601595a70ab815c96711a31bc65` |
        | Domain ID    | `1`                                          |
      </Tab>

      <Tab title="Base">
        **Faucet:** [Base Sepolia](https://www.alchemy.com/faucets/base-sepolia)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `baseSepolia`                                |
        | USDC address | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
        | Domain ID    | `6`                                          |
      </Tab>

      <Tab title="Ethereum">
        **Faucet:** [Ethereum Sepolia](https://cloud.google.com/application/web3/faucet/ethereum/sepolia)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `sepolia`                                    |
        | USDC address | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` |
        | Domain ID    | `0`                                          |
      </Tab>

      <Tab title="Hyperliquid">
        **Faucet:** [Hyperliquid EVM Testnet](https://app.hyperliquid-testnet.xyz/drip)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `hyperliquidEvmTestnet`                      |
        | USDC address | `0x2B3370eE501B4a559b57D449569354196457D8Ab` |
        | Domain ID    | `19`                                         |
      </Tab>

      <Tab title="Sei">
        **Faucet:** [Sei Testnet](https://docs.sei.io/learn/faucet)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `seiTestnet`                                 |
        | USDC address | `0x4fCF1784B31630811181f670Aea7A7bEF803eaED` |
        | Domain ID    | `16`                                         |
      </Tab>

      <Tab title="Solana">
        **Faucet:** [Solana Devnet](https://faucet.solana.com/)

        | Property     | Value                                                   |
        | ------------ | ------------------------------------------------------- |
        | Chain name   | `solanaDevnet` (note that Solana is not EVM-compatible) |
        | USDC address | `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`          |
        | Domain ID    | `5`                                                     |
      </Tab>

      <Tab title="Sonic">
        **Faucet:** [Sonic Testnet](https://testnet.soniclabs.com/account)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `sonicTestnet`                               |
        | USDC address | `0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51` |
        | Domain ID    | `13`                                         |
      </Tab>

      <Tab title="Worldchain">
        **Faucet:** [Worldchain Sepolia](https://www.l2faucet.com/world)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `worldchainSepolia`                          |
        | USDC address | `0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88` |
        | Domain ID    | `14`                                         |
      </Tab>
    </Tabs>

    ## Step 1. Set up your project

    ### 1.1. Create the project and install dependencies

    ```shell theme={null}
    # Set up your directory and initialize a Node.js project
    mkdir unified-gateway-balance-evm-circle-wallets
    cd unified-gateway-balance-evm-circle-wallets
    npm init -y

    # Set up module type and run scripts
    npm pkg set type=module
    npm pkg set scripts.deposit="tsx --env-file=.env deposit.ts --"
    npm pkg set scripts.balances="tsx --env-file=.env balances.ts"
    npm pkg set scripts.transfer-from-evm="tsx --env-file=.env transfer-from-evm.ts --"
    npm pkg set scripts.transfer-from-sol="tsx --env-file=.env transfer-from-sol.ts"

    # Pin bigint-buffer to a patched version
    npm pkg set overrides.bigint-buffer=npm:@trufflesuite/bigint-buffer@1.1.10

    # Install runtime dependencies
    npm install @circle-fin/developer-controlled-wallets @coral-xyz/anchor @solana/buffer-layout @solana/web3.js bs58 tsx typescript

    # Install dev dependencies
    npm install --save-dev @types/node
    ```

    ### 1.2. Configure TypeScript (optional)

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3. Set environment variables

    Create a `.env` file in the project directory:

    ```text .env theme={null}
    CIRCLE_API_KEY=YOUR_API_KEY
    CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
    DEPOSITOR_ADDRESS=YOUR_SOURCE_WALLET_ADDRESS
    RECIPIENT_ADDRESS=YOUR_DESTINATION_WALLET_ADDRESS
    ```

    * `CIRCLE_API_KEY` is your Circle API key.
    * `CIRCLE_ENTITY_SECRET` is your Circle entity secret.
    * `DEPOSITOR_ADDRESS` is the source depositor wallet for the script you are
      running.
    * `RECIPIENT_ADDRESS` is the destination wallet. It is only required for
      transfer scripts.

    For `transfer-from-evm.ts`, both `DEPOSITOR_ADDRESS` and `RECIPIENT_ADDRESS` are
    EVM addresses.

    For `transfer-from-sol.ts`, `DEPOSITOR_ADDRESS` is a Solana address and
    `RECIPIENT_ADDRESS` is an EVM address.

    <Tip>
      Open `.env` in your editor rather than writing values with shell commands, and
      add `.env` to your `.gitignore`. This prevents credentials from leaking into
      your shell history or version control.
    </Tip>

    ## Step 2. Set up the configuration file

    The shared configuration file is used by the deposit and transfer scripts.

    ### 2.1. Create the configuration file

    ```shell theme={null}
    touch config.ts
    ```

    ### 2.2. Configure wallet account and chain settings

    Add the chain metadata, Gateway contract addresses, Circle Wallets client, and
    Command-line helpers to your `config.ts` file.

    ```ts config.ts expandable theme={null}
    import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

    /* Chain configuration */
    export type WalletChain =
      | "ETH-SEPOLIA"
      | "BASE-SEPOLIA"
      | "AVAX-FUJI"
      | "ARC-TESTNET"
      | "ARB-SEPOLIA"
      | "OP-SEPOLIA"
      | "MATIC-AMOY"
      | "UNI-SEPOLIA";

    export type Chain =
      | "ethereum"
      | "base"
      | "avalanche"
      | "arc"
      | "arbitrum"
      | "optimism"
      | "polygon"
      | "unichain";

    export type ChainConfig = {
      chainName: string;
      usdc: string;
      domain: number;
      walletChain: WalletChain;
    };

    export const chainConfig: Record<Chain, ChainConfig> = {
      ethereum: {
        chainName: "Ethereum Sepolia",
        usdc: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
        domain: 0,
        walletChain: "ETH-SEPOLIA",
      },
      base: {
        chainName: "Base Sepolia",
        usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        domain: 6,
        walletChain: "BASE-SEPOLIA",
      },
      avalanche: {
        chainName: "Avalanche Fuji",
        usdc: "0x5425890298aed601595a70AB815c96711a31Bc65",
        domain: 1,
        walletChain: "AVAX-FUJI",
      },
      arc: {
        chainName: "Arc Testnet",
        usdc: "0x3600000000000000000000000000000000000000",
        domain: 26,
        walletChain: "ARC-TESTNET",
      },
      arbitrum: {
        chainName: "Arbitrum Sepolia",
        usdc: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
        domain: 3,
        walletChain: "ARB-SEPOLIA",
      },
      optimism: {
        chainName: "OP Sepolia",
        usdc: "0x5fd84259d66Cd46123540766Be93DFE6D43130D7",
        domain: 2,
        walletChain: "OP-SEPOLIA",
      },
      polygon: {
        chainName: "Polygon Amoy",
        usdc: "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
        domain: 7,
        walletChain: "MATIC-AMOY",
      },
      unichain: {
        chainName: "Unichain Sepolia",
        usdc: "0x31d0220469e10c4E71834a79b1f276d740d3768F",
        domain: 10,
        walletChain: "UNI-SEPOLIA",
      },
    };

    /* Gateway Contract Addresses */
    export const GATEWAY_WALLET_ADDRESS =
      "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
    export const GATEWAY_MINTER_ADDRESS =
      "0x0022222ABE238Cc2C7Bb1f21003F0a260052475B";

    /* API Credentials */
    export const API_KEY = process.env.CIRCLE_API_KEY!;
    export const ENTITY_SECRET = process.env.CIRCLE_ENTITY_SECRET!;
    export const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;

    if (!API_KEY || !ENTITY_SECRET || !DEPOSITOR_ADDRESS) {
      console.error(
        "Missing required env vars: CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET, DEPOSITOR_ADDRESS",
      );
      process.exit(1);
    }

    /* Circle Wallets Client */
    export const client = initiateDeveloperControlledWalletsClient({
      apiKey: API_KEY,
      entitySecret: ENTITY_SECRET,
    });

    /* Command-line argument parsing helper */
    export function parseSelectedChains(): Chain[] {
      const args = process.argv
        .slice(2)
        .filter((arg) => arg !== "--")
        .map((chain) => chain.toLowerCase());
      const validChains = Object.keys(chainConfig);

      if (args.length === 0) {
        throw new Error(
          "No chains specified. Usage: npm run <script> -- <chain1> [chain2...] or 'all'",
        );
      }

      if (args.length === 1 && args[0] === "all") {
        return Object.keys(chainConfig) as Chain[];
      }

      const invalid = args.filter((arg) => !(arg in chainConfig));
      if (invalid.length > 0) {
        console.error(
          `Unsupported chain: ${invalid.join(", ")}\n` +
            `Valid chains: ${validChains.join(", ")}, all\n` +
            `Example: npm run <script> -- ethereum base`,
        );
        process.exit(1);
      }

      return [...new Set(args)] as Chain[];
    }

    /* Transaction Polling Helper */
    export async function waitForTxCompletion(
      client: ReturnType<typeof initiateDeveloperControlledWalletsClient>,
      txId: string,
      label: string,
    ) {
      const terminalStates = new Set([
        "COMPLETE",
        "CONFIRMED",
        "FAILED",
        "DENIED",
        "CANCELLED",
      ]);

      process.stdout.write(`Waiting for ${label} (txId=${txId})\n`);

      while (true) {
        const { data } = await client.getTransaction({ id: txId });
        const state = data?.transaction?.state;

        process.stdout.write(".");

        if (state && terminalStates.has(state)) {
          process.stdout.write("\n");
          console.log(`${label} final state: ${state}`);

          if (state !== "COMPLETE" && state !== "CONFIRMED") {
            throw new Error(
              `${label} did not complete successfully (state=${state})`,
            );
          }
          return data.transaction;
        }
        await new Promise((resolve) => setTimeout(resolve, 3000));
      }
    }

    /* Balance Parsing Helper */
    export function parseBalance(
      value: string | number | null | undefined,
    ): bigint {
      const str = String(value ?? "0");
      const [whole, decimal = ""] = str.split(".");
      const decimal6 = (decimal + "000000").slice(0, 6);
      return BigInt((whole || "0") + decimal6);
    }
    ```

    ## Step 3. Deposit into a unified crosschain balance (Circle Wallets)

    The deposit script deposits USDC into the Gateway Wallet on selected EVM chains.
    Pass chain names as command-line arguments (for example, `arc`, `base`, or
    `all`). You can skip to the
    [full deposit script](#3-5-full-deposit-script-circle-wallets) if you prefer.

    <Warning>
      Do not transfer USDC directly to the Gateway Wallet contract with a standard
      ERC-20 transfer. You must call a Gateway deposit method or the USDC will not
      be credited to your unified balance.
    </Warning>

    ### 3.1. Create the deposit script

    ```shell theme={null}
    touch deposit.ts
    ```

    ### 3.2. Define constants and deposit amount

    Set the deposit amount once near the top of the script, then use
    `parseSelectedChains()` to let the reader choose one or more EVM source chains
    at runtime.

    ```ts theme={null}
    const DEPOSIT_AMOUNT_USDC = "2";
    ```

    ### 3.3. Approve USDC spending and submit the deposit

    For each selected source chain, the script first approves the Gateway Wallet
    contract to spend USDC, then calls the Gateway `deposit(address,uint256)`
    method.

    ```ts theme={null}
    const approveTx = await client.createContractExecutionTransaction({
      walletAddress: DEPOSITOR_ADDRESS,
      blockchain: chainConfig[chain].walletChain,
      contractAddress: chainConfig[chain].usdc,
      abiFunctionSignature: "approve(address,uint256)",
      abiParameters: [
        GATEWAY_WALLET_ADDRESS,
        parseBalance(DEPOSIT_AMOUNT_USDC).toString(),
      ],
      fee: { type: "level", config: { feeLevel: "MEDIUM" } },
    });

    const depositTx = await client.createContractExecutionTransaction({
      walletAddress: DEPOSITOR_ADDRESS,
      blockchain: chainConfig[chain].walletChain,
      contractAddress: GATEWAY_WALLET_ADDRESS,
      abiFunctionSignature: "deposit(address,uint256)",
      abiParameters: [
        chainConfig[chain].usdc,
        parseBalance(DEPOSIT_AMOUNT_USDC).toString(),
      ],
      fee: { type: "level", config: { feeLevel: "MEDIUM" } },
    });
    ```

    ### 3.4. Wait for Circle Wallet transaction to complete

    Circle Wallet contract execution is asynchronous. After each submit step, wait
    for transaction completion before proceeding to the next phase.

    ```ts theme={null}
    await waitForTxCompletion(client, approveTxId, "USDC approve");
    await waitForTxCompletion(client, depositTxId, "Gateway deposit");
    ```

    ### 3.5. Full deposit script (Circle Wallets)

    The script loops through selected chains, approves USDC spending, and deposits
    into the Gateway Wallet on each chain. Inline comments explain each stage.

    ```ts deposit.ts expandable theme={null}
    import {
      chainConfig,
      GATEWAY_WALLET_ADDRESS,
      DEPOSITOR_ADDRESS,
      client,
      parseSelectedChains,
      waitForTxCompletion,
      parseBalance,
    } from "./config.js";

    const DEPOSIT_AMOUNT_USDC = "2";

    async function main() {
      // Parse the selected source chains from the command-line arguments.
      const selectedChains = parseSelectedChains();
      console.log(`Using account: ${DEPOSITOR_ADDRESS}`);
      console.log(
        `Depositing on: ${selectedChains
          .map((chain) => chainConfig[chain].chainName)
          .join(", ")}`,
      );

      for (const chain of selectedChains) {
        try {
          console.log(`\n=== Processing ${chainConfig[chain].chainName} ===`);

          // [1] Approve the Gateway Wallet to spend USDC on the source chain.
          console.log(
            `Approving ${DEPOSIT_AMOUNT_USDC} USDC on ${chainConfig[chain].chainName}...`,
          );

          const approveTx = await client.createContractExecutionTransaction({
            walletAddress: DEPOSITOR_ADDRESS,
            blockchain: chainConfig[chain].walletChain,
            contractAddress: chainConfig[chain].usdc,
            abiFunctionSignature: "approve(address,uint256)",
            abiParameters: [
              GATEWAY_WALLET_ADDRESS,
              parseBalance(DEPOSIT_AMOUNT_USDC).toString(),
            ],
            fee: { type: "level", config: { feeLevel: "MEDIUM" } },
          });

          const approveTxId = approveTx.data?.id;
          if (!approveTxId) throw new Error("Failed to create approve transaction");

          await waitForTxCompletion(client, approveTxId, "USDC approve");

          // [2] Call the Gateway deposit function for the current source chain.
          console.log(`Depositing ${DEPOSIT_AMOUNT_USDC} USDC to Gateway Wallet`);

          const depositTx = await client.createContractExecutionTransaction({
            walletAddress: DEPOSITOR_ADDRESS,
            blockchain: chainConfig[chain].walletChain,
            contractAddress: GATEWAY_WALLET_ADDRESS,
            abiFunctionSignature: "deposit(address,uint256)",
            abiParameters: [
              chainConfig[chain].usdc,
              parseBalance(DEPOSIT_AMOUNT_USDC).toString(),
            ],
            fee: { type: "level", config: { feeLevel: "MEDIUM" } },
          });

          const depositTxId = depositTx.data?.id;
          if (!depositTxId) throw new Error("Failed to create deposit transaction");

          await waitForTxCompletion(client, depositTxId, "Gateway deposit");
        } catch (err) {
          console.error(`Error on ${chainConfig[chain].chainName}:`, err);
        }
      }

      console.log(
        "\n==| Block confirmation may take up to 19 minutes for some chains |==",
      );
    }

    main().catch((error) => {
      console.error("\nError:", error);
      process.exit(1);
    });
    ```

    ### 3.6. Run the deposit script

    Run the script with one or more supported chains:

    ```shell theme={null}
    npm run deposit -- ethereum
    ```

    ```shell theme={null}
    npm run deposit -- ethereum base arc
    ```

    ```shell theme={null}
    npm run deposit -- all
    ```

    Wait for the
    [required number of block confirmations](https://developers.circle.com/gateway/references/supported-blockchains#required-block-confirmations).
    Once the deposit transactions are final, the total balance is the sum of all the
    USDC from deposit transactions across all supported chains that have reached
    finality.

    ### 3.7. Check the balances on the Gateway Wallet

    Create a new file called `balances.ts`, and add the following code. This script
    retrieves the USDC balances available from your Gateway Wallet for the
    `DEPOSITOR_ADDRESS` currently set in `.env`.

    ```ts balances.ts expandable theme={null}
    interface GatewayBalancesResponse {
      balances: Array<{
        domain: number;
        balance: string;
      }>;
    }

    const EVM_DOMAINS = {
      ethereum: 0,
      avalanche: 1,
      optimism: 2,
      arbitrum: 3,
      base: 6,
      polygon: 7,
      unichain: 10,
      arc: 26,
    };

    const SOLANA_DOMAINS = {
      solana: 5,
    };

    const DOMAINS = { ...EVM_DOMAINS, ...SOLANA_DOMAINS };

    const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;

    if (!DEPOSITOR_ADDRESS) {
      console.error("Missing required env var: DEPOSITOR_ADDRESS");
      process.exit(1);
    }

    const isEvmAddress = DEPOSITOR_ADDRESS.startsWith("0x");

    async function main() {
      console.log(`Depositor address: ${DEPOSITOR_ADDRESS}`);
      console.log(`Address type: ${isEvmAddress ? "EVM" : "Solana"}\n`);

      const activeDomains = isEvmAddress ? EVM_DOMAINS : SOLANA_DOMAINS;
      const domainIds = Object.values(activeDomains);
      const body = {
        token: "USDC",
        sources: domainIds.map((domain) => ({
          domain,
          depositor: DEPOSITOR_ADDRESS,
        })),
      };

      const res = await fetch(
        "https://gateway-api-testnet.circle.com/v1/balances",
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(body),
        },
      );

      const result = (await res.json()) as GatewayBalancesResponse;

      let total = 0;
      for (const balance of result.balances) {
        const chain =
          Object.keys(DOMAINS).find(
            (k) => DOMAINS[k as keyof typeof DOMAINS] === balance.domain,
          ) || `Domain ${balance.domain}`;
        const amount = parseFloat(balance.balance);
        console.log(`${chain}: ${amount.toFixed(6)} USDC`);
        total += amount;
      }

      console.log(`\nTotal: ${total.toFixed(6)} USDC`);
    }

    main().catch((error) => {
      console.error("\nError:", error);
      process.exit(1);
    });
    ```

    You can run it to check whether finality has been reached for recent
    transactions.

    ```shell theme={null}
    npm run balances
    ```

    <Tabs>
      <Tab title="Transfer from EVM">
        ## Step 4. Transfer USDC from EVM to EVM

        The transfer script burns USDC on selected source chains and mints on a
        destination EVM chain via Gateway. Pass source chain names as command-line
        arguments (for example, `ethereum`, `arc`, or `all`). You can skip to the
        [full transfer script](#4-7-full-evm-transfer-script) if you prefer.

        ### 4.1. Create the EVM transfer script

        ```shell theme={null}
        touch transfer-from-evm.ts
        ```

        ### 4.2. Define constants and types

        The validated script uses Arc Testnet as the destination chain. Update
        `DESTINATION_CHAIN` if you want to mint on a different supported EVM testnet.

        The script keeps the same typed burn intent structure as the standard Gateway
        quickstart, but routes signing and mint execution through Circle Wallets.

        ```ts theme={null}
        const DESTINATION_CHAIN: WalletChain = "ARC-TESTNET";
        const TRANSFER_AMOUNT_USDC = 0.5;
        const MAX_FEE = 2_010000n;
        const MAX_UINT256_DEC = ((1n << 256n) - 1n).toString();
        ```

        ### 4.3. Add helper functions

        These helpers derive destination chain config, convert EVM addresses to
        `bytes32`, and serialize typed data for the Gateway API request.

        ```ts theme={null}
        function getConfigByWalletChain(walletChain: WalletChain) {
          const entry = Object.values(chainConfig).find(
            (item) => item.walletChain === walletChain,
          );
          if (!entry) {
            throw new Error(`No config found for destination chain ${walletChain}`);
          }
          return entry;
        }

        function addressToBytes32(address: string) {
          return ("0x" +
            address
              .toLowerCase()
              .replace(/^0x/, "")
              .padStart(64, "0")) as `0x${string}`;
        }
        ```

        ### 4.4. Create and sign burn intents

        For each selected source chain, create an EIP-712 burn intent and sign it with
        the source Developer-Controlled Wallet.

        ```ts theme={null}
        const burnIntent = createBurnIntent({
          sourceChain: chain,
          depositorAddress: DEPOSITOR_ADDRESS,
          recipientAddress: RECIPIENT_ADDRESS,
        });

        const typedData = burnIntentTypedData(burnIntent);

        const sigResp = await client.signTypedData({
          walletAddress: DEPOSITOR_ADDRESS,
          blockchain: chainConfig[chain].walletChain,
          data: stringifyTypedData(typedData),
        });
        ```

        ### 4.5. Request attestation from Gateway API

        Send the signed burn intents to the Gateway API and validate that the response
        includes both the attestation and the operator signature needed for minting.

        ```ts theme={null}
        const response = await fetch(
          "https://gateway-api-testnet.circle.com/v1/transfer",
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: stringifyTypedData(requests),
          },
        );
        ```

        ### 4.6. Mint on destination chain

        Once the Gateway API returns the attestation set, call
        `gatewayMint(bytes,bytes)` on the destination EVM chain and wait for Circle
        Wallet transaction completion.

        ```ts theme={null}
        const tx = await client.createContractExecutionTransaction({
          walletAddress: DEPOSITOR_ADDRESS,
          blockchain: DESTINATION_CHAIN,
          contractAddress: GATEWAY_MINTER_ADDRESS,
          abiFunctionSignature: "gatewayMint(bytes,bytes)",
          abiParameters: [attestation, operatorSig],
          fee: { type: "level", config: { feeLevel: "MEDIUM" } },
        });

        await waitForTxCompletion(client, txId, "USDC mint");
        ```

        ### 4.7. Full EVM transfer script (Circle Wallets)

        The script builds and signs burn intents for the selected EVM source chains,
        requests a Gateway attestation, and mints on the destination chain. Inline
        comments explain each stage.

        ```ts transfer-from-evm.ts expandable theme={null}
        import { randomBytes } from "node:crypto";
        import {
          chainConfig,
          GATEWAY_WALLET_ADDRESS,
          GATEWAY_MINTER_ADDRESS,
          DEPOSITOR_ADDRESS,
          client,
          parseSelectedChains,
          waitForTxCompletion,
          parseBalance,
          type Chain,
          type WalletChain,
        } from "./config.js";

        const RECIPIENT_ADDRESS = process.env.RECIPIENT_ADDRESS!;

        if (!RECIPIENT_ADDRESS) {
          console.error("Missing required env var: RECIPIENT_ADDRESS");
          process.exit(1);
        }

        const DESTINATION_CHAIN: WalletChain = "ARC-TESTNET";
        const TRANSFER_AMOUNT_USDC = 0.5;
        const MAX_FEE = 2_010000n;
        const MAX_UINT256_DEC = ((1n << 256n) - 1n).toString();

        const domain = { name: "GatewayWallet", version: "1" };

        const EIP712Domain = [
          { name: "name", type: "string" },
          { name: "version", type: "string" },
        ];

        const TransferSpec = [
          { name: "version", type: "uint32" },
          { name: "sourceDomain", type: "uint32" },
          { name: "destinationDomain", type: "uint32" },
          { name: "sourceContract", type: "bytes32" },
          { name: "destinationContract", type: "bytes32" },
          { name: "sourceToken", type: "bytes32" },
          { name: "destinationToken", type: "bytes32" },
          { name: "sourceDepositor", type: "bytes32" },
          { name: "destinationRecipient", type: "bytes32" },
          { name: "sourceSigner", type: "bytes32" },
          { name: "destinationCaller", type: "bytes32" },
          { name: "value", type: "uint256" },
          { name: "salt", type: "bytes32" },
          { name: "hookData", type: "bytes" },
        ];

        const BurnIntent = [
          { name: "maxBlockHeight", type: "uint256" },
          { name: "maxFee", type: "uint256" },
          { name: "spec", type: "TransferSpec" },
        ];

        // Build a burn intent for an EVM source chain and destination EVM recipient.
        function createBurnIntent(params: {
          sourceChain: Chain;
          depositorAddress: string;
          recipientAddress?: string;
        }) {
          const {
            sourceChain,
            depositorAddress,
            recipientAddress = depositorAddress,
          } = params;
          const source = chainConfig[sourceChain];
          const destination = getConfigByWalletChain(DESTINATION_CHAIN);
          const value = parseBalance(String(TRANSFER_AMOUNT_USDC));

          return {
            maxBlockHeight: MAX_UINT256_DEC,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: source.domain,
              destinationDomain: destination.domain,
              sourceContract: GATEWAY_WALLET_ADDRESS,
              destinationContract: GATEWAY_MINTER_ADDRESS,
              sourceToken: source.usdc,
              destinationToken: destination.usdc,
              sourceDepositor: depositorAddress,
              destinationRecipient: recipientAddress,
              sourceSigner: depositorAddress,
              destinationCaller: "0x0000000000000000000000000000000000000000",
              value,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Format the burn intent as EIP-712 typed data for Circle Wallet signing.
        function burnIntentTypedData(burnIntent: ReturnType<typeof createBurnIntent>) {
          return {
            types: { EIP712Domain, TransferSpec, BurnIntent },
            domain,
            primaryType: "BurnIntent",
            message: {
              ...burnIntent,
              spec: {
                ...burnIntent.spec,
                sourceContract: addressToBytes32(burnIntent.spec.sourceContract),
                destinationContract: addressToBytes32(
                  burnIntent.spec.destinationContract,
                ),
                sourceToken: addressToBytes32(burnIntent.spec.sourceToken),
                destinationToken: addressToBytes32(burnIntent.spec.destinationToken),
                sourceDepositor: addressToBytes32(burnIntent.spec.sourceDepositor),
                destinationRecipient: addressToBytes32(
                  burnIntent.spec.destinationRecipient,
                ),
                sourceSigner: addressToBytes32(burnIntent.spec.sourceSigner),
                destinationCaller: addressToBytes32(
                  burnIntent.spec.destinationCaller ??
                    "0x0000000000000000000000000000000000000000",
                ),
              },
            },
          };
        }

        // Resolve the destination chain config from the selected wallet chain.
        function getConfigByWalletChain(walletChain: WalletChain) {
          const entry = Object.values(chainConfig).find(
            (item) => item.walletChain === walletChain,
          );
          if (!entry) {
            throw new Error(`No config found for destination chain ${walletChain}`);
          }
          return entry;
        }

        // Convert an EVM address to a 32-byte hex string.
        function addressToBytes32(address: string) {
          return ("0x" +
            address
              .toLowerCase()
              .replace(/^0x/, "")
              .padStart(64, "0")) as `0x${string}`;
        }

        function formatUnits(value: bigint, decimals: number) {
          let display = value.toString();
          const negative = display.startsWith("-");
          if (negative) display = display.slice(1);
          display = display.padStart(decimals, "0");
          const integer = display.slice(0, display.length - decimals);
          let fraction = display.slice(display.length - decimals);
          fraction = fraction.replace(/(0+)$/, "");
          return `${negative ? "-" : ""}${integer || "0"}${
            fraction ? `.${fraction}` : ""
          }`;
        }

        // Serialize typed data while converting bigint values to strings.
        function stringifyTypedData<T>(obj: T) {
          return JSON.stringify(obj, (_key, value) =>
            typeof value === "bigint" ? value.toString() : value,
          );
        }

        async function main() {
          // Parse the selected source chains from the command-line arguments.
          const selectedChains = parseSelectedChains();
          console.log(`Sender (EVM): ${DEPOSITOR_ADDRESS}`);
          console.log(`Recipient (EVM): ${RECIPIENT_ADDRESS}`);
          console.log(
            `Transferring balances from: ${selectedChains
              .map((chain) => chainConfig[chain].chainName)
              .join(", ")}`,
          );

          const requests = [];

          // [1] Create and sign burn intents for each source chain.
          for (const chain of selectedChains) {
            console.log(
              `Creating burn intent from ${chain} -> ${DESTINATION_CHAIN}...`,
            );

            const burnIntent = createBurnIntent({
              sourceChain: chain,
              depositorAddress: DEPOSITOR_ADDRESS,
              recipientAddress: RECIPIENT_ADDRESS,
            });

            const typedData = burnIntentTypedData(burnIntent);

            const sigResp = await client.signTypedData({
              walletAddress: DEPOSITOR_ADDRESS,
              blockchain: chainConfig[chain].walletChain,
              data: stringifyTypedData(typedData),
            });

            requests.push({
              burnIntent: typedData.message,
              signature: sigResp.data?.signature,
            });
          }
          console.log("Signed burn intents.");

          // [2] Request the attestation set from Gateway API.
          const response = await fetch(
            "https://gateway-api-testnet.circle.com/v1/transfer",
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: stringifyTypedData(requests),
            },
          );

          if (!response.ok) {
            console.error("Gateway API error status:", response.status);
            console.error(await response.text());
            throw new Error("Gateway API request failed");
          }

          const json = (await response.json()) as {
            attestation: string;
            signature: string;
          };
          console.log("Gateway API response:", JSON.stringify(json, null, 2));

          const attestation = json?.attestation;
          const operatorSig = json?.signature;

          if (!attestation || !operatorSig) {
            console.error("Gateway /transfer error: missing attestation or signature");
            throw new Error("Invalid Gateway API response");
          }

          // [3] Mint on the destination EVM chain with the returned attestation.
          console.log(
            `Minting funds on ${getConfigByWalletChain(DESTINATION_CHAIN).chainName}...`,
          );

          const tx = await client.createContractExecutionTransaction({
            walletAddress: DEPOSITOR_ADDRESS,
            blockchain: DESTINATION_CHAIN,
            contractAddress: GATEWAY_MINTER_ADDRESS,
            abiFunctionSignature: "gatewayMint(bytes,bytes)",
            abiParameters: [attestation, operatorSig],
            fee: { type: "level", config: { feeLevel: "MEDIUM" } },
          });

          console.log("Mint tx submitted:", tx.data?.id);

          const txId = tx.data?.id;
          if (!txId) throw new Error("Failed to submit mint transaction");
          await waitForTxCompletion(client, txId, "USDC mint");

          const totalMinted =
            BigInt(requests.length) * parseBalance(String(TRANSFER_AMOUNT_USDC));
          console.log(`Minted ${formatUnits(totalMinted, 6)} USDC`);
          console.log(`Mint transaction ID (${DESTINATION_CHAIN}):`, txId);
        }

        main().catch((error) => {
          console.error("\nError:", error);
          process.exit(1);
        });
        ```

        ### 4.8. Run the EVM to EVM transfer script

        ```shell theme={null}
        npm run transfer-from-evm -- arc
        ```

        ```shell theme={null}
        npm run transfer-from-evm -- ethereum base
        ```

        ```shell theme={null}
        npm run transfer-from-evm -- all
        ```
      </Tab>

      <Tab title="Transfer from Solana">
        ## Step 4. Transfer USDC from Solana to EVM

        The transfer script burns USDC on Solana Devnet and mints on a destination EVM
        chain via Gateway. You can skip to the
        [full transfer script](#4-7-full-solana-transfer-script-circle-wallets) if you
        prefer.

        ### 4.1. Create the Solana to EVM transfer script

        ```shell theme={null}
        touch transfer-from-sol.ts
        ```

        ### 4.2. Define constants and types

        The validated script uses Arc Testnet as the destination chain. Update
        `DESTINATION_CHAIN` if you want to mint on a different supported EVM testnet.

        This flow mirrors the standard Solana to EVM Gateway quickstart, but swaps in
        Circle Wallet signing and transaction execution.

        ```ts theme={null}
        const DESTINATION_CHAIN: Chain = "arc";

        const SOLANA_GATEWAY_WALLET = "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
        const SOLANA_USDC = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
        const SOLANA_DOMAIN = 5;
        ```

        ### 4.3. Add helper functions

        The helper layer encodes the Solana burn intent into the binary layout expected
        by Gateway, then normalizes addresses and payloads for the API request.

        ```ts theme={null}
        function solanaAddressToBytes32(address: string): string {
          const decoded = Buffer.from(bs58.decode(address));
          return `0x${decoded.toString("hex")}`;
        }

        function evmAddressToBytes32(address: string): string {
          return "0x" + address.toLowerCase().replace(/^0x/, "").padStart(64, "0");
        }
        ```

        ### 4.4. Create and sign burn intent

        Build the Solana burn intent, prefix the encoded payload, and sign it with the
        source Solana Developer-Controlled Wallet.

        For Solana-origin transfers, the burn intent uses Solana-specific binary
        encoding and must be signed with the Solana signing-domain prefix. See the
        [Solana Technical Guide](/gateway/references/solana#signing) for the signing
        rules and message format details.

        ```ts theme={null}
        const burnIntent = createBurnIntent({
          sourceDepositor: DEPOSITOR_ADDRESS,
          destinationRecipient: RECIPIENT_ADDRESS,
        });

        const encoded = encodeBurnIntent(burnIntent);
        const prefixed = Buffer.concat([
          Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
          encoded,
        ]);

        const sigResult = await client.signMessage({
          walletAddress: DEPOSITOR_ADDRESS,
          blockchain: "SOL-DEVNET",
          encodedByHex: true,
          message: "0x" + prefixed.toString("hex"),
        });
        ```

        ### 4.5. Request attestation from Gateway API

        Submit the signed burn intent to the Gateway API and verify that it returns the
        attestation and operator signature required by the destination minter.

        ```ts theme={null}
        const response = await fetch(
          "https://gateway-api-testnet.circle.com/v1/transfer",
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: stringifyTypedData(request),
          },
        );
        ```

        ### 4.6. Mint on destination chain

        Use the destination EVM Developer-Controlled Wallet to call
        `gatewayMint(bytes,bytes)` on the Gateway Minter contract, then wait for
        completion.

        ```ts theme={null}
        const tx = await client.createContractExecutionTransaction({
          walletAddress: RECIPIENT_ADDRESS,
          blockchain: destConfig.walletChain,
          contractAddress: GATEWAY_MINTER_ADDRESS,
          abiFunctionSignature: "gatewayMint(bytes,bytes)",
          abiParameters: [attestation, operatorSig],
          fee: { type: "level", config: { feeLevel: "MEDIUM" } },
        });

        await waitForTxCompletion(client, txId, "USDC mint");
        ```

        ### 4.7. Full Solana transfer script (Circle Wallets)

        The script signs a Solana burn intent, requests a Gateway attestation, and mints
        on the destination EVM chain. Inline comments explain each stage.

        ```ts transfer-from-sol.ts expandable theme={null}
        import { randomBytes } from "node:crypto";
        import { PublicKey } from "@solana/web3.js";
        import { u32be, struct, blob, offset, Layout } from "@solana/buffer-layout";
        import bs58 from "bs58";
        import {
          chainConfig,
          GATEWAY_MINTER_ADDRESS,
          client,
          waitForTxCompletion,
          type Chain,
        } from "./config.js";

        const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;
        const RECIPIENT_ADDRESS = process.env.RECIPIENT_ADDRESS!;

        if (!DEPOSITOR_ADDRESS || !RECIPIENT_ADDRESS) {
          console.error(
            "Missing required env vars: DEPOSITOR_ADDRESS, RECIPIENT_ADDRESS",
          );
          process.exit(1);
        }

        const DESTINATION_CHAIN: Chain = "arc";

        const SOLANA_GATEWAY_WALLET = "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
        const SOLANA_USDC = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
        const SOLANA_DOMAIN = 5;

        const TRANSFER_AMOUNT = 0.1;
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;

        const TRANSFER_SPEC_MAGIC = 0xca85def7;
        const BURN_INTENT_MAGIC = 0x070afbc2;

        // Custom layout for Solana PublicKey values in the burn intent payload.
        class PublicKeyLayout extends Layout<PublicKey> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0): PublicKey {
            return new PublicKey(b.subarray(offset, offset + 32));
          }
          encode(src: PublicKey, b: Buffer, offset = 0): number {
            const pubkeyBuffer = src.toBuffer();
            pubkeyBuffer.copy(b, offset);
            return 32;
          }
        }

        const publicKey = (property: string) => new PublicKeyLayout(property);

        // Custom layout for 256-bit unsigned integers.
        class UInt256BE extends Layout<bigint> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0) {
            const buffer = b.subarray(offset, offset + 32);
            return buffer.readBigUInt64BE(24);
          }
          encode(src: bigint, b: Buffer, offset = 0) {
            const buffer = Buffer.alloc(32);
            buffer.writeBigUInt64BE(BigInt(src), 24);
            buffer.copy(b, offset);
            return 32;
          }
        }

        const uint256be = (property: string) => new UInt256BE(property);

        const BurnIntentLayout = struct([
          u32be("magic"),
          uint256be("maxBlockHeight"),
          uint256be("maxFee"),
          u32be("transferSpecLength"),
          struct(
            [
              u32be("magic"),
              u32be("version"),
              u32be("sourceDomain"),
              u32be("destinationDomain"),
              publicKey("sourceContract"),
              publicKey("destinationContract"),
              publicKey("sourceToken"),
              publicKey("destinationToken"),
              publicKey("sourceDepositor"),
              publicKey("destinationRecipient"),
              publicKey("sourceSigner"),
              publicKey("destinationCaller"),
              uint256be("value"),
              blob(32, "salt"),
              u32be("hookDataLength"),
              blob(offset(u32be(), -4), "hookData"),
            ] as any,
            "spec",
          ),
        ] as any);

        function createBurnIntent(params: {
          sourceDepositor: string;
          destinationRecipient: string;
        }) {
          const { sourceDepositor, destinationRecipient } = params;
          const destConfig = chainConfig[DESTINATION_CHAIN];

          return {
            maxBlockHeight: MAX_UINT64,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: SOLANA_DOMAIN,
              destinationDomain: destConfig.domain,
              sourceContract: solanaAddressToBytes32(SOLANA_GATEWAY_WALLET),
              destinationContract: evmAddressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: solanaAddressToBytes32(SOLANA_USDC),
              destinationToken: evmAddressToBytes32(destConfig.usdc),
              sourceDepositor: solanaAddressToBytes32(sourceDepositor),
              destinationRecipient: evmAddressToBytes32(destinationRecipient),
              sourceSigner: solanaAddressToBytes32(sourceDepositor),
              destinationCaller: evmAddressToBytes32(
                "0x0000000000000000000000000000000000000000",
              ),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Encode the burn intent into the binary layout expected by Gateway.
        function encodeBurnIntent(bi: ReturnType<typeof createBurnIntent>): Buffer {
          const hookData = Buffer.from((bi.spec.hookData || "0x").slice(2), "hex");
          const prepared = {
            magic: BURN_INTENT_MAGIC,
            maxBlockHeight: bi.maxBlockHeight,
            maxFee: bi.maxFee,
            transferSpecLength: 340 + hookData.length,
            spec: {
              magic: TRANSFER_SPEC_MAGIC,
              version: bi.spec.version,
              sourceDomain: bi.spec.sourceDomain,
              destinationDomain: bi.spec.destinationDomain,
              sourceContract: hexToPublicKey(bi.spec.sourceContract),
              destinationContract: hexToPublicKey(bi.spec.destinationContract),
              sourceToken: hexToPublicKey(bi.spec.sourceToken),
              destinationToken: hexToPublicKey(bi.spec.destinationToken),
              sourceDepositor: hexToPublicKey(bi.spec.sourceDepositor),
              destinationRecipient: hexToPublicKey(bi.spec.destinationRecipient),
              sourceSigner: hexToPublicKey(bi.spec.sourceSigner),
              destinationCaller: hexToPublicKey(bi.spec.destinationCaller),
              value: bi.spec.value,
              salt: Buffer.from(bi.spec.salt.slice(2), "hex"),
              hookDataLength: hookData.length,
              hookData,
            },
          };
          const buffer = Buffer.alloc(72 + 340 + hookData.length);
          const bytesWritten = BurnIntentLayout.encode(prepared, buffer);
          return buffer.subarray(0, bytesWritten);
        }

        // Convert a Solana address to a 32-byte hex string.
        function solanaAddressToBytes32(address: string): string {
          const decoded = Buffer.from(bs58.decode(address));
          return `0x${decoded.toString("hex")}`;
        }

        // Convert an EVM address to a 32-byte hex string.
        function evmAddressToBytes32(address: string): string {
          return "0x" + address.toLowerCase().replace(/^0x/, "").padStart(64, "0");
        }

        // Convert a 32-byte hex string into a Solana PublicKey.
        function hexToPublicKey(hex: string): PublicKey {
          return new PublicKey(Buffer.from(hex.slice(2), "hex"));
        }

        // Serialize typed data while converting bigint values to strings.
        function stringifyTypedData<T>(obj: T) {
          return JSON.stringify(obj, (_key, value) =>
            typeof value === "bigint" ? value.toString() : value,
          );
        }

        async function main() {
          const destConfig = chainConfig[DESTINATION_CHAIN];

          console.log(`Sender (Solana): ${DEPOSITOR_ADDRESS}`);
          console.log(`Recipient (EVM): ${RECIPIENT_ADDRESS}`);
          console.log(`Transferring from: Solana Devnet -> ${destConfig.chainName}`);

          console.log(
            `Creating burn intent from Solana Devnet -> ${destConfig.chainName}...`,
          );

          // [1] Create and sign the Solana burn intent.
          const burnIntent = createBurnIntent({
            sourceDepositor: DEPOSITOR_ADDRESS,
            destinationRecipient: RECIPIENT_ADDRESS,
          });

          const encoded = encodeBurnIntent(burnIntent);
          const prefixed = Buffer.concat([
            Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
            encoded,
          ]);

          const sigResult = await client.signMessage({
            walletAddress: DEPOSITOR_ADDRESS,
            blockchain: "SOL-DEVNET",
            encodedByHex: true,
            message: "0x" + prefixed.toString("hex"),
          });

          const burnIntentSignature = sigResult.data?.signature;
          if (!burnIntentSignature) throw new Error("Failed to sign burn intent");

          const formattedSignature = burnIntentSignature.startsWith("0x")
            ? burnIntentSignature
            : `0x${burnIntentSignature}`;

          const request = [{ burnIntent, signature: formattedSignature }];
          console.log("Signed burn intent.");

          // [2] Request the attestation set from Gateway API.
          const response = await fetch(
            "https://gateway-api-testnet.circle.com/v1/transfer",
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: stringifyTypedData(request),
            },
          );

          if (!response.ok) {
            console.error("Gateway API error status:", response.status);
            console.error(await response.text());
            throw new Error("Gateway API request failed");
          }

          const json = (await response.json()) as {
            attestation: string;
            signature: string;
          };
          console.log("Gateway API response:", JSON.stringify(json, null, 2));

          const attestation = json?.attestation;
          const operatorSig = json?.signature;

          if (!attestation || !operatorSig) {
            throw new Error("Missing attestation or signature in Gateway API response");
          }

          // [3] Mint on the destination EVM chain with the returned attestation.
          console.log(`Minting funds on ${destConfig.chainName}...`);

          const tx = await client.createContractExecutionTransaction({
            walletAddress: RECIPIENT_ADDRESS,
            blockchain: destConfig.walletChain,
            contractAddress: GATEWAY_MINTER_ADDRESS,
            abiFunctionSignature: "gatewayMint(bytes,bytes)",
            abiParameters: [attestation, operatorSig],
            fee: { type: "level", config: { feeLevel: "MEDIUM" } },
          });

          const txId = tx.data?.id;
          if (!txId) throw new Error("Failed to submit mint transaction");
          console.log("Mint tx submitted:", txId);

          await waitForTxCompletion(client, txId, "USDC mint");

          console.log(`Minted ${Number(TRANSFER_VALUE) / 1_000_000} USDC`);
          console.log(`Mint transaction ID (${destConfig.walletChain}):`, txId);
        }

        main().catch((error) => {
          console.error("\nError:", error);
          process.exit(1);
        });
        ```

        ### 4.8. Run the Solana to EVM transfer script

        Before you run this script, update `.env` so:

        * `DEPOSITOR_ADDRESS` is the Solana source wallet
        * `RECIPIENT_ADDRESS` is the destination EVM wallet

        Then run:

        ```shell theme={null}
        npm run transfer-from-sol
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Self-managed">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared an EVM testnet wallet with the private key available
      * Added the
        [supported Testnets](/gateway/references/supported-blockchains#testnet) of
        your choice to your wallet

    If you want to try the Solana to EVM transfer, ensure that you've:

    * Prepared a Solana Devnet wallet and exported its keypair as a JSON array
    * Completed
      [Step 3: Deposit into a unified crosschain balance](/gateway/quickstarts/unified-balance-solana#step-3-deposit-into-a-unified-crosschain-balance-self-managed)
      from the
      [Solana quickstart](/gateway/quickstarts/unified-balance-solana#self-managed)

    ### Add testnet funds to your wallet

    To interact with Gateway, you need test USDC and native tokens in your wallet on
    each chain you deposit from. You also need testnet native tokens on the
    destination chain to call the Gateway Minter contract.

    Use the [Circle Faucet](https://faucet.circle.com/) to get testnet USDC. If you
    have a [Circle Developer Console](https://console.circle.com) account, you can
    use the [Console Faucet](https://console.circle.com/faucet) to get testnet
    native tokens. In addition, the following faucets can also be used to fund your
    wallet with testnet native tokens:

    <Tabs>
      <Tab title="Arc">
        **Faucet:** [Arc Testnet](https://faucet.circle.com) (USDC + native tokens)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `arcTestnet`                                 |
        | USDC address | `0x3600000000000000000000000000000000000000` |
        | Domain ID    | `26`                                         |
      </Tab>

      <Tab title="Avalanche">
        **Faucet:** [Avalanche Fuji](https://core.app/tools/testnet-faucet)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `avalancheFuji`                              |
        | USDC address | `0x5425890298aed601595a70ab815c96711a31bc65` |
        | Domain ID    | `1`                                          |
      </Tab>

      <Tab title="Base">
        **Faucet:** [Base Sepolia](https://www.alchemy.com/faucets/base-sepolia)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `baseSepolia`                                |
        | USDC address | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
        | Domain ID    | `6`                                          |
      </Tab>

      <Tab title="Ethereum">
        **Faucet:** [Ethereum Sepolia](https://cloud.google.com/application/web3/faucet/ethereum/sepolia)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `sepolia`                                    |
        | USDC address | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` |
        | Domain ID    | `0`                                          |
      </Tab>

      <Tab title="Hyperliquid">
        **Faucet:** [Hyperliquid EVM Testnet](https://app.hyperliquid-testnet.xyz/drip)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `hyperliquidEvmTestnet`                      |
        | USDC address | `0x2B3370eE501B4a559b57D449569354196457D8Ab` |
        | Domain ID    | `19`                                         |
      </Tab>

      <Tab title="Sei">
        **Faucet:** [Sei Testnet](https://docs.sei.io/learn/faucet)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `seiTestnet`                                 |
        | USDC address | `0x4fCF1784B31630811181f670Aea7A7bEF803eaED` |
        | Domain ID    | `16`                                         |
      </Tab>

      <Tab title="Solana">
        **Faucet:** [Solana Devnet](https://faucet.solana.com/)

        | Property     | Value                                                   |
        | ------------ | ------------------------------------------------------- |
        | Chain name   | `solanaDevnet` (note that Solana is not EVM-compatible) |
        | USDC address | `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`          |
        | Domain ID    | `5`                                                     |
      </Tab>

      <Tab title="Sonic">
        **Faucet:** [Sonic Testnet](https://testnet.soniclabs.com/account)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `sonicTestnet`                               |
        | USDC address | `0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51` |
        | Domain ID    | `13`                                         |
      </Tab>

      <Tab title="Worldchain">
        **Faucet:** [Worldchain Sepolia](https://www.l2faucet.com/world)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `worldchainSepolia`                          |
        | USDC address | `0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88` |
        | Domain ID    | `14`                                         |
      </Tab>
    </Tabs>

    ## Step 1: Set up your project

    This step shows you how to prepare your project and environment.

    ### 1.1. Create a new project

    Create a new directory and install the required dependencies:

    ```shell theme={null}
    # Set up your directory and initialize a Node.js project
    mkdir unified-gateway-balance-evm
    cd unified-gateway-balance-evm
    npm init -y

    # Set up module type and run scripts
    npm pkg set type=module
    npm pkg set scripts.deposit="tsx --env-file=.env deposit.ts"
    npm pkg set scripts.transfer-from-evm="tsx --env-file=.env transfer-from-evm.ts"
    npm pkg set scripts.balances="tsx --env-file=.env balances.ts"

    # Install dependencies
    npm install viem tsx typescript
    npm install --save-dev @types/node
    ```

    If you want to try the Solana to EVM transfer, add the run script and install
    these additional dependencies:

    ```shell theme={null}
    npm pkg set scripts.transfer-from-sol="tsx --env-file=.env transfer-from-sol.ts"
    npm pkg set overrides.bigint-buffer=npm:@trufflesuite/bigint-buffer@1.1.10
    npm install @coral-xyz/anchor @solana/buffer-layout @solana/spl-token @solana/web3.js bs58
    ```

    ### 1.2. Initialize and configure the project

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3 Configure environment variables

    Open `.env` in your editor and add:

    ```text theme={null}
    EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY
    ```

    If you want to try the Solana to EVM transfer, also add:

    ```text theme={null}
    SOLANA_PRIVATE_KEYPAIR=YOUR_SOLANA_KEYPAIR_ARRAY
    ```

    * `EVM_PRIVATE_KEY` is the private key for the EVM wallet you use for the EVM
      side of the transfer.
    * `SOLANA_PRIVATE_KEYPAIR` is the Solana wallet keypair as a JSON array for the
      Solana side of the transfer.

    <Note>
      If your wallet exports a private key hash instead, you can use `bs58` to convert it:

      ```ts TypeScript theme={null}
      const bytes = bs58.decode({ YOUR_PRIVATE_KEY_HASH });
      console.log(JSON.stringify(Array.from(bytes)));
      ```
    </Note>

    <Tip>
      Open `.env` in your editor rather than writing values with shell commands, and
      add `.env` to your `.gitignore`. This prevents credentials from leaking into
      your shell history or version control.
    </Tip>

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Set up the configuration file

    This section covers the shared configuration file will be used by both the
    deposit and transfer scripts.

    ### 2.1. Create the configuration file

    ```shell theme={null}
    touch config.ts
    ```

    ### 2.2. Configure wallet account and chain settings

    Add the account setup, Gateway contract addresses, and chain-specific
    configuration to your `config.ts` file. This includes RPC endpoints, USDC
    addresses, and domain IDs for all supported testnet chains.

    ```ts config.ts expandable theme={null}
    import { type Address } from "viem";
    import {
      sepolia,
      baseSepolia,
      avalancheFuji,
      arcTestnet,
      hyperliquidEvmTestnet,
      seiTestnet,
      sonicTestnet,
      worldchainSepolia,
    } from "viem/chains";
    import { privateKeyToAccount } from "viem/accounts";

    /* Account Setup */
    if (!process.env.EVM_PRIVATE_KEY) {
      throw new Error("EVM_PRIVATE_KEY not set in environment");
    }
    export const account = privateKeyToAccount(
      process.env.EVM_PRIVATE_KEY as `0x${string}`,
    );

    /* Gateway Contract Addresses */
    export const GATEWAY_WALLET_ADDRESS: Address =
      "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
    export const GATEWAY_MINTER_ADDRESS: Address =
      "0x0022222ABE238Cc2C7Bb1f21003F0a260052475B";

    /* Chain Configuration */
    export const chainConfigs = {
      sepolia: {
        chain: sepolia,
        usdcAddress: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as Address,
        domainId: 0,
      },
      baseSepolia: {
        chain: baseSepolia,
        usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e" as Address,
        domainId: 6,
      },
      avalancheFuji: {
        chain: avalancheFuji,
        usdcAddress: "0x5425890298aed601595a70ab815c96711a31bc65" as Address,
        domainId: 1,
      },
      arcTestnet: {
        chain: arcTestnet,
        usdcAddress: "0x3600000000000000000000000000000000000000" as Address,
        domainId: 26,
      },
      hyperliquidEvmTestnet: {
        chain: hyperliquidEvmTestnet,
        usdcAddress: "0x2B3370eE501B4a559b57D449569354196457D8Ab" as Address,
        domainId: 19,
      },
      seiTestnet: {
        chain: seiTestnet,
        usdcAddress: "0x4fCF1784B31630811181f670Aea7A7bEF803eaED" as Address,
        domainId: 16,
      },
      sonicTestnet: {
        chain: sonicTestnet,
        usdcAddress: "0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51" as Address,
        domainId: 13,
      },
      worldchainSepolia: {
        chain: worldchainSepolia,
        usdcAddress: "0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88" as Address,
        domainId: 14,
      },
    } as const;

    export type ChainKey = keyof typeof chainConfigs;

    /* CLI Argument Parsing Helper */
    export function parseSelectedChains(): ChainKey[] {
      const args = process.argv.slice(2);
      const validChains = Object.keys(chainConfigs) as ChainKey[];

      if (args.length === 0) {
        throw new Error(
          "No chains specified. Usage: npm run <script> <chain1> [chain2...] or 'all'",
        );
      }

      if (args.length === 1 && args[0] === "all") {
        return validChains;
      }

      const invalid = args.filter((c) => !validChains.includes(c as ChainKey));
      if (invalid.length > 0) {
        console.error(`Unsupported chain: ${invalid.join(", ")}`);
        console.error(`Valid chains: ${validChains.join(", ")}, all`);
        process.exit(1);
      }

      return [...new Set(args)] as ChainKey[];
    }
    ```

    ## Step 3: Deposit into a unified crosschain balance (Self-managed)

    This section explains parts of the deposit script that allows you to deposit
    USDC into the Gateway Wallet contracts. The script accepts chain names as CLI
    arguments. Specify one or more chains (for example, `arcTestnet` `baseSepolia`)
    or use `all` for all supported testnets. You can skip to the
    [full deposit script](#3-5-full-deposit-script-self-managed) if you prefer.

    ### 3.1. Create the script file

    ```shell theme={null}
    touch deposit.ts
    ```

    ### 3.2. Define constants and ABI

    ```ts deposit.ts theme={null}
    const DEPOSIT_AMOUNT = 2_000000n; // 2 USDC (6 decimals)

    // Gateway Wallet ABI (minimal - only deposit function)
    const gatewayWalletAbi = [
      {
        type: "function",
        name: "deposit",
        inputs: [
          { name: "token", type: "address" },
          { name: "value", type: "uint256" },
        ],
        outputs: [],
        stateMutability: "nonpayable",
      },
    ] as const;
    ```

    ### 3.3. Setup clients and check balances

    Set up the client and contracts for the chain, then verify sufficient USDC
    balance before depositing.

    ```ts deposit.ts theme={null}
    const config = chainConfigs[chainName];

    // Create client for current chain
    const client = createPublicClient({
      chain: config.chain,
      transport: http(),
    });

    // Get contract instances
    const usdcContract = getContract({
      address: config.usdcAddress,
      abi: erc20Abi,
      client,
    });

    const gatewayWallet = getContract({
      address: GATEWAY_WALLET_ADDRESS,
      abi: gatewayWalletAbi,
      client,
    });

    // Check USDC balance
    const balance = await usdcContract.read.balanceOf([account.address]);
    console.log(`Current balance: ${formatUnits(balance, 6)} USDC`);

    if (balance < DEPOSIT_AMOUNT) {
      throw new Error(
        "Insufficient USDC balance. Please top up at https://faucet.circle.com",
      );
    }
    ```

    ### 3.4. Approve and deposit USDC

    The main logic performs two key actions:

    * Approve USDC transfers: It calls the `approve` method on the USDC contract to
      allow the Gateway Wallet contract to transfer USDC from your wallet.
    * Deposit USDC into Gateway: After receiving the approval transaction hash, it
      calls the `deposit` method on the Gateway Wallet contract.

    ```ts deposit.ts theme={null}
    // [1] Approve Gateway Wallet to spend USDC
    console.log(
      `Approving ${formatUnits(DEPOSIT_AMOUNT, 6)} USDC on ${chainName}...`,
    );
    const approvalTx = await usdcContract.write.approve(
      [GATEWAY_WALLET_ADDRESS, DEPOSIT_AMOUNT],
      { account },
    );
    await client.waitForTransactionReceipt({ hash: approvalTx });
    console.log(`Approved on ${chainName}: ${approvalTx}`);

    // [2] Deposit USDC into Gateway Wallet
    console.log(
      `Depositing ${formatUnits(DEPOSIT_AMOUNT, 6)} USDC to Gateway Wallet`,
    );
    const depositTx = await gatewayWallet.write.deposit(
      [config.usdcAddress, DEPOSIT_AMOUNT],
      { account },
    );
    await client.waitForTransactionReceipt({ hash: depositTx });
    console.log(`Done on ${chainName}. Deposit tx: ${depositTx}`);
    ```

    ### 3.5. Full deposit script (Self-managed)

    The complete deposit script loops through selected chains, validates USDC
    balances, and deposits funds into the Gateway Wallet contract on each chain. The
    script includes inline comments to explain what each function does, making it
    easier to follow and modify if needed.

    ```ts deposit.ts expandable theme={null}
    import {
      createPublicClient,
      getContract,
      http,
      erc20Abi,
      formatUnits,
    } from "viem";
    import {
      account,
      chainConfigs,
      parseSelectedChains,
      GATEWAY_WALLET_ADDRESS,
    } from "./config.js";

    const DEPOSIT_AMOUNT = 2_000000n; // 2 USDC (6 decimals)

    // Gateway Wallet ABI (minimal - only deposit function)
    const gatewayWalletAbi = [
      {
        type: "function",
        name: "deposit",
        inputs: [
          { name: "token", type: "address" },
          { name: "value", type: "uint256" },
        ],
        outputs: [],
        stateMutability: "nonpayable",
      },
    ] as const;

    async function main() {
      console.log(`Using account: ${account.address}\n`);

      const selectedChains = parseSelectedChains();
      console.log(`Depositing on: ${selectedChains.join(", ")}\n`);

      for (const chainName of selectedChains) {
        const config = chainConfigs[chainName];

        // Create client for current chain
        const client = createPublicClient({
          chain: config.chain,
          transport: http(),
        });

        // Get contract instances
        const usdcContract = getContract({
          address: config.usdcAddress,
          abi: erc20Abi,
          client,
        });

        const gatewayWallet = getContract({
          address: GATEWAY_WALLET_ADDRESS,
          abi: gatewayWalletAbi,
          client,
        });

        console.log(`\n=== Processing ${chainName} ===`);

        // Check USDC balance
        const balance = await usdcContract.read.balanceOf([account.address]);
        console.log(`Current balance: ${formatUnits(balance, 6)} USDC`);

        if (balance < DEPOSIT_AMOUNT) {
          throw new Error(
            "Insufficient USDC balance. Please top up at https://faucet.circle.com",
          );
        }

        try {
          // [1] Approve Gateway Wallet to spend USDC
          console.log(
            `Approving ${formatUnits(DEPOSIT_AMOUNT, 6)} USDC on ${chainName}...`,
          );
          const approvalTx = await usdcContract.write.approve(
            [GATEWAY_WALLET_ADDRESS, DEPOSIT_AMOUNT],
            { account },
          );
          await client.waitForTransactionReceipt({ hash: approvalTx });
          console.log(`Approved on ${chainName}: ${approvalTx}`);

          // [2] Deposit USDC into Gateway Wallet
          console.log(
            `Depositing ${formatUnits(DEPOSIT_AMOUNT, 6)} USDC to Gateway Wallet`,
          );
          const depositTx = await gatewayWallet.write.deposit(
            [config.usdcAddress, DEPOSIT_AMOUNT],
            { account },
          );
          await client.waitForTransactionReceipt({ hash: depositTx });
          console.log(`Done on ${chainName}. Deposit tx: ${depositTx}`);
        } catch (err) {
          console.error(`Error on ${chainName}:`, err);
        }
      }
    }

    main().catch((error) => {
      console.error("\nError:", error);
      process.exit(1);
    });
    ```

    ### 3.6. Run the script to create a crosschain balance

    Run the deposit script to make the deposits. You must specify at least one chain
    using command-line arguments.

    ```shell theme={null}
    # Deposit to all supported chains
    npm run deposit -- all

    # Deposit to a single chain
    npm run deposit -- sepolia

    # Deposit to multiple chains
    npm run deposit -- baseSepolia avalancheFuji
    ```

    Wait for the
    [required number of block confirmations](https://developers.circle.com/gateway/references/supported-blockchains#required-block-confirmations).
    Once the deposit transactions are final, the total balance is the sum of all the
    USDC from deposit transactions across all supported chains that have reached
    finality. Note that for certain chains, finality may take up to 20 minutes to be
    reached.

    ### 3.7. Check the balances on the Gateway Wallet

    Create a new file called `balances.ts`, and add the following code. This script
    retrieves the USDC balances available from your Gateway Wallet on each supported
    chain.

    ```ts balances.ts expandable theme={null}
    import { privateKeyToAccount } from "viem/accounts";

    if (!process.env.EVM_PRIVATE_KEY) {
      throw new Error("Missing EVM_PRIVATE_KEY in environment");
    }

    const DOMAINS = {
      sepolia: 0,
      avalancheFuji: 1,
      baseSepolia: 6,
      arcTestnet: 26,
      hyperliquidEvmTestnet: 19,
      seiTestnet: 16,
      sonicTestnet: 13,
      worldchainSepolia: 14,
    };

    async function main() {
      const account = privateKeyToAccount(
        process.env.EVM_PRIVATE_KEY as `0x${string}`,
      );
      const depositor = account.address;

      console.log(`Depositor address: ${depositor}\n`);

      const body = {
        token: "USDC",
        sources: Object.entries(DOMAINS).map(([_, domain]) => ({
          domain,
          depositor,
        })),
      };

      const res = await fetch(
        "https://gateway-api-testnet.circle.com/v1/balances",
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(body),
        },
      );

      const result = await res.json();

      let total = 0;
      for (const balance of result.balances) {
        const chain =
          Object.keys(DOMAINS).find(
            (key) => DOMAINS[key as keyof typeof DOMAINS] === balance.domain,
          ) || `Domain ${balance.domain}`;
        const amount = parseFloat(balance.balance);
        console.log(`${chain}: ${amount.toFixed(6)} USDC`);
        total += amount;
      }

      console.log(`\nTotal: ${total.toFixed(6)} USDC`);
    }

    main().catch((error) => {
      console.error("\nError:", error);
      process.exit(1);
    });
    ```

    You can run it to check whether finality has been reached for recent
    transactions.

    ```shell theme={null}
    npm run balances
    ```

    <Tabs>
      <Tab title="Transfer from EVM">
        ## Step 4: Transfer USDC from the crosschain balance

        This section explains parts of the transfer script that burns USDC from source
        chains and mints on a destination chain via Gateway. The script accepts chain
        names as CLI arguments. Specify one or more source chains (for example,
        `seiTestnet` or `arcTestnet`) or use `all` for all supported testnets. You can
        skip to the [full transfer script](#4-7-full-evm-transfer-script-self-managed)
        if you prefer.

        ### 4.1. Create the script file

        ```shell theme={null}
        touch transfer-from-evm.ts
        ```

        ### 4.2. Define constants and types

        You can set which chain to deposit to by modifying the `DESTINATION_CHAIN`
        value. This example sets it to `seiTestnet`. You can also set the amount to be
        transferred from each source chain by changing the `TRANSFER_VALUE`.

        ```ts transfer-from-evm.ts theme={null}
        const DESTINATION_CHAIN: ChainKey = "seiTestnet";
        const TRANSFER_VALUE = 1_000000n; // 1 USDC (6 decimals)
        const MAX_FEE = 2_010000n;

        // EIP-712 Domain and Types for Gateway burn intents
        const domain = { name: "GatewayWallet", version: "1" };

        const EIP712Domain = [
          { name: "name", type: "string" },
          { name: "version", type: "string" },
        ] as const;

        const TransferSpec = [
          { name: "version", type: "uint32" },
          { name: "sourceDomain", type: "uint32" },
          { name: "destinationDomain", type: "uint32" },
          { name: "sourceContract", type: "bytes32" },
          { name: "destinationContract", type: "bytes32" },
          { name: "sourceToken", type: "bytes32" },
          { name: "destinationToken", type: "bytes32" },
          { name: "sourceDepositor", type: "bytes32" },
          { name: "destinationRecipient", type: "bytes32" },
          { name: "sourceSigner", type: "bytes32" },
          { name: "destinationCaller", type: "bytes32" },
          { name: "value", type: "uint256" },
          { name: "salt", type: "bytes32" },
          { name: "hookData", type: "bytes" },
        ] as const;

        const BurnIntent = [
          { name: "maxBlockHeight", type: "uint256" },
          { name: "maxFee", type: "uint256" },
          { name: "spec", type: "TransferSpec" },
        ] as const;

        const gatewayMinterAbi = [
          {
            type: "function",
            name: "gatewayMint",
            inputs: [
              { name: "attestationPayload", type: "bytes" },
              { name: "signature", type: "bytes" },
            ],
            outputs: [],
            stateMutability: "nonpayable",
          },
        ] as const;
        ```

        ### 4.3. Add helper functions

        ```ts transfer-from-evm.ts theme={null}
        // Create a burn intent for cross-chain transfer
        function createBurnIntent(params: {
          sourceChain: ChainKey;
          depositorAddress: string;
          recipientAddress?: string;
        }) {
          const {
            sourceChain,
            depositorAddress,
            recipientAddress = depositorAddress,
          } = params;
          const sourceConfig = chainConfigs[sourceChain];
          const destConfig = chainConfigs[DESTINATION_CHAIN];

          return {
            maxBlockHeight: maxUint256,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: sourceConfig.domainId,
              destinationDomain: destConfig.domainId,
              sourceContract: GATEWAY_WALLET_ADDRESS,
              destinationContract: GATEWAY_MINTER_ADDRESS,
              sourceToken: sourceConfig.usdcAddress,
              destinationToken: destConfig.usdcAddress,
              sourceDepositor: depositorAddress,
              destinationRecipient: recipientAddress,
              sourceSigner: depositorAddress,
              destinationCaller: zeroAddress,
              value: TRANSFER_VALUE,
              salt: ("0x" + randomBytes(32).toString("hex")) as Hex,
              hookData: "0x" as Hex,
            },
          };
        }

        // Create EIP-712 typed data for signing
        function burnIntentTypedData(burnIntent: ReturnType<typeof createBurnIntent>) {
          return {
            types: { EIP712Domain, TransferSpec, BurnIntent },
            domain,
            primaryType: "BurnIntent" as const,
            message: {
              ...burnIntent,
              spec: {
                ...burnIntent.spec,
                sourceContract: addressToBytes32(burnIntent.spec.sourceContract),
                destinationContract: addressToBytes32(
                  burnIntent.spec.destinationContract,
                ),
                sourceToken: addressToBytes32(burnIntent.spec.sourceToken),
                destinationToken: addressToBytes32(burnIntent.spec.destinationToken),
                sourceDepositor: addressToBytes32(burnIntent.spec.sourceDepositor),
                destinationRecipient: addressToBytes32(
                  burnIntent.spec.destinationRecipient,
                ),
                sourceSigner: addressToBytes32(burnIntent.spec.sourceSigner),
                destinationCaller: addressToBytes32(burnIntent.spec.destinationCaller),
              },
            },
          };
        }

        // Convert address to bytes32
        function addressToBytes32(address: string): Hex {
          return pad(address.toLowerCase() as Hex, { size: 32 });
        }
        ```

        ### 4.4. Create and sign burn intents

        ```ts transfer-from-evm.ts theme={null}
        const requests = [];

        for (const chainName of selectedChains) {
          console.log(
            `Creating burn intent from ${chainName} → ${DESTINATION_CHAIN}...`,
          );

          const intent = createBurnIntent({
            sourceChain: chainName,
            depositorAddress: account.address,
          });

          const typedData = burnIntentTypedData(intent);
          const signature = await account.signTypedData(typedData);

          requests.push({ burnIntent: typedData.message, signature });
        }
        console.log("Signed burn intents.");
        ```

        ### 4.5. Request attestation from Gateway API

        ```ts transfer-from-evm.ts theme={null}
        const response = await fetch(
          "https://gateway-api-testnet.circle.com/v1/transfer",
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(requests, (_key, value) =>
              typeof value === "bigint" ? value.toString() : value,
            ),
          },
        );

        if (!response.ok) {
          const text = await response.text();
          throw new Error(`Gateway API error: ${response.status} ${text}`);
        }

        const json = await response.json();
        console.log("Gateway API response:", JSON.stringify(json, null, 2));

        const attestation = json?.attestation;
        const operatorSig = json?.signature;

        if (!attestation || !operatorSig) {
          throw new Error("Missing attestation or signature in response");
        }
        ```

        ### 4.6. Mint on destination chain

        ```ts transfer-from-evm.ts theme={null}
        const destConfig = chainConfigs[DESTINATION_CHAIN];

        const destClient = createPublicClient({
          chain: destConfig.chain,
          transport: http(),
        });

        const walletClient = createWalletClient({
          account,
          chain: destConfig.chain,
          transport: http(),
        });

        const destinationGatewayMinterContract = getContract({
          address: GATEWAY_MINTER_ADDRESS,
          abi: gatewayMinterAbi,
          client: { public: destClient, wallet: walletClient },
        });

        console.log(`Minting funds on ${destConfig.chain.name}...`);
        const mintTx = await destinationGatewayMinterContract.write.gatewayMint(
          [attestation, operatorSig],
          { account },
        );

        await destClient.waitForTransactionReceipt({ hash: mintTx });

        const totalMinted = BigInt(requests.length) * TRANSFER_VALUE;
        console.log(`Minted ${formatUnits(totalMinted, 6)} USDC`);
        console.log(`Mint transaction hash (${DESTINATION_CHAIN}):`, mintTx);
        ```

        ### 4.7. Full EVM transfer script (Self-managed)

        The complete transfer script loops through selected source chains, creates and
        signs burn intents for each chain, submits them to the Gateway API for
        attestation, and mints USDC on the destination chain. The script includes inline
        comments to explain what each function does, making it easier to follow and
        modify if needed.

        ```ts transfer-from-evm.ts expandable theme={null}
        import {
          createPublicClient,
          createWalletClient,
          getContract,
          http,
          pad,
          zeroAddress,
          maxUint256,
          formatUnits,
          type Hex,
        } from "viem";
        import { randomBytes } from "node:crypto";
        import {
          account,
          chainConfigs,
          parseSelectedChains,
          GATEWAY_WALLET_ADDRESS,
          GATEWAY_MINTER_ADDRESS,
          type ChainKey,
        } from "./config.js";

        const DESTINATION_CHAIN: ChainKey = "seiTestnet";
        const TRANSFER_VALUE = 1_000000n; // 1 USDC (6 decimals)
        const MAX_FEE = 2_010000n;

        // EIP-712 Domain and Types for Gateway burn intents
        const domain = { name: "GatewayWallet", version: "1" };

        const EIP712Domain = [
          { name: "name", type: "string" },
          { name: "version", type: "string" },
        ] as const;

        const TransferSpec = [
          { name: "version", type: "uint32" },
          { name: "sourceDomain", type: "uint32" },
          { name: "destinationDomain", type: "uint32" },
          { name: "sourceContract", type: "bytes32" },
          { name: "destinationContract", type: "bytes32" },
          { name: "sourceToken", type: "bytes32" },
          { name: "destinationToken", type: "bytes32" },
          { name: "sourceDepositor", type: "bytes32" },
          { name: "destinationRecipient", type: "bytes32" },
          { name: "sourceSigner", type: "bytes32" },
          { name: "destinationCaller", type: "bytes32" },
          { name: "value", type: "uint256" },
          { name: "salt", type: "bytes32" },
          { name: "hookData", type: "bytes" },
        ] as const;

        const BurnIntent = [
          { name: "maxBlockHeight", type: "uint256" },
          { name: "maxFee", type: "uint256" },
          { name: "spec", type: "TransferSpec" },
        ] as const;

        const gatewayMinterAbi = [
          {
            type: "function",
            name: "gatewayMint",
            inputs: [
              { name: "attestationPayload", type: "bytes" },
              { name: "signature", type: "bytes" },
            ],
            outputs: [],
            stateMutability: "nonpayable",
          },
        ] as const;

        // Create a burn intent for cross-chain transfer
        function createBurnIntent(params: {
          sourceChain: ChainKey;
          depositorAddress: string;
          recipientAddress?: string;
        }) {
          const {
            sourceChain,
            depositorAddress,
            recipientAddress = depositorAddress,
          } = params;
          const sourceConfig = chainConfigs[sourceChain];
          const destConfig = chainConfigs[DESTINATION_CHAIN];

          return {
            maxBlockHeight: maxUint256,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: sourceConfig.domainId,
              destinationDomain: destConfig.domainId,
              sourceContract: GATEWAY_WALLET_ADDRESS,
              destinationContract: GATEWAY_MINTER_ADDRESS,
              sourceToken: sourceConfig.usdcAddress,
              destinationToken: destConfig.usdcAddress,
              sourceDepositor: depositorAddress,
              destinationRecipient: recipientAddress,
              sourceSigner: depositorAddress,
              destinationCaller: zeroAddress,
              value: TRANSFER_VALUE,
              salt: ("0x" + randomBytes(32).toString("hex")) as Hex,
              hookData: "0x" as Hex,
            },
          };
        }

        // Create EIP-712 typed data for signing
        function burnIntentTypedData(burnIntent: ReturnType<typeof createBurnIntent>) {
          return {
            types: { EIP712Domain, TransferSpec, BurnIntent },
            domain,
            primaryType: "BurnIntent" as const,
            message: {
              ...burnIntent,
              spec: {
                ...burnIntent.spec,
                sourceContract: addressToBytes32(burnIntent.spec.sourceContract),
                destinationContract: addressToBytes32(
                  burnIntent.spec.destinationContract,
                ),
                sourceToken: addressToBytes32(burnIntent.spec.sourceToken),
                destinationToken: addressToBytes32(burnIntent.spec.destinationToken),
                sourceDepositor: addressToBytes32(burnIntent.spec.sourceDepositor),
                destinationRecipient: addressToBytes32(
                  burnIntent.spec.destinationRecipient,
                ),
                sourceSigner: addressToBytes32(burnIntent.spec.sourceSigner),
                destinationCaller: addressToBytes32(burnIntent.spec.destinationCaller),
              },
            },
          };
        }

        // Convert address to bytes32
        function addressToBytes32(address: string): Hex {
          return pad(address.toLowerCase() as Hex, { size: 32 });
        }

        async function main() {
          console.log(`Using account: ${account.address}`);

          const selectedChains = parseSelectedChains();
          console.log(`Transfering balances from: ${selectedChains.join(", ")}`);

          // [1] Create and sign burn intents for each source chain
          const requests = [];

          for (const chainName of selectedChains) {
            console.log(
              `Creating burn intent from ${chainName} → ${DESTINATION_CHAIN}...`,
            );

            const intent = createBurnIntent({
              sourceChain: chainName,
              depositorAddress: account.address,
            });

            const typedData = burnIntentTypedData(intent);
            const signature = await account.signTypedData(typedData);

            requests.push({ burnIntent: typedData.message, signature });
          }
          console.log("Signed burn intents.");

          // [2] Request attestation from Gateway API
          const response = await fetch(
            "https://gateway-api-testnet.circle.com/v1/transfer",
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: JSON.stringify(requests, (_key, value) =>
                typeof value === "bigint" ? value.toString() : value,
              ),
            },
          );

          if (!response.ok) {
            const text = await response.text();
            throw new Error(`Gateway API error: ${response.status} ${text}`);
          }

          const json = await response.json();
          console.log("Gateway API response:", JSON.stringify(json, null, 2));

          const attestation = json?.attestation;
          const operatorSig = json?.signature;

          if (!attestation || !operatorSig) {
            throw new Error("Missing attestation or signature in response");
          }

          // [3] Mint on destination chain
          const destConfig = chainConfigs[DESTINATION_CHAIN];

          const destClient = createPublicClient({
            chain: destConfig.chain,
            transport: http(),
          });

          const walletClient = createWalletClient({
            account,
            chain: destConfig.chain,
            transport: http(),
          });

          const destinationGatewayMinterContract = getContract({
            address: GATEWAY_MINTER_ADDRESS,
            abi: gatewayMinterAbi,
            client: { public: destClient, wallet: walletClient },
          });

          console.log(`Minting funds on ${destConfig.chain.name}...`);
          const mintTx = await destinationGatewayMinterContract.write.gatewayMint(
            [attestation, operatorSig],
            { account },
          );

          await destClient.waitForTransactionReceipt({ hash: mintTx });

          const totalMinted = BigInt(requests.length) * TRANSFER_VALUE;
          console.log(`Minted ${formatUnits(totalMinted, 6)} USDC`);
          console.log(`Mint transaction hash (${DESTINATION_CHAIN}):`, mintTx);
        }

        main().catch((error) => {
          console.error("\nError:", error);
          process.exit(1);
        });
        ```

        ### 4.8. Run the script to transfer USDC to destination chain

        Run the transfer script to transfer 1 USDC from each selected Gateway balance to
        the destination chain.

        <Note>
          [Gateway gas fees](https://developers.circle.com/gateway/references/fees) are
          charged per burn intent. To reduce overall gas costs, consider keeping most
          Gateway funds on low-cost chains, where Circle’s base fee for burns is cheaper.
        </Note>

        ```shell theme={null}
        # Transfer from all chains
        npm run transfer-from-evm -- all

        # Transfer from a single chain
        npm run transfer-from-evm -- arcTestnet

        # Transfer from multiple chains
        npm run transfer-from-evm -- baseSepolia avalancheFuji
        ```
      </Tab>

      <Tab title="Transfer from Solana">
        ## Step 4: Transfer USDC from the crosschain balance

        This section explains parts of the transfer script that burns USDC from Solana
        Devnet and mints on an EVM chain via Gateway. You can skip to the
        [full transfer script](#4-7-full-solana-transfer-script-self-managed) if you
        prefer.

        ### 4.1. Create the script file

        ```shell theme={null}
        touch transfer-from-sol.ts
        ```

        ### 4.2. Define constants and types

        You can set which chain to deposit to by modifying the `DESTINATION_CHAIN`
        value. This example sets it to `seiTestnet`. You can also set the amount to be
        transferred from each source chain by changing the `TRANSFER_VALUE`.

        ```ts transfer-from-sol.ts expandable theme={null}
        /* Constants */
        const DESTINATION_CHAIN: ChainKey = "seiTestnet";
        const TRANSFER_VALUE = 1_000000n; // 1 USDC (6 decimals)
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;

        const GATEWAY_WALLET_ADDRESS = "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
        const USDC_ADDRESS = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
        const SOLANA_DOMAIN = 5;

        const TRANSFER_SPEC_MAGIC = 0xca85def7;
        const BURN_INTENT_MAGIC = 0x070afbc2;

        /* Type definitions */
        // Custom layout for Solana PublicKey (32 bytes)
        class PublicKeyLayout extends Layout<PublicKey> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0): PublicKey {
            return new PublicKey(b.subarray(offset, offset + 32));
          }
          encode(src: PublicKey, b: Buffer, offset = 0): number {
            const pubkeyBuffer = src.toBuffer();
            pubkeyBuffer.copy(b, offset);
            return 32;
          }
        }

        const publicKey = (property: string) => new PublicKeyLayout(property);

        // Custom layout for 256-bit unsigned integers
        class UInt256BE extends Layout<bigint> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0) {
            const buffer = b.subarray(offset, offset + 32);
            return buffer.readBigUInt64BE(24);
          }
          encode(src: bigint, b: Buffer, offset = 0) {
            const buffer = Buffer.alloc(32);
            buffer.writeBigUInt64BE(BigInt(src), 24);
            buffer.copy(b, offset);
            return 32;
          }
        }

        const uint256be = (property: string) => new UInt256BE(property);

        // Type 'as any' used due to @solana/buffer-layout's incomplete TypeScript definitions (archived Jan 2025)
        const BurnIntentLayout = struct([
          u32be("magic"),
          uint256be("maxBlockHeight"),
          uint256be("maxFee"),
          u32be("transferSpecLength"),
          struct(
            [
              u32be("magic"),
              u32be("version"),
              u32be("sourceDomain"),
              u32be("destinationDomain"),
              publicKey("sourceContract"),
              publicKey("destinationContract"),
              publicKey("sourceToken"),
              publicKey("destinationToken"),
              publicKey("sourceDepositor"),
              publicKey("destinationRecipient"),
              publicKey("sourceSigner"),
              publicKey("destinationCaller"),
              uint256be("value"),
              blob(32, "salt"),
              u32be("hookDataLength"),
              blob(offset(u32be(), -4), "hookData"),
            ] as any,
            "spec",
          ),
        ] as any);

        const gatewayMinterAbi = [
          {
            type: "function",
            name: "gatewayMint",
            inputs: [
              { name: "attestationPayload", type: "bytes" },
              { name: "signature", type: "bytes" },
            ],
            outputs: [],
            stateMutability: "nonpayable",
          },
        ] as const;
        ```

        ### 4.3. Add helper functions

        ```ts transfer-from-sol.ts expandable theme={null}
        // Construct burn intent for Solana to EVM transfer
        function createBurnIntent(params: {
          sourceDepositor: string;
          destinationRecipient: string;
        }) {
          const { sourceDepositor, destinationRecipient } = params;
          const destConfig = chainConfigs[DESTINATION_CHAIN];

          return {
            maxBlockHeight: MAX_UINT64,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: SOLANA_DOMAIN,
              destinationDomain: destConfig.domainId,
              sourceContract: solanaAddressToBytes32(GATEWAY_WALLET_ADDRESS),
              destinationContract: evmAddressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: solanaAddressToBytes32(USDC_ADDRESS),
              destinationToken: evmAddressToBytes32(destConfig.usdcAddress),
              sourceDepositor: solanaAddressToBytes32(sourceDepositor),
              destinationRecipient: evmAddressToBytes32(destinationRecipient),
              sourceSigner: solanaAddressToBytes32(sourceDepositor),
              destinationCaller: evmAddressToBytes32(
                "0x0000000000000000000000000000000000000000",
              ),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Encode burn intent as binary layout for signing
        function encodeBurnIntent(bi: any): Buffer {
          const hookData = Buffer.from((bi.spec.hookData || "0x").slice(2), "hex");
          const prepared = {
            magic: BURN_INTENT_MAGIC,
            maxBlockHeight: bi.maxBlockHeight,
            maxFee: bi.maxFee,
            transferSpecLength: 340 + hookData.length,
            spec: {
              magic: TRANSFER_SPEC_MAGIC,
              version: bi.spec.version,
              sourceDomain: bi.spec.sourceDomain,
              destinationDomain: bi.spec.destinationDomain,
              sourceContract: hexToPublicKey(bi.spec.sourceContract),
              destinationContract: hexToPublicKey(bi.spec.destinationContract),
              sourceToken: hexToPublicKey(bi.spec.sourceToken),
              destinationToken: hexToPublicKey(bi.spec.destinationToken),
              sourceDepositor: hexToPublicKey(bi.spec.sourceDepositor),
              destinationRecipient: hexToPublicKey(bi.spec.destinationRecipient),
              sourceSigner: hexToPublicKey(bi.spec.sourceSigner),
              destinationCaller: hexToPublicKey(bi.spec.destinationCaller),
              value: bi.spec.value,
              salt: Buffer.from(bi.spec.salt.slice(2), "hex"),
              hookDataLength: hookData.length,
              hookData,
            },
          };
          const buffer = Buffer.alloc(72 + 340 + hookData.length);
          const bytesWritten = BurnIntentLayout.encode(prepared, buffer);
          return buffer.subarray(0, bytesWritten);
        }

        // Sign burn intent with Ed25519 keypair
        function signBurnIntent(keypair: Keypair, payload: any): string {
          const encoded = encodeBurnIntent(payload);
          const prefixed = Buffer.concat([
            Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
            encoded,
          ]);
          const privateKey = crypto.createPrivateKey({
            key: Buffer.concat([
              Buffer.from("302e020100300506032b657004220420", "hex"),
              Buffer.from(keypair.secretKey.slice(0, 32)),
            ]),
            format: "der",
            type: "pkcs8",
          });
          return `0x${crypto.sign(null, prefixed, privateKey).toString("hex")}`;
        }

        // Get Solana keypair from environment variable
        function getSolanaKeypair(): Keypair {
          if (!process.env.SOLANA_PRIVATE_KEYPAIR) {
            throw new Error("SOLANA_PRIVATE_KEYPAIR not set");
          }
          const secretKey = JSON.parse(process.env.SOLANA_PRIVATE_KEYPAIR);
          return Keypair.fromSecretKey(Uint8Array.from(secretKey));
        }

        // Convert Solana address to 32-byte hex string
        function solanaAddressToBytes32(address: string): string {
          const decoded = Buffer.from(bs58.decode(address));
          return `0x${decoded.toString("hex")}`;
        }

        // Pad EVM address to 32 bytes
        function evmAddressToBytes32(address: string): string {
          return pad(address.toLowerCase() as Hex, { size: 32 });
        }

        // Convert hex string to Solana PublicKey
        function hexToPublicKey(hexString: string): PublicKey {
          const cleanHex = hexString.startsWith("0x") ? hexString.slice(2) : hexString;
          const buffer = Buffer.from(cleanHex, "hex");
          return new PublicKey(buffer);
        }

        // Serialize typed data (convert bigints to strings)
        function stringifyTypedData(obj: unknown) {
          return JSON.stringify(obj, (_key: string, value: unknown) =>
            typeof value === "bigint" ? value.toString() : value,
          );
        }
        ```

        ### 4.4. Create and sign burn intent

        ```ts transfer-from-sol.ts theme={null}
        const intent = createBurnIntent({
          sourceDepositor: solanaKeypair.publicKey.toBase58(),
          destinationRecipient: account.address,
        });

        const signature = signBurnIntent(solanaKeypair, intent);
        const request = [{ burnIntent: intent, signature }];
        console.log("Signed burn intents.");
        ```

        For Solana-origin transfers, the burn intent uses Solana-specific binary
        encoding and must be signed with the Solana signing-domain prefix. See the
        [Solana Technical Guide](/gateway/references/solana#signing) for the signing
        rules and message format details.

        ### 4.5. Request attestation from Gateway API

        ```ts transfer-from-sol.ts theme={null}
        const response = await fetch(
          "https://gateway-api-testnet.circle.com/v1/transfer",
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: stringifyTypedData(request),
          },
        );

        if (!response.ok) {
          const text = await response.text();
          throw new Error(`Gateway API error: ${response.status} ${text}`);
        }

        const json = await response.json();
        console.log("Gateway API response:", JSON.stringify(json, null, 2));

        const attestation = json?.attestation;
        const operatorSig = json?.signature;

        if (!attestation || !operatorSig) {
          throw new Error("Missing attestation or signature in response");
        }
        ```

        ### 4.6. Mint on destination chain

        ```ts transfer-from-sol.ts theme={null}
        const destConfig = chainConfigs[DESTINATION_CHAIN];
        console.log(`Minting funds on ${destConfig.chain.name}...`);

        const destClient = createPublicClient({
          chain: destConfig.chain,
          transport: http(),
        });

        const walletClient = createWalletClient({
          account,
          chain: destConfig.chain,
          transport: http(),
        });

        const destinationGatewayMinterContract = getContract({
          address: GATEWAY_MINTER_ADDRESS,
          abi: gatewayMinterAbi,
          client: { public: destClient, wallet: walletClient },
        });

        const mintTx = await destinationGatewayMinterContract.write.gatewayMint(
          [attestation, operatorSig],
          { account },
        );

        await destClient.waitForTransactionReceipt({ hash: mintTx });

        console.log(`Minted ${formatUnits(TRANSFER_VALUE, 6)} USDC`);
        console.log(`Mint transaction hash (${DESTINATION_CHAIN}):`, mintTx);
        ```

        ### 4.7. Full Solana transfer script (Self-managed)

        The complete transfer script creates and signs a burn intent on Solana Devnet,
        submits it to the Gateway API for attestation, and mints USDC on the destination
        EVM chain. The script includes inline comments to explain what each function
        does, making it easier to follow and modify if needed.

        ```ts transfer-from-sol.ts expandable theme={null}
        import { randomBytes } from "node:crypto";
        import * as crypto from "crypto";
        import {
          createPublicClient,
          createWalletClient,
          getContract,
          http,
          pad,
          formatUnits,
          type Hex,
        } from "viem";
        import { Keypair, PublicKey } from "@solana/web3.js";
        import { u32be, struct, blob, offset, Layout } from "@solana/buffer-layout";
        import bs58 from "bs58";
        import {
          account,
          chainConfigs,
          GATEWAY_MINTER_ADDRESS,
          type ChainKey,
        } from "./config.js";

        /* Constants */
        const DESTINATION_CHAIN: ChainKey = "seiTestnet";
        const TRANSFER_VALUE = 1_000000n; // 1 USDC (6 decimals)
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;

        const GATEWAY_WALLET_ADDRESS = "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
        const USDC_ADDRESS = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
        const SOLANA_DOMAIN = 5;

        const TRANSFER_SPEC_MAGIC = 0xca85def7;
        const BURN_INTENT_MAGIC = 0x070afbc2;

        /* Type definitions */
        // Custom layout for Solana PublicKey (32 bytes)
        class PublicKeyLayout extends Layout<PublicKey> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0): PublicKey {
            return new PublicKey(b.subarray(offset, offset + 32));
          }
          encode(src: PublicKey, b: Buffer, offset = 0): number {
            const pubkeyBuffer = src.toBuffer();
            pubkeyBuffer.copy(b, offset);
            return 32;
          }
        }

        const publicKey = (property: string) => new PublicKeyLayout(property);

        // Custom layout for 256-bit unsigned integers
        class UInt256BE extends Layout<bigint> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0) {
            const buffer = b.subarray(offset, offset + 32);
            return buffer.readBigUInt64BE(24);
          }
          encode(src: bigint, b: Buffer, offset = 0) {
            const buffer = Buffer.alloc(32);
            buffer.writeBigUInt64BE(BigInt(src), 24);
            buffer.copy(b, offset);
            return 32;
          }
        }

        const uint256be = (property: string) => new UInt256BE(property);

        // Type 'as any' used due to @solana/buffer-layout's incomplete TypeScript definitions (archived Jan 2025)
        const BurnIntentLayout = struct([
          u32be("magic"),
          uint256be("maxBlockHeight"),
          uint256be("maxFee"),
          u32be("transferSpecLength"),
          struct(
            [
              u32be("magic"),
              u32be("version"),
              u32be("sourceDomain"),
              u32be("destinationDomain"),
              publicKey("sourceContract"),
              publicKey("destinationContract"),
              publicKey("sourceToken"),
              publicKey("destinationToken"),
              publicKey("sourceDepositor"),
              publicKey("destinationRecipient"),
              publicKey("sourceSigner"),
              publicKey("destinationCaller"),
              uint256be("value"),
              blob(32, "salt"),
              u32be("hookDataLength"),
              blob(offset(u32be(), -4), "hookData"),
            ] as any,
            "spec",
          ),
        ] as any);

        const gatewayMinterAbi = [
          {
            type: "function",
            name: "gatewayMint",
            inputs: [
              { name: "attestationPayload", type: "bytes" },
              { name: "signature", type: "bytes" },
            ],
            outputs: [],
            stateMutability: "nonpayable",
          },
        ] as const;

        /* Helpers */
        // Construct burn intent for Solana to EVM transfer
        function createBurnIntent(params: {
          sourceDepositor: string;
          destinationRecipient: string;
        }) {
          const { sourceDepositor, destinationRecipient } = params;
          const destConfig = chainConfigs[DESTINATION_CHAIN];

          return {
            maxBlockHeight: MAX_UINT64,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: SOLANA_DOMAIN,
              destinationDomain: destConfig.domainId,
              sourceContract: solanaAddressToBytes32(GATEWAY_WALLET_ADDRESS),
              destinationContract: evmAddressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: solanaAddressToBytes32(USDC_ADDRESS),
              destinationToken: evmAddressToBytes32(destConfig.usdcAddress),
              sourceDepositor: solanaAddressToBytes32(sourceDepositor),
              destinationRecipient: evmAddressToBytes32(destinationRecipient),
              sourceSigner: solanaAddressToBytes32(sourceDepositor),
              destinationCaller: evmAddressToBytes32(
                "0x0000000000000000000000000000000000000000",
              ),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Encode burn intent as binary layout for signing
        function encodeBurnIntent(bi: any): Buffer {
          const hookData = Buffer.from((bi.spec.hookData || "0x").slice(2), "hex");
          const prepared = {
            magic: BURN_INTENT_MAGIC,
            maxBlockHeight: bi.maxBlockHeight,
            maxFee: bi.maxFee,
            transferSpecLength: 340 + hookData.length,
            spec: {
              magic: TRANSFER_SPEC_MAGIC,
              version: bi.spec.version,
              sourceDomain: bi.spec.sourceDomain,
              destinationDomain: bi.spec.destinationDomain,
              sourceContract: hexToPublicKey(bi.spec.sourceContract),
              destinationContract: hexToPublicKey(bi.spec.destinationContract),
              sourceToken: hexToPublicKey(bi.spec.sourceToken),
              destinationToken: hexToPublicKey(bi.spec.destinationToken),
              sourceDepositor: hexToPublicKey(bi.spec.sourceDepositor),
              destinationRecipient: hexToPublicKey(bi.spec.destinationRecipient),
              sourceSigner: hexToPublicKey(bi.spec.sourceSigner),
              destinationCaller: hexToPublicKey(bi.spec.destinationCaller),
              value: bi.spec.value,
              salt: Buffer.from(bi.spec.salt.slice(2), "hex"),
              hookDataLength: hookData.length,
              hookData,
            },
          };
          const buffer = Buffer.alloc(72 + 340 + hookData.length);
          const bytesWritten = BurnIntentLayout.encode(prepared, buffer);
          return buffer.subarray(0, bytesWritten);
        }

        // Sign burn intent with Ed25519 keypair
        function signBurnIntent(keypair: Keypair, payload: any): string {
          const encoded = encodeBurnIntent(payload);
          const prefixed = Buffer.concat([
            Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
            encoded,
          ]);
          const privateKey = crypto.createPrivateKey({
            key: Buffer.concat([
              Buffer.from("302e020100300506032b657004220420", "hex"),
              Buffer.from(keypair.secretKey.slice(0, 32)),
            ]),
            format: "der",
            type: "pkcs8",
          });
          return `0x${crypto.sign(null, prefixed, privateKey).toString("hex")}`;
        }

        // Get Solana keypair from environment variable
        function getSolanaKeypair(): Keypair {
          if (!process.env.SOLANA_PRIVATE_KEYPAIR) {
            throw new Error("SOLANA_PRIVATE_KEYPAIR not set");
          }
          const secretKey = JSON.parse(process.env.SOLANA_PRIVATE_KEYPAIR);
          return Keypair.fromSecretKey(Uint8Array.from(secretKey));
        }

        // Convert Solana address to 32-byte hex string
        function solanaAddressToBytes32(address: string): string {
          const decoded = Buffer.from(bs58.decode(address));
          return `0x${decoded.toString("hex")}`;
        }

        // Pad EVM address to 32 bytes
        function evmAddressToBytes32(address: string): string {
          return pad(address.toLowerCase() as Hex, { size: 32 });
        }

        // Convert hex string to Solana PublicKey
        function hexToPublicKey(hexString: string): PublicKey {
          const cleanHex = hexString.startsWith("0x") ? hexString.slice(2) : hexString;
          const buffer = Buffer.from(cleanHex, "hex");
          return new PublicKey(buffer);
        }

        // Serialize typed data (convert bigints to strings)
        function stringifyTypedData(obj: unknown) {
          return JSON.stringify(obj, (_key: string, value: unknown) =>
            typeof value === "bigint" ? value.toString() : value,
          );
        }

        /* Main logic */
        async function main() {
          const solanaKeypair = getSolanaKeypair();
          console.log(`Sender (Solana): ${solanaKeypair.publicKey.toBase58()}`);
          console.log(`Recipient (EVM): ${account.address}`);
          console.log(`Transfering balances from: solanaDevnet`);

          // [1] Create and sign burn intent
          console.log(
            `Creating burn intent from solanaDevnet → ${DESTINATION_CHAIN}...`,
          );

          const intent = createBurnIntent({
            sourceDepositor: solanaKeypair.publicKey.toBase58(),
            destinationRecipient: account.address,
          });

          const signature = signBurnIntent(solanaKeypair, intent);
          const request = [{ burnIntent: intent, signature }];
          console.log("Signed burn intents.");

          // [2] Request attestation from Gateway API
          const response = await fetch(
            "https://gateway-api-testnet.circle.com/v1/transfer",
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: stringifyTypedData(request),
            },
          );

          if (!response.ok) {
            const text = await response.text();
            throw new Error(`Gateway API error: ${response.status} ${text}`);
          }

          const json = await response.json();
          console.log("Gateway API response:", JSON.stringify(json, null, 2));

          const attestation = json?.attestation;
          const operatorSig = json?.signature;

          if (!attestation || !operatorSig) {
            throw new Error("Missing attestation or signature in response");
          }

          // [3] Mint on destination chain
          const destConfig = chainConfigs[DESTINATION_CHAIN];
          console.log(`Minting funds on ${destConfig.chain.name}...`);

          const destClient = createPublicClient({
            chain: destConfig.chain,
            transport: http(),
          });

          const walletClient = createWalletClient({
            account,
            chain: destConfig.chain,
            transport: http(),
          });

          const destinationGatewayMinterContract = getContract({
            address: GATEWAY_MINTER_ADDRESS,
            abi: gatewayMinterAbi,
            client: { public: destClient, wallet: walletClient },
          });

          const mintTx = await destinationGatewayMinterContract.write.gatewayMint(
            [attestation, operatorSig],
            { account },
          );

          await destClient.waitForTransactionReceipt({ hash: mintTx });

          console.log(`Minted ${formatUnits(TRANSFER_VALUE, 6)} USDC`);
          console.log(`Mint transaction hash (${DESTINATION_CHAIN}):`, mintTx);
        }

        main().catch((error) => {
          console.error("\nError:", error);
          process.exit(1);
        });
        ```

        ### 4.8. Run the script to transfer USDC to destination chain

        Run the transfer script to transfer 1 USDC from your Solana Devnet Gateway
        balance to the destination EVM chain.

        <Note>
          [Gateway gas fees](https://developers.circle.com/gateway/references/fees) are
          charged per burn intent. To reduce overall gas costs, consider keeping most
          Gateway funds on low-cost chains, where Circle’s base fee for burns is cheaper.
        </Note>

        ```shell theme={null}
        npm run transfer-from-sol
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Quickstart: Create and Transfer a Unified USDC Balance on Solana
Source: https://developers.circle.com/gateway/quickstarts/unified-balance-solana

Create and transfer a unified USDC balance on Solana using Circle Gateway.

This guide walks you through the process of creating Unified Crosschain USDC
Balances on Solana using Circle Gateway, and performing transfers from EVM to
Solana and from Solana to Solana.

<Tip>
  **Use
  [Unified Balance Kit](https://www.npmjs.com/package/@circle-fin/unified-balance-kit)
  to simplify this integration.**

  This quickstart uses a manual Gateway integration. It is for learning or for
  developers who need direct control.

  To simplify, use Unified Balance Kit to deposit and spend USDC in just a few
  lines of code.
</Tip>

Select a tab below for the Circle Wallets or self-managed wallet path.

<Tabs>
  <Tab title="Circle Wallets">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Obtained a
      [Circle API Key](/w3s/circle-developer-account#creating-an-api-key-for-developer-services)
      and [Entity Secret](/wallets/dev-controlled/register-entity-secret) from the
      [Circle Console](/w3s/circle-developer-account).
    * Created a Solana Devnet
      [Developer-Controlled Wallet](/wallets/dev-controlled/create-your-first-wallet)
    * Funded your wallet with testnet tokens:
      * Get testnet USDC from the [Circle Faucet](https://faucet.circle.com/).
      * Get test native tokens from the
        [Console Faucet](https://console.circle.com/faucet).

    If you want to try the EVM to Solana transfer, ensure that you've:

    * Created EVM Developer-Controlled Wallets on the source chains you want to test
    * Created a Solana Devnet Developer-Controlled Wallet to receive the minted USDC
    * Completed the
      [deposit flow](/gateway/quickstarts/unified-balance-evm#step-3-deposit-into-a-unified-crosschain-balance-circle-wallets)
      from the
      [EVM quickstart](/gateway/quickstarts/unified-balance-evm#circle-wallets)
      first

    ### Add testnet funds to your wallet

    To interact with Gateway, you need test USDC and native tokens in your wallet on
    each chain you deposit from. You also need SOL on the destination wallet to
    create the recipient Associated Token Account and call the Gateway Minter
    program.

    <Tip>
      You can skip the SOL requirement on the destination wallet by using the
      [Forwarding Service](/gateway/howtos/forwarding-service), which handles ATA
      creation and minting automatically.
    </Tip>

    Use the [Circle Faucet](https://faucet.circle.com/) to get test USDC. If you
    have a [Circle Developer Console](https://console.circle.com) account, you can
    use the [Console Faucet](https://console.circle.com/faucet) to get testnet
    native tokens. In addition, the following faucets can also be used to fund your
    wallet with testnet native tokens:

    <Tabs>
      <Tab title="Arc">
        **Faucet:** [Arc Testnet](https://faucet.circle.com) (USDC + native tokens)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `arcTestnet`                                 |
        | USDC address | `0x3600000000000000000000000000000000000000` |
        | Domain ID    | `26`                                         |
      </Tab>

      <Tab title="Avalanche">
        **Faucet:** [Avalanche Fuji](https://core.app/tools/testnet-faucet)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `avalancheFuji`                              |
        | USDC address | `0x5425890298aed601595a70ab815c96711a31bc65` |
        | Domain ID    | `1`                                          |
      </Tab>

      <Tab title="Base">
        **Faucet:** [Base Sepolia](https://www.alchemy.com/faucets/base-sepolia)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `baseSepolia`                                |
        | USDC address | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
        | Domain ID    | `6`                                          |
      </Tab>

      <Tab title="Ethereum">
        **Faucet:** [Ethereum Sepolia](https://cloud.google.com/application/web3/faucet/ethereum/sepolia)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `sepolia`                                    |
        | USDC address | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` |
        | Domain ID    | `0`                                          |
      </Tab>

      <Tab title="Hyperliquid">
        **Faucet:** [Hyperliquid EVM Testnet](https://app.hyperliquid-testnet.xyz/drip)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `hyperliquidEvmTestnet`                      |
        | USDC address | `0x2B3370eE501B4a559b57D449569354196457D8Ab` |
        | Domain ID    | `19`                                         |
      </Tab>

      <Tab title="Sei">
        **Faucet:** [Sei Testnet](https://docs.sei.io/learn/faucet)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `seiTestnet`                                 |
        | USDC address | `0x4fCF1784B31630811181f670Aea7A7bEF803eaED` |
        | Domain ID    | `16`                                         |
      </Tab>

      <Tab title="Solana">
        **Faucet:** [Solana Devnet](https://faucet.solana.com/)

        | Property     | Value                                                   |
        | ------------ | ------------------------------------------------------- |
        | Chain name   | `solanaDevnet` (note that Solana is not EVM-compatible) |
        | USDC address | `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`          |
        | Domain ID    | `5`                                                     |
      </Tab>

      <Tab title="Sonic">
        **Faucet:** [Sonic Testnet](https://testnet.soniclabs.com/account)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `sonicTestnet`                               |
        | USDC address | `0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51` |
        | Domain ID    | `13`                                         |
      </Tab>

      <Tab title="Worldchain">
        **Faucet:** [Worldchain Sepolia](https://www.l2faucet.com/world)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `worldchainSepolia`                          |
        | USDC address | `0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88` |
        | Domain ID    | `14`                                         |
      </Tab>
    </Tabs>

    ## Step 1. Set up your project

    ### 1.1. Create the project and install dependencies

    ```shell theme={null}
    # Set up your directory and initialize a Node.js project
    mkdir unified-gateway-balance-solana-circle-wallets
    cd unified-gateway-balance-solana-circle-wallets
    npm init -y

    # Set up module type and run scripts
    npm pkg set type=module
    npm pkg set scripts.deposit="tsx --env-file=.env deposit.ts"
    npm pkg set scripts.balances="tsx --env-file=.env balances.ts"
    npm pkg set scripts.transfer-from-sol="tsx --env-file=.env transfer-from-sol.ts"
    npm pkg set scripts.transfer-from-evm="tsx --env-file=.env transfer-from-evm.ts --"

    # Pin bigint-buffer to a patched version
    npm pkg set overrides.bigint-buffer=npm:@trufflesuite/bigint-buffer@1.1.10

    # Install runtime dependencies
    npm install @circle-fin/developer-controlled-wallets @coral-xyz/anchor @solana/buffer-layout @solana/spl-token @solana/web3.js bs58 bn.js tsx typescript

    # Install dev dependencies
    npm install --save-dev @types/node @types/bn.js
    ```

    ### 1.2. Configure TypeScript (optional)

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3. Set environment variables

    Create a `.env` file in the project directory:

    ```text .env theme={null}
    CIRCLE_API_KEY=YOUR_API_KEY
    CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
    DEPOSITOR_ADDRESS=YOUR_SOURCE_WALLET_ADDRESS
    RECIPIENT_ADDRESS=YOUR_DESTINATION_WALLET_ADDRESS
    ```

    * `CIRCLE_API_KEY` is your Circle API key.
    * `CIRCLE_ENTITY_SECRET` is your Circle entity secret.
    * `DEPOSITOR_ADDRESS` is the source depositor wallet for the script you are
      running.
    * `RECIPIENT_ADDRESS` is the destination wallet that receives the minted USDC.

    For `transfer-from-sol.ts`, both values are Solana addresses.

    For `transfer-from-evm.ts`, `DEPOSITOR_ADDRESS` is an EVM address and
    `RECIPIENT_ADDRESS` is a Solana address.

    <Tip>
      Open `.env` in your editor rather than writing values with shell commands, and
      add `.env` to your `.gitignore`. This prevents credentials from leaking into
      your shell history or version control.
    </Tip>

    ## Step 2. Set up the configuration file

    The shared Solana configuration and helpers are used by the deposit and transfer
    scripts.

    ### 2.1. Create the configuration file

    ```shell theme={null}
    touch config.ts
    ```

    ### 2.2. Configure Solana settings and Gateway helpers

    Add the shared Solana RPC configuration, Gateway addresses, IDLs, attestation
    decoding helpers, and Circle Wallets signing helpers to `config.ts`.

    The local IDL fragments in this example are only the subset needed by the sample
    code. For canonical static instruction and account definitions, use the onchain
    IDLs linked from
    [Solana Programs and Interfaces](/gateway/references/solana-programs#account-structures).

    ```ts config.ts expandable theme={null}
    import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
    import { Connection, PublicKey, Transaction } from "@solana/web3.js";
    import {
      u32be,
      nu64be,
      struct,
      seq,
      blob,
      offset,
      Layout,
    } from "@solana/buffer-layout";
    import bs58 from "bs58";

    export const RPC_ENDPOINT = "https://api.devnet.solana.com";
    export const SOLANA_DOMAIN = 5;
    export const SOLANA_ZERO_ADDRESS = "11111111111111111111111111111111";

    export const GATEWAY_WALLET_ADDRESS =
      "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
    export const GATEWAY_MINTER_ADDRESS =
      "GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr";
    export const USDC_ADDRESS = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";

    const API_KEY = process.env.CIRCLE_API_KEY!;
    const ENTITY_SECRET = process.env.CIRCLE_ENTITY_SECRET!;

    if (!API_KEY || !ENTITY_SECRET) {
      console.error(
        "Missing required env vars: CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET",
      );
      process.exit(1);
    }

    export const client = initiateDeveloperControlledWalletsClient({
      apiKey: API_KEY,
      entitySecret: ENTITY_SECRET,
    });

    export class PublicKeyLayout extends Layout<PublicKey> {
      constructor(property: string) {
        super(32, property);
      }
      decode(b: Buffer, offset = 0): PublicKey {
        return new PublicKey(b.subarray(offset, offset + 32));
      }
      encode(src: PublicKey, b: Buffer, offset = 0): number {
        const pubkeyBuffer = src.toBuffer();
        pubkeyBuffer.copy(b, offset);
        return 32;
      }
    }

    export const publicKey = (property: string) => new PublicKeyLayout(property);

    const MintAttestationElementLayout = struct([
      publicKey("destinationToken"),
      publicKey("destinationRecipient"),
      nu64be("value"),
      blob(32, "transferSpecHash"),
      u32be("hookDataLength"),
      blob(offset(u32be(), -4), "hookData"),
    ] as any);

    const MintAttestationSetLayout = struct([
      u32be("magic"),
      u32be("version"),
      u32be("destinationDomain"),
      publicKey("destinationContract"),
      publicKey("destinationCaller"),
      nu64be("maxBlockHeight"),
      u32be("numAttestations"),
      seq(MintAttestationElementLayout, offset(u32be(), -4), "attestations"),
    ] as any);

    // Sample-local IDL subset for this example.
    export const gatewayWalletIdl = {
      address: GATEWAY_WALLET_ADDRESS,
      metadata: {
        name: "gatewayWallet",
        version: "0.1.0",
        spec: "0.1.0",
      },
      instructions: [
        {
          name: "deposit",
          discriminator: [22, 0],
          accounts: [
            { name: "payer", writable: true, signer: true },
            { name: "owner", signer: true },
            { name: "gatewayWallet" },
            { name: "ownerTokenAccount", writable: true },
            { name: "custodyTokenAccount", writable: true },
            { name: "deposit", writable: true },
            { name: "depositorDenylist" },
            { name: "tokenProgram" },
            { name: "systemProgram" },
            { name: "eventAuthority" },
            { name: "program" },
          ],
          args: [{ name: "amount", type: "u64" }],
        },
      ],
    };

    // Sample-local IDL subset for this example.
    export const gatewayMinterIdl = {
      address: GATEWAY_MINTER_ADDRESS,
      metadata: { name: "gatewayMinter", version: "0.1.0", spec: "0.1.0" },
      instructions: [
        {
          name: "gatewayMint",
          discriminator: [12, 0],
          accounts: [
            { name: "payer", writable: true, signer: true },
            { name: "destinationCaller", signer: true },
            { name: "gatewayMinter" },
            { name: "systemProgram" },
            { name: "tokenProgram" },
            { name: "eventAuthority" },
            { name: "program" },
          ],
          args: [
            {
              name: "params",
              type: { defined: { name: "gatewayMintParams" } },
            },
          ],
        },
      ],
      types: [
        {
          name: "gatewayMintParams",
          type: {
            kind: "struct",
            fields: [
              { name: "attestation", type: "bytes" },
              { name: "signature", type: "bytes" },
            ],
          },
        },
      ],
    };

    export function findDepositPDAs(
      programId: PublicKey,
      usdcMint: PublicKey,
      owner: PublicKey,
    ) {
      return {
        wallet: PublicKey.findProgramAddressSync(
          [Buffer.from("gateway_wallet")],
          programId,
        )[0],
        custody: PublicKey.findProgramAddressSync(
          [Buffer.from("gateway_wallet_custody"), usdcMint.toBuffer()],
          programId,
        )[0],
        deposit: PublicKey.findProgramAddressSync(
          [Buffer.from("gateway_deposit"), usdcMint.toBuffer(), owner.toBuffer()],
          programId,
        )[0],
        denylist: PublicKey.findProgramAddressSync(
          [Buffer.from("denylist"), owner.toBuffer()],
          programId,
        )[0],
      };
    }

    export function findCustodyPda(
      mint: PublicKey,
      minterProgramId: PublicKey,
    ): PublicKey {
      return PublicKey.findProgramAddressSync(
        [Buffer.from("gateway_minter_custody"), mint.toBuffer()],
        minterProgramId,
      )[0];
    }

    export function findTransferSpecHashPda(
      transferSpecHash: Uint8Array | Buffer,
      minterProgramId: PublicKey,
    ): PublicKey {
      return PublicKey.findProgramAddressSync(
        [Buffer.from("used_transfer_spec_hash"), Buffer.from(transferSpecHash)],
        minterProgramId,
      )[0];
    }

    export function decodeAttestationSet(attestation: string) {
      const buffer = Buffer.from(attestation.slice(2), "hex");
      return MintAttestationSetLayout.decode(buffer) as {
        attestations: Array<{
          destinationToken: PublicKey;
          destinationRecipient: PublicKey;
          transferSpecHash: Uint8Array;
        }>;
      };
    }

    export function solanaAddressToBytes32(address: string): string {
      const decoded = Buffer.from(bs58.decode(address));
      return `0x${decoded.toString("hex")}`;
    }

    export function hexToPublicKey(hex: string): PublicKey {
      return new PublicKey(Buffer.from(hex.slice(2), "hex"));
    }

    export async function signAndBroadcast(
      circleClient: ReturnType<typeof initiateDeveloperControlledWalletsClient>,
      connection: Connection,
      transaction: Transaction,
      walletAddress: string,
      label: string,
    ): Promise<string> {
      const serialized = transaction.serialize({
        requireAllSignatures: false,
        verifySignatures: false,
      });

      console.log(`Signing ${label} via Circle Wallets...`);
      const signResult = await circleClient.signTransaction({
        walletAddress,
        blockchain: "SOL-DEVNET",
        rawTransaction: serialized.toString("base64"),
      });

      const signedTxBase64 = signResult.data?.signedTransaction;
      if (!signedTxBase64) throw new Error(`Failed to sign ${label}`);

      console.log(`Broadcasting ${label}...`);
      const signedTxBytes = Buffer.from(signedTxBase64, "base64");
      return connection.sendRawTransaction(signedTxBytes);
    }

    export function stringifyTypedData<T>(obj: T) {
      return JSON.stringify(obj, (_key, value) =>
        typeof value === "bigint" ? value.toString() : value,
      );
    }
    ```

    ## Step 3. Deposit into a unified crosschain balance (Circle Wallets)

    The deposit script submits a Gateway deposit on Solana Devnet. You can skip to
    the [full deposit script](#3-5-full-deposit-script-circle-wallets) if you
    prefer.

    <Warning>
      Do not send USDC directly to the Gateway Wallet address or custody account.
      You must use a Gateway deposit instruction for the funds to be credited to
      your unified balance.
    </Warning>

    ### 3.1. Create the deposit script

    ```shell theme={null}
    touch deposit.ts
    ```

    ### 3.2. Define constants and helpers

    Set the deposit amount near the top of the file, then derive the owner ATA and
    load the account so the script can validate balance before it builds the Gateway
    instruction.

    ```ts theme={null}
    const DEPOSIT_AMOUNT = new BN(1_000_000);
    ```

    ### 3.3. Initialize connection, Anchor client, and validate balance

    The Solana version follows the same teaching order as the standard quickstart:
    initialize the connection, check the source wallet balance, then set up the
    Anchor client and derive the Gateway PDAs.

    ```ts theme={null}
    const connection = new Connection(RPC_ENDPOINT, "confirmed");
    const usdcMint = new PublicKey(USDC_ADDRESS);
    const programId = new PublicKey(GATEWAY_WALLET_ADDRESS);
    const owner = new PublicKey(DEPOSITOR_ADDRESS);

    const userTokenAccount = getAssociatedTokenAddressSync(usdcMint, owner);
    const tokenAccountInfo = await getAccount(connection, userTokenAccount);

    const dummyWallet = new Wallet(Keypair.generate());
    const provider = new AnchorProvider(
      connection,
      dummyWallet,
      AnchorProvider.defaultOptions(),
    );
    ```

    ### 3.4. Execute the deposit

    After the balance check and PDA derivation, build the Gateway deposit
    instruction, sign it with Circle Wallets, broadcast it, and wait for Solana
    confirmation.

    ```ts theme={null}
    const depositIx = await program.methods
      .deposit(DEPOSIT_AMOUNT)
      .accountsPartial({
        payer: owner,
        owner: owner,
        gatewayWallet: pdas.wallet,
        ownerTokenAccount: userTokenAccount,
        custodyTokenAccount: pdas.custody,
        deposit: pdas.deposit,
        depositorDenylist: pdas.denylist,
        tokenProgram: TOKEN_PROGRAM_ID,
        systemProgram: SystemProgram.programId,
      })
      .instruction();

    const txSignature = await signAndBroadcast(
      client,
      connection,
      transaction,
      DEPOSITOR_ADDRESS,
      "deposit",
    );
    ```

    ### 3.5. Full deposit script (Circle Wallets)

    The script validates the source balance, builds the Gateway deposit instruction,
    and confirms the deposit on Solana Devnet. Inline comments explain each stage.

    ```ts deposit.ts expandable theme={null}
    import {
      Wallet,
      AnchorProvider,
      setProvider,
      Program,
    } from "@coral-xyz/anchor";
    import {
      Connection,
      Keypair,
      PublicKey,
      SystemProgram,
      Transaction,
    } from "@solana/web3.js";
    import {
      getAssociatedTokenAddressSync,
      getAccount,
      TOKEN_PROGRAM_ID,
    } from "@solana/spl-token";
    import BN from "bn.js";
    import {
      RPC_ENDPOINT,
      GATEWAY_WALLET_ADDRESS,
      USDC_ADDRESS,
      client,
      gatewayWalletIdl,
      findDepositPDAs,
      signAndBroadcast,
    } from "./config.js";

    const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;

    if (!DEPOSITOR_ADDRESS) {
      console.error("Missing required env var: DEPOSITOR_ADDRESS");
      process.exit(1);
    }

    const DEPOSIT_AMOUNT = new BN(1_000_000);

    async function main() {
      // Set up the Solana connection and core account addresses.
      const connection = new Connection(RPC_ENDPOINT, "confirmed");
      const usdcMint = new PublicKey(USDC_ADDRESS);
      const programId = new PublicKey(GATEWAY_WALLET_ADDRESS);
      const owner = new PublicKey(DEPOSITOR_ADDRESS);

      console.log(`Using account: ${owner.toBase58()}`);
      console.log(`\n=== Processing Solana Devnet ===`);

      // [1] Check the depositor's current USDC balance.
      const userTokenAccount = getAssociatedTokenAddressSync(usdcMint, owner);
      const tokenAccountInfo = await getAccount(connection, userTokenAccount);
      const currentBalance = Number(tokenAccountInfo.amount) / 1_000_000;
      console.log(`Current balance: ${currentBalance} USDC`);

      if (tokenAccountInfo.amount < BigInt(DEPOSIT_AMOUNT.toString())) {
        throw new Error(
          "Insufficient USDC balance. Please top up at https://faucet.circle.com",
        );
      }

      // [2] Set up the Anchor client and derive the Gateway deposit PDAs.
      const dummyWallet = new Wallet(Keypair.generate());
      const provider = new AnchorProvider(
        connection,
        dummyWallet,
        AnchorProvider.defaultOptions(),
      );
      setProvider(provider);
      const program = new Program(gatewayWalletIdl, provider);
      const pdas = findDepositPDAs(programId, usdcMint, owner);

      // [3] Build, sign, and confirm the Gateway deposit transaction.
      const depositIx = await program.methods
        .deposit(DEPOSIT_AMOUNT)
        .accountsPartial({
          payer: owner,
          owner: owner,
          gatewayWallet: pdas.wallet,
          ownerTokenAccount: userTokenAccount,
          custodyTokenAccount: pdas.custody,
          deposit: pdas.deposit,
          depositorDenylist: pdas.denylist,
          tokenProgram: TOKEN_PROGRAM_ID,
          systemProgram: SystemProgram.programId,
        })
        .instruction();

      const { blockhash, lastValidBlockHeight } =
        await connection.getLatestBlockhash();
      const transaction = new Transaction();
      transaction.add(depositIx);
      transaction.recentBlockhash = blockhash;
      transaction.feePayer = owner;

      const txSignature = await signAndBroadcast(
        client,
        connection,
        transaction,
        DEPOSITOR_ADDRESS,
        "deposit",
      );

      await connection.confirmTransaction(
        { signature: txSignature, blockhash, lastValidBlockHeight },
        "confirmed",
      );

      console.log(`Done on Solana Devnet. Deposit tx: ${txSignature}`);
    }

    /* Main invocation */
    main().catch((error) => {
      console.error("\nError:", error);
      process.exit(1);
    });
    ```

    ### 3.6. Run the deposit script

    ```shell theme={null}
    npm run deposit
    ```

    Wait for the required number of block confirmations. Once the deposit
    transaction is final, your Gateway balance on Solana Devnet will be updated.
    Solana Devnet transactions typically reach finality in seconds.

    ### 3.7. Check the balances on the Gateway Wallet

    Create a new file called `balances.ts`, and add the following code. This script
    retrieves the USDC balances available from your Gateway Wallet for the
    `DEPOSITOR_ADDRESS` currently set in `.env`.

    ```ts balances.ts expandable theme={null}
    interface GatewayBalancesResponse {
      balances: Array<{
        domain: number;
        balance: string;
      }>;
    }

    const EVM_DOMAINS = {
      ethereum: 0,
      avalanche: 1,
      optimism: 2,
      arbitrum: 3,
      base: 6,
      polygon: 7,
      unichain: 10,
      arc: 26,
    };

    const SOLANA_DOMAINS = {
      solana: 5,
    };

    const DOMAINS = { ...EVM_DOMAINS, ...SOLANA_DOMAINS };

    const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;

    if (!DEPOSITOR_ADDRESS) {
      console.error("Missing required env var: DEPOSITOR_ADDRESS");
      process.exit(1);
    }

    const isEvmAddress = DEPOSITOR_ADDRESS.startsWith("0x");

    async function main() {
      console.log(`Depositor address: ${DEPOSITOR_ADDRESS}`);
      console.log(`Address type: ${isEvmAddress ? "EVM" : "Solana"}\n`);

      const activeDomains = isEvmAddress ? EVM_DOMAINS : SOLANA_DOMAINS;
      const domainIds = Object.values(activeDomains);
      const body = {
        token: "USDC",
        sources: domainIds.map((domain) => ({
          domain,
          depositor: DEPOSITOR_ADDRESS,
        })),
      };

      const res = await fetch(
        "https://gateway-api-testnet.circle.com/v1/balances",
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(body),
        },
      );

      const result = (await res.json()) as GatewayBalancesResponse;

      let total = 0;
      for (const balance of result.balances) {
        const chain =
          Object.keys(DOMAINS).find(
            (k) => DOMAINS[k as keyof typeof DOMAINS] === balance.domain,
          ) || `Domain ${balance.domain}`;
        const amount = parseFloat(balance.balance);
        console.log(`${chain}: ${amount.toFixed(6)} USDC`);
        total += amount;
      }

      console.log(`\nTotal: ${total.toFixed(6)} USDC`);
    }

    main().catch((error) => {
      console.error("\nError:", error);
      process.exit(1);
    });
    ```

    You can run it to verify your balance on Gateway.

    ```shell theme={null}
    npm run balances
    ```

    <Tabs>
      <Tab title="Transfer from Solana">
        ## Step 4. Transfer USDC from Solana to Solana

        The transfer script burns USDC on your Solana Devnet Gateway balance and mints
        to a recipient on Solana Devnet via Gateway. You can skip to the
        [full transfer script](#4-9-full-solana-transfer-script-circle-wallets) if you
        prefer.

        ### 4.1. Create the Solana transfer script

        ```shell theme={null}
        touch transfer-from-sol.ts
        ```

        ### 4.2. Define constants and types

        This flow uses the same Solana burn intent layout as the standard Gateway
        quickstart, but swaps in Circle Wallet signing for both the burn intent and the
        mint transaction.

        ```ts theme={null}
        const TRANSFER_AMOUNT = 0.1;
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;
        ```

        ### 4.3. Add helper functions

        The helper layer encodes the Solana burn intent, creates a lightweight Anchor
        provider, and exposes the address conversion utilities required for Gateway
        minting.

        ```ts theme={null}
        function createProvider(connection: Connection) {
          const dummyWallet = new Wallet(Keypair.generate());
          const provider = new AnchorProvider(
            connection,
            dummyWallet,
            AnchorProvider.defaultOptions(),
          );
          setProvider(provider);
          return provider;
        }
        ```

        ### 4.4. Initialize connection and create recipient ATA

        Before minting to the destination wallet, derive the recipient Associated Token
        Account and create it `idempotently` with the destination Developer-Controlled
        Account and create it idempotently with the destination Developer-Controlled

        <Info>
          For transfers to Solana, the `destinationRecipient` must be an initialized
          USDC Token Account. If the intended recipient is a standard wallet address,
          consider setting the `destinationRecipient` to its Associated Token Account
          (ATA) not the recipient wallet address. See the [Solana Technical
          Guide](/gateway/references/solana#reducedmintattestation) and [Solana Programs
          and Interfaces](/gateway/references/solana-programs#gatewaymint) for
          high-level Solana guidance and `gatewayMint` account requirements. Use the
          onchain IDLs linked from [Solana Programs and
          Interfaces](/gateway/references/solana-programs#account-structures) as the
          canonical static instruction and account definitions.
        </Info>

        ```ts theme={null}
        const provider = createProvider(connection);

        const recipientAta = getAssociatedTokenAddressSync(usdcMint, recipientPubkey);
        const ataTx = new Transaction();
        ataTx.add(
          createAssociatedTokenAccountIdempotentInstruction(
            owner,
            recipientAta,
            recipientPubkey,
            usdcMint,
          ),
        );
        ```

        ### 4.5. Create and sign burn intent

        Encode the Solana burn intent, prefix the payload, and sign it with the source
        Developer-Controlled Wallet.

        ```ts theme={null}
        const burnIntent = createBurnIntent({
          sourceDepositor: owner.toBase58(),
          destinationRecipient: recipientAta.toBase58(),
          sourceSigner: owner.toBase58(),
        });

        const sigResult = await client.signMessage({
          walletAddress: DEPOSITOR_ADDRESS,
          blockchain: "SOL-DEVNET",
          encodedByHex: true,
          message: "0x" + prefixed.toString("hex"),
        });
        ```

        ### 4.6. Request attestation from Gateway API

        Submit the signed burn intent to the Gateway API and decode the attestation set
        that comes back from the response.

        ```ts theme={null}
        const response = await fetch(
          "https://gateway-api-testnet.circle.com/v1/transfer",
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: stringifyTypedData(request),
          },
        );
        ```

        ### 4.7. Set up minter client

        Once the API returns the attestation, initialize the Gateway Minter program and
        derive the PDA accounts needed for the Solana mint.

        The local IDL fragments in this example are only the subset needed by the sample
        code. For canonical static instruction and account definitions, use the onchain
        IDLs linked from
        [Solana Programs and Interfaces](/gateway/references/solana-programs#account-structures).

        ```ts theme={null}
        const minterProgram = new Program(gatewayMinterIdl, provider);
        const [minterPda] = PublicKey.findProgramAddressSync(
          [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
          minterProgramId,
        );
        ```

        ### 4.8. Mint on Solana

        Create the mint instruction, sign the transaction with the destination
        Developer-Controlled Wallet, and confirm it on Solana Devnet.

        The direct-mint flow uses the destination wallet as both `payer` and
        `destinationCaller`. If an attestation specifies a non-zero `destinationCaller`,
        the transaction signer must match it.

        In this quickstart's client shape, the instruction accounts are assembled as the
        fixed `gatewayMint` accounts first, followed by one ordered triplet per
        attestation: `custody_token_account`, `destination_recipient`, and
        `transfer_spec_hash_account`.

        ```ts theme={null}
        const mintIx = await minterProgram.methods
          .gatewayMint({
            attestation: attestationBytes,
            signature: signatureBytes,
          })
          .accountsPartial({
            gatewayMinter: minterPda,
            destinationCaller: owner,
            payer: owner,
            systemProgram: SystemProgram.programId,
            tokenProgram: TOKEN_PROGRAM_ID,
          })
          .remainingAccounts(remainingAccounts)
          .instruction();
        ```

        ### 4.9. Full Solana transfer script (Circle Wallets)

        The script creates the recipient ATA, signs a Solana burn intent, requests a
        Gateway attestation, and mints on Solana Devnet. Inline comments explain each
        stage.

        ```ts transfer-from-sol.ts expandable theme={null}
        import { randomBytes } from "node:crypto";
        import {
          Wallet,
          AnchorProvider,
          setProvider,
          Program,
          utils,
        } from "@coral-xyz/anchor";
        import {
          Connection,
          Keypair,
          PublicKey,
          SystemProgram,
          Transaction,
        } from "@solana/web3.js";
        import {
          TOKEN_PROGRAM_ID,
          getAssociatedTokenAddressSync,
          createAssociatedTokenAccountIdempotentInstruction,
        } from "@solana/spl-token";
        import { u32be, struct, blob, offset, Layout } from "@solana/buffer-layout";
        import {
          RPC_ENDPOINT,
          GATEWAY_WALLET_ADDRESS,
          GATEWAY_MINTER_ADDRESS,
          USDC_ADDRESS,
          SOLANA_DOMAIN,
          SOLANA_ZERO_ADDRESS,
          client,
          gatewayMinterIdl,
          publicKey,
          hexToPublicKey,
          solanaAddressToBytes32,
          decodeAttestationSet,
          findCustodyPda,
          findTransferSpecHashPda,
          signAndBroadcast,
          stringifyTypedData,
        } from "./config.js";

        const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;
        const RECIPIENT_ADDRESS = process.env.RECIPIENT_ADDRESS!;

        if (!DEPOSITOR_ADDRESS || !RECIPIENT_ADDRESS) {
          console.error(
            "Missing required env vars: DEPOSITOR_ADDRESS, RECIPIENT_ADDRESS",
          );
          process.exit(1);
        }

        const TRANSFER_AMOUNT = 0.1;
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;

        const TRANSFER_SPEC_MAGIC = 0xca85def7;
        const BURN_INTENT_MAGIC = 0x070afbc2;

        // Custom layout for 256-bit unsigned integers.
        class UInt256BE extends Layout<bigint> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0) {
            const buffer = b.subarray(offset, offset + 32);
            return buffer.readBigUInt64BE(24);
          }
          encode(src: bigint, b: Buffer, offset = 0) {
            const buffer = Buffer.alloc(32);
            buffer.writeBigUInt64BE(BigInt(src), 24);
            buffer.copy(b, offset);
            return 32;
          }
        }

        const uint256be = (property: string) => new UInt256BE(property);

        const BurnIntentLayout = struct([
          u32be("magic"),
          uint256be("maxBlockHeight"),
          uint256be("maxFee"),
          u32be("transferSpecLength"),
          struct(
            [
              u32be("magic"),
              u32be("version"),
              u32be("sourceDomain"),
              u32be("destinationDomain"),
              publicKey("sourceContract"),
              publicKey("destinationContract"),
              publicKey("sourceToken"),
              publicKey("destinationToken"),
              publicKey("sourceDepositor"),
              publicKey("destinationRecipient"),
              publicKey("sourceSigner"),
              publicKey("destinationCaller"),
              uint256be("value"),
              blob(32, "salt"),
              u32be("hookDataLength"),
              blob(offset(u32be(), -4), "hookData"),
            ] as any,
            "spec",
          ),
        ] as any);

        function createBurnIntent(params: {
          sourceDepositor: string;
          destinationRecipient: string;
          sourceSigner: string;
        }) {
          const { sourceDepositor, destinationRecipient, sourceSigner } = params;

          return {
            maxBlockHeight: MAX_UINT64,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: SOLANA_DOMAIN,
              destinationDomain: SOLANA_DOMAIN,
              sourceContract: solanaAddressToBytes32(GATEWAY_WALLET_ADDRESS),
              destinationContract: solanaAddressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: solanaAddressToBytes32(USDC_ADDRESS),
              destinationToken: solanaAddressToBytes32(USDC_ADDRESS),
              sourceDepositor: solanaAddressToBytes32(sourceDepositor),
              destinationRecipient: solanaAddressToBytes32(destinationRecipient),
              sourceSigner: solanaAddressToBytes32(sourceSigner),
              destinationCaller: solanaAddressToBytes32(SOLANA_ZERO_ADDRESS),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Encode the burn intent into the binary layout expected by Gateway.
        function encodeBurnIntent(bi: ReturnType<typeof createBurnIntent>): Buffer {
          const hookData = Buffer.from((bi.spec.hookData || "0x").slice(2), "hex");
          const prepared = {
            magic: BURN_INTENT_MAGIC,
            maxBlockHeight: bi.maxBlockHeight,
            maxFee: bi.maxFee,
            transferSpecLength: 340 + hookData.length,
            spec: {
              magic: TRANSFER_SPEC_MAGIC,
              version: bi.spec.version,
              sourceDomain: bi.spec.sourceDomain,
              destinationDomain: bi.spec.destinationDomain,
              sourceContract: hexToPublicKey(bi.spec.sourceContract),
              destinationContract: hexToPublicKey(bi.spec.destinationContract),
              sourceToken: hexToPublicKey(bi.spec.sourceToken),
              destinationToken: hexToPublicKey(bi.spec.destinationToken),
              sourceDepositor: hexToPublicKey(bi.spec.sourceDepositor),
              destinationRecipient: hexToPublicKey(bi.spec.destinationRecipient),
              sourceSigner: hexToPublicKey(bi.spec.sourceSigner),
              destinationCaller: hexToPublicKey(bi.spec.destinationCaller),
              value: bi.spec.value,
              salt: Buffer.from(bi.spec.salt.slice(2), "hex"),
              hookDataLength: hookData.length,
              hookData,
            },
          };
          const buffer = Buffer.alloc(72 + 340 + hookData.length);
          const bytesWritten = BurnIntentLayout.encode(prepared, buffer);
          return buffer.subarray(0, bytesWritten);
        }

        // Create a lightweight Anchor provider for PDA derivation and instruction building.
        function createProvider(connection: Connection) {
          const dummyWallet = new Wallet(Keypair.generate());
          const provider = new AnchorProvider(
            connection,
            dummyWallet,
            AnchorProvider.defaultOptions(),
          );
          setProvider(provider);
          return provider;
        }

        async function main() {
          // Set up the Solana connection and destination accounts.
          const connection = new Connection(RPC_ENDPOINT, "confirmed");
          const usdcMint = new PublicKey(USDC_ADDRESS);
          const minterProgramId = new PublicKey(GATEWAY_MINTER_ADDRESS);
          const owner = new PublicKey(DEPOSITOR_ADDRESS);
          const recipientPubkey = new PublicKey(RECIPIENT_ADDRESS);

          console.log(`Using account: ${owner.toBase58()}`);
          console.log(`Transferring from: Solana Devnet -> Solana Devnet`);

          const provider = createProvider(connection);

          // [1] Create the recipient ATA if it does not already exist.
          const recipientAta = getAssociatedTokenAddressSync(usdcMint, recipientPubkey);
          const { blockhash: ataBlockhash, lastValidBlockHeight: ataBlockHeight } =
            await connection.getLatestBlockhash();
          const ataTx = new Transaction();
          ataTx.add(
            createAssociatedTokenAccountIdempotentInstruction(
              owner,
              recipientAta,
              recipientPubkey,
              usdcMint,
            ),
          );
          ataTx.recentBlockhash = ataBlockhash;
          ataTx.feePayer = owner;

          const ataSig = await signAndBroadcast(
            client,
            connection,
            ataTx,
            DEPOSITOR_ADDRESS,
            "ATA creation",
          );
          await connection.confirmTransaction(
            {
              signature: ataSig,
              blockhash: ataBlockhash,
              lastValidBlockHeight: ataBlockHeight,
            },
            "confirmed",
          );

          // [2] Create and sign the Solana burn intent.
          const burnIntent = createBurnIntent({
            sourceDepositor: owner.toBase58(),
            destinationRecipient: recipientAta.toBase58(),
            sourceSigner: owner.toBase58(),
          });

          const encoded = encodeBurnIntent(burnIntent);
          const prefixed = Buffer.concat([
            Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
            encoded,
          ]);

          const sigResult = await client.signMessage({
            walletAddress: DEPOSITOR_ADDRESS,
            blockchain: "SOL-DEVNET",
            encodedByHex: true,
            message: "0x" + prefixed.toString("hex"),
          });

          const burnIntentSignature = sigResult.data?.signature;
          if (!burnIntentSignature) throw new Error("Failed to sign burn intent");

          const formattedSignature = burnIntentSignature.startsWith("0x")
            ? burnIntentSignature
            : `0x${burnIntentSignature}`;

          const request = [{ burnIntent, signature: formattedSignature }];
          console.log("Signed burn intent.");

          // [3] Request the attestation set from Gateway API.
          const response = await fetch(
            "https://gateway-api-testnet.circle.com/v1/transfer",
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: stringifyTypedData(request),
            },
          );

          const json = (await response.json()) as {
            attestation: string;
            signature: string;
            success?: boolean;
            message?: string;
          };
          if (json.success === false) {
            throw new Error(`Gateway API error: ${json.message}`);
          }
          console.log("Gateway API response:", JSON.stringify(json, null, 2));

          const { attestation, signature: mintSignature } = json;
          const decoded = decodeAttestationSet(attestation);

          // [4] Set up the Gateway Minter client and remaining accounts.
          const minterProgram = new Program(gatewayMinterIdl, provider);
          const [minterPda] = PublicKey.findProgramAddressSync(
            [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
            minterProgramId,
          );

          const remainingAccounts = decoded.attestations.flatMap((e) => [
            {
              pubkey: findCustodyPda(e.destinationToken, minterProgramId),
              isWritable: true,
              isSigner: false,
            },
            { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
            {
              pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
              isWritable: true,
              isSigner: false,
            },
          ]);

          const attestationBytes = Buffer.from(attestation.slice(2), "hex");
          const signatureBytes = Buffer.from(mintSignature.slice(2), "hex");

          // [5] Mint on Solana with the returned attestation.
          console.log("Minting funds on Solana Devnet...");
          const mintIx = await minterProgram.methods
            .gatewayMint({
              attestation: attestationBytes,
              signature: signatureBytes,
            })
            .accountsPartial({
              gatewayMinter: minterPda,
              destinationCaller: owner,
              payer: owner,
              systemProgram: SystemProgram.programId,
              tokenProgram: TOKEN_PROGRAM_ID,
            })
            .remainingAccounts(remainingAccounts)
            .instruction();

          const { blockhash, lastValidBlockHeight } =
            await connection.getLatestBlockhash();
          const mintTx = new Transaction();
          mintTx.add(mintIx);
          mintTx.recentBlockhash = blockhash;
          mintTx.feePayer = owner;

          const mintSig = await signAndBroadcast(
            client,
            connection,
            mintTx,
            DEPOSITOR_ADDRESS,
            "mint",
          );

          await connection.confirmTransaction(
            { signature: mintSig, blockhash, lastValidBlockHeight },
            "confirmed",
          );

          console.log(`Minted ${Number(TRANSFER_VALUE) / 1_000_000} USDC`);
          console.log(`Mint transaction hash (Solana Devnet):`, mintSig);
        }

        /* Main invocation */
        main().catch((error) => {
          console.error("\nError:", error);
          process.exit(1);
        });
        ```

        ### 4.10. Run the Solana to Solana transfer script

        ```shell theme={null}
        npm run transfer-from-sol
        ```
      </Tab>

      <Tab title="Transfer from EVM">
        ## Step 4. Transfer USDC from EVM to Solana

        The transfer script burns USDC on selected EVM source chains and mints on Solana
        Devnet via Gateway. Pass source chain names as command-line arguments (for
        example, `arc`, `base`, or `all`). You can skip to the
        [full transfer script](#4-9-full-evm-transfer-script-circle-wallets) if you
        prefer.

        ### 4.1. Create the EVM to Solana transfer script

        ```shell theme={null}
        touch transfer-from-evm.ts
        ```

        ### 4.2. Define constants and types

        This flow matches the standard EVM to Solana quickstart, but uses Circle Wallets
        for signing on both sides. Keep the typed EIP-712 burn intent structures at the
        top of the file so the source and destination formats are easy to compare.

        ```ts theme={null}
        const EVM_GATEWAY_WALLET = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";

        const TRANSFER_AMOUNT = 0.1;
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;
        ```

        ### 4.3. Add helper functions

        The helper layer parses selected EVM source chains, converts EVM addresses to
        `bytes32`, and creates a lightweight Anchor provider for the destination Solana
        mint.

        ```ts theme={null}
        const args = process.argv
          .slice(2)
          .filter((arg) => arg !== "--")
          .map((chain) => chain.toLowerCase());

        function createProvider(connection: Connection) {
          const dummyWallet = new Wallet(Keypair.generate());
          const provider = new AnchorProvider(
            connection,
            dummyWallet,
            AnchorProvider.defaultOptions(),
          );
          setProvider(provider);
          return provider;
        }
        ```

        ### 4.4. Initialize connection and create recipient ATA

        Set up the destination Solana connection first, derive the recipient ATA, and
        create it `idempotently` before you request any Gateway attestations. create it
        idempotently before you request any Gateway attestations.

        <Info>
          For transfers to Solana, the `destinationRecipient` must be an initialized
          USDC Token Account. If the intended recipient is a standard wallet address,
          consider setting the `destinationRecipient` to its Associated Token Account
          (ATA) not the recipient wallet address. See the [Solana Technical
          Guide](/gateway/references/solana#reducedmintattestation) and [Solana Programs
          and Interfaces](/gateway/references/solana-programs#gatewaymint) for
          high-level Solana guidance and `gatewayMint` account requirements. Use the
          onchain IDLs linked from [Solana Programs and
          Interfaces](/gateway/references/solana-programs#account-structures) as the
          canonical static instruction and account definitions.
        </Info>

        ```ts theme={null}
        const connection = new Connection(RPC_ENDPOINT, "confirmed");
        const recipientPubkey = new PublicKey(RECIPIENT_ADDRESS);

        const recipientAta = getAssociatedTokenAddressSync(usdcMint, recipientPubkey);
        const ataTx = new Transaction();
        ataTx.add(
          createAssociatedTokenAccountIdempotentInstruction(
            recipientPubkey,
            recipientAta,
            recipientPubkey,
            usdcMint,
          ),
        );
        ```

        ### 4.5. Create and sign burn intents

        For each selected EVM source chain, create a burn intent and sign the typed data
        with the source Developer-Controlled Wallet.

        ```ts theme={null}
        const burnIntent = createBurnIntent({
          sourceChain: chainName,
          depositorAddress: DEPOSITOR_ADDRESS,
          recipientAta: recipientAta.toBase58(),
        });

        const sigResp = await client.signTypedData({
          walletAddress: DEPOSITOR_ADDRESS,
          blockchain: evmChainConfigs[chainName].walletChain,
          data: stringifyTypedData(typedData),
        });
        ```

        ### 4.6. Request attestation from Gateway API

        Submit all signed burn intents to the Gateway API and validate that the response
        contains both the attestation and operator signature needed for the Solana mint.

        ```ts theme={null}
        const response = await fetch(
          "https://gateway-api-testnet.circle.com/v1/transfer",
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: stringifyTypedData(requests),
          },
        );
        ```

        ### 4.7. Set up minter client

        After decoding the attestation set, initialize the Gateway Minter program and
        build the remaining account list expected by the Solana mint instruction.

        <Info>
          The ordered remaining-account list and PDA derivations are documented in
          [Solana Programs and
          Interfaces](/gateway/references/solana-programs#gatewaymint). For static
          instruction definitions, use the onchain IDLs linked from that page.
        </Info>

        ```ts theme={null}
        const decoded = decodeAttestationSet(attestation);
        const minterProgram = new Program(gatewayMinterIdl, provider);

        const remainingAccounts = decoded.attestations.flatMap((e) => [
          {
            pubkey: findCustodyPda(e.destinationToken, minterProgramId),
            isWritable: true,
            isSigner: false,
          },
          { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
          {
            pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
            isWritable: true,
            isSigner: false,
          },
        ]);
        ```

        ### 4.8. Mint on Solana

        Create the Solana mint instruction, sign it with the destination
        Developer-Controlled Wallet, then confirm the transaction on Solana Devnet.

        In the common direct-mint flow, the destination wallet acts as both `payer` and
        `destinationCaller`. If the attestation specifies a non-zero
        `destinationCaller`, the transaction signer must match it.

        In this quickstart's client shape, the instruction accounts are assembled as the
        fixed `gatewayMint` accounts first, followed by one ordered triplet per
        attestation: `custody_token_account`, `destination_recipient`, and
        `transfer_spec_hash_account`.

        ```ts theme={null}
        const mintIx = await minterProgram.methods
          .gatewayMint({
            attestation: attestationBytes,
            signature: signatureBytes,
          })
          .accountsPartial({
            gatewayMinter: minterPda,
            destinationCaller: recipientPubkey,
            payer: recipientPubkey,
            systemProgram: SystemProgram.programId,
            tokenProgram: TOKEN_PROGRAM_ID,
          })
          .remainingAccounts(remainingAccounts)
          .instruction();
        ```

        ### 4.9. Full EVM transfer script (Circle Wallets)

        The script creates the recipient ATA, signs EVM burn intents, requests a Gateway
        attestation, and mints on Solana Devnet. Inline comments explain each stage.

        ```ts transfer-from-evm.ts expandable theme={null}
        import { randomBytes } from "node:crypto";
        import {
          Wallet,
          AnchorProvider,
          setProvider,
          Program,
          utils,
        } from "@coral-xyz/anchor";
        import {
          Connection,
          Keypair,
          PublicKey,
          SystemProgram,
          Transaction,
        } from "@solana/web3.js";
        import {
          TOKEN_PROGRAM_ID,
          getAssociatedTokenAddressSync,
          createAssociatedTokenAccountIdempotentInstruction,
        } from "@solana/spl-token";
        import {
          RPC_ENDPOINT,
          GATEWAY_MINTER_ADDRESS,
          USDC_ADDRESS,
          SOLANA_DOMAIN,
          SOLANA_ZERO_ADDRESS,
          client,
          gatewayMinterIdl,
          solanaAddressToBytes32,
          decodeAttestationSet,
          findCustodyPda,
          findTransferSpecHashPda,
          signAndBroadcast,
          stringifyTypedData,
        } from "./config.js";

        const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;
        const RECIPIENT_ADDRESS = process.env.RECIPIENT_ADDRESS!;

        if (!DEPOSITOR_ADDRESS || !RECIPIENT_ADDRESS) {
          console.error(
            "Missing required env vars: DEPOSITOR_ADDRESS, RECIPIENT_ADDRESS",
          );
          process.exit(1);
        }

        export type WalletChain =
          | "ETH-SEPOLIA"
          | "BASE-SEPOLIA"
          | "AVAX-FUJI"
          | "ARC-TESTNET"
          | "ARB-SEPOLIA"
          | "OP-SEPOLIA"
          | "MATIC-AMOY"
          | "UNI-SEPOLIA";

        export type EvmChain =
          | "ethereum"
          | "base"
          | "avalanche"
          | "arc"
          | "arbitrum"
          | "optimism"
          | "polygon"
          | "unichain";

        type EvmChainConfig = {
          chainName: string;
          usdc: string;
          domain: number;
          walletChain: WalletChain;
        };

        const evmChainConfigs: Record<EvmChain, EvmChainConfig> = {
          ethereum: {
            chainName: "Ethereum Sepolia",
            usdc: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
            domain: 0,
            walletChain: "ETH-SEPOLIA",
          },
          base: {
            chainName: "Base Sepolia",
            usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
            domain: 6,
            walletChain: "BASE-SEPOLIA",
          },
          avalanche: {
            chainName: "Avalanche Fuji",
            usdc: "0x5425890298aed601595a70AB815c96711a31Bc65",
            domain: 1,
            walletChain: "AVAX-FUJI",
          },
          arc: {
            chainName: "Arc Testnet",
            usdc: "0x3600000000000000000000000000000000000000",
            domain: 26,
            walletChain: "ARC-TESTNET",
          },
          arbitrum: {
            chainName: "Arbitrum Sepolia",
            usdc: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
            domain: 3,
            walletChain: "ARB-SEPOLIA",
          },
          optimism: {
            chainName: "OP Sepolia",
            usdc: "0x5fd84259d66Cd46123540766Be93DFE6D43130D7",
            domain: 2,
            walletChain: "OP-SEPOLIA",
          },
          polygon: {
            chainName: "Polygon Amoy",
            usdc: "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
            domain: 7,
            walletChain: "MATIC-AMOY",
          },
          unichain: {
            chainName: "Unichain Sepolia",
            usdc: "0x31d0220469e10c4E71834a79b1f276d740d3768F",
            domain: 10,
            walletChain: "UNI-SEPOLIA",
          },
        };

        const EVM_GATEWAY_WALLET = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";

        const TRANSFER_AMOUNT = 0.1;
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;
        const MAX_UINT64_DEC = MAX_UINT64.toString();

        const eip712Domain = { name: "GatewayWallet", version: "1" };

        const EIP712Domain = [
          { name: "name", type: "string" },
          { name: "version", type: "string" },
        ];

        const TransferSpec = [
          { name: "version", type: "uint32" },
          { name: "sourceDomain", type: "uint32" },
          { name: "destinationDomain", type: "uint32" },
          { name: "sourceContract", type: "bytes32" },
          { name: "destinationContract", type: "bytes32" },
          { name: "sourceToken", type: "bytes32" },
          { name: "destinationToken", type: "bytes32" },
          { name: "sourceDepositor", type: "bytes32" },
          { name: "destinationRecipient", type: "bytes32" },
          { name: "sourceSigner", type: "bytes32" },
          { name: "destinationCaller", type: "bytes32" },
          { name: "value", type: "uint256" },
          { name: "salt", type: "bytes32" },
          { name: "hookData", type: "bytes" },
        ];

        const BurnIntent = [
          { name: "maxBlockHeight", type: "uint256" },
          { name: "maxFee", type: "uint256" },
          { name: "spec", type: "TransferSpec" },
        ];

        // Parse the selected EVM source chains from the command-line arguments.
        function parseSelectedChains(): EvmChain[] {
          const args = process.argv
            .slice(2)
            .filter((arg) => arg !== "--")
            .map((chain) => chain.toLowerCase());
          const validChains = Object.keys(evmChainConfigs);

          if (args.length === 0) {
            throw new Error(
              "No chains specified. Usage: npx tsx transfer-from-evm.ts <chain1> [chain2...] or 'all'",
            );
          }

          if (args.length === 1 && args[0] === "all") {
            return Object.keys(evmChainConfigs) as EvmChain[];
          }

          const invalid = args.filter((arg) => !(arg in evmChainConfigs));
          if (invalid.length > 0) {
            console.error(
              `Unsupported chain: ${invalid.join(", ")}\n` +
                `Valid chains: ${validChains.join(", ")}, all\n` +
                `Example: npx tsx transfer-from-evm.ts ethereum base`,
            );
            process.exit(1);
          }

          return [...new Set(args)] as EvmChain[];
        }

        // Build a burn intent for an EVM source chain and Solana recipient ATA.
        function createBurnIntent(params: {
          sourceChain: EvmChain;
          depositorAddress: string;
          recipientAta: string;
        }) {
          const { sourceChain, depositorAddress, recipientAta } = params;
          const sourceConfig = evmChainConfigs[sourceChain];

          return {
            maxBlockHeight: MAX_UINT64_DEC,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: sourceConfig.domain,
              destinationDomain: SOLANA_DOMAIN,
              sourceContract: EVM_GATEWAY_WALLET,
              destinationContract: solanaAddressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: sourceConfig.usdc,
              destinationToken: solanaAddressToBytes32(USDC_ADDRESS),
              sourceDepositor: depositorAddress,
              destinationRecipient: solanaAddressToBytes32(recipientAta),
              sourceSigner: depositorAddress,
              destinationCaller: solanaAddressToBytes32(SOLANA_ZERO_ADDRESS),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Format the burn intent as EIP-712 typed data for Circle Wallet signing.
        function burnIntentTypedData(burnIntent: ReturnType<typeof createBurnIntent>) {
          return {
            types: { EIP712Domain, TransferSpec, BurnIntent },
            domain: eip712Domain,
            primaryType: "BurnIntent",
            message: {
              ...burnIntent,
              spec: {
                ...burnIntent.spec,
                sourceContract: evmAddressToBytes32(burnIntent.spec.sourceContract),
                destinationContract: burnIntent.spec.destinationContract,
                sourceToken: evmAddressToBytes32(burnIntent.spec.sourceToken),
                destinationToken: burnIntent.spec.destinationToken,
                sourceDepositor: evmAddressToBytes32(burnIntent.spec.sourceDepositor),
                destinationRecipient: burnIntent.spec.destinationRecipient,
                sourceSigner: evmAddressToBytes32(burnIntent.spec.sourceSigner),
                destinationCaller: burnIntent.spec.destinationCaller,
              },
            },
          };
        }

        // Convert an EVM address to a 32-byte hex string.
        function evmAddressToBytes32(address: string): string {
          return "0x" + address.toLowerCase().replace(/^0x/, "").padStart(64, "0");
        }

        // Create a lightweight Anchor provider for PDA derivation and instruction building.
        function createProvider(connection: Connection) {
          const dummyWallet = new Wallet(Keypair.generate());
          const provider = new AnchorProvider(
            connection,
            dummyWallet,
            AnchorProvider.defaultOptions(),
          );
          setProvider(provider);
          return provider;
        }

        async function main() {
          // Parse the selected source chains and set up Solana destination accounts.
          const selectedChains = parseSelectedChains();
          console.log(`Sender (EVM): ${DEPOSITOR_ADDRESS}`);
          console.log(`Recipient (Solana): ${RECIPIENT_ADDRESS}`);
          console.log(
            `Transferring balances from: ${selectedChains.map((c) => evmChainConfigs[c].chainName).join(", ")}`,
          );

          const connection = new Connection(RPC_ENDPOINT, "confirmed");
          const usdcMint = new PublicKey(USDC_ADDRESS);
          const minterProgramId = new PublicKey(GATEWAY_MINTER_ADDRESS);
          const recipientPubkey = new PublicKey(RECIPIENT_ADDRESS);

          const provider = createProvider(connection);

          // [1] Create the recipient ATA if it does not already exist.
          const recipientAta = getAssociatedTokenAddressSync(usdcMint, recipientPubkey);
          console.log(`Recipient ATA: ${recipientAta.toBase58()}`);

          const { blockhash: ataBlockhash, lastValidBlockHeight: ataBlockHeight } =
            await connection.getLatestBlockhash();
          const ataTx = new Transaction();
          ataTx.add(
            createAssociatedTokenAccountIdempotentInstruction(
              recipientPubkey,
              recipientAta,
              recipientPubkey,
              usdcMint,
            ),
          );
          ataTx.recentBlockhash = ataBlockhash;
          ataTx.feePayer = recipientPubkey;

          const ataSig = await signAndBroadcast(
            client,
            connection,
            ataTx,
            RECIPIENT_ADDRESS,
            "ATA creation",
          );
          await connection.confirmTransaction(
            {
              signature: ataSig,
              blockhash: ataBlockhash,
              lastValidBlockHeight: ataBlockHeight,
            },
            "confirmed",
          );

          // [2] Create and sign burn intents for each selected EVM source chain.
          const requests = [];

          for (const chainName of selectedChains) {
            console.log(
              `Creating burn intent from ${evmChainConfigs[chainName].chainName} → Solana Devnet...`,
            );

            const burnIntent = createBurnIntent({
              sourceChain: chainName,
              depositorAddress: DEPOSITOR_ADDRESS,
              recipientAta: recipientAta.toBase58(),
            });

            const typedData = burnIntentTypedData(burnIntent);

            const sigResp = await client.signTypedData({
              walletAddress: DEPOSITOR_ADDRESS,
              blockchain: evmChainConfigs[chainName].walletChain,
              data: stringifyTypedData(typedData),
            });

            const burnIntentSignature = sigResp.data?.signature;
            if (!burnIntentSignature) {
              throw new Error(`Failed to sign burn intent for ${chainName}`);
            }

            requests.push({
              burnIntent: typedData.message,
              signature: burnIntentSignature,
            });
          }
          console.log("Signed burn intents.");

          // [3] Request the attestation set from Gateway API.
          const response = await fetch(
            "https://gateway-api-testnet.circle.com/v1/transfer",
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: stringifyTypedData(requests),
            },
          );

          if (!response.ok) {
            console.error("Gateway API error status:", response.status);
            console.error(await response.text());
            throw new Error("Gateway API request failed");
          }

          const json = (await response.json()) as {
            attestation: string;
            signature: string;
          };
          console.log("Gateway API response:", JSON.stringify(json, null, 2));

          const { attestation, signature: mintSignature } = json;
          if (!attestation || !mintSignature) {
            throw new Error("Missing attestation or signature in Gateway API response");
          }

          // [4] Set up the Gateway Minter client and remaining accounts.
          const decoded = decodeAttestationSet(attestation);
          const minterProgram = new Program(gatewayMinterIdl, provider);
          const [minterPda] = PublicKey.findProgramAddressSync(
            [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
            minterProgramId,
          );

          const remainingAccounts = decoded.attestations.flatMap((e) => [
            {
              pubkey: findCustodyPda(e.destinationToken, minterProgramId),
              isWritable: true,
              isSigner: false,
            },
            { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
            {
              pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
              isWritable: true,
              isSigner: false,
            },
          ]);

          const attestationBytes = Buffer.from(attestation.slice(2), "hex");
          const signatureBytes = Buffer.from(mintSignature.slice(2), "hex");

          // [5] Mint on Solana with the returned attestation.
          console.log("Minting funds on Solana Devnet...");
          const mintIx = await minterProgram.methods
            .gatewayMint({
              attestation: attestationBytes,
              signature: signatureBytes,
            })
            .accountsPartial({
              gatewayMinter: minterPda,
              destinationCaller: recipientPubkey,
              payer: recipientPubkey,
              systemProgram: SystemProgram.programId,
              tokenProgram: TOKEN_PROGRAM_ID,
            })
            .remainingAccounts(remainingAccounts)
            .instruction();

          const { blockhash, lastValidBlockHeight } =
            await connection.getLatestBlockhash();
          const mintTx = new Transaction();
          mintTx.add(mintIx);
          mintTx.recentBlockhash = blockhash;
          mintTx.feePayer = recipientPubkey;

          const mintSig = await signAndBroadcast(
            client,
            connection,
            mintTx,
            RECIPIENT_ADDRESS,
            "mint",
          );

          await connection.confirmTransaction(
            { signature: mintSig, blockhash, lastValidBlockHeight },
            "confirmed",
          );

          const totalMinted = BigInt(requests.length) * TRANSFER_VALUE;
          console.log(`Minted ${Number(totalMinted) / 1_000_000} USDC`);
          console.log(`Mint transaction hash (Solana Devnet):`, mintSig);
        }

        /* Main invocation */
        main().catch((error) => {
          console.error("\nError:", error);
          process.exit(1);
        });
        ```

        ### 4.10. Run the EVM to Solana transfer script

        Before you run this script, update `.env` so:

        * `DEPOSITOR_ADDRESS` is the source EVM wallet
        * `RECIPIENT_ADDRESS` is the destination Solana wallet

        Then run:

        ```shell theme={null}
        npm run transfer-from-evm -- arc
        ```

        ```shell theme={null}
        npm run transfer-from-evm -- arbitrum base
        ```

        ```shell theme={null}
        npm run transfer-from-evm -- all
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Self-managed">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/)
    * Prepared Solana Devnet wallets (sender and recipient) and have the private key
      pairs exported as JSON arrays

    If you want to try the EVM to Solana transfer, ensure that you've:

    * Prepared an EVM testnet wallet with the private key available
      * Added the
        [supported Testnets](/gateway/references/supported-blockchains#testnet) of
        your choice to your wallet
    * Completed
      [Step 3: Deposit into a unified crosschain balance](/gateway/quickstarts/unified-balance-evm#step-3-deposit-into-a-unified-crosschain-balance-self-managed)
      from the
      [EVM quickstart](/gateway/quickstarts/unified-balance-evm#self-managed)

    ### Add testnet funds to your wallet

    To interact with Gateway, you need test USDC and native tokens in your wallet on
    each chain you deposit from. You also need testnet native tokens on the
    destination chain to call the Gateway Minter contract.

    Use the [Circle Faucet](https://faucet.circle.com/) to get testnet USDC. If you
    have a [Circle Developer Console](https://console.circle.com) account, you can
    use the [Console Faucet](https://console.circle.com/faucet) to get testnet
    native tokens. In addition, the following faucets can also be used to fund your
    wallet with testnet native tokens:

    <Tabs>
      <Tab title="Arc">
        **Faucet:** [Arc Testnet](https://faucet.circle.com) (USDC + native tokens)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `arcTestnet`                                 |
        | USDC address | `0x3600000000000000000000000000000000000000` |
        | Domain ID    | `26`                                         |
      </Tab>

      <Tab title="Avalanche">
        **Faucet:** [Avalanche Fuji](https://core.app/tools/testnet-faucet)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `avalancheFuji`                              |
        | USDC address | `0x5425890298aed601595a70ab815c96711a31bc65` |
        | Domain ID    | `1`                                          |
      </Tab>

      <Tab title="Base">
        **Faucet:** [Base Sepolia](https://www.alchemy.com/faucets/base-sepolia)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `baseSepolia`                                |
        | USDC address | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
        | Domain ID    | `6`                                          |
      </Tab>

      <Tab title="Ethereum">
        **Faucet:** [Ethereum Sepolia](https://cloud.google.com/application/web3/faucet/ethereum/sepolia)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `sepolia`                                    |
        | USDC address | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` |
        | Domain ID    | `0`                                          |
      </Tab>

      <Tab title="Hyperliquid">
        **Faucet:** [Hyperliquid EVM Testnet](https://app.hyperliquid-testnet.xyz/drip)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `hyperliquidEvmTestnet`                      |
        | USDC address | `0x2B3370eE501B4a559b57D449569354196457D8Ab` |
        | Domain ID    | `19`                                         |
      </Tab>

      <Tab title="Sei">
        **Faucet:** [Sei Testnet](https://docs.sei.io/learn/faucet)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `seiTestnet`                                 |
        | USDC address | `0x4fCF1784B31630811181f670Aea7A7bEF803eaED` |
        | Domain ID    | `16`                                         |
      </Tab>

      <Tab title="Solana">
        **Faucet:** [Solana Devnet](https://faucet.solana.com/)

        | Property     | Value                                                   |
        | ------------ | ------------------------------------------------------- |
        | Chain name   | `solanaDevnet` (note that Solana is not EVM-compatible) |
        | USDC address | `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`          |
        | Domain ID    | `5`                                                     |
      </Tab>

      <Tab title="Sonic">
        **Faucet:** [Sonic Testnet](https://testnet.soniclabs.com/account)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `sonicTestnet`                               |
        | USDC address | `0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51` |
        | Domain ID    | `13`                                         |
      </Tab>

      <Tab title="Worldchain">
        **Faucet:** [Worldchain Sepolia](https://www.l2faucet.com/world)

        | Property     | Value                                        |
        | ------------ | -------------------------------------------- |
        | Chain name   | `worldchainSepolia`                          |
        | USDC address | `0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88` |
        | Domain ID    | `14`                                         |
      </Tab>
    </Tabs>

    ## Step 1: Set up your project

    This step shows you how to prepare your project and environment.

    ### 1.1. Create a new project

    Create a new directory and install the required dependencies:

    ```shell theme={null}
    # Set up your directory and initialize a Node.js project
    mkdir unified-gateway-balance-sol
    cd unified-gateway-balance-sol
    npm init -y

    # Set up module type and run scripts
    npm pkg set type=module
    npm pkg set scripts.deposit="tsx --env-file=.env deposit.ts"
    npm pkg set scripts.transfer-from-sol="tsx --env-file=.env transfer-from-sol.ts"
    npm pkg set scripts.balances="tsx --env-file=.env balances.ts"

    # Install dependencies
    npm pkg set overrides.bigint-buffer=npm:@trufflesuite/bigint-buffer@1.1.10
    npm install @coral-xyz/anchor @solana/buffer-layout @solana/spl-token @solana/web3.js bs58 tsx typescript
    npm install --save-dev @types/node
    ```

    If you want to try the EVM to Solana transfer, add the run script and install
    [Viem](https://viem.sh/) :

    ```shell theme={null}
    npm pkg set scripts.transfer-from-evm="tsx --env-file=.env transfer-from-evm.ts"
    npm install viem
    ```

    ### 1.2. Initialize and configure the project

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3 Configure environment variables

    Open `.env` in your editor and add:

    ```text theme={null}
    SOLANA_PRIVATE_KEYPAIR=YOUR_SOLANA_KEYPAIR_ARRAY
    RECIPIENT_KEYPAIR=YOUR_RECIPIENT_KEYPAIR_ARRAY
    ```

    * `SOLANA_PRIVATE_KEYPAIR` is the Solana wallet keypair as a JSON array for the
      sender wallet.
    * `RECIPIENT_KEYPAIR` is the Solana wallet keypair as a JSON array for the
      recipient wallet.

    <Note>
      If your wallet exports a private key hash instead, you can use `bs58` to convert it:

      ```ts TypeScript theme={null}
      const bytes = bs58.decode({ YOUR_PRIVATE_KEY_HASH });
      console.log(JSON.stringify(Array.from(bytes)));
      ```
    </Note>

    If you want to try the EVM to Solana transfer, also add:

    ```text theme={null}
    EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY
    ```

    * `EVM_PRIVATE_KEY` is the private key for the EVM wallet you use for the EVM
      side of the transfer.

    <Tip>
      Open `.env` in your editor rather than writing values with shell commands, and
      add `.env` to your `.gitignore`. This prevents credentials from leaking into
      your shell history or version control.
    </Tip>

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Set up the configuration file

    This section covers the shared configuration file will be used by both the
    deposit and transfer scripts.

    ### 2.1. Create the configuration file

    ```shell theme={null}
    touch config.ts
    ```

    ### 2.2. Configure Solana settings and Gateway addresses

    Add the Solana-specific configuration, Gateway contract addresses, and account
    setup helper to your `config.ts` file. This includes the RPC endpoint, USDC
    address, domain ID, and the IDL definitions for interacting with Gateway Wallet
    and Gateway Minter programs on Solana Devnet.

    The local IDL fragments in this example are only the subset needed by the sample
    code. For canonical static instruction and account definitions, use the onchain
    IDLs linked from
    [Solana Programs and Interfaces](/gateway/references/solana-programs#account-structures).

    ```ts config.ts expandable theme={null}
    import { Keypair } from "@solana/web3.js";

    /* Solana Configuration */
    export const RPC_ENDPOINT = "https://api.devnet.solana.com";
    export const SOLANA_DOMAIN = 5;
    export const SOLANA_ZERO_ADDRESS = "11111111111111111111111111111111";

    /* Gateway Contract Addresses */
    export const GATEWAY_WALLET_ADDRESS =
      "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
    export const GATEWAY_MINTER_ADDRESS =
      "GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr";
    export const USDC_ADDRESS = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";

    /* Account Setup Helper */
    export function createKeypairFromEnv(privateKey: string): Keypair {
      const secretKey = JSON.parse(privateKey);
      return Keypair.fromSecretKey(Uint8Array.from(secretKey));
    }

    /* Sample-local Gateway Wallet IDL subset used by this runnable example. */
    export const gatewayWalletIdl = {
      address: GATEWAY_WALLET_ADDRESS,
      metadata: {
        name: "gatewayWallet",
        version: "0.1.0",
        spec: "0.1.0",
      },
      instructions: [
        {
          name: "deposit",
          discriminator: [22, 0],
          accounts: [
            { name: "payer", writable: true, signer: true },
            { name: "owner", signer: true },
            { name: "gatewayWallet" },
            { name: "ownerTokenAccount", writable: true },
            { name: "custodyTokenAccount", writable: true },
            { name: "deposit", writable: true },
            { name: "depositorDenylist" },
            { name: "tokenProgram" },
            { name: "systemProgram" },
            { name: "eventAuthority" },
            { name: "program" },
          ],
          args: [{ name: "amount", type: "u64" }],
        },
      ],
    };

    /* Sample-local Gateway Minter IDL subset used by this runnable example. */
    export const gatewayMinterIdl = {
      address: GATEWAY_MINTER_ADDRESS,
      metadata: { name: "gatewayMinter", version: "0.1.0", spec: "0.1.0" },
      instructions: [
        {
          name: "gatewayMint",
          discriminator: [12, 0],
          accounts: [
            { name: "payer", writable: true, signer: true },
            { name: "destinationCaller", signer: true },
            { name: "gatewayMinter" },
            { name: "systemProgram" },
            { name: "tokenProgram" },
            { name: "eventAuthority" },
            { name: "program" },
          ],
          args: [
            { name: "params", type: { defined: { name: "gatewayMintParams" } } },
          ],
        },
      ],
      types: [
        {
          name: "gatewayMintParams",
          type: {
            kind: "struct",
            fields: [
              { name: "attestation", type: "bytes" },
              { name: "signature", type: "bytes" },
            ],
          },
        },
      ],
    };
    ```

    ## Step 3: Deposit into a unified crosschain balance (Self-managed)

    This section explains parts of the deposit script that allows you to deposit
    USDC into the Gateway Wallet contract on Solana Devnet. You can skip to the
    [full deposit script](#3-5-full-deposit-script-self-managed) if you prefer.

    ### 3.1. Create the script file

    ```shell theme={null}
    touch deposit.ts
    ```

    ### 3.2. Define constants and helpers

    You can adjust the `DEPOSIT_AMOUNT` to a different value. For now, it is set to
    10 USDC.

    ```ts deposit.ts theme={null}
    const DEPOSIT_AMOUNT = new BN(10000000); // 10 USDC (6 decimals)

    /* Helpers */
    function findPDAs(programId: PublicKey, usdcMint: PublicKey, owner: PublicKey) {
      return {
        wallet: PublicKey.findProgramAddressSync(
          [Buffer.from(utils.bytes.utf8.encode("gateway_wallet"))],
          programId,
        )[0],
        custody: PublicKey.findProgramAddressSync(
          [
            Buffer.from(utils.bytes.utf8.encode("gateway_wallet_custody")),
            usdcMint.toBuffer(),
          ],
          programId,
        )[0],
        deposit: PublicKey.findProgramAddressSync(
          [Buffer.from("gateway_deposit"), usdcMint.toBuffer(), owner.toBuffer()],
          programId,
        )[0],
        denylist: PublicKey.findProgramAddressSync(
          [Buffer.from("denylist"), owner.toBuffer()],
          programId,
        )[0],
      };
    }
    ```

    ### 3.3. Initialize connection, Anchor client, and validate balance

    Initialize the Solana connection and keypair, set up the Anchor client with
    Program Derived Addresses (PDAs) for interacting with the Gateway Wallet
    contract, then verify sufficient USDC balance before depositing.

    ```ts deposit.ts theme={null}
    const keypair = createKeypairFromEnv(process.env.SOLANA_PRIVATE_KEYPAIR);
    const connection = new Connection(RPC_ENDPOINT, "confirmed");
    const programId = new PublicKey(GATEWAY_WALLET_ADDRESS);
    const usdcMint = new PublicKey(USDC_ADDRESS);

    console.log(`Using account: ${keypair.publicKey.toBase58()}`);

    // Check USDC balance
    const userAta = await getAssociatedTokenAddress(usdcMint, keypair.publicKey);
    const ataInfo = await getAccount(connection, userAta);
    const currentBalance = ataInfo.amount;

    console.log(
      `Current balance: ${Number(currentBalance.toString()) / 1_000_000} USDC`,
    );

    if (currentBalance < BigInt(DEPOSIT_AMOUNT.toString())) {
      throw new Error(
        `Insufficient USDC balance! Please top up at https://faucet.circle.com`,
      );
    }

    const pdas = findPDAs(programId, usdcMint, keypair.publicKey);

    const anchorWallet = new Wallet(keypair);
    const provider = new AnchorProvider(
      connection,
      anchorWallet,
      AnchorProvider.defaultOptions(),
    );
    setProvider(provider);
    const program = new Program(gatewayWalletIdl, provider);
    ```

    ### 3.4. Execute the deposit

    ```ts deposit.ts theme={null}
    const txHash = await program.methods
      .deposit(DEPOSIT_AMOUNT)
      .accountsPartial({
        payer: keypair.publicKey,
        owner: keypair.publicKey,
        gatewayWallet: pdas.wallet,
        ownerTokenAccount: userAta,
        custodyTokenAccount: pdas.custody,
        deposit: pdas.deposit,
        depositorDenylist: pdas.denylist,
        tokenProgram: TOKEN_PROGRAM_ID,
        systemProgram: SystemProgram.programId,
      })
      .signers([keypair])
      .rpc();

    console.log(`Done on Solana Devnet. Deposit tx: ${txHash}`);
    ```

    ### 3.5. Full deposit script (Self-managed)

    The complete deposit script initializes the Solana connection and Anchor client,
    validates the USDC balance, and deposits funds into the Gateway Wallet contract
    on Solana Devnet. The script includes inline comments to explain what each
    function does, making it easier to follow and modify if needed.

    ```ts deposit.ts expandable theme={null}
    import {
      Wallet,
      AnchorProvider,
      setProvider,
      Program,
      utils,
    } from "@coral-xyz/anchor";
    import { Connection, PublicKey, SystemProgram } from "@solana/web3.js";
    import {
      getAssociatedTokenAddress,
      getAccount,
      TOKEN_PROGRAM_ID,
    } from "@solana/spl-token";
    import BN from "bn.js";
    import {
      RPC_ENDPOINT,
      GATEWAY_WALLET_ADDRESS,
      USDC_ADDRESS,
      createKeypairFromEnv,
      gatewayWalletIdl,
    } from "./config.js";

    const DEPOSIT_AMOUNT = new BN(10000000); // 10 USDC (6 decimals)

    /* Helpers */
    function findPDAs(programId: PublicKey, usdcMint: PublicKey, owner: PublicKey) {
      return {
        wallet: PublicKey.findProgramAddressSync(
          [Buffer.from(utils.bytes.utf8.encode("gateway_wallet"))],
          programId,
        )[0],
        custody: PublicKey.findProgramAddressSync(
          [
            Buffer.from(utils.bytes.utf8.encode("gateway_wallet_custody")),
            usdcMint.toBuffer(),
          ],
          programId,
        )[0],
        deposit: PublicKey.findProgramAddressSync(
          [Buffer.from("gateway_deposit"), usdcMint.toBuffer(), owner.toBuffer()],
          programId,
        )[0],
        denylist: PublicKey.findProgramAddressSync(
          [Buffer.from("denylist"), owner.toBuffer()],
          programId,
        )[0],
      };
    }

    /* Main logic */
    async function main() {
      if (!process.env.SOLANA_PRIVATE_KEYPAIR) {
        throw new Error("SOLANA_PRIVATE_KEYPAIR not set in environment");
      }

      const keypair = createKeypairFromEnv(process.env.SOLANA_PRIVATE_KEYPAIR);
      const connection = new Connection(RPC_ENDPOINT, "confirmed");
      const programId = new PublicKey(GATEWAY_WALLET_ADDRESS);
      const usdcMint = new PublicKey(USDC_ADDRESS);

      console.log(`Using account: ${keypair.publicKey.toBase58()}`);

      console.log(`\n=== Processing Solana Devnet ===`);

      // Check USDC balance
      const userAta = await getAssociatedTokenAddress(usdcMint, keypair.publicKey);
      const ataInfo = await getAccount(connection, userAta);
      const currentBalance = ataInfo.amount;

      console.log(
        `Current balance: ${Number(currentBalance.toString()) / 1_000_000} USDC`,
      );

      if (currentBalance < BigInt(DEPOSIT_AMOUNT.toString())) {
        throw new Error(
          `Insufficient USDC balance! Please top up at https://faucet.circle.com`,
        );
      }

      console.log(
        `Depositing ${Number(DEPOSIT_AMOUNT.toString()) / 1_000_000} USDC to Gateway Wallet`,
      );

      // Set up Anchor client
      const pdas = findPDAs(programId, usdcMint, keypair.publicKey);

      const anchorWallet = new Wallet(keypair);
      const provider = new AnchorProvider(
        connection,
        anchorWallet,
        AnchorProvider.defaultOptions(),
      );
      setProvider(provider);
      const program = new Program(gatewayWalletIdl, provider);

      // Execute deposit
      const txHash = await program.methods
        .deposit(DEPOSIT_AMOUNT)
        .accountsPartial({
          payer: keypair.publicKey,
          owner: keypair.publicKey,
          gatewayWallet: pdas.wallet,
          ownerTokenAccount: userAta,
          custodyTokenAccount: pdas.custody,
          deposit: pdas.deposit,
          depositorDenylist: pdas.denylist,
          tokenProgram: TOKEN_PROGRAM_ID,
          systemProgram: SystemProgram.programId,
        })
        .signers([keypair])
        .rpc();

      console.log(`Done on Solana Devnet. Deposit tx: ${txHash}`);
    }

    main().catch((error) => {
      console.error("\nError:", error);
      process.exit(1);
    });
    ```

    ### 3.6. Run the script to create a crosschain balance

    Run the deposit script to deposit USDC into your Gateway balance on Solana
    Devnet.

    ```shell theme={null}
    npm run deposit
    ```

    Wait for the required number of block confirmations. Once the deposit
    transaction is final, your Gateway balance on Solana Devnet will be updated.
    Solana Devnet transactions typically reach finality in seconds.

    ### 3.7. Check the balances on the Gateway Wallet

    Create a new file called `balances.ts`, and add the following code. This script
    retrieves the USDC balances available from your Gateway Wallet on Solana Devnet.

    ```ts balances.ts expandable theme={null}
    import { Keypair } from "@solana/web3.js";

    /* Constants */
    const SOLANA_DOMAIN = 5;

    /* Helpers */
    function createKeypairFromEnv(privateKey: string): Keypair {
      const secretKey = JSON.parse(privateKey);
      return Keypair.fromSecretKey(Uint8Array.from(secretKey));
    }

    async function main() {
      if (!process.env.SOLANA_PRIVATE_KEYPAIR) {
        throw new Error("SOLANA_PRIVATE_KEYPAIR not set in environment");
      }

      const keypair = createKeypairFromEnv(process.env.SOLANA_PRIVATE_KEYPAIR);
      const depositor = keypair.publicKey.toBase58();

      console.log(`Depositor address: ${depositor}\n`);

      const body = {
        token: "USDC",
        sources: [{ domain: SOLANA_DOMAIN, depositor }],
      };

      const res = await fetch(
        "https://gateway-api-testnet.circle.com/v1/balances",
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(body),
        },
      );

      const result = await res.json();

      for (const balance of result.balances) {
        const amount = parseFloat(balance.balance);
        console.log(`solanaDevnet: ${amount.toFixed(6)} USDC`);
      }
    }

    main().catch((error) => {
      console.error("\nError:", error);
      process.exit(1);
    });
    ```

    You can run it to verify your balance on Gateway.

    ```shell theme={null}
    npm run balances
    ```

    <Tabs>
      <Tab title="Transfer from Solana">
        ## Step 4: Transfer USDC from the crosschain balance

        This section explains parts of the transfer script that burns USDC from your
        Solana Devnet Gateway balance to a recipient on Solana Devnet via Gateway. You
        can skip to the
        [full transfer script](#4-9-full-solana-transfer-script-self-managed) if you
        prefer.

        ### 4.1. Create the script file

        ```shell theme={null}
        touch transfer-from-sol.ts
        ```

        ### 4.2. Define constants and types

        You can set the amount to be transferred from your Gateway balance by changing
        the `TRANSFER_AMOUNT`. For now, it is set to 1 USDC.

        ```ts transfer-from-sol.ts expandable theme={null}
        const TRANSFER_AMOUNT = 1; // 1 USDC
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;

        const TRANSFER_SPEC_MAGIC = 0xca85def7;
        const BURN_INTENT_MAGIC = 0x070afbc2;

        /* Type definitions */
        // Custom layout for Solana PublicKey (32 bytes)
        class PublicKeyLayout extends Layout<PublicKey> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0): PublicKey {
            return new PublicKey(b.subarray(offset, offset + 32));
          }
          encode(src: PublicKey, b: Buffer, offset = 0): number {
            const pubkeyBuffer = src.toBuffer();
            pubkeyBuffer.copy(b, offset);
            return 32;
          }
        }

        const publicKey = (property: string) => new PublicKeyLayout(property);

        // Custom layout for 256-bit unsigned integers
        class UInt256BE extends Layout<bigint> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0) {
            const buffer = b.subarray(offset, offset + 32);
            return buffer.readBigUInt64BE(24);
          }
          encode(src: bigint, b: Buffer, offset = 0) {
            const buffer = Buffer.alloc(32);
            buffer.writeBigUInt64BE(BigInt(src), 24);
            buffer.copy(b, offset);
            return 32;
          }
        }

        const uint256be = (property: string) => new UInt256BE(property);

        // Type 'as any' used due to @solana/buffer-layout's incomplete TypeScript definitions (archived Jan 2025)
        const BurnIntentLayout = struct([
          u32be("magic"),
          uint256be("maxBlockHeight"),
          uint256be("maxFee"),
          u32be("transferSpecLength"),
          struct(
            [
              u32be("magic"),
              u32be("version"),
              u32be("sourceDomain"),
              u32be("destinationDomain"),
              publicKey("sourceContract"),
              publicKey("destinationContract"),
              publicKey("sourceToken"),
              publicKey("destinationToken"),
              publicKey("sourceDepositor"),
              publicKey("destinationRecipient"),
              publicKey("sourceSigner"),
              publicKey("destinationCaller"),
              uint256be("value"),
              blob(32, "salt"),
              u32be("hookDataLength"),
              blob(offset(u32be(), -4), "hookData"),
            ] as any,
            "spec",
          ),
        ] as any);

        const MintAttestationElementLayout = struct([
          publicKey("destinationToken"),
          publicKey("destinationRecipient"),
          nu64be("value"),
          blob(32, "transferSpecHash"),
          u32be("hookDataLength"),
          blob(offset(u32be(), -4), "hookData"),
        ] as any);

        const MintAttestationSetLayout = struct([
          u32be("magic"),
          u32be("version"),
          u32be("destinationDomain"),
          publicKey("destinationContract"),
          publicKey("destinationCaller"),
          nu64be("maxBlockHeight"),
          u32be("numAttestations"),
          seq(MintAttestationElementLayout, offset(u32be(), -4), "attestations"),
        ] as any);
        ```

        ### 4.3. Add helper functions

        ```ts transfer-from-sol.ts expandable theme={null}
        // Construct burn intent for a given source
        function createBurnIntent(params: {
          sourceDepositor: string;
          destinationRecipient: string;
          sourceSigner: string;
        }) {
          const { sourceDepositor, destinationRecipient, sourceSigner } = params;

          return {
            maxBlockHeight: MAX_UINT64,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: SOLANA_DOMAIN,
              destinationDomain: SOLANA_DOMAIN,
              sourceContract: addressToBytes32(GATEWAY_WALLET_ADDRESS),
              destinationContract: addressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: addressToBytes32(USDC_ADDRESS),
              destinationToken: addressToBytes32(USDC_ADDRESS),
              sourceDepositor: addressToBytes32(sourceDepositor),
              destinationRecipient: addressToBytes32(destinationRecipient),
              sourceSigner: addressToBytes32(sourceSigner),
              destinationCaller: addressToBytes32(SOLANA_ZERO_ADDRESS),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Encode burn intent as binary layout for signing
        function encodeBurnIntent(bi: any): Buffer {
          const hookData = Buffer.from((bi.spec.hookData || "0x").slice(2), "hex");
          const prepared = {
            magic: BURN_INTENT_MAGIC,
            maxBlockHeight: bi.maxBlockHeight,
            maxFee: bi.maxFee,
            transferSpecLength: 340 + hookData.length,
            spec: {
              magic: TRANSFER_SPEC_MAGIC,
              version: bi.spec.version,
              sourceDomain: bi.spec.sourceDomain,
              destinationDomain: bi.spec.destinationDomain,
              sourceContract: hexToPublicKey(bi.spec.sourceContract),
              destinationContract: hexToPublicKey(bi.spec.destinationContract),
              sourceToken: hexToPublicKey(bi.spec.sourceToken),
              destinationToken: hexToPublicKey(bi.spec.destinationToken),
              sourceDepositor: hexToPublicKey(bi.spec.sourceDepositor),
              destinationRecipient: hexToPublicKey(bi.spec.destinationRecipient),
              sourceSigner: hexToPublicKey(bi.spec.sourceSigner),
              destinationCaller: hexToPublicKey(bi.spec.destinationCaller),
              value: bi.spec.value,
              salt: Buffer.from(bi.spec.salt.slice(2), "hex"),
              hookDataLength: hookData.length,
              hookData,
            },
          };
          const buffer = Buffer.alloc(72 + 340 + hookData.length);
          const bytesWritten = BurnIntentLayout.encode(prepared, buffer);
          return buffer.subarray(0, bytesWritten);
        }

        // Sign burn intent with Ed25519 keypair
        function signBurnIntent(keypair: Keypair, payload: any): string {
          const encoded = encodeBurnIntent(payload);
          const prefixed = Buffer.concat([
            Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
            encoded,
          ]);
          const privateKey = crypto.createPrivateKey({
            key: Buffer.concat([
              Buffer.from("302e020100300506032b657004220420", "hex"),
              Buffer.from(keypair.secretKey.slice(0, 32)),
            ]),
            format: "der",
            type: "pkcs8",
          });
          return `0x${crypto.sign(null, prefixed, privateKey).toString("hex")}`;
        }

        // Convert Solana address to 32-byte hex string
        function addressToBytes32(address: string): string {
          const decoded = Buffer.from(bs58.decode(address));
          return `0x${decoded.toString("hex")}`;
        }

        // Convert hex string to Solana PublicKey
        function hexToPublicKey(hex: string): PublicKey {
          return new PublicKey(Buffer.from(hex.slice(2), "hex"));
        }

        // Decode attestation set from Gateway API response
        function decodeAttestationSet(attestation: string) {
          const buffer = Buffer.from(attestation.slice(2), "hex");
          return MintAttestationSetLayout.decode(buffer) as {
            attestations: Array<{
              destinationToken: PublicKey;
              destinationRecipient: PublicKey;
              transferSpecHash: Uint8Array;
            }>;
          };
        }

        // Find PDA for token custody account
        function findCustodyPda(
          mint: PublicKey,
          minterProgramId: PublicKey,
        ): PublicKey {
          return PublicKey.findProgramAddressSync(
            [Buffer.from("gateway_minter_custody"), mint.toBuffer()],
            minterProgramId,
          )[0];
        }

        // Find PDA for transfer spec hash tracking
        function findTransferSpecHashPda(
          transferSpecHash: Uint8Array | Buffer,
          minterProgramId: PublicKey,
        ): PublicKey {
          return PublicKey.findProgramAddressSync(
            [Buffer.from("used_transfer_spec_hash"), Buffer.from(transferSpecHash)],
            minterProgramId,
          )[0];
        }
        ```

        ### 4.4. Initialize connection and create recipient ATA

        Initialize the Solana connection and keypairs, then create the recipient's
        Associated Token Account (ATA) for receiving USDC on the destination chain.

        <Info>
          For transfers to Solana, the `destinationRecipient` must be an initialized
          USDC Token Account. If the intended recipient is a standard wallet address,
          consider setting the `destinationRecipient` to its Associated Token Account
          (ATA) not the recipient wallet address. See the [Solana Technical
          Guide](/gateway/references/solana#reducedmintattestation) and [Solana Programs
          and Interfaces](/gateway/references/solana-programs#gatewaymint) for
          high-level Solana guidance and `gatewayMint` account requirements. Use the
          onchain IDLs linked from [Solana Programs and
          Interfaces](/gateway/references/solana-programs#account-structures) as the
          canonical static instruction and account definitions.
        </Info>

        ```ts transfer-from-sol.ts theme={null}
        const senderKeypair = createKeypairFromEnv(process.env.SOLANA_PRIVATE_KEYPAIR);
        const recipientKeypair = createKeypairFromEnv(process.env.RECIPIENT_KEYPAIR);
        const connection = new Connection(RPC_ENDPOINT, "confirmed");
        const usdcMint = new PublicKey(USDC_ADDRESS);

        console.log(`Using account: ${senderKeypair.publicKey.toBase58()}`);
        console.log(`Transferring balances from: Solana Devnet`);

        // Create recipient's Associated Token Account
        const recipientAta = getAssociatedTokenAddressSync(
          usdcMint,
          recipientKeypair.publicKey,
        );

        const createAtaIx = createAssociatedTokenAccountIdempotentInstruction(
          senderKeypair.publicKey,
          recipientAta,
          recipientKeypair.publicKey,
          usdcMint,
        );
        const tx = new Transaction().add(createAtaIx);
        await sendAndConfirmTransaction(connection, tx, [senderKeypair]);
        ```

        ### 4.5. Create and sign burn intent

        ```ts transfer-from-sol.ts theme={null}
        const burnIntent = createBurnIntent({
          sourceDepositor: senderKeypair.publicKey.toBase58(),
          destinationRecipient: recipientAta.toBase58(),
          sourceSigner: senderKeypair.publicKey.toBase58(),
        });

        const burnIntentSignature = signBurnIntent(senderKeypair, burnIntent);
        const request = [{ burnIntent, signature: burnIntentSignature }];
        console.log("Signed burn intent.");
        ```

        ### 4.6. Request attestation from Gateway API

        ```ts transfer-from-sol.ts theme={null}
        const response = await fetch(
          "https://gateway-api-testnet.circle.com/v1/transfer",
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(request, (_key, value) =>
              typeof value === "bigint" ? value.toString() : value,
            ),
          },
        );

        const json = await response.json();
        if (json.success === false) {
          throw new Error(`Gateway API error: ${json.message}`);
        }
        console.log("Gateway API response:", JSON.stringify(json, null, 2));

        const { attestation, signature: mintSignature } = json;
        const decoded = decodeAttestationSet(attestation);
        ```

        ### 4.7. Set up minter client

        ```ts transfer-from-sol.ts theme={null}
        const minterProgramId = new PublicKey(GATEWAY_MINTER_ADDRESS);
        const anchorWallet = new Wallet(senderKeypair);
        const provider = new AnchorProvider(
          connection,
          anchorWallet,
          AnchorProvider.defaultOptions(),
        );
        setProvider(provider);
        const minterProgram = new Program(gatewayMinterIdl, provider);

        const [minterPda] = PublicKey.findProgramAddressSync(
          [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
          minterProgramId,
        );
        ```

        <Info>
          The ordered remaining-account list and PDA derivations are documented in
          [Solana Programs and
          Interfaces](/gateway/references/solana-programs#gatewaymint). For static
          instruction definitions, use the onchain IDLs linked from that page.
        </Info>

        ### 4.8. Mint on Solana

        ```ts transfer-from-sol.ts expandable theme={null}
        const remainingAccounts = decoded.attestations.flatMap((e) => [
          {
            pubkey: findCustodyPda(e.destinationToken, minterProgramId),
            isWritable: true,
            isSigner: false,
          },
          { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
          {
            pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
            isWritable: true,
            isSigner: false,
          },
        ]);

        const attestationBytes = Buffer.from(attestation.slice(2), "hex");
        const signatureBytes = Buffer.from(mintSignature.slice(2), "hex");

        console.log("Minting funds on Solana Devnet...");
        const mintTx = await minterProgram.methods
          .gatewayMint({ attestation: attestationBytes, signature: signatureBytes })
          .accountsPartial({
            gatewayMinter: minterPda,
            destinationCaller: senderKeypair.publicKey,
            payer: senderKeypair.publicKey,
            systemProgram: SystemProgram.programId,
            tokenProgram: TOKEN_PROGRAM_ID,
          })
          .remainingAccounts(remainingAccounts)
          .signers([senderKeypair])
          .rpc();

        // [6] Wait for confirmation
        const latest = await connection.getLatestBlockhash();
        await connection.confirmTransaction(
          {
            signature: mintTx,
            blockhash: latest.blockhash,
            lastValidBlockHeight: latest.lastValidBlockHeight,
          },
          "confirmed",
        );

        console.log(`Minted ${Number(TRANSFER_VALUE) / 1_000_000} USDC`);
        console.log(`Mint transaction hash (solanaDevnet):`, mintTx);
        ```

        ### 4.9. Full Solana transfer script (Self-managed)

        The complete transfer script creates and signs a burn intent on Solana Devnet,
        submits it to the Gateway API for attestation, and mints USDC on Solana Devnet
        for the recipient. The script includes inline comments to explain what each
        function does, making it easier to follow and modify if needed.

        ```ts transfer-from-sol.ts expandable theme={null}
        import { randomBytes } from "node:crypto";
        import * as crypto from "crypto";
        import {
          Wallet,
          AnchorProvider,
          setProvider,
          Program,
          utils,
        } from "@coral-xyz/anchor";
        import {
          Connection,
          Keypair,
          PublicKey,
          SystemProgram,
          Transaction,
          sendAndConfirmTransaction,
        } from "@solana/web3.js";
        import {
          TOKEN_PROGRAM_ID,
          getAssociatedTokenAddressSync,
          createAssociatedTokenAccountIdempotentInstruction,
        } from "@solana/spl-token";
        import {
          u32be,
          nu64be,
          struct,
          seq,
          blob,
          offset,
          Layout,
        } from "@solana/buffer-layout";
        import bs58 from "bs58";
        import {
          RPC_ENDPOINT,
          GATEWAY_WALLET_ADDRESS,
          GATEWAY_MINTER_ADDRESS,
          USDC_ADDRESS,
          SOLANA_DOMAIN,
          SOLANA_ZERO_ADDRESS,
          createKeypairFromEnv,
          gatewayMinterIdl,
        } from "./config.js";

        const TRANSFER_AMOUNT = 1; // 1 USDC
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;

        const TRANSFER_SPEC_MAGIC = 0xca85def7;
        const BURN_INTENT_MAGIC = 0x070afbc2;

        /* Type definitions */
        // Custom layout for Solana PublicKey (32 bytes)
        class PublicKeyLayout extends Layout<PublicKey> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0): PublicKey {
            return new PublicKey(b.subarray(offset, offset + 32));
          }
          encode(src: PublicKey, b: Buffer, offset = 0): number {
            const pubkeyBuffer = src.toBuffer();
            pubkeyBuffer.copy(b, offset);
            return 32;
          }
        }

        const publicKey = (property: string) => new PublicKeyLayout(property);

        // Custom layout for 256-bit unsigned integers
        class UInt256BE extends Layout<bigint> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0) {
            const buffer = b.subarray(offset, offset + 32);
            return buffer.readBigUInt64BE(24);
          }
          encode(src: bigint, b: Buffer, offset = 0) {
            const buffer = Buffer.alloc(32);
            buffer.writeBigUInt64BE(BigInt(src), 24);
            buffer.copy(b, offset);
            return 32;
          }
        }

        const uint256be = (property: string) => new UInt256BE(property);

        // Type 'as any' used due to @solana/buffer-layout's incomplete TypeScript definitions (archived Jan 2025)
        const BurnIntentLayout = struct([
          u32be("magic"),
          uint256be("maxBlockHeight"),
          uint256be("maxFee"),
          u32be("transferSpecLength"),
          struct(
            [
              u32be("magic"),
              u32be("version"),
              u32be("sourceDomain"),
              u32be("destinationDomain"),
              publicKey("sourceContract"),
              publicKey("destinationContract"),
              publicKey("sourceToken"),
              publicKey("destinationToken"),
              publicKey("sourceDepositor"),
              publicKey("destinationRecipient"),
              publicKey("sourceSigner"),
              publicKey("destinationCaller"),
              uint256be("value"),
              blob(32, "salt"),
              u32be("hookDataLength"),
              blob(offset(u32be(), -4), "hookData"),
            ] as any,
            "spec",
          ),
        ] as any);

        const MintAttestationElementLayout = struct([
          publicKey("destinationToken"),
          publicKey("destinationRecipient"),
          nu64be("value"),
          blob(32, "transferSpecHash"),
          u32be("hookDataLength"),
          blob(offset(u32be(), -4), "hookData"),
        ] as any);

        const MintAttestationSetLayout = struct([
          u32be("magic"),
          u32be("version"),
          u32be("destinationDomain"),
          publicKey("destinationContract"),
          publicKey("destinationCaller"),
          nu64be("maxBlockHeight"),
          u32be("numAttestations"),
          seq(MintAttestationElementLayout, offset(u32be(), -4), "attestations"),
        ] as any);

        /* Helpers */
        // Construct burn intent for a given source
        function createBurnIntent(params: {
          sourceDepositor: string;
          destinationRecipient: string;
          sourceSigner: string;
        }) {
          const { sourceDepositor, destinationRecipient, sourceSigner } = params;

          return {
            maxBlockHeight: MAX_UINT64,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: SOLANA_DOMAIN,
              destinationDomain: SOLANA_DOMAIN,
              sourceContract: addressToBytes32(GATEWAY_WALLET_ADDRESS),
              destinationContract: addressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: addressToBytes32(USDC_ADDRESS),
              destinationToken: addressToBytes32(USDC_ADDRESS),
              sourceDepositor: addressToBytes32(sourceDepositor),
              destinationRecipient: addressToBytes32(destinationRecipient),
              sourceSigner: addressToBytes32(sourceSigner),
              destinationCaller: addressToBytes32(SOLANA_ZERO_ADDRESS),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Encode burn intent as binary layout for signing
        function encodeBurnIntent(bi: any): Buffer {
          const hookData = Buffer.from((bi.spec.hookData || "0x").slice(2), "hex");
          const prepared = {
            magic: BURN_INTENT_MAGIC,
            maxBlockHeight: bi.maxBlockHeight,
            maxFee: bi.maxFee,
            transferSpecLength: 340 + hookData.length,
            spec: {
              magic: TRANSFER_SPEC_MAGIC,
              version: bi.spec.version,
              sourceDomain: bi.spec.sourceDomain,
              destinationDomain: bi.spec.destinationDomain,
              sourceContract: hexToPublicKey(bi.spec.sourceContract),
              destinationContract: hexToPublicKey(bi.spec.destinationContract),
              sourceToken: hexToPublicKey(bi.spec.sourceToken),
              destinationToken: hexToPublicKey(bi.spec.destinationToken),
              sourceDepositor: hexToPublicKey(bi.spec.sourceDepositor),
              destinationRecipient: hexToPublicKey(bi.spec.destinationRecipient),
              sourceSigner: hexToPublicKey(bi.spec.sourceSigner),
              destinationCaller: hexToPublicKey(bi.spec.destinationCaller),
              value: bi.spec.value,
              salt: Buffer.from(bi.spec.salt.slice(2), "hex"),
              hookDataLength: hookData.length,
              hookData,
            },
          };
          const buffer = Buffer.alloc(72 + 340 + hookData.length);
          const bytesWritten = BurnIntentLayout.encode(prepared, buffer);
          return buffer.subarray(0, bytesWritten);
        }

        // Sign burn intent with Ed25519 keypair
        function signBurnIntent(keypair: Keypair, payload: any): string {
          const encoded = encodeBurnIntent(payload);
          const prefixed = Buffer.concat([
            Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
            encoded,
          ]);
          const privateKey = crypto.createPrivateKey({
            key: Buffer.concat([
              Buffer.from("302e020100300506032b657004220420", "hex"),
              Buffer.from(keypair.secretKey.slice(0, 32)),
            ]),
            format: "der",
            type: "pkcs8",
          });
          return `0x${crypto.sign(null, prefixed, privateKey).toString("hex")}`;
        }

        // Convert Solana address to 32-byte hex string
        function addressToBytes32(address: string): string {
          const decoded = Buffer.from(bs58.decode(address));
          return `0x${decoded.toString("hex")}`;
        }

        // Convert hex string to Solana PublicKey
        function hexToPublicKey(hex: string): PublicKey {
          return new PublicKey(Buffer.from(hex.slice(2), "hex"));
        }

        // Decode attestation set from Gateway API response
        function decodeAttestationSet(attestation: string) {
          const buffer = Buffer.from(attestation.slice(2), "hex");
          return MintAttestationSetLayout.decode(buffer) as {
            attestations: Array<{
              destinationToken: PublicKey;
              destinationRecipient: PublicKey;
              transferSpecHash: Uint8Array;
            }>;
          };
        }

        // Find PDA for token custody account
        function findCustodyPda(
          mint: PublicKey,
          minterProgramId: PublicKey,
        ): PublicKey {
          return PublicKey.findProgramAddressSync(
            [Buffer.from("gateway_minter_custody"), mint.toBuffer()],
            minterProgramId,
          )[0];
        }

        // Find PDA for transfer spec hash tracking
        function findTransferSpecHashPda(
          transferSpecHash: Uint8Array | Buffer,
          minterProgramId: PublicKey,
        ): PublicKey {
          return PublicKey.findProgramAddressSync(
            [Buffer.from("used_transfer_spec_hash"), Buffer.from(transferSpecHash)],
            minterProgramId,
          )[0];
        }

        /* Main logic */
        async function main() {
          if (!process.env.SOLANA_PRIVATE_KEYPAIR || !process.env.RECIPIENT_KEYPAIR) {
            throw new Error("SOLANA_PRIVATE_KEYPAIR and RECIPIENT_KEYPAIR must be set");
          }

          const senderKeypair = createKeypairFromEnv(
            process.env.SOLANA_PRIVATE_KEYPAIR,
          );
          const recipientKeypair = createKeypairFromEnv(process.env.RECIPIENT_KEYPAIR);
          const connection = new Connection(RPC_ENDPOINT, "confirmed");
          const usdcMint = new PublicKey(USDC_ADDRESS);

          console.log(`Using account: ${senderKeypair.publicKey.toBase58()}`);
          console.log(`Transferring balances from: Solana Devnet`);

          // [1] Create recipient's Associated Token Account
          const recipientAta = getAssociatedTokenAddressSync(
            usdcMint,
            recipientKeypair.publicKey,
          );

          const createAtaIx = createAssociatedTokenAccountIdempotentInstruction(
            senderKeypair.publicKey,
            recipientAta,
            recipientKeypair.publicKey,
            usdcMint,
          );
          const tx = new Transaction().add(createAtaIx);
          await sendAndConfirmTransaction(connection, tx, [senderKeypair]);

          // [2] Create and sign burn intent
          console.log(`Creating burn intent from Solana Devnet → Solana Devnet...`);
          const burnIntent = createBurnIntent({
            sourceDepositor: senderKeypair.publicKey.toBase58(),
            destinationRecipient: recipientAta.toBase58(),
            sourceSigner: senderKeypair.publicKey.toBase58(),
          });

          const burnIntentSignature = signBurnIntent(senderKeypair, burnIntent);
          const request = [{ burnIntent, signature: burnIntentSignature }];
          console.log("Signed burn intent.");

          // [3] Request attestation from Gateway API
          const response = await fetch(
            "https://gateway-api-testnet.circle.com/v1/transfer",
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: JSON.stringify(request, (_key, value) =>
                typeof value === "bigint" ? value.toString() : value,
              ),
            },
          );

          const json = await response.json();
          if (json.success === false) {
            throw new Error(`Gateway API error: ${json.message}`);
          }
          console.log("Gateway API response:", JSON.stringify(json, null, 2));

          const { attestation, signature: mintSignature } = json;
          const decoded = decodeAttestationSet(attestation);

          // [4] Set up the minter client
          const minterProgramId = new PublicKey(GATEWAY_MINTER_ADDRESS);
          const anchorWallet = new Wallet(senderKeypair);
          const provider = new AnchorProvider(
            connection,
            anchorWallet,
            AnchorProvider.defaultOptions(),
          );
          setProvider(provider);
          const minterProgram = new Program(gatewayMinterIdl, provider);

          const [minterPda] = PublicKey.findProgramAddressSync(
            [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
            minterProgramId,
          );

          // [5] Mint on Solana
          const remainingAccounts = decoded.attestations.flatMap((e) => [
            {
              pubkey: findCustodyPda(e.destinationToken, minterProgramId),
              isWritable: true,
              isSigner: false,
            },
            { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
            {
              pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
              isWritable: true,
              isSigner: false,
            },
          ]);

          const attestationBytes = Buffer.from(attestation.slice(2), "hex");
          const signatureBytes = Buffer.from(mintSignature.slice(2), "hex");

          console.log("Minting funds on Solana Devnet...");
          const mintTx = await minterProgram.methods
            .gatewayMint({ attestation: attestationBytes, signature: signatureBytes })
            .accountsPartial({
              gatewayMinter: minterPda,
              destinationCaller: senderKeypair.publicKey,
              payer: senderKeypair.publicKey,
              systemProgram: SystemProgram.programId,
              tokenProgram: TOKEN_PROGRAM_ID,
            })
            .remainingAccounts(remainingAccounts)
            .signers([senderKeypair])
            .rpc();

          // [6] Wait for confirmation
          const latest = await connection.getLatestBlockhash();
          await connection.confirmTransaction(
            {
              signature: mintTx,
              blockhash: latest.blockhash,
              lastValidBlockHeight: latest.lastValidBlockHeight,
            },
            "confirmed",
          );

          console.log(`Minted ${Number(TRANSFER_VALUE) / 1_000_000} USDC`);
          console.log(`Mint transaction hash (solanaDevnet):`, mintTx);
        }

        main().catch((error) => {
          console.error("\nError:", error);
          process.exit(1);
        });
        ```

        ### 4.10. Run the script to transfer USDC to Solana Devnet

        Run the transfer script to transfer 1 USDC from your Solana Devnet Gateway
        balance to the recipient ATA on Solana Devnet.

        <Note>
          [Gateway gas fees](https://developers.circle.com/gateway/references/fees) are
          charged per burn intent. To reduce overall gas costs, consider keeping most
          Gateway funds on low-cost chains, where Circle’s base fee for burns is cheaper.
        </Note>

        ```shell theme={null}
        npm run transfer-from-sol
        ```
      </Tab>

      <Tab title="Transfer from EVM">
        ## Step 4: Transfer USDC from the crosschain balance

        This section explains parts of the transfer script that burns USDC from source
        chains and mints on a destination chain via Gateway. The script accepts chain
        names as CLI arguments. Specify one or more source chains (for example,
        `seiTestnet` `arcTestnet`) or use all for all supported testnets. You can skip
        to the [full transfer script](#4-9-full-evm-transfer-script-self-managed) if you
        prefer.

        ### 4.1. Create the script file

        ```shell theme={null}
        touch transfer-from-evm.ts
        ```

        ### 4.2. Define constants and types

        You can set the amount to be transferred from your Gateway balance by changing
        the `TRANSFER_AMOUNT`. For now, it is set to 1 USDC.

        ```ts transfer-from-evm.ts expandable theme={null}
        type ChainKey = keyof typeof chainConfigs;

        const GATEWAY_WALLET_ADDRESS = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";

        const TRANSFER_AMOUNT = 1; // 1 USDC
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;

        const chainConfigs = {
          sepolia: {
            chain: sepolia,
            usdcAddress: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
            domainId: 0,
          },
          baseSepolia: {
            chain: baseSepolia,
            usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
            domainId: 6,
          },
          avalancheFuji: {
            chain: avalancheFuji,
            usdcAddress: "0x5425890298aed601595a70ab815c96711a31bc65",
            domainId: 1,
          },
          arcTestnet: {
            chain: arcTestnet,
            usdcAddress: "0x3600000000000000000000000000000000000000",
            domainId: 26,
          },
          hyperliquidEvmTestnet: {
            chain: hyperliquidEvmTestnet,
            usdcAddress: "0x2B3370eE501B4a559b57D449569354196457D8Ab",
            domainId: 19,
          },
          seiTestnet: {
            chain: seiTestnet,
            usdcAddress: "0x4fCF1784B31630811181f670Aea7A7bEF803eaED",
            domainId: 16,
          },
          sonicTestnet: {
            chain: sonicTestnet,
            usdcAddress: "0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51",
            domainId: 13,
          },
          worldchainSepolia: {
            chain: worldchainSepolia,
            usdcAddress: "0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88",
            domainId: 14,
          },
        } as const;

        const domain = { name: "GatewayWallet", version: "1" };

        const EIP712Domain = [
          { name: "name", type: "string" },
          { name: "version", type: "string" },
        ];

        const TransferSpec = [
          { name: "version", type: "uint32" },
          { name: "sourceDomain", type: "uint32" },
          { name: "destinationDomain", type: "uint32" },
          { name: "sourceContract", type: "bytes32" },
          { name: "destinationContract", type: "bytes32" },
          { name: "sourceToken", type: "bytes32" },
          { name: "destinationToken", type: "bytes32" },
          { name: "sourceDepositor", type: "bytes32" },
          { name: "destinationRecipient", type: "bytes32" },
          { name: "sourceSigner", type: "bytes32" },
          { name: "destinationCaller", type: "bytes32" },
          { name: "value", type: "uint256" },
          { name: "salt", type: "bytes32" },
          { name: "hookData", type: "bytes" },
        ];

        const BurnIntent = [
          { name: "maxBlockHeight", type: "uint256" },
          { name: "maxFee", type: "uint256" },
          { name: "spec", type: "TransferSpec" },
        ];

        // Custom layout for Solana PublicKey (32 bytes)
        class PublicKeyLayout extends Layout<PublicKey> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0): PublicKey {
            return new PublicKey(b.subarray(offset, offset + 32));
          }
          encode(src: PublicKey, b: Buffer, offset = 0): number {
            const pubkeyBuffer = src.toBuffer();
            pubkeyBuffer.copy(b, offset);
            return 32;
          }
        }

        const publicKey = (property: string) => new PublicKeyLayout(property);

        const MintAttestationElementLayout = struct([
          publicKey("destinationToken"),
          publicKey("destinationRecipient"),
          nu64be("value"),
          blob(32, "transferSpecHash"),
          u32be("hookDataLength"),
          blob(offset(u32be(), -4), "hookData"),
        ] as any);

        const MintAttestationSetLayout = struct([
          u32be("magic"),
          u32be("version"),
          u32be("destinationDomain"),
          publicKey("destinationContract"),
          publicKey("destinationCaller"),
          nu64be("maxBlockHeight"),
          u32be("numAttestations"),
          seq(MintAttestationElementLayout, offset(u32be(), -4), "attestations"),
        ] as any);
        ```

        ### 4.3. Add helper functions

        ```ts transfer-from-evm.ts expandable theme={null}
        // Construct burn intent for EVM to Solana transfer
        function createBurnIntent(params: {
          sourceChain: ChainKey;
          depositorAddress: string;
          recipientAddress: string;
        }) {
          const { sourceChain, depositorAddress, recipientAddress } = params;
          const sourceConfig = chainConfigs[sourceChain];

          return {
            maxBlockHeight: MAX_UINT64,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: sourceConfig.domainId,
              destinationDomain: SOLANA_DOMAIN,
              sourceContract: GATEWAY_WALLET_ADDRESS,
              destinationContract: solanaAddressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: sourceConfig.usdcAddress,
              destinationToken: solanaAddressToBytes32(USDC_ADDRESS),
              sourceDepositor: depositorAddress,
              destinationRecipient: solanaAddressToBytes32(recipientAddress),
              sourceSigner: depositorAddress,
              destinationCaller: solanaAddressToBytes32(SOLANA_ZERO_ADDRESS),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Format burn intent as EIP-712 typed data for signing
        function burnIntentTypedData(burnIntent: ReturnType<typeof createBurnIntent>) {
          return {
            types: { EIP712Domain, TransferSpec, BurnIntent },
            domain,
            primaryType: "BurnIntent",
            message: {
              ...burnIntent,
              spec: {
                ...burnIntent.spec,
                sourceContract: evmAddressToBytes32(burnIntent.spec.sourceContract),
                destinationContract: burnIntent.spec.destinationContract,
                sourceToken: evmAddressToBytes32(burnIntent.spec.sourceToken),
                destinationToken: burnIntent.spec.destinationToken,
                sourceDepositor: evmAddressToBytes32(burnIntent.spec.sourceDepositor),
                destinationRecipient: burnIntent.spec.destinationRecipient,
                sourceSigner: evmAddressToBytes32(burnIntent.spec.sourceSigner),
                destinationCaller: burnIntent.spec.destinationCaller,
              },
            },
          };
        }

        // Get EVM keypair from environment variable
        function createKeypairFromEnv(privateKey: string) {
          const key = privateKey.startsWith("0x")
            ? (privateKey as `0x${string}`)
            : (`0x${privateKey}` as `0x${string}`);
          return privateKeyToAccount(key);
        }

        // Get Solana keypair from environment variable
        function createSolanaKeypairFromEnv(privateKey: string): Keypair {
          const secretKey = JSON.parse(privateKey);
          return Keypair.fromSecretKey(Uint8Array.from(secretKey));
        }

        // Parse chains from CLI arguments
        function parseSelectedChains(): ChainKey[] {
          const args = process.argv.slice(2);
          const validChains = Object.keys(chainConfigs) as ChainKey[];

          if (args.length === 0) {
            throw new Error(
              "No chains specified. Usage: npm run transfer -- <chain1> [chain2...] or 'all'",
            );
          }

          if (args.length === 1 && args[0] === "all") {
            return validChains;
          }

          const invalid = args.filter((c) => !validChains.includes(c as ChainKey));
          if (invalid.length > 0) {
            console.error(`Unsupported chain: ${invalid.join(", ")}`);
            console.error(`Valid chains: ${validChains.join(", ")}, all`);
            process.exit(1);
          }

          return [...new Set(args)] as ChainKey[];
        }

        // Pad EVM address to 32 bytes
        function evmAddressToBytes32(address: string) {
          return pad(address.toLowerCase() as `0x${string}`, { size: 32 });
        }

        // Convert Solana address to 32-byte hex string
        function solanaAddressToBytes32(address: string): string {
          const decoded = Buffer.from(bs58.decode(address));
          return `0x${decoded.toString("hex")}`;
        }

        // Serialize typed data (convert bigints to strings)
        function stringifyTypedData(obj: unknown) {
          return JSON.stringify(obj, (_key: string, value: unknown) =>
            typeof value === "bigint" ? value.toString() : value,
          );
        }

        // Decode attestation set from Gateway API response
        function decodeAttestationSet(attestation: string) {
          const buffer = Buffer.from(attestation.slice(2), "hex");
          return MintAttestationSetLayout.decode(buffer) as {
            attestations: Array<{
              destinationToken: PublicKey;
              destinationRecipient: PublicKey;
              transferSpecHash: Uint8Array;
            }>;
          };
        }

        // Find PDA for token custody account
        function findCustodyPda(
          mint: PublicKey,
          minterProgramId: PublicKey,
        ): PublicKey {
          return PublicKey.findProgramAddressSync(
            [Buffer.from("gateway_minter_custody"), mint.toBuffer()],
            minterProgramId,
          )[0];
        }

        // Find PDA for transfer spec hash tracking
        function findTransferSpecHashPda(
          transferSpecHash: Uint8Array | Buffer,
          minterProgramId: PublicKey,
        ): PublicKey {
          return PublicKey.findProgramAddressSync(
            [Buffer.from("used_transfer_spec_hash"), Buffer.from(transferSpecHash)],
            minterProgramId,
          )[0];
        }
        ```

        ### 4.4. Initialize connection and create recipient ATA

        Initialize the Solana connection and keypairs, then create the recipient’s
        Associated Token Account (ATA) for receiving USDC on the destination chain.

        <Info>
          For transfers to Solana, the `destinationRecipient` must be an initialized
          USDC Token Account. If the intended recipient is a standard wallet address,
          consider setting the `destinationRecipient` to its Associated Token Account
          (ATA) not the recipient wallet address. See the [Solana Technical
          Guide](/gateway/references/solana#reducedmintattestation) and [Solana Programs
          and Interfaces](/gateway/references/solana-programs#gatewaymint) for
          high-level Solana guidance and `gatewayMint` account requirements. Use the
          onchain IDLs linked from [Solana Programs and
          Interfaces](/gateway/references/solana-programs#account-structures) as the
          canonical static instruction and account definitions.
        </Info>

        ```ts transfer-from-evm.ts theme={null}
        const connection = new Connection(RPC_ENDPOINT, "confirmed");
        const usdcMint = new PublicKey(USDC_ADDRESS);
        const recipientAta = getAssociatedTokenAddressSync(
          usdcMint,
          solanaKeypair.publicKey,
        );

        const createAtaIx = createAssociatedTokenAccountIdempotentInstruction(
          solanaKeypair.publicKey,
          recipientAta,
          solanaKeypair.publicKey,
          usdcMint,
        );
        const tx = new Transaction().add(createAtaIx);
        await sendAndConfirmTransaction(connection, tx, [solanaKeypair]);
        ```

        ### 4.5. Create and sign burn intents

        ```ts transfer-from-evm.ts theme={null}
        const requests = [];

        for (const chainName of selectedChains) {
          console.log(`Creating burn intent from ${chainName} → Solana Devnet...`);

          const burnIntent = createBurnIntent({
            sourceChain: chainName,
            depositorAddress: evmAccount.address,
            recipientAddress: recipientAta.toBase58(),
          });

          const typedData = burnIntentTypedData(burnIntent);
          const signature = await evmAccount.signTypedData(
            typedData as Parameters<typeof evmAccount.signTypedData>[0],
          );

          requests.push({ burnIntent: typedData.message, signature });
        }
        console.log("Signed burn intents.");
        ```

        ### 4.6. Request attestation from Gateway API

        ```ts transfer-from-evm.ts theme={null}
        const response = await fetch(
          "https://gateway-api-testnet.circle.com/v1/transfer",
          {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: stringifyTypedData(requests),
          },
        );

        if (!response.ok) {
          console.error("Gateway API error status:", response.status);
          console.error(await response.text());
          throw new Error("Gateway API request failed");
        }

        const json = await response.json();
        console.log("Gateway API response:", JSON.stringify(json, null, 2));

        const { attestation, signature: mintSignature } = json;
        const decoded = decodeAttestationSet(attestation);
        ```

        ### 4.7. Set up minter client

        ```ts transfer-from-evm.ts theme={null}
        const minterProgramId = new PublicKey(GATEWAY_MINTER_ADDRESS);
        const anchorWallet = new Wallet(solanaKeypair);
        const provider = new AnchorProvider(
          connection,
          anchorWallet,
          AnchorProvider.defaultOptions(),
        );
        setProvider(provider);
        const minterProgram = new Program(gatewayMinterIdl, provider);

        const [minterPda] = PublicKey.findProgramAddressSync(
          [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
          minterProgramId,
        );
        ```

        <Info>
          The ordered remaining-account list and PDA derivations are documented in
          [Solana Programs and
          Interfaces](/gateway/references/solana-programs#gatewaymint). For static
          instruction definitions, use the onchain IDLs linked from that page.
        </Info>

        ### 4.8. Mint on Solana

        ```ts transfer-from-evm.ts expandable theme={null}
        const remainingAccounts = decoded.attestations.flatMap((e) => [
          {
            pubkey: findCustodyPda(e.destinationToken, minterProgramId),
            isWritable: true,
            isSigner: false,
          },
          { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
          {
            pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
            isWritable: true,
            isSigner: false,
          },
        ]);

        const attestationBytes = Buffer.from(attestation.slice(2), "hex");
        const signatureBytes = Buffer.from(mintSignature.slice(2), "hex");

        const mintTx = await minterProgram.methods
          .gatewayMint({ attestation: attestationBytes, signature: signatureBytes })
          .accountsPartial({
            gatewayMinter: minterPda,
            destinationCaller: solanaKeypair.publicKey,
            payer: solanaKeypair.publicKey,
            systemProgram: SystemProgram.programId,
            tokenProgram: TOKEN_PROGRAM_ID,
          })
          .remainingAccounts(remainingAccounts)
          .signers([solanaKeypair])
          .rpc();

        // [6] Wait for confirmation
        const latest = await connection.getLatestBlockhash();
        await connection.confirmTransaction(
          {
            signature: mintTx,
            blockhash: latest.blockhash,
            lastValidBlockHeight: latest.lastValidBlockHeight,
          },
          "confirmed",
        );

        const totalMinted = BigInt(requests.length) * TRANSFER_VALUE;
        console.log(`Minted ${Number(totalMinted) / 1_000_000} USDC`);
        console.log(`Mint transaction hash (Solana Devnet):`, mintTx);
        ```

        ### 4.9. Full EVM transfer script (Self-managed)

        The complete transfer script loops through selected EVM source chains, creates
        and signs burn intents for each chain, submits them to the Gateway API for
        attestation, and mints USDC on Solana Devnet. The script includes inline
        comments to explain what each function does, making it easier to follow and
        modify if needed.

        ```ts transfer-from-evm.ts expandable theme={null}
        import { randomBytes } from "node:crypto";
        import { pad } from "viem";
        import { privateKeyToAccount } from "viem/accounts";
        import {
          Wallet,
          AnchorProvider,
          setProvider,
          Program,
          utils,
        } from "@coral-xyz/anchor";
        import {
          Connection,
          Keypair,
          PublicKey,
          SystemProgram,
          Transaction,
          sendAndConfirmTransaction,
        } from "@solana/web3.js";
        import {
          TOKEN_PROGRAM_ID,
          getAssociatedTokenAddressSync,
          createAssociatedTokenAccountIdempotentInstruction,
        } from "@solana/spl-token";
        import {
          u32be,
          nu64be,
          struct,
          seq,
          blob,
          offset,
          Layout,
        } from "@solana/buffer-layout";
        import bs58 from "bs58";
        import {
          sepolia,
          baseSepolia,
          avalancheFuji,
          arcTestnet,
          hyperliquidEvmTestnet,
          seiTestnet,
          sonicTestnet,
          worldchainSepolia,
        } from "viem/chains";
        import {
          RPC_ENDPOINT,
          GATEWAY_MINTER_ADDRESS,
          USDC_ADDRESS,
          SOLANA_DOMAIN,
          SOLANA_ZERO_ADDRESS,
          gatewayMinterIdl,
        } from "./config.js";

        type ChainKey = keyof typeof chainConfigs;

        const chainConfigs = {
          sepolia: {
            chain: sepolia,
            usdcAddress: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
            domainId: 0,
          },
          baseSepolia: {
            chain: baseSepolia,
            usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
            domainId: 6,
          },
          avalancheFuji: {
            chain: avalancheFuji,
            usdcAddress: "0x5425890298aed601595a70ab815c96711a31bc65",
            domainId: 1,
          },
          arcTestnet: {
            chain: arcTestnet,
            usdcAddress: "0x3600000000000000000000000000000000000000",
            domainId: 26,
          },
          hyperliquidEvmTestnet: {
            chain: hyperliquidEvmTestnet,
            usdcAddress: "0x2B3370eE501B4a559b57D449569354196457D8Ab",
            domainId: 19,
          },
          seiTestnet: {
            chain: seiTestnet,
            usdcAddress: "0x4fCF1784B31630811181f670Aea7A7bEF803eaED",
            domainId: 16,
          },
          sonicTestnet: {
            chain: sonicTestnet,
            usdcAddress: "0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51",
            domainId: 13,
          },
          worldchainSepolia: {
            chain: worldchainSepolia,
            usdcAddress: "0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88",
            domainId: 14,
          },
        } as const;

        const GATEWAY_WALLET_ADDRESS = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";

        const TRANSFER_AMOUNT = 1; // 1 USDC
        const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
        const MAX_FEE = 2_010000n;
        const MAX_UINT64 = 2n ** 64n - 1n;

        const domain = { name: "GatewayWallet", version: "1" };

        const EIP712Domain = [
          { name: "name", type: "string" },
          { name: "version", type: "string" },
        ];

        const TransferSpec = [
          { name: "version", type: "uint32" },
          { name: "sourceDomain", type: "uint32" },
          { name: "destinationDomain", type: "uint32" },
          { name: "sourceContract", type: "bytes32" },
          { name: "destinationContract", type: "bytes32" },
          { name: "sourceToken", type: "bytes32" },
          { name: "destinationToken", type: "bytes32" },
          { name: "sourceDepositor", type: "bytes32" },
          { name: "destinationRecipient", type: "bytes32" },
          { name: "sourceSigner", type: "bytes32" },
          { name: "destinationCaller", type: "bytes32" },
          { name: "value", type: "uint256" },
          { name: "salt", type: "bytes32" },
          { name: "hookData", type: "bytes" },
        ];

        const BurnIntent = [
          { name: "maxBlockHeight", type: "uint256" },
          { name: "maxFee", type: "uint256" },
          { name: "spec", type: "TransferSpec" },
        ];

        /* Type definitions */
        // Custom layout for Solana PublicKey (32 bytes)
        class PublicKeyLayout extends Layout<PublicKey> {
          constructor(property: string) {
            super(32, property);
          }
          decode(b: Buffer, offset = 0): PublicKey {
            return new PublicKey(b.subarray(offset, offset + 32));
          }
          encode(src: PublicKey, b: Buffer, offset = 0): number {
            const pubkeyBuffer = src.toBuffer();
            pubkeyBuffer.copy(b, offset);
            return 32;
          }
        }

        const publicKey = (property: string) => new PublicKeyLayout(property);

        const MintAttestationElementLayout = struct([
          publicKey("destinationToken"),
          publicKey("destinationRecipient"),
          nu64be("value"),
          blob(32, "transferSpecHash"),
          u32be("hookDataLength"),
          blob(offset(u32be(), -4), "hookData"),
        ] as any);

        const MintAttestationSetLayout = struct([
          u32be("magic"),
          u32be("version"),
          u32be("destinationDomain"),
          publicKey("destinationContract"),
          publicKey("destinationCaller"),
          nu64be("maxBlockHeight"),
          u32be("numAttestations"),
          seq(MintAttestationElementLayout, offset(u32be(), -4), "attestations"),
        ] as any);

        /* Helpers */
        // Construct burn intent for EVM to Solana transfer
        function createBurnIntent(params: {
          sourceChain: ChainKey;
          depositorAddress: string;
          recipientAddress: string;
        }) {
          const { sourceChain, depositorAddress, recipientAddress } = params;
          const sourceConfig = chainConfigs[sourceChain];

          return {
            maxBlockHeight: MAX_UINT64,
            maxFee: MAX_FEE,
            spec: {
              version: 1,
              sourceDomain: sourceConfig.domainId,
              destinationDomain: SOLANA_DOMAIN,
              sourceContract: GATEWAY_WALLET_ADDRESS,
              destinationContract: solanaAddressToBytes32(GATEWAY_MINTER_ADDRESS),
              sourceToken: sourceConfig.usdcAddress,
              destinationToken: solanaAddressToBytes32(USDC_ADDRESS),
              sourceDepositor: depositorAddress,
              destinationRecipient: solanaAddressToBytes32(recipientAddress),
              sourceSigner: depositorAddress,
              destinationCaller: solanaAddressToBytes32(SOLANA_ZERO_ADDRESS),
              value: TRANSFER_VALUE,
              salt: "0x" + randomBytes(32).toString("hex"),
              hookData: "0x",
            },
          };
        }

        // Format burn intent as EIP-712 typed data for signing
        function burnIntentTypedData(burnIntent: ReturnType<typeof createBurnIntent>) {
          return {
            types: { EIP712Domain, TransferSpec, BurnIntent },
            domain,
            primaryType: "BurnIntent",
            message: {
              ...burnIntent,
              spec: {
                ...burnIntent.spec,
                sourceContract: evmAddressToBytes32(burnIntent.spec.sourceContract),
                destinationContract: burnIntent.spec.destinationContract,
                sourceToken: evmAddressToBytes32(burnIntent.spec.sourceToken),
                destinationToken: burnIntent.spec.destinationToken,
                sourceDepositor: evmAddressToBytes32(burnIntent.spec.sourceDepositor),
                destinationRecipient: burnIntent.spec.destinationRecipient,
                sourceSigner: evmAddressToBytes32(burnIntent.spec.sourceSigner),
                destinationCaller: burnIntent.spec.destinationCaller,
              },
            },
          };
        }

        // Get EVM keypair from environment variable
        function createKeypairFromEnv(privateKey: string) {
          const key = privateKey.startsWith("0x")
            ? (privateKey as `0x${string}`)
            : (`0x${privateKey}` as `0x${string}`);
          return privateKeyToAccount(key);
        }

        // Get Solana keypair from environment variable
        function createSolanaKeypairFromEnv(privateKey: string): Keypair {
          const secretKey = JSON.parse(privateKey);
          return Keypair.fromSecretKey(Uint8Array.from(secretKey));
        }

        // Parse chains from CLI arguments
        function parseSelectedChains(): ChainKey[] {
          const args = process.argv.slice(2);
          const validChains = Object.keys(chainConfigs) as ChainKey[];

          if (args.length === 0) {
            throw new Error(
              "No chains specified. Usage: npm run transfer -- <chain1> [chain2...] or 'all'",
            );
          }

          if (args.length === 1 && args[0] === "all") {
            return validChains;
          }

          const invalid = args.filter((c) => !validChains.includes(c as ChainKey));
          if (invalid.length > 0) {
            console.error(`Unsupported chain: ${invalid.join(", ")}`);
            console.error(`Valid chains: ${validChains.join(", ")}, all`);
            process.exit(1);
          }

          return [...new Set(args)] as ChainKey[];
        }

        // Pad EVM address to 32 bytes
        function evmAddressToBytes32(address: string) {
          return pad(address.toLowerCase() as `0x${string}`, { size: 32 });
        }

        // Convert Solana address to 32-byte hex string
        function solanaAddressToBytes32(address: string): string {
          const decoded = Buffer.from(bs58.decode(address));
          return `0x${decoded.toString("hex")}`;
        }

        // Serialize typed data (convert bigints to strings)
        function stringifyTypedData(obj: unknown) {
          return JSON.stringify(obj, (_key: string, value: unknown) =>
            typeof value === "bigint" ? value.toString() : value,
          );
        }

        // Decode attestation set from Gateway API response
        function decodeAttestationSet(attestation: string) {
          const buffer = Buffer.from(attestation.slice(2), "hex");
          return MintAttestationSetLayout.decode(buffer) as {
            attestations: Array<{
              destinationToken: PublicKey;
              destinationRecipient: PublicKey;
              transferSpecHash: Uint8Array;
            }>;
          };
        }

        // Find PDA for token custody account
        function findCustodyPda(
          mint: PublicKey,
          minterProgramId: PublicKey,
        ): PublicKey {
          return PublicKey.findProgramAddressSync(
            [Buffer.from("gateway_minter_custody"), mint.toBuffer()],
            minterProgramId,
          )[0];
        }

        // Find PDA for transfer spec hash tracking
        function findTransferSpecHashPda(
          transferSpecHash: Uint8Array | Buffer,
          minterProgramId: PublicKey,
        ): PublicKey {
          return PublicKey.findProgramAddressSync(
            [Buffer.from("used_transfer_spec_hash"), Buffer.from(transferSpecHash)],
            minterProgramId,
          )[0];
        }

        /* Main logic */
        async function main() {
          if (!process.env.EVM_PRIVATE_KEY || !process.env.SOLANA_PRIVATE_KEYPAIR) {
            throw new Error("EVM_PRIVATE_KEY and SOLANA_PRIVATE_KEYPAIR must be set");
          }

          const evmAccount = createKeypairFromEnv(process.env.EVM_PRIVATE_KEY);
          const solanaKeypair = createSolanaKeypairFromEnv(
            process.env.SOLANA_PRIVATE_KEYPAIR,
          );

          console.log(`Sender (EVM): ${evmAccount.address}`);
          console.log(
            `Recipient (Solana Devnet): ${solanaKeypair.publicKey.toBase58()}`,
          );

          // Validate chain selection
          const selectedChains = parseSelectedChains();
          console.log(`Transferring balances from: ${selectedChains.join(", ")}`);

          // [1] Create recipient's Associated Token Account
          const connection = new Connection(RPC_ENDPOINT, "confirmed");
          const usdcMint = new PublicKey(USDC_ADDRESS);
          const recipientAta = getAssociatedTokenAddressSync(
            usdcMint,
            solanaKeypair.publicKey,
          );

          const createAtaIx = createAssociatedTokenAccountIdempotentInstruction(
            solanaKeypair.publicKey,
            recipientAta,
            solanaKeypair.publicKey,
            usdcMint,
          );
          const tx = new Transaction().add(createAtaIx);
          await sendAndConfirmTransaction(connection, tx, [solanaKeypair]);

          // [2] Create and sign burn intents for each source chain
          const requests = [];

          for (const chainName of selectedChains) {
            console.log(`Creating burn intent from ${chainName} → Solana Devnet...`);

            const burnIntent = createBurnIntent({
              sourceChain: chainName,
              depositorAddress: evmAccount.address,
              recipientAddress: recipientAta.toBase58(),
            });

            const typedData = burnIntentTypedData(burnIntent);
            const signature = await evmAccount.signTypedData(
              typedData as Parameters<typeof evmAccount.signTypedData>[0],
            );

            requests.push({ burnIntent: typedData.message, signature });
          }
          console.log("Signed burn intents.");

          // [3] Request attestation from Gateway API
          const response = await fetch(
            "https://gateway-api-testnet.circle.com/v1/transfer",
            {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: stringifyTypedData(requests),
            },
          );

          if (!response.ok) {
            console.error("Gateway API error status:", response.status);
            console.error(await response.text());
            throw new Error("Gateway API request failed");
          }

          const json = await response.json();
          console.log("Gateway API response:", JSON.stringify(json, null, 2));

          const { attestation, signature: mintSignature } = json;
          const decoded = decodeAttestationSet(attestation);

          // [4] Set up the minter client
          const minterProgramId = new PublicKey(GATEWAY_MINTER_ADDRESS);
          const anchorWallet = new Wallet(solanaKeypair);
          const provider = new AnchorProvider(
            connection,
            anchorWallet,
            AnchorProvider.defaultOptions(),
          );
          setProvider(provider);
          const minterProgram = new Program(gatewayMinterIdl, provider);

          const [minterPda] = PublicKey.findProgramAddressSync(
            [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
            minterProgramId,
          );

          // [5] Mint on Solana
          console.log("Minting funds on Solana Devnet...");

          const remainingAccounts = decoded.attestations.flatMap((e) => [
            {
              pubkey: findCustodyPda(e.destinationToken, minterProgramId),
              isWritable: true,
              isSigner: false,
            },
            { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
            {
              pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
              isWritable: true,
              isSigner: false,
            },
          ]);

          const attestationBytes = Buffer.from(attestation.slice(2), "hex");
          const signatureBytes = Buffer.from(mintSignature.slice(2), "hex");

          const mintTx = await minterProgram.methods
            .gatewayMint({ attestation: attestationBytes, signature: signatureBytes })
            .accountsPartial({
              gatewayMinter: minterPda,
              destinationCaller: solanaKeypair.publicKey,
              payer: solanaKeypair.publicKey,
              systemProgram: SystemProgram.programId,
              tokenProgram: TOKEN_PROGRAM_ID,
            })
            .remainingAccounts(remainingAccounts)
            .signers([solanaKeypair])
            .rpc();

          // [6] Wait for confirmation
          const latest = await connection.getLatestBlockhash();
          await connection.confirmTransaction(
            {
              signature: mintTx,
              blockhash: latest.blockhash,
              lastValidBlockHeight: latest.lastValidBlockHeight,
            },
            "confirmed",
          );

          const totalMinted = BigInt(requests.length) * TRANSFER_VALUE;
          console.log(`Minted ${Number(totalMinted) / 1_000_000} USDC`);
          console.log(`Mint transaction hash (Solana Devnet):`, mintTx);
        }

        /* Main invocation */
        main().catch((error) => {
          console.error("\nError:", error);
          process.exit(1);
        });
        ```

        ### 4.10. Run the script to transfer USDC to Solana Devnet

        Run the transfer script to transfer 1 USDC from each selected EVM Gateway
        balance to the recipient ATA on Solana Devnet.

        <Note>
          [Gateway gas fees](https://developers.circle.com/gateway/references/fees) are
          charged per burn intent. To reduce overall gas costs, consider keeping most
          Gateway funds on low-cost chains, where Circle’s base fee for burns is cheaper.
        </Note>

        ```shell theme={null}
        # Transfer from all chains
        npm run transfer-from-evm -- all

        # Transfer from a single chain
        npm run transfer-from-evm -- arcTestnet

        # Transfer from multiple chains
        npm run transfer-from-evm -- baseSepolia avalancheFuji
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Gateway Smart Contract Addresses on EVM
Source: https://developers.circle.com/gateway/references/contract-addresses

Circle Gateway smart contract addresses on EVM

The following sections list the onchain addresses for the
[Gateway EVM smart contracts](/gateway/references/contract-interfaces-and-events).

## Testnet contract addresses

### GatewayWallet

| Chain               | Domain | Address                                                                                                                                  |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Arc Testnet         | 26     | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://testnet.arcscan.app/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)           |
| Arbitrum Sepolia    | 3      | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://sepolia.arbiscan.io/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)           |
| Avalanche Fuji      | 1      | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://testnet.snowscan.xyz/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)          |
| Base Sepolia        | 6      | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://sepolia.basescan.org/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)          |
| Ethereum Sepolia    | 0      | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://sepolia.etherscan.io/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)          |
| HyperEVM Testnet    | 19     | `0x0077777d7EBA4688BDeF3E311b846F25870A19B9`                                                                                             |
| OP Sepolia          | 2      | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://sepolia-optimism.etherscan.io/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9) |
| Polygon PoS Amoy    | 7      | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://amoy.polygonscan.com/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)          |
| Sei Atlantic        | 16     | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://testnet.seiscan.io/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)            |
| Solana Devnet       | 5      | [`GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu`](https://solscan.io/account/GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu?cluster=devnet) |
| Sonic Testnet       | 13     | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://testnet.sonicscan.org/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)         |
| Unichain Sepolia    | 10     | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://sepolia.uniscan.xyz/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)           |
| World Chain Sepolia | 14     | [`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`](https://sepolia.worldscan.org/address/0x0077777d7EBA4688BDeF3E311b846F25870A19B9)         |

### GatewayMinter

| Chain               | Domain | Address                                                                                                                                  |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Arc Testnet         | 26     | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://testnet.arcscan.app/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)           |
| Arbitrum Sepolia    | 3      | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://sepolia.arbiscan.io/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)           |
| Avalanche Fuji      | 1      | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://testnet.snowscan.xyz/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)          |
| Base Sepolia        | 6      | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://sepolia.basescan.org/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)          |
| Ethereum Sepolia    | 0      | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://sepolia.etherscan.io/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)          |
| HyperEVM Testnet    | 19     | `0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`                                                                                             |
| OP Sepolia          | 2      | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://sepolia-optimism.etherscan.io/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B) |
| Polygon PoS Amoy    | 7      | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://amoy.polygonscan.com/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)          |
| Sei Atlantic        | 16     | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://testnet.seiscan.io/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)            |
| Solana Devnet       | 5      | [`GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr`](https://solscan.io/account/GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr?cluster=devnet) |
| Sonic Testnet       | 13     | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://testnet.sonicscan.org/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)         |
| Unichain Sepolia    | 10     | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://sepolia.uniscan.xyz/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)           |
| World Chain Sepolia | 14     | [`0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`](https://sepolia.worldscan.org/address/0x0022222ABE238Cc2C7Bb1f21003F0a260052475B)         |

## Mainnet contract addresses

### GatewayWallet

| Chain       | Domain | Address                                                                                                                            |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum    | 3      | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://arbiscan.io/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)             |
| Avalanche   | 1      | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://snowscan.xyz/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)            |
| Base        | 6      | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://basescan.org/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)            |
| Ethereum    | 0      | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://etherscan.io/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)            |
| HyperEVM    | 19     | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://hyperevmscan.io/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)         |
| OP          | 2      | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://optimistic.etherscan.io/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE) |
| Polygon PoS | 7      | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://polygonscan.com/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)         |
| Sei         | 16     | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://seiscan.io/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)              |
| Sonic       | 13     | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://sonicscan.org/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)           |
| Unichain    | 10     | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://uniscan.xyz/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)             |
| World Chain | 14     | [`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`](https://worldscan.org/address/0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE)           |

### GatewayMinter

| Chain       | Domain | Address                                                                                                                            |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum    | 3      | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://arbiscan.io/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)             |
| Avalanche   | 1      | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://snowscan.xyz/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)            |
| Base        | 6      | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://basescan.org/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)            |
| Ethereum    | 0      | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://etherscan.io/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)            |
| HyperEVM    | 19     | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://hyperevmscan.io/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)         |
| OP          | 2      | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://optimistic.etherscan.io/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205) |
| Polygon PoS | 7      | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://polygonscan.com/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)         |
| Sei         | 16     | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://seiscan.io/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)              |
| Sonic       | 13     | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://sonicscan.org/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)           |
| Unichain    | 10     | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://uniscan.xyz/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)             |
| World Chain | 14     | [`0x2222222d7164433c4C09B0b0D809a9b52C04C205`](https://worldscan.org/address/0x2222222d7164433c4C09B0b0D809a9b52C04C205)           |


# Gateway Contract Interfaces and Events on EVM
Source: https://developers.circle.com/gateway/references/contract-interfaces-and-events

Learn about the Circle Gateway smart contracts on EVM

The [wallet and minter smart contracts](/gateway/references/contract-addresses)
have a set of interfaces and events that you can use to build with Circle
Gateway. This page describes the user-facing methods of these contracts.

## Interfaces

This section provides information on the public methods of the `GatewayWallet`
and `GatewayMinter` smart contracts. The full ABIs are
[available on GitHub](https://github.com/circlefin/evm-gateway-contracts).

### GatewayWallet

#### deposit

Deposit tokens after approving this contract for the token. The resulting
balance belongs to the function caller.

```solidity Solidity theme={null}
function deposit(address token, uint256 value) external;
```

**Parameters**

| Name    | Type      | Description                         |
| ------- | --------- | ----------------------------------- |
| `token` | `address` | The address of the token to deposit |
| `value` | `uint256` | The amount of tokens to deposit     |

#### depositFor

Deposit tokens on behalf of another address after approving this contract for
the token. The resulting balance belongs to the address specified by the
`depositor` parameter, not the function caller.

```solidity Solidity theme={null}
function depositFor(address token, address depositor, uint256 value) external;
```

**Parameters**

| Name        | Type      | Description                                       |
| ----------- | --------- | ------------------------------------------------- |
| `token`     | `address` | The address of the token to deposit               |
| `depositor` | `address` | The address that should own the resulting balance |
| `value`     | `uint256` | The amount of tokens to deposit                   |

#### depositWithPermit

Deposit tokens with an EIP-2612 permit. The resulting balance belongs to the
`owner` specified in the permit. The permit's `spender` must be the address of
the GatewayWallet contract. The full permitted `value` is always deposited.

```solidity Solidity theme={null}
function depositWithPermit(address token, address owner, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external;
```

**Parameters**

| Name       | Type      | Description                                                                                       |
| ---------- | --------- | ------------------------------------------------------------------------------------------------- |
| `token`    | `address` | The address of the token to deposit                                                               |
| `owner`    | `address` | The depositor's address                                                                           |
| `value`    | `uint256` | The amount of tokens to deposit                                                                   |
| `deadline` | `uint256` | The unix timestamp at which the signature expires, or max `uint256` value to signal no expiration |
| `v`        | `uint8`   | `v` of the signature                                                                              |
| `r`        | `bytes32` | `r` of the signature                                                                              |
| `s`        | `bytes32` | `s` of the signature                                                                              |

#### depositWithPermit

Deposit tokens with an EIP-2612 permit (using the EIP-7597 extension), passing
the signature as bytes to allow for SCA deposits. The resulting balance belongs
to the `owner` specified in the permit. The permit's `spender` must be the
address of the GatewayWallet contract. The full permitted `value` is always
deposited. EOA wallet signatures should be packed in the order of r, s, v.

```solidity Solidity theme={null}
function depositWithPermit(address token, address owner, uint256 value, uint256 deadline, bytes calldata signature) external;
```

**Parameters**

| Name        | Type      | Description                                                                                  |
| ----------- | --------- | -------------------------------------------------------------------------------------------- |
| `token`     | `address` | The address of the token to deposit                                                          |
| `owner`     | `address` | The depositor's address                                                                      |
| `value`     | `uint256` | The amount of tokens to deposit                                                              |
| `deadline`  | `uint256` | The unix time at which the signature expires, or max `uint256` value to signal no expiration |
| `signature` | `bytes`   | Signature bytes signed by an EOA wallet or a contract wallet                                 |

#### depositWithAuthorization

Deposit tokens with an ERC-3009 authorization. The resulting balance in this
contract belongs to the `from` specified in the authorization. The
authorization's `to` must be the address of the GatewayWallet contract.

```solidity Solidity theme={null}
function depositWithAuthorization(address token, address from, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s) external;
```

**Parameters**

| Name          | Type      | Description                                                |
| ------------- | --------- | ---------------------------------------------------------- |
| `token`       | `address` | The address of the token to deposit                        |
| `from`        | `address` | The depositor's address                                    |
| `value`       | `uint256` | The amount of tokens to deposit                            |
| `validAfter`  | `uint256` | The unix timestamp after which the authorization is valid  |
| `validBefore` | `uint256` | The unix timestamp before which the authorization is valid |
| `nonce`       | `bytes32` | Unique nonce                                               |
| `v`           | `uint8`   | v of the signature                                         |
| `r`           | `bytes32` | r of the signature                                         |
| `s`           | `bytes32` | s of the signature                                         |

#### depositWithAuthorization

Deposit tokens with an ERC-3009 authorization (using the ERC-7598 extension),
passing the signature as bytes to allow for SCA deposits. The resulting balance
in this contract belongs to the `from` specified in the authorization. The
authorization's `to` must be the address of this contract. The transfer will be
done via `receiveWithAuthorization`. EOA wallet signatures should be packed in
the order of r, s, v.

```solidity Solidity theme={null}
function depositWithAuthorization(address token, address from, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes calldata signature) external;
```

**Parameters**

| Name          | Type      | Description                                                  |
| ------------- | --------- | ------------------------------------------------------------ |
| `token`       | `address` | The address of the token to deposit                          |
| `from`        | `address` | The depositor's address                                      |
| `value`       | `uint256` | The amount of tokens to deposit                              |
| `validAfter`  | `uint256` | The unix timestamp after which the authorization is valid    |
| `validBefore` | `uint256` | The unix timestamp before which the authorization is valid   |
| `nonce`       | `bytes32` | Unique nonce                                                 |
| `signature`   | `bytes`   | Signature bytes signed by an EOA wallet or a contract wallet |

#### totalBalance

Returns the total balance of a depositor for a given token. This will always be
equal to the sum of `availableBalance` and `withdrawingBalance`.

```solidity Solidity theme={null}
function totalBalance(address token, address depositor) public view returns (uint256);
```

**Parameters**

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `token`     | `address` | The address of the token to check |
| `depositor` | `address` | The depositor to check            |

**Returns**

| Name     | Type      | Description                                      |
| -------- | --------- | ------------------------------------------------ |
| `<none>` | `uint256` | The total balance of the depositor for the token |

#### availableBalance

Returns the balance that is available to the depositor, subject to deposits
being observed by Circle in a finalized block and excepting in-flight transfers.

```solidity Solidity theme={null}
function availableBalance(address token, address depositor) public view returns (uint256);
```

**Parameters**

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `token`     | `address` | The address of the token to check |
| `depositor` | `address` | The depositor to check            |

**Returns**

| Name     | Type      | Description                                          |
| -------- | --------- | ---------------------------------------------------- |
| `<none>` | `uint256` | The available balance of the depositor for the token |

#### withdrawingBalance

Returns the balance that is in the process of being withdrawn from the
GatewayWallet contract.

```solidity Solidity theme={null}
function withdrawingBalance(address token, address depositor) public view returns (uint256);
```

**Parameters**

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `token`     | `address` | The address of the token to check |
| `depositor` | `address` | The depositor to check            |

**Returns**

| Name     | Type      | Description                                            |
| -------- | --------- | ------------------------------------------------------ |
| `<none>` | `uint256` | The withdrawing balance of the depositor for the token |

#### withdrawableBalance

Returns the balance that is withdrawable as of the current block. This will
either be 0 or `withdrawingBalance`.

```solidity Solidity theme={null}
function withdrawableBalance(address token, address depositor) public view returns (uint256);
```

**Parameters**

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `token`     | `address` | The address of the token to check |
| `depositor` | `address` | The depositor to check            |

**Returns**

| Name     | Type      | Description                                             |
| -------- | --------- | ------------------------------------------------------- |
| `<none>` | `uint256` | The withdrawable balance of the depositor for the token |

#### balanceOf

Returns the balance of a depositor for a given token and balance type,
compatible with ERC-1155. The "token" `id` is encoded as
`uint256(bytes32(abi.encodePacked(uint96(BALANCE_TYPE), address(token))))`,
where `BALANCE_TYPE` is 0 for `Total`, 1 for `Available`, 2 for `Withdrawing`,
and 3 for `Withdrawable`.

```solidity Solidity theme={null}
function balanceOf(address depositor, uint256 id) public view returns (uint256 balance);
```

**Parameters**

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `depositor` | `address` | The depositor to check            |
| `id`        | `uint256` | The packed token and balance type |

**Returns**

| Name      | Type      | Description                                                 |
| --------- | --------- | ----------------------------------------------------------- |
| `balance` | `uint256` | The balance of the depositor for the token and balance type |

#### balanceOfBatch

The batch version of `balanceOf`, compatible with ERC-1155. `depositors` and
`ids` must be the same length. See the documentation for `balanceOf` for the
format of `ids`.

```solidity Solidity theme={null}
function balanceOfBatch(address[] calldata depositors, uint256[] calldata ids) external view override returns (uint256[] memory balances);
```

**Parameters**

| Name         | Type        | Description                         |
| ------------ | ----------- | ----------------------------------- |
| `depositors` | `address[]` | The depositors to check             |
| `ids`        | `uint256[]` | The packed tokens and balance types |

**Returns**

| Name       | Type        | Description                                                     |
| ---------- | ----------- | --------------------------------------------------------------- |
| `balances` | `uint256[]` | The balances of the depositors for the tokens and balance types |

#### addDelegate

Allow a delegate to transfer the caller's balance of the specified token. This
acts as a full allowance for `delegate` on the `token` balance of the function
caller.

```solidity Solidity theme={null}
function addDelegate(address token, address delegate) external;
```

**Parameters**

| Name       | Type      | Description                                                       |
| ---------- | --------- | ----------------------------------------------------------------- |
| `token`    | `address` | The address of the token that `delegate` should be authorized for |
| `delegate` | `address` | The address being authorized                                      |

#### removeDelegate

Stop allowing a delegate to transfer the caller's balance of the specified
token. This revocation is not respected for burn intents that have already been
signed, so that burns cannot be prevented by removing the delegate.

```solidity Solidity theme={null}
function removeDelegate(address token, address delegate) external;
```

**Parameters**

| Name       | Type      | Description                                                              |
| ---------- | --------- | ------------------------------------------------------------------------ |
| `token`    | `address` | The address of the token the delegate should no longer be authorized for |
| `delegate` | `address` | The address that should no longer be authorized                          |

#### isAuthorizedForBalance

Returns whether an address is authorized to transfer tokens on behalf of a
depositor.

```solidity Solidity theme={null}
function isAuthorizedForBalance(address token, address depositor, address addr) public view returns (bool);
```

**Parameters**

| Name        | Type      | Description                       |
| ----------- | --------- | --------------------------------- |
| `token`     | `address` | The address of the token to check |
| `depositor` | `address` | The depositor to check            |
| `addr`      | `address` | The address to check              |

**Returns**

| Name     | Type   | Description                                            |
| -------- | ------ | ------------------------------------------------------ |
| `<none>` | `bool` | `true` if the address is authorized, `false` otherwise |

#### withdrawalDelay

Returns the number of blocks that must pass after calling `initiateWithdrawal`
before a withdrawal can be completed.

```solidity Solidity theme={null}
function withdrawalDelay() public view returns (uint256);
```

**Returns**

| Name     | Type      | Description                         |
| -------- | --------- | ----------------------------------- |
| `<none>` | `uint256` | The number of blocks that must pass |

#### withdrawalBlock

Returns the block height at which an in-progress withdrawal is withdrawable, or
0 if there is no in-progress withdrawal.

```solidity Solidity theme={null}
function withdrawalBlock(address token, address depositor) public view returns (uint256);
```

**Parameters**

| Name        | Type      | Description                                                |
| ----------- | --------- | ---------------------------------------------------------- |
| `token`     | `address` | The address of the token of the in-progress withdrawal     |
| `depositor` | `address` | The address of the depositor of the in-progress withdrawal |

**Returns**

| Name     | Type      | Description                                                   |
| -------- | --------- | ------------------------------------------------------------- |
| `<none>` | `uint256` | The block number at which the withdrawal will be withdrawable |

#### initiateWithdrawal

Starts the withdrawal process. After `withdrawalDelay` blocks, `withdraw` may be
called to complete the withdrawal. Once a withdrawal has been initiated, that
amount can no longer be used. Repeated calls will add to the amount and reset
the timer.

```solidity Solidity theme={null}
function initiateWithdrawal(address token, uint256 value) external;
```

**Parameters**

| Name    | Type      | Description                                           |
| ------- | --------- | ----------------------------------------------------- |
| `token` | `address` | The address of the token to initiate a withdrawal for |
| `value` | `uint256` | The amount to be withdrawn                            |

#### withdraw

Completes a withdrawal that was initiated at least `withdrawalDelay` blocks ago.
The funds are sent to the depositor (who must be the caller of this function).
The full amount that is in the process of being withdrawn is always withdrawn.

```solidity Solidity theme={null}
function withdraw(address token) external;
```

**Parameters**

| Name    | Type      | Description                          |
| ------- | --------- | ------------------------------------ |
| `token` | `address` | The address of the token to withdraw |

### GatewayMinter

#### gatewayMint

Mint funds via a signed attestation from the Gateway API. Emits an event
containing the `keccak256` hash of the encoded `TransferSpec` (which is the same
for the corresponding burn that will happen on the source domain), to be used as
a cross-chain identifier and for replay protection.

```solidity Solidity theme={null}
function gatewayMint(bytes memory attestationPayload, bytes memory signature) external;
```

**Parameters**

| Name                 | Type    | Description                                                           |
| -------------------- | ------- | --------------------------------------------------------------------- |
| `attestationPayload` | `bytes` | The byte-encoded attestation(s)                                       |
| `signature`          | `bytes` | The signature from a valid attestation signer on `attestationPayload` |

### Common

These methods are supported by both the `GatewayWallet` and `GatewayMinter`
contracts.

#### domain

The domain assigned to the chain this contract is deployed on.

```solidity Solidity theme={null}
function domain() public view returns (uint32);
```

**Returns**

| Name     | Type     | Description                                        |
| -------- | -------- | -------------------------------------------------- |
| `<none>` | `uint32` | The Circle-issued identifier for the current chain |

#### isTokenSupported

Whether or not a token is supported.

```solidity Solidity theme={null}
function isTokenSupported(address token) public view returns (bool);
```

**Parameters**

| Name    | Type      | Description                       |
| ------- | --------- | --------------------------------- |
| `token` | `address` | The address of the token to check |

**Returns**

| Name     | Type   | Description                                         |
| -------- | ------ | --------------------------------------------------- |
| `<none>` | `bool` | `true` if the token is supported, `false` otherwise |

#### isTransferSpecHashUsed

Whether or not a transfer spec hash has been used.

```solidity Solidity theme={null}
function isTransferSpecHashUsed(bytes32 transferSpecHash) public view returns (bool);
```

**Parameters**

| Name               | Type      | Description                     |
| ------------------ | --------- | ------------------------------- |
| `transferSpecHash` | `bytes32` | The transfer spec hash to check |

**Returns**

| Name     | Type   | Description                                                       |
| -------- | ------ | ----------------------------------------------------------------- |
| `<none>` | `bool` | `true` if the transfer spec hash has been used, `false` otherwise |

#### isDenylisted

Whether or not a given address is denied from interacting with the contract.

```solidity Solidity theme={null}
function isDenylisted(address addr) public view returns (bool);
```

**Parameters**

| Name   | Type      | Description          |
| ------ | --------- | -------------------- |
| `addr` | `address` | The address to check |

**Returns**

| Name     | Type   | Description                                            |
| -------- | ------ | ------------------------------------------------------ |
| `<none>` | `bool` | `true` if the address is denylisted, `false` otherwise |

## Events

### GatewayWallet

#### Deposited

Emitted when a deposit is made. The `sender` will always be the same as
`depositor`, except when a deposit is made using `depositFor`.

```solidity Solidity theme={null}
event Deposited(address indexed token, address indexed depositor, address indexed sender, uint256 value);
```

**Parameters**

| Name        | Type      | Description                                           |
| ----------- | --------- | ----------------------------------------------------- |
| `token`     | `address` | The address of the token that was deposited           |
| `depositor` | `address` | The address that the resulting balance is credited to |
| `sender`    | `address` | The address that the funds were deposited from        |
| `value`     | `uint256` | The amount that was deposited                         |

#### DelegateAdded

Emitted when a delegate is authorized for a depositor's balance.

```solidity Solidity theme={null}
event DelegateAdded(address indexed token, address indexed depositor, address delegate);
```

**Parameters**

| Name        | Type      | Description                                                      |
| ----------- | --------- | ---------------------------------------------------------------- |
| `token`     | `address` | The address of the token that the delegate is now authorized for |
| `depositor` | `address` | The depositor who added the delegate                             |
| `delegate`  | `address` | The delegate that was added                                      |

#### DelegateRemoved

Emitted when a delegate's authorization is revoked.

```solidity Solidity theme={null}
event DelegateRemoved(address indexed token, address indexed depositor, address delegate);
```

**Parameters**

| Name        | Type      | Description                                                       |
| ----------- | --------- | ----------------------------------------------------------------- |
| `token`     | `address` | The address of the token the delegate is no longer authorized for |
| `depositor` | `address` | The depositor who removed the delegate                            |
| `delegate`  | `address` | The delegate that was removed                                     |

#### WithdrawalInitiated

Emitted when a withdrawal is initiated.

```solidity Solidity theme={null}
event WithdrawalInitiated(
    address indexed token,
    address indexed depositor,
    uint256 value,
    uint256 remainingAvailable,
    uint256 totalWithdrawing,
    uint256 withdrawalBlock
);
```

**Parameters**

| Name                 | Type      | Description                                                    |
| -------------------- | --------- | -------------------------------------------------------------- |
| `token`              | `address` | The address of the token that is being withdrawn               |
| `depositor`          | `address` | The owner of the funds being withdrawn                         |
| `value`              | `uint256` | The value that was added to the in-progress withdrawal         |
| `remainingAvailable` | `uint256` | The remaining available balance after the withdrawal           |
| `totalWithdrawing`   | `uint256` | The total value that is now being withdrawn                    |
| `withdrawalBlock`    | `uint256` | The block number at which the full withdrawal can be completed |

#### WithdrawalCompleted

Emitted when a withdrawal is completed and funds have been transferred to the
depositor.

```solidity Solidity theme={null}
event WithdrawalCompleted(address indexed token, address indexed depositor, uint256 value);
```

**Parameters**

| Name        | Type      | Description                                 |
| ----------- | --------- | ------------------------------------------- |
| `token`     | `address` | The address of the token that was withdrawn |
| `depositor` | `address` | The owner of the withdrawn funds            |
| `value`     | `uint256` | The value that was withdrawn                |

#### GatewayBurned

Emitted when Circle burns tokens that have been minted on another domain

```solidity Solidity theme={null}
event GatewayBurned(
    address indexed token,
    address indexed depositor,
    bytes32 indexed transferSpecHash,
    uint32 destinationDomain,
    bytes32 destinationRecipient,
    address signer,
    uint256 value,
    uint256 fee,
    uint256 fromAvailable,
    uint256 fromWithdrawing
);
```

**Parameters**

| Name                   | Type      | Description                                          |
| ---------------------- | --------- | ---------------------------------------------------- |
| `token`                | `address` | The address of the token that was burned             |
| `depositor`            | `address` | The depositor who owned the balance                  |
| `transferSpecHash`     | `bytes32` | The `keccak256` hash of the `TransferSpec`           |
| `destinationDomain`    | `uint32`  | The domain the corresponding attestation was used on |
| `destinationRecipient` | `bytes32` | The recipient of the funds at the destination        |
| `signer`               | `address` | The address that authorized the transfer             |
| `value`                | `uint256` | The value that was burned                            |
| `fee`                  | `uint256` | The fee charged for the burn                         |
| `fromAvailable`        | `uint256` | The value burned from the `available` balance        |
| `fromWithdrawing`      | `uint256` | The value burned from the `withdrawing` balance      |

### GatewayMinter

#### AttestationUsed

Emitted when an attestation is used.

```solidity Solidity theme={null}
event AttestationUsed(
    address indexed token,
    address indexed recipient,
    bytes32 indexed transferSpecHash,
    uint32 sourceDomain,
    bytes32 sourceDepositor,
    bytes32 sourceSigner,
    uint256 value
);
```

**Parameters**

| Name               | Type      | Description                                                             |
| ------------------ | --------- | ----------------------------------------------------------------------- |
| `token`            | `address` | The address of the token that was minted                                |
| `recipient`        | `address` | The recipient of the funds                                              |
| `transferSpecHash` | `bytes32` | The `keccak256` hash of the `TransferSpec`, shared with the burn intent |
| `sourceDomain`     | `uint32`  | The domain the funds came from                                          |
| `sourceDepositor`  | `bytes32` | The depositor on the source domain                                      |
| `sourceSigner`     | `bytes32` | The signer that authorized the transfer                                 |
| `value`            | `uint256` | The amount that was minted                                              |

### Common

These events are emitted by both the `GatewayWallet` and `GatewayMinter`
contracts.

#### Denylisted

Emitted when an address is added to the denylist.

```solidity Solidity theme={null}
event Denylisted(address indexed addr);
```

**Parameters**

| Name   | Type      | Description                                                             |
| ------ | --------- | ----------------------------------------------------------------------- |
| `addr` | `address` | The address that is now being denied from interacting with the contract |

#### UnDenylisted

Emitted when an address is removed from the denylist.

```solidity Solidity theme={null}
event UnDenylisted(address indexed addr);
```

**Parameters**

| Name   | Type      | Description                                                     |
| ------ | --------- | --------------------------------------------------------------- |
| `addr` | `address` | The address that is allowed to interact with the contract again |

#### TokenSupported

Emitted when a token is added to the set of supported tokens.

```solidity Solidity theme={null}
event TokenSupported(address token);
```

**Parameters**

| Name    | Type      | Description                                    |
| ------- | --------- | ---------------------------------------------- |
| `token` | `address` | The address of the token that is now supported |


# Gateway Fees
Source: https://developers.circle.com/gateway/references/fees

Understanding Gateway transfer fees and gas costs

Gateway charges a transfer fee and a gas fee for crosschain transfers. If you
use the [Circle Forwarding Service](/gateway/references/forwarding-service) to
handle the destination mint, Gateway also charges a forwarding fee.

## Transfer fee

Crosschain transfers incur a percentage-based fee of **0.005%** (0.5 basis
points) on the transfer amount.

* **When charged**: On crosschain transfers (source and destination are
  different blockchains)
* **Payment method**: Deducted from your unified USDC balance at the time of
  burn

Same-chain transfers (withdrawals where source and destination are the same
blockchain) do not incur the transfer fee.

## Gas fees

Each burn intent includes a gas fee that covers the cost of executing the burn
transaction on the source blockchain. The gas fee varies by source blockchain:

| Source blockchain | Gas fee (USDC) |
| ----------------- | -------------- |
| Arbitrum          | \$0.01         |
| Avalanche         | \$0.02         |
| Base              | \$0.01         |
| Ethereum          | \$2.00         |
| HyperEVM          | \$0.05         |
| OP                | \$0.0015       |
| Polygon PoS       | \$0.0015       |
| Sei               | \$0.001        |
| Solana            | \$0.15         |
| Sonic             | \$0.01         |
| Unichain          | \$0.001        |
| World Chain       | \$0.01         |

## Forwarding fees

When you use the
[Circle Forwarding Service](/gateway/references/forwarding-service) to handle
destination chain minting, Gateway charges an additional forwarding fee. The
forwarding fee has two parts:

* **Forwarding service fee**: A flat fee per transfer
* **Forwarding gas fee**: Covers the cost of executing the mint on the
  destination blockchain

The forwarding service fee is **\$0.20** per transfer on all destination
blockchains. The forwarding gas fee is approximately the same as the
[gas fee](#gas-fees) charged for a burn on the corresponding blockchain.

To estimate the forwarding fee before submitting a transfer, call the
[`/estimate`](/api-reference/gateway/all/estimate-transfer) endpoint with
`enableForwarder=true`. The returned `forwardingFee` value includes both the
service fee and the gas fee.

<Note>
  When the destination is Solana and
  [automatic Associated Token Account (ATA) creation](/gateway/references/forwarding-service#automatic-ata-creation-for-solana)
  is enabled, the forwarding fee also includes the Solana rent cost for the token
  account.
</Note>

For details on how the forwarding fee is collected across burn intents, see
[Fee collection](/gateway/references/forwarding-service#fee-collection) in the
Forwarding Service topic.

## Setting `maxFee`

When creating a [burn intent](/gateway/references/technical-guide#burn-intent),
set the `maxFee` field to cover the gas fee, the transfer fee, and any
forwarding fee:

```text theme={null}
maxFee ≥ gas fee + forwarding fee + (transfer amount * 0.00005)
```

For example, transferring 1,000 USDC from Base without forwarding:

* Gas fee: \$0.01
* Transfer fee: 1,000 \* 0.00005 = \$0.05
* Minimum `maxFee`: \$0.06 (60,000 in USDC subunits)

For the same transfer with the Forwarding Service enabled:

* Gas fee: \$0.01
* Forwarding fee: \$0.21 (service fee plus forwarding gas fee)
* Transfer fee: 1,000 \* 0.00005 = \$0.05
* Minimum `maxFee`: \$0.27 (270,000 in USDC subunits)

<Tip>
  Add a buffer to your `maxFee` calculation to account for gas fee fluctuations.
</Tip>

## Optimizing costs

To reduce overall costs:

* **Use low-cost source blockchains**: Keep the majority of your Gateway balance
  on blockchains with lower gas fees (such as OP, Polygon PoS, Sei, or Unichain)
* **Consolidate burn intents**: The gas cost of minting scales slower than
  multiple individual [CCTP](/cctp) transfers. Each additional burn intent adds
  approximately 60k gas to the mint transaction.


# Circle Forwarding Service for Gateway
Source: https://developers.circle.com/gateway/references/forwarding-service

Forward destination chain mints to simplify crosschain transfers

The Circle Forwarding Service is a service for Gateway that simplifies
integration by removing the need for you to run multichain infrastructure. This
can improve user experience for crosschain transfers by ensuring reliability and
eliminating the need to handle destination chain gas fees.

## How it works

A Gateway transfer without the Forwarding Service is a three-step process
(assuming funds already deposited):

1. Create burn intents to burn USDC on the source chain.
2. Use the burn intents to request an attestation from the Circle API.
3. Submit the attestation to the destination minter contract to mint USDC.

This process requires you to have a wallet that can sign transactions on the
source and destination chains, and native tokens for paying the transaction gas
fee on both chains.

By enabling the forwarding service, you can pay for all the costs (base fee,
transfer fee, forwarding fee) when the funds are burned on the source chain.

## Enabling the Forwarding Service

To enable the Forwarding Service, add the `enableForwarder=true` query parameter
to the [`/transfer`](/api-reference/gateway/all/create-transfer-attestation)
endpoint:

```bash theme={null}
POST /v1/transfer?enableForwarder=true
```

When this parameter is set to `true`, Gateway will handle the destination chain
minting automatically. Because forwarding submits the destination mint for you,
the `POST /v1/transfer?enableForwarder=true` response may omit top-level
`attestation` and `signature` fields. Use
[`GET /v1/transfer/{id}`](/api-reference/gateway/all/get-transfer-by-id) for the
full transfer record, including nested attestation details.

## Fees and execution

The Forwarding Fee includes two parts:

* Forwarding Service fee
* Forwarding Gas Fee

The *Forwarding Service fee* for each transfer:

| Destination chain | Service fee (USDC) |
| ----------------- | ------------------ |
| All chains        | \$0.20             |

The *Forwarding Gas fee* is the amount needed to execute the mint attestation.
This cost is roughly the same gas costs as the
[burn fees](/gateway/references/fees#gas-fees).

The burn intent max fee must account for the forwarding fee.

```text theme={null}
maxFee ≥ gas fee + forwarding fee + (transfer amount * 0.00005)
```

For example, transferring 1,000 USDC from Base:

* Gas fee: \$0.01
* forwarding fee: \$0.21 (forwarding service and gas fee)
* Transfer fee: 1,000 \* 0.00005 = \$0.05
* Minimum `maxFee`: \$0.27 (270,000 in USDC subunits)

## Estimate forwarding fee

The [`/estimation`](/api-reference/gateway/all/estimate-transfer) endpoint can
be utilized by passing in the query parameter `enableForwarder=true`

```bash theme={null}
POST /v1/estimate?enableForwarder=true
```

Note that the `forwardingFee` includes the forwarding service and gas fees. If
the `maxFee` specified in the first burn intent is not enough to satisfy the
forwarding fee, the estimate endpoint will automatically bump up the max fee.

## Fee collection

Similar to the gas fee and transfer fee, forwarding fees will also be collected
when funds are burned on the source chain.

The forwarding fee collection process works as follows:

1. The forwarding fee is deducted from the `maxFee` of the burn intents in the
   order they were passed to the transfer endpoint.
2. The system will take up to the `maxFee` amount from the first burn intent to
   satisfy the forwarding fee.

**Example:**

If the forwarding fee is \$0.25 and the request contains three burn intents with
the following parameters:

* Burn intent 1: `maxFee` = \$0.30
  * Gas and transfer fees: \$0.08
  * Available for forwarding: \$0.22
* Burn intent 2: `maxFee` = \$0.15
  * Gas and transfer fees: \$0.05
  * Available for forwarding: \$0.10
* Burn intent 3: `maxFee` = \$0.25
  * Gas and transfer fees: \$0.06
  * Available for forwarding: \$0.19

The forwarding fee collection would work as follows:

1. \$0.22 is collected from burn intent 1's available `maxFee` after gas and
   transfer fees
2. \$0.03 is collected from burn intent 2's available `maxFee` to satisfy the
   remaining forwarding fee, totaling \$0.25
3. No forwarding fee is collected from burn intent 3 since the full forwarding
   fee has already been satisfied

Note that each burn intent's `maxFee` must first cover the gas and transfer fees
before any remaining amount can be applied to the forwarding fee.

## Automatic ATA creation for Solana

When the destination chain is Solana, the transfer `destinationRecipient` must
be an initialized USDC token account. If the recipient does not already have a
USDC token account, the Forwarding Service can create an Associated Token
Account (ATA) automatically as part of the mint transaction.

To enable automatic ATA creation, include `recipientSetupOptions` in each burn
intent that requires ATA creation in the
[`/transfer`](/api-reference/gateway/all/create-transfer-attestation) and
[`/estimate`](/api-reference/gateway/all/estimate-transfer) request bodies:

| Field                   | Type      | Description                                      |
| :---------------------- | :-------- | :----------------------------------------------- |
| `includeRecipientSetup` | `boolean` | Set to `true` to request ATA creation            |
| `recipientOwnerAddress` | `bytes32` | Recipient wallet address (hex-encoded, 32 bytes) |

The following example shows how to derive the ATA address, construct
`recipientSetupOptions`, and include it in the `/estimate` and `/transfer`
requests.

```typescript theme={null}
import { PublicKey } from "@solana/web3.js";
import { getAssociatedTokenAddressSync } from "@solana/spl-token";

const recipientWallet = new PublicKey("RecipientWalletAddress");
const USDC_MINT = new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");

// Derive the ATA address — use this as destinationRecipient in the transfer spec
const recipientAta = getAssociatedTokenAddressSync(USDC_MINT, recipientWallet);
const destinationRecipient =
  "0x" + Buffer.from(recipientAta.toBytes()).toString("hex");
const recipientWalletHex =
  "0x" + Buffer.from(recipientWallet.toBytes()).toString("hex");

// In the /estimate request body
const estimateRequest = [
  {
    spec: {
      // ... rest of the transfer spec
      destinationRecipient: destinationRecipient,
    },
    recipientSetupOptions: {
      includeRecipientSetup: true,
      recipientOwnerAddress: recipientWalletHex,
    },
  },
];

// In the /transfer request body
const transferRequest = [
  {
    burnIntent: {
      // ... rest of the burn intent
      spec: {
        // ... rest of the transfer spec
        destinationRecipient: destinationRecipient,
      },
      recipientSetupOptions: {
        includeRecipientSetup: true,
        recipientOwnerAddress: recipientWalletHex,
      },
    },
    signature,
  },
];
```

For a complete walkthrough, see
[Forward to a Solana destination with ATA creation](/gateway/howtos/forwarding-service#forward-to-a-solana-destination-with-ata-creation).

### Constraints

* `recipientSetupOptions` is only valid for requests using the Forwarding
  Service.
* The `destinationRecipient` must equal the ATA derived from the
  `recipientOwnerAddress` and the USDC token mint.
* The `recipientOwnerAddress` cannot be a Program Derived Account (PDA). The
  Forwarding Service only supports deriving ATAs from standard wallet addresses.

### ATA creation fees

When automatic ATA creation is enabled, the forwarding fee includes the Solana
rent cost for creating the token account. The
[`/estimate`](/api-reference/gateway/all/estimate-transfer) endpoint factors
this cost in automatically when `recipientSetupOptions` is provided. If multiple
burn intents reference the same `recipientOwnerAddress`, the ATA creation fee is
charged only once.


# Technical Guide for Gateway on Solana
Source: https://developers.circle.com/gateway/references/solana

Differences between Gateway on Solana and EVM

## Overview

The Solana Gateway protocol implementation is split into two programs:
`GatewayWallet` and `GatewayMinter`. To ensure alignment with EVM contracts'
logic and state, and to facilitate upgrades and maintenance, the code and state
of Solana programs reflect the EVM counterparts as closely as possible.

Key differences for Solana:

* Where canonical addresses are expected in the API, Solana addresses should be
  represented as base58.
* Where 32-byte addresses are expected in the API, Solana addresses should be
  represented as hex.
* All block height expiration fields in the API (such as `maxBlockHeight` and
  `expirationBlock`) refer to the last *slot* before the signed message is
  invalid.
* `BurnIntentSets` originating from Solana are not supported. Each transfer from
  Solana must be specified as a separate signed `BurnIntent`.
* Solana uses a reduced attestation format to accommodate transaction size
  limits.

## Message formats

Gateway on Solana uses the same message formats as on EVM for the
[`TransferSpec`](/gateway/references/technical-guide#transfer-specification) and
[`BurnIntent`](/gateway/references/technical-guide#burn-intent) messages. These
messages are described in the
[Gateway Technical Guide](/gateway/references/technical-guide).

Gateway on Solana uses a reduced attestation format to accommodate transaction
size limits.

For static Solana instruction and account definitions, use the onchain program
IDLs as the source of truth:

* [`GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
* [`GatewayMinter` IDL](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/idl)

This page provides high-level Solana-specific guidance, including signing rules,
integration constraints, and reduced attestation concepts.

### `ReducedMintAttestation`

A mint attestation contains the details needed for the `GatewayMinter` to mint.
Mint attestations on Solana use a "reduced" encoding to account for Solana's
transaction size limits. On Solana, all attestations are
`ReducedMintAttestationSets`. This reduces ambiguity when decoding
`MintAttestations` and saves transaction size on common fields between elements
that have been hoisted to the set level.

All integer fields in the reduced attestation encoding use big-endian byte
order. In Solana payout flows, the `destinationRecipient` field must contain the
initialized USDC token account or Associated Token Account that will receive the
mint, not the recipient wallet address.

#### Reduced attestation structure

The following tables are provided as implementation guidance for Solana reduced
attestation parsing. For canonical static program interfaces, rely on the
onchain IDLs.

#### Attestation set encoding

| Field                 | Offset | Bytes | Description                    |
| :-------------------- | :----- | :---- | :----------------------------- |
| `magic`               | 0      | 4     | `0x10cbb1ec`                   |
| `version`             | 4      | 4     | Protocol version               |
| `destinationDomain`   | 8      | 4     | Destination domain identifier  |
| `destinationContract` | 12     | 32    | Minter contract address        |
| `destinationCaller`   | 44     | 32    | Allowed caller address         |
| `maxBlockHeight`      | 76     | 8     | Expiration slot                |
| `numAttestations`     | 84     | 4     | Number of attestation elements |
| `attestations`        | 88     | var   | Array of attestation elements  |

#### Attestation element encoding

| Field                  | Offset | Bytes | Description                          |
| :--------------------- | :----- | :---- | :----------------------------------- |
| `destinationToken`     | 0      | 32    | Token address on destination         |
| `destinationRecipient` | 32     | 32    | Recipient address                    |
| `value`                | 64     | 8     | Amount to mint                       |
| `transferSpecHash`     | 72     | 32    | `keccak256` hash of the TransferSpec |
| `hookDataLength`       | 104    | 4     | Length of hook data                  |
| `hookData`             | 108    | var   | Hook data bytes                      |

Unlike standard `MintAttestation` messages, the `ReducedMintAttestation` does
not include the full `TransferSpec`. The `TransferSpec` hash is encoded directly
into the message and can be used as a unique crosschain identifier. Retrieve the
original `TransferSpec` through the
[Get transfer spec](/api-reference/gateway/all/get-transfer-spec) endpoint.

## Signing

### `BurnIntent` signing

Once a `BurnIntent` has been constructed, prepend the signing domain header
(`0xff000000000000000000000000000000`) before signing using the ed25519 keypair
associated with the source depositor. Alternatively, sign with a delegated
address.

| Field           | Offset | Bytes | Description                          |
| :-------------- | :----- | :---- | :----------------------------------- |
| `signingDomain` | 0      | 16    | `0xff000000000000000000000000000000` |
| `burnIntent`    | 16     | var   | Encoded `BurnIntent`                 |

The signing domain header ensures:

1. The signature cannot authorize a transaction due to illegal first byte
   (`0xff`).
2. The program can be upgraded to support
   [Off-Chain Message Signing Format (OCMSF)](https://docs.anza.xyz/proposals/off-chain-message-signing)
   without introducing ambiguity between signing payload types.

### `MintAttestation` signing

`ReducedMintAttestation` messages are signed by the Gateway API service using
EVM-style ECDSA signatures. The `keccak256` hash of the message is signed by the
Circle attestation signer according to
[EIP-191](https://eips.ethereum.org/EIPS/eip-191), using the `personal_sign`
(`0x45`) format.

## Transaction size limits

Solana transactions can be at most 1232 bytes. To maximize composability of
`gatewayMint` instructions, the protocol minimizes the data size needed to
execute mints. The `ReducedMintAttestation` message reduces the size of the
original `MintAttestation` designed for EVM by removing fields that do not need
to be validated on the destination chain. The parameter mode for `gatewayMint`
further reduces redundancy by inferring data from the execution context or
account list.

To ensure that USDC supply can be maintained 1:1, the Gateway Transfer API
rejects user `BurnIntents` that are too large to be safely executed on Solana.
Verify your transaction sizes before broadcasting transactions using the
`gatewayMint` instruction.

### Executing large mint attestations

You can execute large `MintAttestations` that exceed the transaction size limit,
as long as strict atomicity is not required. Deploy a separate program that
writes `MintAttestation` data into a buffer account across multiple
transactions. Once the message has been written to the buffer account, this
program can execute a cross-program invocation (CPI) into the Gateway Minter
program, passing in the `MintAttestation` bytes from the buffer account as an
argument. CPI calls can be at most 10 \* 1024 bytes.


# Solana Programs and Interfaces for Gateway
Source: https://developers.circle.com/gateway/references/solana-programs



The wallet and minter programs have a set of accounts and instructions that you
can use to build with Gateway on Solana. The following sections describe the
main [Program Derived Account (PDA) structures](#program-derived-account-pdas)
and [instructions](#instructions) for the Gateway programs.

For static Solana accounts, instruction arguments, and instruction definitions,
use the onchain IDLs as the source of truth. This page adds high-level Gateway
guidance and documents the dynamic `gatewayMint` remaining accounts that are not
represented statically in the IDL.

## Mainnet program addresses

| Program         | Address                                                                                                                                   |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `GatewayWallet` | [`GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ`](https://solscan.io/account/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ?cluster=mainnet) |
| `GatewayMinter` | [`GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ`](https://solscan.io/account/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ?cluster=mainnet) |

## Devnet program addresses

| Program         | Address                                                                                                                                  |
| :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `GatewayWallet` | [`GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu`](https://solscan.io/account/GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu?cluster=devnet) |
| `GatewayMinter` | [`GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr`](https://solscan.io/account/GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr?cluster=devnet) |

## Account structures

The following section describes the main Program Derived Account (PDA)
structures for the Gateway programs. You can find the full IDLs for the Gateway
Solana programs at the following links:

* [`GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
* [`GatewayMinter` IDL](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/idl)

### `GatewayDeposit`

A Gateway Wallet data account used to track the balance of a particular
depositor and token.

| Parameter            | Type     | Description                                             |
| -------------------- | -------- | ------------------------------------------------------- |
| `bump`               | `u8`     | The bump seed for the GatewayDeposit PDA.               |
| `depositor`          | `Pubkey` | The depositor of the GatewayDeposit.                    |
| `token_mint`         | `Pubkey` | The mint of the token being deposited.                  |
| `available_amount`   | `u64`    | The available amount of the token.                      |
| `withdrawing_amount` | `u64`    | The amount of the token pending withdrawal.             |
| `withdrawal_block`   | `u64`    | The block number at which the withdrawal was initiated. |

### `GatewayDelegate`

A Gateway Wallet data account used to store delegates.

| Parameter            | Type             | Description                                           |
| -------------------- | ---------------- | ----------------------------------------------------- |
| `bump`               | `u8`             | The bump seed for the GatewayDelegate PDA.            |
| `status`             | `DelegateStatus` | The status of the delegate.                           |
| `closeable_at_block` | `u64`            | The block number at which the delegate can be closed. |
| `token`              | `Pubkey`         | The mint of the token being delegated.                |
| `depositor`          | `Pubkey`         | The depositor of the delegate.                        |
| `delegate`           | `Pubkey`         | The delegate address.                                 |

### `Denylist`

A Gateway Wallet data account used to store a single denylisted account. The
address being denylisted is implied in the PDA address, and the account itself
stores no additional data.

### `UsedTransferSpecHash`

A Gateway Wallet data account used to store whether a `TransferSpecHash` has
been used, to prevent replay. The used `TransferSpecHash` is implied in the PDA
address, and the account itself stores no additional data.

## PDA derivation

The following PDAs are used by the Gateway Solana programs. Seed bytes are ASCII
strings unless otherwise noted.

### `GatewayWallet` program PDAs

| PDA                    | Program         | Seeds                                                   |
| ---------------------- | --------------- | ------------------------------------------------------- |
| `GatewayWallet`        | `GatewayWallet` | `["gateway_wallet"]`                                    |
| `GatewayWalletCustody` | `GatewayWallet` | `["gateway_wallet_custody", token_mint]`                |
| `GatewayDeposit`       | `GatewayWallet` | `["gateway_deposit", token_mint, depositor]`            |
| `Denylist`             | `GatewayWallet` | `["denylist", account]`                                 |
| `GatewayDelegate`      | `GatewayWallet` | `["gateway_delegate", token_mint, depositor, delegate]` |

### `GatewayMinter` program PDAs

| PDA                    | Program         | Seeds                                             |
| ---------------------- | --------------- | ------------------------------------------------- |
| `GatewayMinter`        | `GatewayMinter` | `["gateway_minter"]`                              |
| `GatewayMinterCustody` | `GatewayMinter` | `["gateway_minter_custody", token_mint]`          |
| `UsedTransferSpecHash` | `GatewayMinter` | `["used_transfer_spec_hash", transfer_spec_hash]` |

### `GatewayMinter`

Stores general configuration for the GatewayMinter program.

| Parameter                     | Type          | Description                                           |
| ----------------------------- | ------------- | ----------------------------------------------------- |
| `bump`                        | `u8`          | The bump seed for the GatewayMinter PDA.              |
| `owner`                       | `Pubkey`      | The owner of the GatewayMinter.                       |
| `pending_owner`               | `Pubkey`      | The pending owner of the GatewayMinter.               |
| `pauser`                      | `Pubkey`      | The pauser of the GatewayMinter.                      |
| `token_controller`            | `Pubkey`      | The token controller of the GatewayMinter.            |
| `paused`                      | `bool`        | Whether the GatewayMinter is paused.                  |
| `enabled_attesters`           | `Vec<Pubkey>` | The enabled attesters of the GatewayMinter.           |
| `local_domain`                | `u32`         | The local domain of the GatewayMinter.                |
| `version`                     | `u32`         | The version of the GatewayMinter.                     |
| `supported_tokens`            | `Vec<Pubkey>` | The supported tokens of the GatewayMinter.            |
| `custody_token_account_bumps` | `Vec<u8>`     | The custody token account bumps of the GatewayMinter. |

### `GatewayWallet`

Stores general configuration for the GatewayWallet program.

| Parameter                     | Type          | Description                                           |
| ----------------------------- | ------------- | ----------------------------------------------------- |
| `bump`                        | `u8`          | The bump seed for the GatewayWallet PDA.              |
| `owner`                       | `Pubkey`      | The owner of the GatewayWallet.                       |
| `pending_owner`               | `Pubkey`      | The pending owner of the GatewayWallet.               |
| `pauser`                      | `Pubkey`      | The pauser of the GatewayWallet.                      |
| `denylister`                  | `Pubkey`      | The denylister of the GatewayWallet.                  |
| `token_controller`            | `Pubkey`      | The token controller of the GatewayWallet.            |
| `fee_recipient`               | `Pubkey`      | The fee recipient of the GatewayWallet.               |
| `local_domain`                | `u32`         | The local domain of the GatewayWallet.                |
| `version`                     | `u32`         | The version of the GatewayWallet.                     |
| `withdrawal_delay`            | `u64`         | The withdrawal delay of the GatewayWallet.            |
| `paused`                      | `bool`        | Whether the GatewayWallet is paused.                  |
| `supported_tokens`            | `Vec<Pubkey>` | The supported tokens of the GatewayWallet.            |
| `custody_token_account_bumps` | `Vec<u8>`     | The custody token account bumps of the GatewayWallet. |
| `burn_signers`                | `Vec<Pubkey>` | The burn signers of the GatewayWallet.                |

## Instructions

The following section describes the main instructions for the Gateway programs.
Instruction data uses Anchor-style `Borsh` encoding.

### `gatewayMint`

Mints tokens to a recipient on Solana based on a signed attestation produced by
the Gateway API. The instruction supports two parameter encodings:

* **Full attestation mode**: Pass the full ReducedMintAttestation message and
  its ECDSA signature as returned by the Transfer API.
* **Parameter mode**: Pass only the minimal fields that cannot be inferred
  onchain; the program reconstructs the attestation and verifies the ECDSA
  signature against it.

For the static instruction definition, refer to the
[onchain `GatewayMinter` IDL](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/idl).
The remaining accounts described below are dynamic and therefore are not
captured statically in the IDL.

#### Account list

The Gateway Mint flow uses fixed program accounts together with three additional
ordered accounts for each transfer in the attestation. Refer to the
[onchain IDL](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/idl)
for the canonical static account list.

<Info>
  For transfers to Solana, the `destinationRecipient` must be an initialized
  USDC Token Account. If the intended recipient is a standard wallet address,
  consider setting the `destinationRecipient` to its Associated Token Account
  (ATA) not the recipient wallet address. See the [Solana Technical
  Guide](/gateway/references/solana#reducedmintattestation) and [Solana Programs
  and Interfaces](/gateway/references/solana-programs#gatewaymint) for
  high-level Solana guidance and `gatewayMint` account requirements. Use the
  onchain IDLs linked from [Solana Programs and
  Interfaces](/gateway/references/solana-programs#account-structures) as the
  canonical static instruction and account definitions.
</Info>

| Parameter            | Type                     | Description                                |
| -------------------- | ------------------------ | ------------------------------------------ |
| `payer`              | `Signer`                 | The payer of the transaction.              |
| `destination_caller` | `Signer`                 | The destination caller of the transaction. |
| `gateway_minter`     | `Account<GatewayMinter>` | The GatewayMinter account.                 |
| `system_program`     | `Program<System>`        | The System program.                        |
| `token_program`      | `Program<Token>`         | The Token program.                         |

Three additional ordered accounts are required in the remaining accounts list
for each transfer in the attestation:

| Parameter                    | Type                            | Description                                                 |
| ---------------------------- | ------------------------------- | ----------------------------------------------------------- |
| `custody_token_account`      | `Account<TokenAccount>`         | The custody token account of the token used in the transfer |
| `destination_recipient`      | `Account<TokenAccount>`         | The destination recipient token account of the transfer     |
| `transfer_spec_hash_account` | `Account<UsedTransferSpecHash>` | The transfer spec hash account                              |

In the common direct-mint flow, `destination_caller` is the transaction sender
and usually matches `payer`. If the attestation sets a non-zero
`destinationCaller`, it must match the signer that submits the mint transaction.

#### Full attestation mode (`gateway_mint`)

Pass the full reduced attestation bytes and signature returned by the Transfer
API. Refer to the
[onchain IDL](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/idl)
for the canonical static argument definitions for `gateway_mint` and
`gateway_mint_with_params`.

#### Parameter mode (`gateway_mint_with_params`)

Saves transaction space by assuming certain fields or reading them from the
account list. Refer to the
[onchain IDL](https://explorer.solana.com/address/GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ/idl)
for the canonical static argument definitions for `gateway_mint_with_params` and
`MintAttestationParams`.

### `deposit`

Deposits tokens into the Gateway Wallet system.

* **Deposit mode**: Deposits tokens on behalf of the signer. The tokens are
  transferred from the signer's token account to the Gateway Wallet custody and
  tracked in the signer's balance.
* **Deposit For mode**: Deposits tokens on behalf of another depositor. The
  tokens are transferred from the signer's token account to the Gateway Wallet
  custody and tracked in the specified depositor's balance.

Refer to the
[onchain `GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
for the canonical static account and argument definitions for `deposit` and
`depositFor`.

### `initiateWithdrawal`

Starts the withdrawal process. After a program-defined `withdrawal_delay` (in
slots), `withdraw` may be called to complete the withdrawal. Repeated calls add
to the amount and reset the delay timer.

Refer to the
[onchain `GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
for the canonical static account and argument definitions for
`initiateWithdrawal`.

### `withdraw`

Completes a withdrawal that was initiated at least `withdrawal_delay` earlier.
The full pending amount is withdrawn to the depositor's token account.

Refer to the
[onchain `GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
for the canonical static account definitions for `withdraw`.

### `addDelegate`

Allows a delegate to transfer the caller's balance for the specified token.

Refer to the
[onchain `GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
for the canonical static account and argument definitions for `addDelegate`.

### `removeDelegate`

Revokes a previously granted delegate for the caller's balance of the specified
token.

<Note>
  Revocation is respected by the Gateway API, which refuses BurnIntents signed by
  a revoked delegate. However, revocation does not prevent a BurnIntent signed by
  the delegate from being executed onchain. This design prevents malicious users
  from blocking a burn transaction by pre-emptively revoking a signer.
</Note>

Refer to the
[onchain `GatewayWallet` IDL](https://explorer.solana.com/address/GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ/idl)
for the canonical static account and argument definitions for `removeDelegate`.


# Gateway Supported Blockchains
Source: https://developers.circle.com/gateway/references/supported-blockchains

List of blockchains that Gateway supports

Gateway supports a subset of blockchains where USDC is natively issued. The
following sections show the chains that Gateway supports.

Circle identifies each blockchain by a numeric domain identifier. These domain
identifiers are not tied to any existing public chain ID. Gateway uses the same
domain identifiers as [CCTP](/cctp/cctp-supported-blockchains).

## Testnet

| Blockchain          | Domain | Nanopayments | `SupportedChainName` |
| ------------------- | ------ | ------------ | -------------------- |
| Arc Testnet         | 26     | Yes          | `arcTestnet`         |
| Arbitrum Sepolia    | 3      | Yes          | `arbitrumSepolia`    |
| Avalanche Fuji      | 1      | Yes          | `avalancheFuji`      |
| Base Sepolia        | 6      | Yes          | `baseSepolia`        |
| Ethereum Sepolia    | 0      | Yes          | `sepolia`            |
| HyperEVM Testnet    | 19     | Yes          | `hyperEvmTestnet`    |
| OP Sepolia          | 2      | Yes          | `optimismSepolia`    |
| Polygon Amoy        | 7      | Yes          | `polygonAmoy`        |
| Sei Atlantic        | 16     | Yes          | `seiAtlantic`        |
| Solana Devnet       | 5      | No           |                      |
| Sonic Testnet       | 13     | Yes          | `sonicTestnet`       |
| Unichain Sepolia    | 10     | Yes          | `unichainSepolia`    |
| World Chain Sepolia | 14     | Yes          | `worldChainSepolia`  |

## Mainnet

| Blockchain  | Domain | Nanopayments |
| ----------- | ------ | ------------ |
| Arbitrum    | 3      | Yes          |
| Avalanche   | 1      | Yes          |
| Base        | 6      | Yes          |
| Ethereum    | 0      | Yes          |
| HyperEVM    | 19     | Yes          |
| OP          | 2      | Yes          |
| Polygon PoS | 7      | Yes          |
| Sei         | 16     | Yes          |
| Solana      | 5      | No           |
| Sonic       | 13     | Yes          |
| Unichain    | 10     | Yes          |
| World Chain | 14     | Yes          |

## Required block confirmations

Before updating the unified USDC balance or issuing
[attestations](/gateway/references/technical-guide#attestation), the Gateway API
waits for a specific number of block confirmations so that the deposit
transaction is unlikely to be reverted.

The following table shows the number of block confirmations and the average time
to attestation for each supported chain. The average time to attestation is the
time it takes for a transaction to be included in a block and confirmed by the
network.

| Blockchain  | Number of blocks | Average time       |
| ----------- | ---------------- | ------------------ |
| Arbitrum    | \~65 ETH blocks  | \~13 to 19 minutes |
| Arc Testnet | \~1              | \~0.5 seconds      |
| Avalanche   | 1                | \~8 seconds        |
| Base        | \~65 ETH blocks  | \~13 to 19 minutes |
| Ethereum    | \~65             | \~13 to 19 minutes |
| HyperEVM    | \~1              | \~5 seconds        |
| OP          | \~65 ETH blocks  | \~13 to 19 minutes |
| Polygon PoS | \~2-3            | \~8 seconds        |
| Sei         | \~1              | \~5 seconds        |
| Solana      | \~2-3            | \~8 seconds        |
| Sonic       | \~1              | \~8 seconds        |
| Unichain    | \~65 ETH blocks  | \~13 to 19 minutes |
| World Chain | \~65 ETH blocks  | \~13 to 19 minutes |

## Fast deposits

Some deposit times may be too long for certain use cases. Third parties may
offer alternative methods for depositing funds into Gateway with faster deposit
times. For example, [Eco](https://www.eco.com) offers a
[Gateway deposit service](https://eco.com/docs/getting-started/programmable-addresses/gateway-deposits).
Circle does not endorse, maintain, or audit Eco or any other similar third-party
service. Use of any such third-party service involves risks, and you are solely
responsible for conducting your own diligence and reviewing the applicable terms
and conditions before using such service. This guide is provided solely for
informational purposes and may become outdated.


# Gateway Technical Guide
Source: https://developers.circle.com/gateway/references/technical-guide



Circle Gateway consists of
[two smart contracts](/gateway/references/contract-addresses) (each deployed on
multiple chains), and an offchain system. Users deposit USDC into Gateway Wallet
contracts on any supported source chain. Once their deposits are finalized, they
can instantly transfer their USDC to a destination chain through an API call,
followed by a contract call to the Gateway Minter on the destination chain. The
contracts, together with the offchain system, ensure the integrity of the USDC
supply and prevent double-spending.

Compared to [CCTP](/cctp), Gateway allows users to front-load the finalization
wait time rather than requiring finality in the middle of a transfer flow. This
enables users to use all of their USDC instantly on any chain (even in amounts
exceeding the balance held on any single chain), without needing to decide
beforehand what amount or destination is needed. As such, it is optimized for
use-cases requiring capital efficiency, low latency, and chain abstraction.

## Gateway Wallet contracts

The wallet contract accepts deposits from users via direct transfer, EIP-2612
permit, or ERC-3009 authorization. It's deployed to multiple chains so users can
deposit from whatever source chain they hold USDC on. The contract is
non-custodial, meaning users always have full control over their USDC and Circle
can't transfer or burn any USDC without explicit user authorization. Once USDC
is deposited and the deposit events are finalized onchain, the USDC can be used
crosschain.

To preserve the non-custodial nature of the USDC held in the Gateway Wallet
contract, there is a trustless withdrawal mechanism that may be used in the
unlikely event that Circle's APIs are down for an extended period or service is
otherwise unavailable. To withdraw USDC onchain with no API interaction, users
must first initiate a withdrawal with a transaction, wait for a 7-day withdrawal
delay period, and then the user may complete the withdrawal and receive the
USDC. This delay is what allows the Gateway System to safely issue attestations
to instantly transfer USDC to other chains, since it guarantees that there is
sufficient time to submit the corresponding burn transaction.

## Gateway Minter contracts

The
[minter contract](/gateway/references/contract-interfaces-and-events#gatewayminter)
accepts attestations signed by the Gateway System and mints USDC to the
specified destination. It's also deployed to multiple chains, including chains
that may not yet support the wallet contract.

## Gateway system

Circle runs an offchain, automated system that serves an API for user
interaction, observes onchain events, and ensures that every mint on a
destination chain corresponds 1:1 with a burn on each source chain.

### Balances

At the center of the system is an offchain ledger that represents the USDC
balances that are deposited and are available for use in instant transfers.
These balances are tracked for every combination of chain, token, and address.
They're eventually consistent with onchain state, where safety is ensured by
mechanisms built into the wallet contract.

### Inputs

The following table describes the main inputs to the Gateway System, along with
what it does in response to each.

| Input                                 | Response                             |
| ------------------------------------- | ------------------------------------ |
| `Deposit` event                       | Increment balance                    |
| Transfer request (attestation issued) | Decrement balance                    |
| `AttestationUsed` event               | Submit burn intents to source chains |
| Attestation expires unused            | Increment balance                    |
| `WithdrawInitiated` event             | Decrement balance                    |

All onchain events are only observed as they're finalized. See
[Required block confirmations](/gateway/references/supported-blockchains#required-block-confirmations)
for the details on finality on each supported chain.

## Core primitives

The contracts and API share a set of primitives that are used to represent
transfers consistently, both when interacting with the API and as inputs to the
smart contracts. There is also a byte encoding for each that's used across
chains. See the
[source code of the EVM contracts](https://github.com/circlefin/evm-gateway-contracts)
for details about widths, offsets, and type markers.

<Note>
  Solana uses different message encodings and signing requirements to accommodate
  transaction size limits. See
  [Solana programs and interfaces](/gateway/references/solana-programs) for
  Solana-specific details.
</Note>

### Transfer specification

A
[transfer specification](https://github.com/circlefin/evm-gateway-contracts/blob/master/src/lib/TransferSpec.sol)
describes everything about a transfer from one domain to another. It's embedded
in the other two primitives, and its `keccak256` hash is used as a crosschain
identifier and replay protection.

**`TransferSpec`**

| Field                  | Description                                                                   |
| ---------------------- | ----------------------------------------------------------------------------- |
| `version`              | The protocol version, used for forward compatibility. Always set to 1.        |
| `sourceDomain`         | The domain of the wallet contract from which this transfer came               |
| `destinationDomain`    | The domain of the minter contract from which this transfer is valid           |
| `sourceContract`       | The address of the wallet contract on the source domain                       |
| `destinationContract`  | The address of the minter contract on the destination domain                  |
| `sourceToken`          | The token address on the source domain                                        |
| `destinationToken`     | The token address on the destination domain                                   |
| `sourceDepositor`      | The address to debit in the wallet contract on the source domain              |
| `destinationRecipient` | The address to receive the USDC on the destination domain                     |
| `sourceSigner`         | The signer who signed for the transfer (may be the same as `sourceDepositor`) |
| `destinationCaller`    | The address of the caller who may use the attestation (0 for any caller)      |
| `value`                | The amount to be transferred                                                  |
| `salt`                 | An arbitrary value that can make the transfer spec hash unique                |
| `hookData`             | Arbitrary bytes that may be used for onchain composition                      |

### Burn intent

A
[burn intent](https://github.com/circlefin/evm-gateway-contracts/blob/master/src/lib/BurnIntents.sol)
is constructed and signed by the user, and provided to the Gateway API during a
transfer request. This is used to authenticate the user (since it must be signed
by the address specified in the `sourceSigner` field of the transfer spec) as
well as to declare the parameters of the desired transfer.

**`BurnIntent`**

| Field            | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `maxBlockHeight` | The expiration block height on the source chain            |
| `maxFee`         | The maximum fee that may be collected by Circle            |
| `spec`           | The transfer specification describing the desired transfer |

<Note>
  **Note**: When Arbitrum is the source chain, the `maxBlockHeight` in the burn
  intent should be in terms of the **Ethereum L1 block height**. Refer to the
  [Arbitrum
  Docs](https://docs.arbitrum.io/build-decentralized-apps/arbitrum-vs-ethereum/block-numbers-and-time)
  to learn more about Arbitrum's behavior around block height.
</Note>

<Note>
  **Note**: When Solana is the source chain, `maxBlockHeight` refers to the last
  slot before the signed message is invalid.
</Note>

This user-signed payload is what Gateway System uses to prove to the wallet
contract on the source chain that the user intended to make the specified
transfer. Without this user signature, Circle is unable to unilaterally burn or
transfer user assets from the wallet contract to complete the transfer loop. To
further cement the non-custodial nature of the wallet contract, burn intents
expire so that the Gateway System doesn't hold "active" intents for long.

At the time of the transfer request, the Gateway System verifies that the user's
signature is valid, that the expiry block is sufficiently far in the future (at
least the wallet's `withdrawalDelay` from the current block), and that the fee
is sufficient to cover both the gas for the burn transaction and the transfer
fee.

If multiple burn intents share a common `sourceSigner` and the relevant chains
all share the same signature scheme (such as multiple EVM chains), burn intents
may be packed together into a burn intent set and signed as a single payload:

**`BurnIntentSet`**

| Field     | Description                                            |
| --------- | ------------------------------------------------------ |
| `intents` | An array of burn intents describing multiple transfers |

<Note>
  **Note**: You can include a maximum of 16 burn intents in a single transfer
  request. The Gateway API returns a `400` error for requests that include more
  than 16 burn intents.
</Note>

<Note>
  **Note**: Burn intent sets are only supported on EVM chains. On Solana, each
  transfer must be specified as a separate signed `BurnIntent`. See [Solana
  programs and interfaces](/gateway/references/solana-programs) for details.
</Note>

For EVM chains, this structure is signed as EIP-712 typed data. For other
chains, it's signed in its byte-encoded form. Because the Gateway System needs
to statically verify the signature offchain and guarantee that the signature is
still be valid at the time of the burn transaction, only EOA signatures are
accepted. To use Gateway with SCAs, the SCA must add an EOA as a delegate that
may sign transfer requests (see below for more details).

### Attestation

An
[attestation](https://github.com/circlefin/evm-gateway-contracts/blob/master/src/lib/Attestations.sol)
is constructed and signed by the Gateway System in response to a transfer
request. It proves to the minter contract that at the time of the transfer
request, the user had a sufficient balance in the wallet contracts and all other
details of the transfer were valid, so the mint is safe to perform. Attestations
expire after 10 minutes.

**`Attestation`**

| Field            | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `maxBlockHeight` | The expiration block height on the destination chain       |
| `spec`           | The transfer specification describing the desired transfer |

<Note>
  **Note**: When Arbitrum is the destination chain, the `maxBlockHeight` in the
  attestation is returned in terms of the **Ethereum L1 block height**. Refer to
  the [Arbitrum
  Docs](https://docs.arbitrum.io/build-decentralized-apps/arbitrum-vs-ethereum/block-numbers-and-time)
  to learn more about Arbitrum's behavior around block height.
</Note>

The transfer specification contained in an attestation is identical to what was
signed by the user. Because of this, its `keccak256` hash is emitted during the
mint transaction and the same hash is emitted during the corresponding burn
transaction. This allows for crosschain traceability and reconciles the 1:1
relationship between mints and burns in the system.

When a transfer involves multiple source domains (such as when the user passes a
burn intent set or multiple standalone burn intents), the Gateway System
constructs and signs an attestation set:

**`AttestationSet`**

| Field          | Description                                            |
| -------------- | ------------------------------------------------------ |
| `attestations` | An array of attestations describing multiple transfers |

While events are emitted for each attestation contained in a set, the entire
transaction is atomic and only one mint (of the total value of all contained
attestations) happens during the transaction.

## Key operations

The Gateway System supports the following key operations.

### Deposit

To deposit USDC into the Gateway System, users may choose between several
onchain deposit methods:

| Method                                                 | Description                                                            |
| ------------------------------------------------------ | ---------------------------------------------------------------------- |
| [`deposit`][deposit]                                   | Deposit to the contract after granting an allowance for the token      |
| [`depositFor`][depositFor]                             | Same as `deposit`, but credit the USDC to another depositor's balance  |
| [`depositWithPermit`][depositWithPermit]               | Deposit using a signed EIP-2612 permit (credited to the signer)        |
| [`depositWithAuthorization`][depositWithAuthorization] | Deposit using a signed ERC-3009 authorization (credited to the signer) |

[deposit]: /gateway/references/contract-interfaces-and-events#deposit

[depositFor]: /gateway/references/contract-interfaces-and-events#depositfor

[depositWithPermit]: /gateway/references/contract-interfaces-and-events#depositwithpermit

[depositWithAuthorization]: /gateway/references/contract-interfaces-and-events#depositwithauthorization

<Warning>
  **Warning:** Directly transferring USDC to the Gateway Wallet contract with a
  standard ERC-20 transfer will result in loss of that USDC. You must use one of
  the deposit methods on the wallet contract to get a unified USDC balance.
</Warning>

It's important to note that before deposited USDC shows up in the Gateway System
and may be used for transfers, the deposit transactions must be finalized
onchain. See
[Required block confirmations](/gateway/references/supported-blockchains#required-block-confirmations)
for more details about what's considered finalized on each supported chain.

### Check balances

Use the `/v1/balances` endpoint of the API to check the latest available balance
recorded by the Gateway System. These balances are what's available to be
instantly transferred using a transfer request.

### Check pending deposits

Use the [`/v1/deposits`](/api-reference/gateway/all/get-deposits) endpoint to
check pending deposits. A deposit is in `pending` state when the user has
submitted the deposit transaction but it has not yet been processed by the
Gateway service.

### Instant transfer

First, construct a burn intent or burn intent set describing the desired
transfer. Sign it with the address that owns the USDC or is an authorized
delegate (see below for more information about delegates).

Pass the burn intents to the `/v1/transfer` endpoint of the API to request an
attestation from the Gateway System. If the transfer is valid and the request is
not forwarded, the API responds with top-level `attestation` and `signature`
fields for the destination domain.

Forwarded requests may omit those fields. To retrieve the richer transfer
record, including `burnIntents` and nested `attestation.payload` and
`attestation.signature` fields, use
[`GET /v1/transfer/{id}`](/api-reference/gateway/all/get-transfer-by-id).

Next, make a contract call to the minter contract on the destination chain using
the attestation and signature when mint submission is not being forwarded. To
atomically compose this mint with other onchain actions, use a multi-call
contract.

Note that if `destinationCaller` is specified in any of the transfer specs, it
must match the sender of the transaction (this can be used to prevent
front-running a mint when it's intended to be composed with other actions in the
same transaction).

The Gateway System ensures that if an attestation is used, the corresponding
burn transaction is submitted to all involved source chains.

### Withdrawal

There are two ways to remove USDC from the Gateway system:
[instant transfers](#instant) and [trustless withdrawals](#trustless).

#### Instant

The destination chain of a transfer may be the same as the source chain. This
means that to withdraw USDC from the wallet contract on the same chain, the
transfer flow described in the preceding section applies. The only
[fee](/gateway/references/fees) for same-chain withdrawals is to cover gas for
the burn transaction (no other transfer fee is charged).

The reason same-chain withdrawals still involve a mint and burn rather than just
a transfer out of the wallet contract is to ensure that there are no methods of
removing USDC from the wallet contract that don't involve a user signature.

#### Trustless

In the unlikely event that Circle's APIs are down for an extended period or
service is unavailable for any other reason, users can trustlessly withdraw USDC
with a delay.

First, make a contract call to the
[`initiateWithdrawal`](/gateway/references/contract-interfaces-and-events#initiatewithdrawal)
method with the desired amount to withdrawal. After a delay of 7 days, make a
contract call to the
[`withdraw`](/gateway/references/contract-interfaces-and-events#withdraw) method
to complete the withdrawal.

### Delegates

Because the Gateway System needs to statically verify the signature on all burn
intents without involving any onchain state and guarantee that the signature is
valid at the time of the burn transaction, SCA signatures such as EIP-1271
signatures can't be accepted. Burn intents must be signed by an EOA.

There is a
[delegate mechanism](https://github.com/circlefin/evm-gateway-contracts/blob/master/src/modules/wallet/Delegation.sol)
built into Gateway that allows SCAs to make use of the protocol. Any user can
add one or more other addresses that are allowed to sign transfer requests on
their behalf. This acts as a full allowance for the deposited USDC.

These delegate addresses should be EOAs capable of producing a valid ECDSA
signature to be effective. For EOAs that have upgraded to SCAs using EIP-7702,
this delegation is unnecessary, since there is still an underlying EOA that can
produce the necessary signature directly.

#### Adding a delegate

To add a delegate, use the
[`addDelegate`](/gateway/references/contract-interfaces-and-events#adddelegate)
method on the wallet contract. This needs to be done for each wallet contract
where the depositor address holds USDC across all chains.

#### Removing a delegate

To remove a delegate (for key rotation or other purposes), use the
[`removeDelegate`](/gateway/references/contract-interfaces-and-events#removedelegate)
method of the wallet contract. This needs to be done for each wallet contract
where the depositor address holds USDC across all chains.

Note that when delegates are removed, signatures they produced are still valid
for the purpose of fulfilling burn intents onchain. This ensures that burns may
be executed safely even in the event of a revocation. The API still reflects
revocations as soon as they're finalized onchain.

## Security audit

The Gateway smart contracts have been independently audited by two third-party
security firms:

* [ChainSecurity audit report](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/CCTP/%5BPublic%5D%20%5BChainSecurity%5D%20Circle_Gateway_audit.pdf)
* [OtterSec audit report](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/Circle%20Gateway%20Audit%20-%20OtterSec%20-%207-21-2025.pdf)


# Gateway Webhook Events
Source: https://developers.circle.com/gateway/references/webhook-events

Reference for Gateway webhook event types, payload schemas, and example notifications.

Gateway sends webhooks for events on registered wallet addresses. All webhooks
use the V2 notification format. The `notificationType` field names the event,
and the `notification` field contains event data.

```json theme={null}
{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notificationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "notificationType": "gateway.deposit.finalized",
  "notification": {
    "...": "Event-specific data. Schema varies by notificationType."
  },
  "timestamp": "2026-04-22T12:00:00.000000000Z",
  "version": 2
}
```

## Deposit events

### `gateway.deposit.finalized`

Fires after tokens are deposited into a Gateway Wallet, the onchain transaction
is finalized, and Gateway processes the deposit.

### Payload fields

| Field           | Type   | Description                                                                                               |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `id`            | string | Unique notification identifier                                                                            |
| `walletAddress` | string | Registered wallet address that owns the funds.                                                            |
| `domain`        | string | Chain domain identifier (for example, `"0"` for Ethereum)                                                 |
| `env`           | string | Network environment: `"testnet"` or `"mainnet"`                                                           |
| `tokenAddress`  | string | Token contract address                                                                                    |
| `amount`        | string | Transfer amount in decimal format (for example, `"1.000000"` for 1 token)                                 |
| `from`          | string | Address that initiated the onchain deposit. May be the wallet owner or a delegate acting on their behalf. |
| `to`            | string | Destination address                                                                                       |
| `txHash`        | string | Onchain transaction hash                                                                                  |

### Example: `gateway.deposit.finalized`

```json theme={null}
{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notificationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "notificationType": "gateway.deposit.finalized",
  "notification": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "walletAddress": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
    "domain": "0",
    "env": "mainnet",
    "tokenAddress": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "amount": "1000.000000",
    "from": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
    "to": "0x19330d10d9cc8751218eaf51e8885d058642e08a",
    "txHash": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b"
  },
  "timestamp": "2026-04-22T12:05:00.000000000Z",
  "version": 2
}
```

## Mint events

The `gateway.mint.finalized` and `gateway.mint.forwarded` events share a payload
schema. Mint event payloads include an `attestations` array. Each burn intent in
a transfer maps to one attestation entry. A single transfer can include multiple
burn intents, each with its own recipient and amount.

### `gateway.mint.finalized`

Fires when an attestation is used and tokens are minted on the destination
blockchain. The `wasForwarded` field shows whether the transfer used the
[forwarding service](/gateway/references/forwarding-service).

### `gateway.mint.forwarded`

Fires when a forwarded mint relay is confirmed. This event only occurs for
transfers that use the
[forwarding service](/gateway/references/forwarding-service).

### Payload fields

| Field           | Type    | Description                                                                               |
| --------------- | ------- | ----------------------------------------------------------------------------------------- |
| `transferId`    | string  | Transfer identifier (attestation group ID)                                                |
| `txHash`        | string  | Onchain transaction hash on the destination blockchain                                    |
| `walletAddress` | string  | The depositor that owns the funds on the source chain                                     |
| `domain`        | string  | Blockchain domain identifier for the destination blockchain (for example, `"7"` for Base) |
| `env`           | string  | Network environment: `"testnet"` or `"mainnet"`                                           |
| `tokenAddress`  | string  | Token contract address on the destination blockchain                                      |
| `wasForwarded`  | boolean | Whether the transfer used the forwarding service (`gateway.mint.finalized` only)          |
| `attestations`  | array   | Array of attestation details (see below)                                                  |

**Attestation fields**

| Field              | Type   | Description                                                            |
| ------------------ | ------ | ---------------------------------------------------------------------- |
| `from`             | string | The depositor address that triggered the burn on the source blockchain |
| `to`               | string | Recipient address for this attestation                                 |
| `amount`           | string | Amount in decimal format (for example, `"1.000000"` for 1 token)       |
| `transferSpecHash` | string | Transfer specification hash for this attestation                       |

### Example: `gateway.mint.finalized`

```json theme={null}
{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notificationId": "f6a7b890-1234-5678-cdef-901234567890",
  "notificationType": "gateway.mint.finalized",
  "notification": {
    "transferId": "a7b89012-3456-7890-abcd-ef1234567890",
    "txHash": "0x1ea922932e2bbefab697b931aa423a6ebe4a683947a5bd105bb38958e52017a5",
    "walletAddress": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
    "domain": "7",
    "env": "mainnet",
    "tokenAddress": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "wasForwarded": false,
    "attestations": [
      {
        "from": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
        "to": "0x7777777700000000000000000000000000000001",
        "amount": "93516.491888",
        "transferSpecHash": "0x4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b"
      }
    ]
  },
  "timestamp": "2026-04-22T12:10:00.000000000Z",
  "version": 2
}
```

### Example: `gateway.mint.forwarded`

This event fires only for transfers that use the forwarding service.

```json theme={null}
{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notificationId": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "notificationType": "gateway.mint.forwarded",
  "notification": {
    "transferId": "b8c90123-4567-8901-abcd-ef2345678901",
    "txHash": "0x2bc033043d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a",
    "walletAddress": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
    "domain": "3",
    "env": "mainnet",
    "tokenAddress": "0xcccccccccccccccccccccccccccccccccccccccc",
    "attestations": [
      {
        "from": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
        "to": "0x8888888800000000000000000000000000000002",
        "amount": "50000.000000",
        "transferSpecHash": "0x5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c"
      }
    ]
  },
  "timestamp": "2026-04-22T12:15:00.000000000Z",
  "version": 2
}
```


# Gateway Webhooks
Source: https://developers.circle.com/gateway/webhooks

Get Gateway event updates for your registered wallet addresses.

Use Gateway webhooks to get updates for your registered wallet addresses. Events
include Gateway Wallet deposits and mints on destination blockchains. Gateway is
fully permissionless, but webhook subscriptions require a free
[Circle Developer Console](https://console.circle.com) account and API key. You
do not need billing or a credit card.

## How it works

Set up Gateway webhooks in two steps:

1. **Expose an endpoint**: Create a public HTTPS endpoint to receive webhooks.
2. **Create a subscription**: Add your endpoint, wallet addresses, blockchains,
   and event types.

When a Gateway event occurs on a registered address and domain, Circle sends a
notification to your endpoint with event details.

Webhook notifications are not guaranteed to arrive in any particular order. The
same notification can be retried. Use notification IDs to find duplicate events.
Make your endpoint safe to run more than once.

Store each notification ID and skip IDs that you have already processed.

## Authentication

While Gateway itself is permissionless and does not require authentication,
webhook subscriptions require a Circle Developer account and API key. Manage
subscriptions through the `POST /v2/notifications/subscriptions/permissionless`
endpoint. Create a free account at the
[Circle Developer Console](https://console.circle.com) to get started. An API
key is only needed for managing webhook subscriptions, not for using Gateway's
core transfer features.

## Event types

Gateway webhooks currently support these event types:

* `gateway.deposit.finalized`: Tokens were deposited into a Gateway Wallet.
  Fires after the deposit transaction is finalized onchain and processed by
  Gateway.
* `gateway.mint.finalized`: Tokens were minted on the destination blockchain.
  Fires after the mint is finalized and processed by Gateway.
* `gateway.mint.forwarded`: A forwarded mint relay was confirmed. Fires only for
  forwarded transfers.

<Note>
  On instant-finality blockchains, the forwarded status moves directly from
  pending to finalized, skipping the confirmed state. Use a combination of
  `gateway.mint.finalized` and `gateway.mint.forwarded` to track the full
  transfer lifecycle across all blockchains.
</Note>

<Tip>
  Omit `notificationTypes` or use `gateway.*` to receive all Gateway event types,
  including any new types added in the future.

  * `gateway.*` (all types): the API returns `"restricted": false`
  * Subset of types: the API returns `"restricted": true`
</Tip>

### Example: deposit and mint lifecycle

The following example shows when events fire during a deposit and mint flow.

1. A user deposits tokens into a Gateway Wallet on a source blockchain →
   **`gateway.deposit.finalized`**
2. If the transfer uses the
   [forwarding service](/gateway/references/forwarding-service), the relay is
   confirmed → **`gateway.mint.forwarded`**
3. The deposit is attested and tokens are minted on the destination blockchain →
   **`gateway.mint.finalized`**

## Limits

| Resource                                   | Limit |
| ------------------------------------------ | ----- |
| Subscriptions per developer account        | 20    |
| Registered addresses per developer account | 50    |

## Environment

Gateway webhooks work with testnet and mainnet API keys. Use `TEST` for testnet.
Use `LIVE` for mainnet. You can create both from the same
[Circle Developer Console](https://console.circle.com) account.

## Get started

<Card title="Webhook events reference" icon="book" href="/gateway/references/webhook-events">
  View schemas and examples for each event type
</Card>


# Circle Developer Docs
Source: https://developers.circle.com/index



<HeroSection />

## Use cases

<CardGroup>
  <Card title="Embedded wallets" icon="wallet" href="/wallets/dev-controlled/create-your-first-wallet">
    Add wallets and USDC payments directly in your app.
  </Card>

  <Card title="Crosschain transfers" icon="arrow-right-arrow-left" href="/cctp/quickstarts/transfer-usdc-ethereum-to-arc">
    Move USDC natively between blockchains with CCTP.
  </Card>

  <Card title="Chain-abstracted balances" icon="coin-blank" href="/gateway/quickstarts/unified-balance-evm">
    Create a unified USDC balance across multiple EVM chains.
  </Card>
</CardGroup>

## Workflows

<div>
  <div>
    <div>
      <span>
        Accept stablecoin payments
      </span>
    </div>

    <a href="/wallets/dev-controlled/create-your-first-wallet">
      <span>
        Create a wallet
      </span>

      <svg>
        <path />
      </svg>
    </a>

    <a href="/stablecoins/quickstarts/transfer-usdc-evm">
      <span>
        Transfer USDC
      </span>

      <svg>
        <path />
      </svg>
    </a>

    <a href="/cpn/managed-payments/quickstarts/receive-stablecoin-payins">
      <span>
        Receive payins
      </span>

      <svg>
        <path />
      </svg>
    </a>
  </div>

  <div>
    <div>
      <span>
        Move USDC across chains
      </span>
    </div>

    <a href="/cctp/quickstarts/transfer-usdc-ethereum-to-arc">
      <span>
        Bridge with CCTP
      </span>

      <svg>
        <path />
      </svg>
    </a>

    <a href="/gateway/quickstarts/unified-balance-evm">
      <span>
        Unified balances
      </span>

      <svg>
        <path />
      </svg>
    </a>

    <a href="/wallets/supported-blockchains">
      <span>
        Supported blockchains
      </span>

      <svg>
        <path />
      </svg>
    </a>
  </div>

  <div>
    <div>
      <span>
        Build onchain apps
      </span>
    </div>

    <a href="/contracts/scp-deploy-smart-contract">
      <span>
        Deploy contracts
      </span>

      <svg>
        <path />
      </svg>
    </a>

    <a href="/wallets/modular">
      <span>
        Modular wallets
      </span>

      <svg>
        <path />
      </svg>
    </a>

    <a href="/wallets/gas-station">
      <span>
        Sponsor gas fees
      </span>

      <svg>
        <path />
      </svg>
    </a>
  </div>
</div>

## Common tasks

<div>
  <div>
    <p>
      Core
    </p>

    <div>
      <a href="/wallets/dev-controlled/create-your-first-wallet">
        Create a wallet
      </a>

      <a href="/contracts/scp-deploy-smart-contract">
        Deploy a contract
      </a>

      <a href="/stablecoins/quickstarts/transfer-usdc-evm">
        Transfer USDC
      </a>
    </div>
  </div>

  <div>
    <p>
      Crosschain
    </p>

    <div>
      <a href="/cctp/quickstarts/transfer-usdc-ethereum-to-arc">
        Bridge USDC
      </a>

      <a href="/gateway/quickstarts/unified-balance-evm">
        Unified balance
      </a>

      <a href="/gateway/nanopayments">
        Nanopayments
      </a>
    </div>
  </div>

  <div>
    <p>
      Payments & gas
    </p>

    <div>
      <a href="/cpn/managed-payments/quickstarts/receive-stablecoin-payins">
        Receive payins
      </a>

      <a href="/wallets/gas-station">
        Gas Station
      </a>

      <a href="/paymaster/pay-gas-fees-usdc">
        Pay gas with USDC
      </a>
    </div>
  </div>
</div>

<div>
  <div>
    <h2>
      Build with AI
    </h2>

    <div>
      <a href="/ai/skills">
        <div>
          <svg>
            <path />
          </svg>
        </div>

        <div>
          <span>Agent Skills</span>
          <span>Install guide</span>
        </div>
      </a>

      <a href="/ai/mcp">
        <div>
          <svg>
            <rect />

            <path />
          </svg>
        </div>

        <div>
          <span>Circle MCP Server</span>
          <span>Setup guide</span>
        </div>
      </a>

      <a href="/llms.txt">
        <div>
          <svg>
            <path />

            <path />
          </svg>
        </div>

        <div>
          <span>LLMs.txt</span>
          <span>Agent context</span>
        </div>
      </a>
    </div>
  </div>

  <div>
    <h2>
      What's new
    </h2>

    <div>
      <div>
        <span>Apr 8</span>
        <span>CPN</span>
        <span>Managed Payments docs and 23 new API endpoints</span>
      </div>

      <div>
        <span>Apr 6</span>
        <span>CCTP</span>
        <span>Stellar testnet support added</span>
      </div>

      <div>
        <span>Apr 3</span>
        <span>Mint</span>
        <span>Singapore coverage for Crypto Payouts</span>
      </div>

      <div>
        <span>Apr 2</span>
        <span>Mint</span>
        <span>Continuous payment intents now default</span>
      </div>

      <div>
        <span>Apr 1</span>
        <span>Mint</span>
        <span>Credit API launched for Settlement Advance</span>
      </div>
    </div>
  </div>
</div>


# Liquidity Services
Source: https://developers.circle.com/liquidity-services

Access institutional-grade tools for minting USDC and EURC directly from Circle, and execute stablecoin FX trades with aggregated liquidity.

## What you can build

Circle provides institutional infrastructure for accessing digital currencies
and executing stablecoin FX trades. These tools enable banks, exchanges, payment
providers, and fintechs to integrate USDC and EURC into their operations at
scale.

Key capabilities:

* **Direct USDC and EURC minting**: Access digital currencies directly from
  Circle, the sole issuer, with 1:1 redemption guarantees.
* **Institutional FX execution**: Execute stablecoin currency swaps with
  competitive rates from multiple liquidity providers.
* **24/7 settlement**: Trade and settle around the clock with sub-second
  finality on Arc blockchain.
* **Simplified operations**: Reduce reliance on multiple intermediaries and
  bilateral agreements with unified API access.

## Choose your product

Both products are designed for institutional customers with different use cases:

<CardGroup>
  <Card title="Circle Mint" icon="building-columns" href="/circle-mint">
    Mint and redeem USDC and EURC directly from Circle. Manage funds securely
    and distribute them to crypto wallets globally, 24/7.
  </Card>

  <Card title="StableFX" icon="swap" href="/stablefx">
    Institutional-grade stablecoin FX engine built on Arc. Execute USDC and EURC
    trades with aggregated liquidity and smart contract settlement.
  </Card>
</CardGroup>

## Circle Mint

Circle Mint is the fastest and most cost-effective way for institutions to
access and redeem USDC and EURC. Your Circle Mint account allows you to manage
funds securely and distribute them worldwide using a web UI or API integration.

**Benefits:**

* Fiat funds from your bank account are automatically converted to USDC and EURC
* Participating banks offer instant settlement programs
* USDC and EURC can always be redeemed 1:1 for US dollars or Euros

**Who should use Circle Mint:**

* Exchanges and institutional traders
* Wallet providers and custodians
* Banks and payment service providers
* Consumer app companies requiring stablecoin infrastructure

<Note>
  Circle Mint is for institutional customers. [Contact
  Circle](https://www.circle.com/mint-contact) to learn more about accessing the
  platform.
</Note>

## StableFX

StableFX is an institutional-grade FX engine that combines Request-for-Quote
(RFQ) execution with onchain settlement. This permissioned platform is designed
for financial institutions including payment service providers, fintechs, crypto
OTC desks, and prime brokers.

**Key features:**

* **Aggregated Liquidity**: Access competitive rates from multiple liquidity
  providers through a single API call
* **24/7 Settlement**: Trade and settle around the clock with sub-second
  finality on Arc
* **Simplified Operations**: Replace multiple bilateral agreements with one
  integration
* **Smart contract escrow**: Both sides of a trade settle simultaneously or not
  at all

**Common use cases:**

* Cross-border payment flows with real-time currency conversion
* Institutional treasury management and automated rebalancing
* Embedded FX liquidity services for platforms
* Next-generation remittance solutions with guaranteed settlement

<Note>
  Reach out to your [Circle representative](mailto:sales@circle.com) to get an
  API key for StableFX.
</Note>

## Dive deeper

* Learn about
  [Circle Mint core capabilities](/circle-mint/quickstarts/getting-started)
  including deposits, withdrawals, and transfers.
* Follow the [StableFX taker quickstart](/stablefx/quickstarts/fx-trade-taker)
  to request and execute your first USDC to EURC trade.
* Follow the [StableFX maker quickstart](/stablefx/quickstarts/fx-trade-maker)
  to fulfill trades and provide liquidity.
* Explore
  [Circle Mint supported chains](/circle-mint/references/supported-chains-and-currencies)
  and
  [StableFX supported currencies](/stablefx/references/supported-currencies).


# Paymaster
Source: https://developers.circle.com/paymaster

Pay gas fees with USDC

Circle has a network of permissionless token paymasters that enables end-users
to pay for network (gas) fees using USDC tokens, instead of chain native tokens.

Paying for gas in USDC has the following advantages:

* USDC holders don't need to source native tokens to transact in USDC.
* End-users pay for network fees in a familiar unit, making network pricing
  easier to understand.

The Circle Paymaster supports the ERC-4337 standard and thus supports any wallet
adhering to that standard. This documentation provides information on how to
integrate with the permissionless Circle Paymaster so that your users can pay
for gas fees in USDC.

There is a 10% surcharge on gas fees to account for operational costs. The 10%
surcharge only applies to Arbitrum and Base (and their testnets). The Paymaster
only supports USDC tokens.

Circle Paymaster supports the
[ERC-4337 v0.7](https://github.com/eth-infinitism/account-abstraction/releases/tag/v0.7.0)
and
[ERC-4337 v0.8](https://github.com/eth-infinitism/account-abstraction/releases/tag/v0.8.0)
on multiple chains. For more information, see
[Supported chains](#supported-chains) below.

In the following pages, `Paymaster v0.7` denotes the Paymaster that supports
Entrypoint v0.7 and `Paymaster v0.8` denotes the Paymaster that supports
Entrypoint v0.8.

## Key features

The Circle Paymaster provides many enhancements for new crypto users who may not
be familiar with gas fees or native tokens. Paymasters allow you to build and
integrate wallets that don't require native tokens for gas, allowing you to
provide users with an experience similar to traditional finance.

### Reliable execution

Circle ensures that there is always a sufficient amount of native gas token for
each supported chain, managing swaps and balances behind-the-scenes to ensure a
reliable, consistent experience with the Paymaster smart contracts.

### Permissionless usage

The Paymaster is an onchain smart contract that any developer can integrate. You
don't need to sign up for a Circle Developer account or generate any API keys.
The Paymaster has no dependency on offchain APIs, and you can extend it for your
specific use case.

### Onboarding without native tokens

Using the USDC smart contract, you can set up an ERC-20 approval with the
Paymaster without using any native tokens. You can then pay for a smart contract
account deployment using USDC set to the pre-deployed account address with a
signed permit. This means that you can transact without ever needing to hold the
blockchain native token.

## Supported chains

| EntryPoint                                                                                 | Chains                                                              |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [ERC-4337 v0.7](https://github.com/eth-infinitism/account-abstraction/releases/tag/v0.7.0) | Arbitrum and Base                                                   |
| [ERC-4337 v0.8](https://github.com/eth-infinitism/account-abstraction/releases/tag/v0.8.0) | Arbitrum, Avalanche, Base, Ethereum, Optimism, Polygon and Unichain |

## Related products

Circle Paymaster allows users to pay gas fees in USDC. If you want to sponsor
network fees for your users, see [Gas Station](/wallets/gas-station).

### Comparison with Gas Station

| Category               | Circle Paymaster                                                                                    | Gas Station                                                                      |
| ---------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Description**        | A permissionless smart contract that allows users to pay gas fees in USDC instead of native tokens. | A feature of Wallets that allows developers to sponsor gas fees for their users. |
| **Circle account**     | Not required                                                                                        | Required                                                                         |
| **Compatible wallets** | Any ERC-4337-compliant wallet                                                                       | Circle Wallets                                                                   |
| **Gas fees paid in**   | USDC                                                                                                | Fiat currency via credit card                                                    |
| **Pricing model**      | 10% of the gas fee                                                                                  | 5% of the gas fee                                                                |
| **Paid by**            | End user                                                                                            | Developer                                                                        |


# Paymaster Addresses and Events
Source: https://developers.circle.com/paymaster/addresses-and-events



This page contains information on the addresses of the Circle Paymaster
contracts, and the events the contracts emit during operation.

## Paymaster addresses

You can access the permissionless paymaster contracts at the following addresses
on supported blockchains:

<Tabs>
  <Tab title="Paymaster v0.7">
    ### Mainnet

    | Blockchain | Symbol | Paymaster contract address                                                                                              |
    | ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
    | Arbitrum   | `ARB`  | [`0x6C973eBe80dCD8660841D4356bf15c32460271C9`](https://arbiscan.io/address/0x6C973eBe80dCD8660841D4356bf15c32460271C9)  |
    | Base       | `BASE` | [`0x6C973eBe80dCD8660841D4356bf15c32460271C9`](https://basescan.org/address/0x6C973eBe80dCD8660841D4356bf15c32460271C9) |

    ### Testnet

    | Blockchain       | Symbol         | Paymaster contract address                                                                                                      |
    | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
    | Arbitrum Sepolia | `ARB-SEPOLIA`  | [`0x31BE08D380A21fc740883c0BC434FcFc88740b58`](https://sepolia.arbiscan.io/address/0x31BE08D380A21fc740883c0BC434FcFc88740b58)  |
    | Arc Testnet      | `ARC-TESTNET`  | [`0x31BE08D380A21fc740883c0BC434FcFc88740b58`](https://testnet.arcscan.app/address/0x31BE08D380A21fc740883c0BC434FcFc88740b58)  |
    | Base Sepolia     | `BASE-SEPOLIA` | [`0x31BE08D380A21fc740883c0BC434FcFc88740b58`](https://sepolia.basescan.org/address/0x31BE08D380A21fc740883c0BC434FcFc88740b58) |
  </Tab>

  <Tab title="Paymaster v0.8">
    ### Mainnet

    | Blockchain | Symbol  | Paymaster contract address                                                                                                         |
    | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
    | Arbitrum   | `ARB`   | [`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`](https://arbiscan.io/address/0x0578cFB241215b77442a541325d6A4E6dFE700Ec)             |
    | Avalanche  | `AVAX`  | [`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`](https://snowtrace.io/address/0x0578cFB241215b77442a541325d6A4E6dFE700Ec)            |
    | Base       | `BASE`  | [`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`](https://basescan.org/address/0x0578cFB241215b77442a541325d6A4E6dFE700Ec)            |
    | Ethereum   | `ETH`   | [`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`](https://etherscan.io/address/0x0578cFB241215b77442a541325d6A4E6dFE700Ec)            |
    | Optimism   | `OP`    | [`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`](https://optimistic.etherscan.io/address/0x0578cFB241215b77442a541325d6A4E6dFE700Ec) |
    | Polygon    | `MATIC` | [`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`](https://polygonscan.com/address/0x0578cFB241215b77442a541325d6A4E6dFE700Ec)         |
    | Unichain   | `UNI`   | [`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`](https://unichain.blockscout.com/address/0x0578cFB241215b77442a541325d6A4E6dFE700Ec) |

    ### Testnet

    | Blockchain       | Symbol         | Paymaster contract address                                                                                                                 |
    | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
    | Arbitrum Sepolia | `ARB-SEPOLIA`  | [`0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966`](https://sepolia.arbiscan.io/address/0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966)             |
    | Arc Testnet      | `ARC-TESTNET`  | [`0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966`](https://testnet.arcscan.app/address/0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966)             |
    | Avalanche Fuji   | `AVAX-FUJI`    | [`0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966`](https://testnet.snowtrace.io/address/0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966)            |
    | Base Sepolia     | `BASE-SEPOLIA` | [`0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966`](https://sepolia.basescan.org/address/0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966)            |
    | Ethereum Sepolia | `ETH-SEPOLIA`  | [`0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966`](https://sepolia.etherscan.io/address/0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966)            |
    | Optimism Sepolia | `OP-SEPOLIA`   | [`0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966`](https://sepolia-optimistic.etherscan.io/address/0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966) |
    | Polygon Amoy     | `MATIC-AMOY`   | [`0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966`](https://amoy.polygonscan.com/address/0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966)            |
    | Unichain Sepolia | `UNI-SEPOLIA`  | [`0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966`](https://unichain-sepolia.blockscout.com/address/0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966) |
  </Tab>
</Tabs>

## Paymaster events

This section explains the events from the Circle Paymaster and when they are
emitted. You can use these events to debug or track the state after submitting a
user operation (user op) to a bundler.

### TokenPaymasterV07.sol and TokenPaymasterV08.sol

These files are the main contract of the Circle Paymaster that support
EntryPoint v0.7 and v0.8. The primary functions they integrate are:

* `_validatePaymasterUserOp`: validates the user op and charges the prefund
  token from the sender before execution.
* `_postOp`: refunds the token back to the sender when the actual amount of
  tokens needed is known after execution.

#### UserOperationSponsored

The contract emits this event after the `_postOp` is executed and the prefund
token (if any) is refunded.

**Attributes**

| Name                | Type      | Description                                                                                  |
| ------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `token`             | `IERC20`  | The ERC-20 token paid by the sender                                                          |
| `sender`            | `address` | The sender address                                                                           |
| `userOpHash`        | `bytes32` | The hash of the user op                                                                      |
| `nativeTokenPrice`  | `uint256` | The price of 1 ether = 1e18 wei, denominated in token                                        |
| `actualTokenNeeded` | `uint256` | The final transaction cost to the smart contract account (SCA), denominated in token         |
| `feeTokenAmount`    | `uint256` | The fee spread used to cover the slippage from exchanging USDC for ETH, denominated in token |

**Example**

Using
[this transaction](https://sepolia.etherscan.io/tx/0x44727688a0bc343ce73b422ac46b2b14a352ccc59f9ff0203588d3718458931e#eventlog)
as an example, the `userOperationSponsored` event contains the following data:

| Name                | Type      | Value                                                                |
| ------------------- | --------- | -------------------------------------------------------------------- |
| `token`             | `IERC20`  | `0x0000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c7238` |
| `sender`            | `address` | `0x000000000000000000000000148cab4b1a7e8c23ae62967cfc8df6292ecf27a8` |
| `userOpHash`        | `bytes32` | `cc6f71a0ba8d9b72e75c45fae7b830c403b46964eb1d3f8daa0b73d14e6c5b0d`   |
| `nativeTokenPrice`  | `uint256` | `3000000000`                                                         |
| `actualTokenNeeded` | `uint256` | `4551712`                                                            |
| `feeTokenAmount`    | `uint256` | `0`                                                                  |


# Quickstart: Circle Paymaster
Source: https://developers.circle.com/paymaster/pay-gas-fees-usdc

Build a smart wallet that pays fees in USDC

<Note>
  Before you begin, select the version of the Circle Paymaster that you want to
  build with.
</Note>

<Tabs>
  <Tab title="Paymaster v0.7">
    This guide walks you through the process of:

    1. Setting up a smart account and checking its USDC balance
    2. Configuring the Circle Paymaster v0.7 to pay for gas with USDC
    3. Connecting to a bundler and submitting a user operation

    This quickstart shows you how you can integrate Circle Paymaster into your app
    to simplify network fee management for your users.

    <Note>
      **Note:** Throughout this tutorial, each snippet lists any new imports above
      the relevant code. You should add the new imports to the top of the file and
      merge with other imports from the same module. You can add the rest of the
      code inline.
    </Note>

    ## Prerequisites

    Before you start building the sample app to pay for gas fees in USDC, ensure
    that **Node.js** and **npm** are installed. You can download and install
    [Node.js](https://nodejs.org) directly, or use a version manager like
    [nvm](https://github.com/nvm-sh/nvm). The npm binary comes with Node.js.

    ## Part 1: Set up a smart account

    The following steps cover the steps required to set up your environment and
    initialize a new smart account.

    ### 1.1. Set up your development environment

    Create a new project, set the package type to `module`, and install the
    necessary dependencies.

    ```shell Shell theme={null}
    npm init
    npm pkg set type="module"
    npm install --save viem @circle-fin/modular-wallets-core dotenv
    ```

    Create a new `.env` file.

    ```shell Shell theme={null}
    touch .env
    ```

    Edit the `.env` file and add the following variables, replacing
    `{YOUR_PRIVATE_KEY}` and `{RECIPIENT_ADDRESS}` with your own values:

    ```text theme={null}
    OWNER_PRIVATE_KEY={YOUR_PRIVATE_KEY}
    RECIPIENT_ADDRESS={RECIPIENT_ADDRESS}
    PAYMASTER_V07_ADDRESS=0x31BE08D380A21fc740883c0BC434FcFc88740b58
    USDC_ADDRESS=0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d # Arbitrum Sepolia
    ```

    The `RECIPIENT_ADDRESS` is the destination address for the example USDC
    transfer.

    ### 1.2. Initialize clients and smart account

    Create a file called `index.js` and add the following code to set up the
    necessary clients and account:

    ```javascript JavaScript theme={null}
    import "dotenv/config";
    import { createPublicClient, http, getContract } from "viem";
    import { arbitrumSepolia } from "viem/chains";
    import { privateKeyToAccount } from "viem/accounts";
    import { toCircleSmartAccount } from "@circle-fin/modular-wallets-core";

    const chain = arbitrumSepolia;
    const usdcAddress = process.env.USDC_ADDRESS;
    const ownerPrivateKey = process.env.OWNER_PRIVATE_KEY;

    const client = createPublicClient({ chain, transport: http() });
    const owner = privateKeyToAccount(ownerPrivateKey);
    const account = await toCircleSmartAccount({ client, owner });
    ```

    ### 1.3. Check the USDC balance

    Check the smart account's USDC balance using the following code:

    ```javascript JavaScript theme={null}
    import { erc20Abi } from "viem";
    const usdc = getContract({ client, address: usdcAddress, abi: erc20Abi });
    const usdcBalance = await usdc.read.balanceOf([account.address]);

    if (usdcBalance < 1000000) {
      console.log(
        `Fund ${account.address} with USDC on ${client.chain.name} using https://faucet.circle.com, then run this again.`,
      );
      process.exit();
    }
    ```

    ## Part 2: Configure the Paymaster

    The Circle Paymaster requires an allowance to spend USDC on behalf of the smart
    account.

    ### 2.1. Implement the permit

    A USDC allowance is required for the paymaster to be able to withdraw USDC from
    the account to pay for fees. A signed permit can be used to set the paymaster's
    allowance without submitting a separate transaction.

    Create a new file called `permit.js` with the following code to sign EIP-2612
    permits:

    ```javascript JavaScript theme={null}
    import { maxUint256, erc20Abi, parseErc6492Signature } from "viem";

    // Adapted from https://github.com/vacekj/wagmi-permit/blob/main/src/permit.ts
    export async function eip2612Permit({
      token,
      chain,
      ownerAddress,
      spenderAddress,
      value,
    }) {
      return {
        types: {
          // Required for compatibility with Circle PW Sign Typed Data API
          EIP712Domain: [
            { name: "name", type: "string" },
            { name: "version", type: "string" },
            { name: "chainId", type: "uint256" },
            { name: "verifyingContract", type: "address" },
          ],
          Permit: [
            { name: "owner", type: "address" },
            { name: "spender", type: "address" },
            { name: "value", type: "uint256" },
            { name: "nonce", type: "uint256" },
            { name: "deadline", type: "uint256" },
          ],
        },
        primaryType: "Permit",
        domain: {
          name: await token.read.name(),
          version: await token.read.version(),
          chainId: chain.id,
          verifyingContract: token.address,
        },
        message: {
          // Convert bigint fields to string to match EIP-712 JSON schema expectations
          owner: ownerAddress,
          spender: spenderAddress,
          value: value.toString(),
          nonce: (await token.read.nonces([ownerAddress])).toString(),
          // The paymaster cannot access block.timestamp due to 4337 opcode
          // restrictions, so the deadline must be MAX_UINT256.
          deadline: maxUint256.toString(),
        },
      };
    }

    export const eip2612Abi = [
      ...erc20Abi,
      {
        inputs: [
          {
            internalType: "address",
            name: "owner",
            type: "address",
          },
        ],
        stateMutability: "view",
        type: "function",
        name: "nonces",
        outputs: [
          {
            internalType: "uint256",
            name: "",
            type: "uint256",
          },
        ],
      },
      {
        inputs: [],
        name: "version",
        outputs: [{ internalType: "string", name: "", type: "string" }],
        stateMutability: "view",
        type: "function",
      },
    ];

    export async function signPermit({
      tokenAddress,
      client,
      account,
      spenderAddress,
      permitAmount,
    }) {
      const token = getContract({
        client,
        address: tokenAddress,
        abi: eip2612Abi,
      });
      const permitData = await eip2612Permit({
        token,
        chain: client.chain,
        ownerAddress: account.address,
        spenderAddress,
        value: permitAmount,
      });

      const wrappedPermitSignature = await account.signTypedData(permitData);

      const isValid = await client.verifyTypedData({
        ...permitData,
        address: account.address,
        signature: wrappedPermitSignature,
      });

      if (!isValid) {
        throw new Error(
          `Invalid permit signature for ${account.address}: ${wrappedPermitSignature}`,
        );
      }

      const { signature } = parseErc6492Signature(wrappedPermitSignature);
      return signature;
    }
    ```

    ### 2.2. Set up Circle Paymaster

    In the `index.js` file, use the Circle permit implementation to build paymaster
    data:

    ```javascript JavaScript theme={null}
    import { encodePacked } from "viem";
    import { signPermit } from "./permit.js";

    const paymasterAddress = process.env.PAYMASTER_V07_ADDRESS;

    const paymaster = {
      async getPaymasterData(parameters) {
        const permitAmount = 10000000n;
        const permitSignature = await signPermit({
          tokenAddress: usdcAddress,
          account,
          client,
          spenderAddress: paymasterAddress,
          permitAmount: permitAmount,
        });

        const paymasterData = encodePacked(
          ["uint8", "address", "uint256", "bytes"],
          [0, usdcAddress, permitAmount, permitSignature],
        );

        return {
          paymaster: paymasterAddress,
          paymasterData,
          paymasterVerificationGasLimit: 200000n,
          paymasterPostOpGasLimit: 15000n,
          isFinal: true,
        };
      },
    };
    ```

    ## Part 3: Submit a user operation

    Once the paymaster is configured, you can connect to a bundler and submit a user
    operation to transfer USDC.

    ### 3.1. Connect to the bundler

    In `index.js`, set up the bundler client with the following code:

    ```javascript JavaScript theme={null}
    import { createBundlerClient } from "viem/account-abstraction";
    import { hexToBigInt } from "viem";

    const bundlerClient = createBundlerClient({
      account,
      client,
      paymaster,
      userOperation: {
        estimateFeesPerGas: async ({ account, bundlerClient, userOperation }) => {
          const { standard: fees } = await bundlerClient.request({
            method: "pimlico_getUserOperationGasPrice",
          });
          const maxFeePerGas = hexToBigInt(fees.maxFeePerGas);
          const maxPriorityFeePerGas = hexToBigInt(fees.maxPriorityFeePerGas);
          return { maxFeePerGas, maxPriorityFeePerGas };
        },
      },
      transport: http(`https://public.pimlico.io/v2/${client.chain.id}/rpc`),
    });
    ```

    ### 3.2. Submit the user operation

    Finally, submit a user operation to transfer USDC, using the paymaster to pay
    for the network fee in USDC. In `index.js` add the following code:

    ```javascript JavaScript theme={null}
    const recipientAddress = process.env.RECIPIENT_ADDRESS;

    const hash = await bundlerClient.sendUserOperation({
      account,
      calls: [
        {
          to: usdc.address,
          abi: usdc.abi,
          functionName: "transfer",
          args: [recipientAddress, 10000n],
        },
      ],
    });
    console.log("UserOperation hash", hash);

    const receipt = await bundlerClient.waitForUserOperationReceipt({ hash });
    console.log("Transaction hash", receipt.receipt.transactionHash);

    // We need to manually exit the process, since viem leaves some promises on the
    // event loop for features we're not using.
    process.exit();
    ```
  </Tab>

  <Tab title="Paymaster v0.8">
    This guide walks you through the process of:

    1. Setting up a 7702 smart account and checking its USDC balance
    2. Configuring the Circle Paymaster v0.8 to pay for gas with USDC
    3. Connecting to a bundler and submitting a user operation

    This quickstart shows you how you can integrate Circle Paymaster into your app
    to simplify network fee management for your users.

    <Note>
      **Note:** Throughout this tutorial, each snippet lists any new imports above
      the relevant code. You should add the new imports to the top of the file and
      merge with other imports from the same module. You can add the rest of the
      code inline.
    </Note>

    If you'd like a video guide on how to implement Circle Paymaster with an
    EIP-7702 smart account, watch the following presentation from Circle Developer
    Relations:

    <iframe title="YouTube video player" />

    ## Prerequisites

    Before you start building the sample app to pay for gas fees in USDC, ensure
    that **Node.js** and **npm** are installed. You can download and install
    [Node.js](https://nodejs.org) directly, or use a version manager like
    [nvm](https://github.com/nvm-sh/nvm). The npm binary comes with Node.js.

    ## Part 1: Set up a 7702 smart account

    The following steps cover the steps required to set up your environment and
    initialize a new smart account.

    ### 1.1. Set up your development environment

    Create a new project, set the package type to `module`, and install the
    necessary dependencies.

    ```shell Shell theme={null}
    npm init
    npm pkg set type="module"
    npm install --save viem dotenv
    ```

    Create a new `.env` file.

    ```shell Shell theme={null}
    touch .env
    ```

    Edit the `.env` file and add the following variables, replacing
    `{YOUR_PRIVATE_KEY}` and `{RECIPIENT_ADDRESS}` with your own values:

    ```text theme={null}
    OWNER_PRIVATE_KEY={YOUR_PRIVATE_KEY}
    RECIPIENT_ADDRESS={RECIPIENT_ADDRESS}
    PAYMASTER_V08_ADDRESS=0x3BA9A96eE3eFf3A69E2B18886AcF52027EFF8966
    USDC_ADDRESS=0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d # Arbitrum Sepolia
    ```

    The `RECIPIENT_ADDRESS` is the destination address for the example USDC
    transfer.

    ### 1.2. Initialize clients and 7702 smart account

    Create a file called `index.js` and add the following code to set up the
    necessary clients and 7702 account:

    ```javascript JavaScript theme={null}
    import "dotenv/config";
    import { createPublicClient, http, getContract } from "viem";
    import { arbitrumSepolia } from "viem/chains";
    import { privateKeyToAccount } from "viem/accounts";
    import {
      createBundlerClient,
      toSimple7702SmartAccount,
    } from "viem/account-abstraction";

    const chain = arbitrumSepolia;
    const usdcAddress = process.env.USDC_ADDRESS;
    const ownerPrivateKey = process.env.OWNER_PRIVATE_KEY;

    const client = createPublicClient({ chain, transport: http() });
    const owner = privateKeyToAccount(ownerPrivateKey);
    const account = await toSimple7702SmartAccount({ client, owner });
    ```

    ### 1.3. Check the USDC balance

    Check the smart account's USDC balance using the following code:

    ```javascript JavaScript theme={null}
    import { erc20Abi } from "viem";
    const usdc = getContract({ client, address: usdcAddress, abi: erc20Abi });
    const usdcBalance = await usdc.read.balanceOf([account.address]);

    if (usdcBalance < 1000000) {
      console.log(
        `Fund ${account.address} with USDC on ${client.chain.name} using https://faucet.circle.com, then run this again.`,
      );
      process.exit();
    }
    ```

    ## Part 2: Configure the Paymaster

    The Circle Paymaster requires an allowance to spend USDC on behalf of the smart
    account.

    ### 2.1. Implement the permit

    A USDC allowance is required for the paymaster to be able to withdraw USDC from
    the account to pay for fees. A signed permit can be used to set the paymaster's
    allowance without submitting a separate transaction.

    Create a new file called `permit.js` with the following code to sign EIP-2612
    permits:

    ```javascript JavaScript theme={null}
    import { maxUint256, erc20Abi, parseErc6492Signature, getContract } from "viem";

    // Adapted from https://github.com/vacekj/wagmi-permit/blob/main/src/permit.ts
    export async function eip2612Permit({
      token,
      chain,
      ownerAddress,
      spenderAddress,
      value,
    }) {
      return {
        types: {
          // Required for compatibility with Circle PW Sign Typed Data API
          EIP712Domain: [
            { name: "name", type: "string" },
            { name: "version", type: "string" },
            { name: "chainId", type: "uint256" },
            { name: "verifyingContract", type: "address" },
          ],
          Permit: [
            { name: "owner", type: "address" },
            { name: "spender", type: "address" },
            { name: "value", type: "uint256" },
            { name: "nonce", type: "uint256" },
            { name: "deadline", type: "uint256" },
          ],
        },
        primaryType: "Permit",
        domain: {
          name: await token.read.name(),
          version: await token.read.version(),
          chainId: chain.id,
          verifyingContract: token.address,
        },
        message: {
          // Convert bigint fields to string to match EIP-712 JSON schema expectations
          owner: ownerAddress,
          spender: spenderAddress,
          value: value.toString(),
          nonce: (await token.read.nonces([ownerAddress])).toString(),
          // The paymaster cannot access block.timestamp due to 4337 opcode
          // restrictions, so the deadline must be MAX_UINT256.
          deadline: maxUint256.toString(),
        },
      };
    }

    export const eip2612Abi = [
      ...erc20Abi,
      {
        inputs: [
          {
            internalType: "address",
            name: "owner",
            type: "address",
          },
        ],
        stateMutability: "view",
        type: "function",
        name: "nonces",
        outputs: [
          {
            internalType: "uint256",
            name: "",
            type: "uint256",
          },
        ],
      },
      {
        inputs: [],
        name: "version",
        outputs: [{ internalType: "string", name: "", type: "string" }],
        stateMutability: "view",
        type: "function",
      },
    ];

    export async function signPermit({
      tokenAddress,
      client,
      account,
      spenderAddress,
      permitAmount,
    }) {
      const token = getContract({
        client,
        address: tokenAddress,
        abi: eip2612Abi,
      });
      const permitData = await eip2612Permit({
        token,
        chain: client.chain,
        ownerAddress: account.address,
        spenderAddress,
        value: permitAmount,
      });

      const wrappedPermitSignature = await account.signTypedData(permitData);

      const isValid = await client.verifyTypedData({
        ...permitData,
        address: account.address,
        signature: wrappedPermitSignature,
      });

      if (!isValid) {
        throw new Error(
          `Invalid permit signature for ${account.address}: ${wrappedPermitSignature}`,
        );
      }

      const { signature } = parseErc6492Signature(wrappedPermitSignature);
      return signature;
    }
    ```

    ### 2.2. Set up Circle Paymaster

    In the `index.js` file, use the Circle permit implementation to build paymaster
    data:

    ```javascript JavaScript theme={null}
    import { encodePacked } from "viem";
    import { signPermit } from "./permit.js";

    const paymasterAddress = process.env.PAYMASTER_V08_ADDRESS;

    const paymaster = {
      async getPaymasterData(parameters) {
        const permitAmount = 10000000n;
        const permitSignature = await signPermit({
          tokenAddress: usdcAddress,
          account,
          client,
          spenderAddress: paymasterAddress,
          permitAmount: permitAmount,
        });

        const paymasterData = encodePacked(
          ["uint8", "address", "uint256", "bytes"],
          [0, usdcAddress, permitAmount, permitSignature],
        );

        return {
          paymaster: paymasterAddress,
          paymasterData,
          paymasterVerificationGasLimit: 200000n,
          paymasterPostOpGasLimit: 15000n,
          isFinal: true,
        };
      },
    };
    ```

    ## Part 3: Submit a user operation

    Once the paymaster is configured, you can connect to a bundler submit a user
    operation to transfer USDC.

    ### 3.1. Connect to the bundler

    In `index.js`, set up the bundler client with the following code:

    ```javascript JavaScript theme={null}
    import { createBundlerClient } from "viem/account-abstraction";
    import { hexToBigInt } from "viem";

    const bundlerClient = createBundlerClient({
      account,
      client,
      paymaster,
      userOperation: {
        estimateFeesPerGas: async ({ account, bundlerClient, userOperation }) => {
          const { standard: fees } = await bundlerClient.request({
            method: "pimlico_getUserOperationGasPrice",
          });
          const maxFeePerGas = hexToBigInt(fees.maxFeePerGas);
          const maxPriorityFeePerGas = hexToBigInt(fees.maxPriorityFeePerGas);
          return { maxFeePerGas, maxPriorityFeePerGas };
        },
      },
      transport: http(`https://public.pimlico.io/v2/${client.chain.id}/rpc`),
    });
    ```

    ### 3.2. Sign an authorization and submit the user operation

    For 7702 smart accounts, you need to sign an authorization to set the code of
    the account to a 7702 smart account before submitting the user operation:

    ```javascript JavaScript theme={null}
    const recipientAddress = process.env.RECIPIENT_ADDRESS;

    // Sign authorization for 7702 account
    const authorization = await owner.signAuthorization({
      chainId: chain.id,
      nonce: await client.getTransactionCount({ address: owner.address }),
      contractAddress: account.authorization.address,
    });

    const hash = await bundlerClient.sendUserOperation({
      account,
      calls: [
        {
          to: usdc.address,
          abi: usdc.abi,
          functionName: "transfer",
          args: [recipientAddress, 10000n],
        },
      ],
      authorization: authorization,
    });
    console.log("UserOperation hash", hash);

    const receipt = await bundlerClient.waitForUserOperationReceipt({ hash });
    console.log("Transaction hash", receipt.receipt.transactionHash);

    // We need to manually exit the process, since viem leaves some promises on the
    // event loop for features we're not using.
    process.exit();
    ```
  </Tab>
</Tabs>

## Next steps

The above example demonstrates how to pay for a transaction using only USDC. You
can review the transaction in an [explorer](https://sepolia.arbiscan.io/) to
verify the details and see the USDC transfers that occurred during the
transaction. Remember that you need to use the transaction hash from the
bundler, not the user operation hash in the explorer. You can also view more
details about the user operation by searching for the user operation hash in a
[user op explorer](https://jiffyscan.xyz/?network=arbitrum-sepolia) on the
appropriate network.


# Payments
Source: https://developers.circle.com/payments

Enable fast, cost-effective, and compliant cross-border payments using stablecoin infrastructure and built-in compliance capabilities.

## What you can build

Circle provides next-generation payment infrastructure that reduces
intermediaries while enhancing transparency, security, and speed. Onchain
primitives and built-in compliance underpin Circle payment products such as
[Circle Payments Network](/cpn) and [Managed Payments](/cpn/managed-payments).
Those offerings support stablecoin-based flows for financial institutions and
partners. Examples include cross-border settlement, managed payins and payouts,
and sub-wallets. You integrate through APIs on your side.

## Circle Payments Network

CPN connects Originating Financial Institutions (OFIs) and Beneficiary Financial
Institutions (BFIs) to enable efficient global payments powered by USDC.

<CardGroup>
  <Card title="Circle Payments Network" icon="chart-network" href="/cpn">
    Fast, cost-effective, and compliant global payment infrastructure for
    financial institutions. Settle cross-border payments with USDC in seconds
    instead of days.
  </Card>
</CardGroup>

### Key capabilities

* **Cross-border payments**: Facilitate international transfers with
  near-instant settlement and transparent pricing.
* **Real-time FX quoting**: Get competitive quotes from multiple providers with
  locked rates to eliminate FX risk.
* **Smart routing**: Automatically select optimal beneficiary financial
  institutions based on pricing and operational preferences.
* **Built-in compliance**: End-to-end encryption for travel rule data and
  beneficiary information throughout the payment flow.

### How it works

CPN enables financial institutions to send cross-border payments efficiently
through a four-stage workflow:

<Steps>
  <Step title="Quote generation">
    OFIs request competitive FX quotes from multiple BFIs through a single API call. Rates are locked to eliminate FX risk during the payment process.
  </Step>

  <Step title="Payment creation">
    After selecting a quote, OFIs create a payment request with encrypted travel
    rule data and beneficiary information. BFIs review and approve the payment.
  </Step>

  <Step title="Onchain transaction">
    OFIs sign and submit USDC transactions to transfer funds to the BFI. CPN
    validates and broadcasts transactions, then notifies both parties when
    confirmed.
  </Step>

  <Step title="Fiat settlement">
    BFIs convert USDC to local fiat and deliver funds to end recipients. CPN provides real-time status updates throughout the entire process.
  </Step>
</Steps>

### Prerequisites for OFIs

Before onboarding as an Originating Financial Institution, ensure you have:

* Access to USDC liquidity
* A custodial solution for USDC and technical capability to interact with
  blockchains
* Established KYC and AML processes for your customers

<Note>
  CPN is designed for institutional customers. [Contact
  Circle](https://www.circle.com/cpn/interest) to learn more about joining the
  network as an OFI.
</Note>

## Managed Payments

[Managed Payments](/cpn/managed-payments) is a complete stablecoin settlement
from Circle. Partners can offer USDC payins, payouts, and sub-wallets for
merchants without holding digital assets. Circle holds assets, runs compliance,
and handles onchain activity. You integrate through APIs and can stay in fiat at
the edge when your product requires it.

<CardGroup>
  <Card title="Managed Payments" icon="wallet" href="/cpn/managed-payments">
    Sub-wallets, continuous crypto payins, payouts, fiat funding, and reporting
    for partners that need USDC payins and payouts without building custody and
    compliance in house.
  </Card>
</CardGroup>

## Dive deeper

* Read the [Managed Payments overview](/cpn/managed-payments) and
  [Quickstart: Receive Stablecoin Payins](/cpn/managed-payments/quickstarts/receive-stablecoin-payins)
  to integrate USDC payins and sub-wallets.
* Follow the
  [CPN OFI integration quickstart](/cpn/quickstarts/integrate-with-cpn-ofi) to
  start building with the API.
* Review [API integration concepts](/cpn/concepts/api/api-integration) to
  understand the CPN workflow and key entities.
* Explore
  [supported blockchains](/cpn/references/blockchains/supported-blockchains) for
  USDC transfers.
* Read the
  [CPN White Paper](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/PDFs/Whitepapers/CPN_Whitepaper.pdf)
  to understand the motivation and use cases.


# All Products
Source: https://developers.circle.com/products

Browse guides and examples by product

Circle offers two broad types of developer products, permissioned and
permissionless products. Permissioned products require a Circle developer
account and an API key, where permissionless products can be integrated with
directly with no authentication with Circle.

Permissionless products are marked on the cards on this page, all other products
are permissioned.

## Assets

<Columns>
  <Card title="USDC" href="/stablecoins/what-is-usdc" icon="coins">
    Digital dollar stablecoin for payments and DeFi

    <PermissionlessBadge />
  </Card>

  <Card title="EURC" href="/stablecoins/what-is-eurc" icon="coins">
    Euro-backed stablecoin for European markets

    <PermissionlessBadge />
  </Card>

  <Card title="xReserve" href="/xreserve" icon="vault">
    Stablecoins backed 1:1 by USDC reserves

    <PermissionlessBadge />
  </Card>

  <Card title="USYC" href="/tokenized/usyc/overview" icon="file-invoice-dollar">
    Tokenized yield-bearing US Treasury product
  </Card>
</Columns>

## Build onchain apps

<Tip>
  **Use [Arc App Kit](https://docs.arc.io/app-kit) to build onchain apps faster**

  App Kit is ideal when you want common payment and liquidity flows across
  blockchains without implementing each step from scratch. The Circle Wallets
  adapter uses your account credentials so App Kit can access dev-controlled
  wallets and Circle Contracts.
</Tip>

<Columns>
  <Card title="Wallets: Dev-Controlled" href="/wallets/dev-controlled" icon="wallet">
    Create wallets and manage them on behalf of your users
  </Card>

  <Card title="Wallets: Modular" href="/wallets/modular" icon="wallet">
    Create flexible, customizable wallets with modules
  </Card>

  <Card title="Wallets: User-Controlled" href="/wallets/user-controlled" icon="wallet">
    Let your users control their own wallets
  </Card>

  <Card title="Gas Station" href="/wallets/gas-station" icon="gas-pump">
    Sponsor network fees for your users
  </Card>

  <Card title="Contracts" href="/contracts" icon="globe">
    Build and manage smart contracts
  </Card>

  <Card title="Paymaster" href="/paymaster" icon="coin-vertical">
    Pay gas fees with USDC

    <PermissionlessBadge />
  </Card>
</Columns>

## Crosschain transfers

<Tip>
  **Use dedicated SDKs for crosschain transfers**

  [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit) and
  [Unified Balance Kit](https://www.npmjs.com/package/@circle-fin/unified-balance-kit)
  let you move USDC across blockchains without low-level protocol work. Both
  support multiple blockchains and wallet providers.
</Tip>

<Columns>
  <Card title="CCTP" href="/cctp" icon="arrow-up-arrow-down">
    Move USDC natively between chains

    <PermissionlessBadge />
  </Card>

  <Card title="Gateway" href="/gateway" icon="dungeon">
    Enable a unified USDC balance

    <PermissionlessBadge />
  </Card>
</Columns>

## Payments

<Card title="Circle Payments Network" href="/cpn" icon="chart-network">
  Global, real-time settlement
</Card>

## Mint & FX

<Columns>
  <Card title="Mint" href="/circle-mint" icon="building-columns">
    Access and distribute USDC liquidity
  </Card>

  <Card title="StableFX" href="/stablefx" icon="swap">
    Integrate FX for stablecoins
  </Card>
</Columns>


# Release Notes
Source: https://developers.circle.com/release-notes

Release notes for Circle's developer products.

## 2026

<Columns>
  <Card title="Agent Stack" href="/release-notes/agent-stack-2026" icon="robot" />

  <Card title="CCTP" href="/release-notes/cctp-2026" icon="arrow-up-arrow-down" />

  <Card title="Gateway" href="/release-notes/gateway-2026" icon="dungeon" />

  <Card title="xReserve" href="/release-notes/xreserve-2026" icon="vault" />

  <Card title="Wallets" href="/release-notes/wallets-2026" icon="wallet" />

  <Card title="Bridge Kit" href="/release-notes/bridge-kit-2026" icon="bridge" />

  <Card title="USDC" href="/release-notes/usdc-2026" icon="https://mintcdn.com/circle-167b8d39/K2XWSLhaeRomzNa1/images/assets/USDC_Token.svg?fit=max&auto=format&n=K2XWSLhaeRomzNa1&q=85&s=c89754c1e0dd17b3e1e1b0f32e256c9a" />

  <Card title="EURC" href="/release-notes/eurc-2026" icon="https://mintcdn.com/circle-167b8d39/K2XWSLhaeRomzNa1/images/assets/EURC_Token.svg?fit=max&auto=format&n=K2XWSLhaeRomzNa1&q=85&s=aae9cb36a2c95fb27b5b6ace4bfd2b3c" />

  <Card title="Mint" href="/release-notes/mint-2026" icon="building-columns" />

  <Card title="Circle Payments Network" href="/release-notes/cpn-2026" icon="globe" />

  <Card title="StableFX" href="/release-notes/stablefx-2026" icon="chart-line" />
</Columns>

## 2025

<Columns>
  <Card title="Developer Services" href="/release-notes/w3s-2025" />

  <Card title="Circle Mint" href="/release-notes/circle-mint-2025" />

  <Card title="Stablecoins" href="/release-notes/stablecoins-2025" />

  <Card title="Tokenized Funds" href="/release-notes/tokenized-funds-2025" />

  <Card title="Circle Payments Network" href="/release-notes/cpn-2025" />

  <Card title="StableFX" href="/release-notes/stablefx-2025" />
</Columns>

## 2024

<Columns>
  <Card title="Developer Services" href="/release-notes/w3s-2024" />

  <Card title="Circle Mint" href="/release-notes/circle-mint-2024" />

  <Card title="Stablecoins" href="/release-notes/stablecoins-2024" />
</Columns>


# Release Notes - Agent Stack - 2026
Source: https://developers.circle.com/release-notes/agent-stack-2026

2026 release notes for Agent Stack

## May 2026

<Update label="2026.05.12">
  Added documentation for Agent Nanopayments, which enables AI agents to make
  sub-cent USDC payments to x402-compatible services using Circle CLI.

  ### Documentation additions

  The following Agent Nanopayments documentation was created:

  * [Agent Nanopayments](/agent-stack/agent-nanopayments)
  * [Quickstart: Make a Nanopayment](/agent-stack/agent-nanopayments/quickstart)
  * [Nanopayment Operations](/agent-stack/agent-nanopayments/operations)
  * [How to: Withdraw Your Balance](/agent-stack/agent-nanopayments/operations/withdraw)

  ### Documentation updates

  The following how-tos moved from Agent Wallets into the new Agent Nanopayments
  section:

  * [How to: Deposit for Nanopayments](/agent-stack/agent-nanopayments/operations/deposit)
  * [How to: Pay for a Service](/agent-stack/agent-nanopayments/operations/pay-for-service)
</Update>

<Update label="2026.05.11">
  Launched Agent Stack, a new product line for AI agents to manage wallets,
  transact onchain, and pay for x402-compatible services using Circle CLI.

  ### Documentation additions

  The following Agent Stack and Circle CLI documentation was created:

  * [Agent Stack](/agent-stack)
  * [Circle CLI](/agent-stack/circle-cli)
  * [CLI Command Reference](/agent-stack/circle-cli/command-reference)

  The following Agent Wallets documentation was created:

  * [Agent Wallets](/agent-stack/agent-wallets)
  * [Quickstart: Create an Agent Wallet](/agent-stack/agent-wallets/quickstart)
  * [Agent Wallet Supported Blockchains](/agent-stack/agent-wallets/supported-blockchains)
  * [Agent Wallet Fees](/agent-stack/agent-wallets/fees)
  * [Wallet Operations](/agent-stack/agent-wallets/wallet-operations)
  * [How to: Authenticate an Agent Wallet](/agent-stack/agent-wallets/wallet-operations/authenticate)
  * [How to: Fund an Agent Wallet](/agent-stack/agent-wallets/wallet-operations/fund)
  * [How to: Transfer USDC](/agent-stack/agent-wallets/wallet-operations/transfer)
  * [How to: Bridge USDC](/agent-stack/agent-wallets/wallet-operations/bridge)
  * [How to: Swap Tokens](/agent-stack/agent-wallets/wallet-operations/swap)
  * [How to: Deposit for Nanopayments](/agent-stack/agent-wallets/wallet-operations/nanopay)
  * [How to: Pay for a Service](/agent-stack/agent-wallets/wallet-operations/pay-for-service)
  * [How to: Execute a Smart Contract](/agent-stack/agent-wallets/wallet-operations/execute-contract)
  * [How to: Sign a Message](/agent-stack/agent-wallets/wallet-operations/sign)
  * [How to: Set Spending Policies](/agent-stack/agent-wallets/wallet-operations/custom-policies)
</Update>


# Release Notes - Bridge Kit - 2026
Source: https://developers.circle.com/release-notes/bridge-kit-2026

2026 release notes for Circle's Bridge Kit SDK

<Check>
  **Bridge Kit has [moved to Arc](https://docs.arc.io/app-kit/bridge).**
</Check>

## March 2026

<Update label="2026.03.17">
  Bridge Kit is now part of [Arc App Kit](https://docs.arc.io/app-kit/).

  ### Documentation updates

  Migrated Bridge Kit documentation to the Arc developer docs:

  * [App Kit: Bridge](https://docs.arc.io/app-kit/bridge)
</Update>

<Update label="2026.03.10">
  Bridge Kit now supports Morph mainnet and Morph Hoodi Testnet (CCTP).

  ### Documentation updates

  Updated the following documentation to reflect support for Morph:

  * [Supported Blockchains](https://docs.arc.io/app-kit/references/supported-blockchains)
</Update>

<Update label="2026.03.09">
  Bridge Kit now supports EDGE mainnet and EDGE Testnet (CCTP).

  ### Documentation updates

  Updated the following documentation to reflect support for EDGE:

  * [Supported Blockchains](https://docs.arc.io/app-kit/references/supported-blockchains)
</Update>

## February 2026

<Update label="2026.02.27">
  Bridge Kit now supports the Circle Forwarding Service.

  ### Documentation additions

  Added the following documentation to reflect support for the Forwarding Service:

  * [Use the Forwarding Service](https://docs.arc.io/app-kit/tutorials/bridge/use-forwarding-service)

  ### Documentation updates

  Updated the following documentation to include the Forwarding Service fee:

  * [Custom Fees](https://docs.arc.io/app-kit/concepts/bridge-fees)
</Update>

## January 2026

<Update label="2026.01.28">
  Bridge Kit now supports Monad.

  ### Documentation updates

  Updated the following documentation to reflect support for Monad mainnet and
  testnet:

  * [Supported Blockchains](https://docs.arc.io/app-kit/references/supported-blockchains)
</Update>

<Update label="2026.01.14">
  The `estimate()` function now returns `token`, `amount`, `source`, and
  `destination` fields alongside cost estimates. Exported error type guards (such
  as `isKitError`, `isBalanceError`, `isOnchainError`), error constants (such as
  `BalanceError`, `OnchainError`), and helper functions (`getErrorCode`,
  `getErrorMessage`) for improved error detection and recovery.

  ### Documentation updates

  Updated the following documentation to reflect new method names and features:

  * [Bridge Kit Installation](https://docs.arc.io/app-kit/tutorials/installation)
  * [Quickstart: Bridge USDC Between EVM Chains](https://docs.arc.io/app-kit/quickstarts/bridge-between-evm-chains)
  * [Quickstart: Bridge USDC between Solana and EVM](https://docs.arc.io/app-kit/quickstarts/bridge-between-solana-and-evm)
  * [Adapter Setups](https://docs.arc.io/app-kit/tutorials/adapter-setups)
  * [Collect a Transfer Fee](https://docs.arc.io/app-kit/tutorials/bridge/collect-bridge-fee)
  * [Estimate Costs Before Transferring](https://docs.arc.io/app-kit/tutorials/bridge/estimate-costs)
  * [Configure Transfer Speed and Maximum Cost](https://docs.arc.io/app-kit/tutorials/bridge/configure-transfer-speed)
  * [Specify Recipient Address](https://docs.arc.io/app-kit/tutorials/bridge/specify-recipient-address)
  * [Error Recovery and Troubleshooting](https://docs.arc.io/app-kit/references/bridge-error-recovery)
  * [Bridge Kit SDK Reference](https://docs.arc.io/app-kit/references/sdk-reference)
</Update>


# Release Notes - CCTP - 2026
Source: https://developers.circle.com/release-notes/cctp-2026

2026 release notes for CCTP

## May 2026

<Update label="2026.05.18">
  Added support for Stellar mainnet.

  ### Documentation additions

  Added the following new topic to reflect Stellar mainnet support:

  * [Transfer USDC on Stellar](/stablecoins/quickstart-transfer-usdc-stellar)

  ### Documentation updates

  Updated the following topics to reflect Stellar mainnet support:

  * [CCTP Stellar Contracts and Interfaces](/cctp/references/stellar-contracts)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
</Update>

<Update label="2026.05.06">
  Added support for Injective mainnet.

  ### Documentation updates

  Updated the following topics to reflect Injective mainnet support:

  * [Contract Addresses: Mainnet](/cctp/references/contract-addresses#mainnet-contract-addresses)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
  * [Finality and Block Confirmations](/cctp/concepts/finality-and-block-confirmations)
</Update>

<Update label="2026.05.05">
  Updated Arc quickstarts to include a Forwarding Service branch.

  ### Documentation updates

  Updated the following topics:

  * [Transfer USDC from Ethereum to Arc](/cctp/quickstarts/transfer-usdc-ethereum-to-arc)
  * [Transfer USDC from Solana to Arc](/cctp/quickstarts/transfer-usdc-solana-to-arc)
</Update>

## April 2026

<Update label="2026.04.15">
  Added support for Pharos mainnet.

  ### Documentation updates

  Updated the following topics to reflect Pharos mainnet support:

  * [CCTP Fees](/cctp/concepts/fees)
  * [Finality and Block Confirmations](/cctp/concepts/finality-and-block-confirmations)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
  * [Contract Addresses: Mainnet](/cctp/references/contract-addresses#mainnet-contract-addresses)
</Update>

<Update label="2026.04.06">
  Added support for Stellar testnet.

  ### Documentation additions

  Added the following new topics to reflect Stellar testnet support:

  * [CCTP on Stellar](/cctp/references/stellar)
  * [CCTP Stellar Contracts and Interfaces](/cctp/references/stellar-contracts)
  * [Transfer USDC to and from Stellar](/cctp/quickstarts/transfer-usdc-stellar-arc)

  ### Documentation updates

  Updated the following topics to reflect Stellar testnet support:

  * [Contract Addresses: Testnet](/cctp/references/contract-addresses#testnet-contract-addresses)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
</Update>

## March 2026

<Update label="2026.03.17">
  Added support for Injective Testnet.

  ### Documentation updates

  Updated the following topics to reflect Injective Testnet support:

  * [Contract Addresses: Testnet](/cctp/references/contract-addresses#testnet-contract-addresses)
  * [Finality and Block Confirmations](/cctp/concepts/finality-and-block-confirmations)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
</Update>

<Update label="2026.03.10">
  Added support for Morph mainnet.

  ### Documentation updates

  Updated the following topics to reflect Morph mainnet support:

  * [Contract Addresses: Mainnet](/cctp/references/contract-addresses#mainnet-contract-addresses)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
  * [Finality and Block Confirmations](/cctp/concepts/finality-and-block-confirmations)
  * [Technical Guide: Fees](/cctp/references/technical-guide#fees)
</Update>

<Update label="2026.03.10">
  Added support for EDGE mainnet.

  ### Documentation updates

  Updated the following topics to reflect EDGE mainnet support:

  * [Contract Addresses: Mainnet](/cctp/references/contract-addresses#mainnet-contract-addresses)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
  * [Finality and Block Confirmations](/cctp/concepts/finality-and-block-confirmations)
  * [Technical Guide: Fees](/cctp/references/technical-guide#fees)
</Update>

## February 2026

<Update label="2026.02.26">
  Added support for Morph Hoodi Testnet.

  ### Documentation updates

  Updated the following topics to reflect Morph Hoodi Testnet support:

  * [Contract Addresses: Testnet](/cctp/references/contract-addresses#testnet-contract-addresses)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
</Update>

<Update label="2026.02.XX">
  Updated HyperCore CCTP transfer how-tos. Fixed signing parameters, contract
  addresses, fee calculations, and modernized code examples.

  ### Documentation updates

  Updated the following topics:

  * [Withdraw USDC from HyperCore to EVM chains](/cctp/howtos/withdraw-usdc-from-hypercore-to-evm)
  * [Withdraw USDC from HyperCore to HyperEVM](/cctp/howtos/withdraw-usdc-from-hypercore-to-hyperevm)
  * [Transfer USDC from Ethereum to HyperCore](/cctp/howtos/transfer-usdc-from-ethereum-to-hypercore)
  * [Transfer USDC from Solana to HyperCore](/cctp/howtos/transfer-usdc-from-solana-to-hypercore)
  * [Transfer USDC from Arbitrum to HyperCore](/cctp/howtos/transfer-usdc-from-arbitrum-to-hypercore)
  * [Transfer USDC from HyperEVM to HyperCore](/cctp/howtos/transfer-usdc-from-hyperevm-to-hypercore)
  * [Transfer USDC with the Forwarding Service](/cctp/howtos/transfer-usdc-with-forwarding-service)
  * [CCTP Fees](/cctp/concepts/fees)
</Update>

<Update label="2026.02.09">
  Added support for EDGE testnet.

  ### Documentation updates

  Updated the following topics to reflect EDGE testnet support:

  * [Contract Addresses](/cctp/references/contract-addresses)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
</Update>

## January 2026

<Update label="2026.01.22">
  Added support for the Circle Forwarding Service. The following new topics were
  created:

  ### Documentation additions

  * [Circle Forwarding Service](/cctp/concepts/forwarding-service)
  * [Transfer USDC with the Forwarding Service](/cctp/howtos/transfer-usdc-with-forwarding-service)

  ### Documentation updates

  * Updated the
    [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
    topic to reflect the new Forwarding Service support.
</Update>

<Update label="2026.01.12">
  ### Documentation updates

  Complete rewrite of the [CCTP documentation](/cctp) to focus on what you can
  build with CCTP. Emphasized [Bridge Kit](https://docs.arc.io/app-kit/bridge) as
  the easiest and preferred way to build with CCTP. Removed or reorganized
  sections to make the documentation more focused and easier to navigate. Updated
  the information architecture of the CCTP topics to be focused on the developer
  experience. Added functional Solana examples.

  The following topics were added or updated:

  * [CCTP Overview](/cctp)
  * [Supported Blockchains and Domains](/cctp/concepts/supported-chains-and-domains)
  * [Finality and Block Confirmations](/cctp/concepts/finality-and-block-confirmations)
  * [Transfer USDC from Ethereum to Arc](/cctp/quickstarts/transfer-usdc-ethereum-to-arc)
  * [Transfer USDC from Solana to Arc](/cctp/quickstarts/transfer-usdc-solana-to-arc)
  * [Transfer Fees](/cctp/concepts/fees)
  * [Fast Transfer Allowance](/cctp/concepts/fast-transfer-allowance)
  * [Get Transfer Fee](/cctp/howtos/get-transfer-fee)
  * [Get Fast Transfer Allowance](/cctp/howtos/get-fast-transfer-allowance)
  * [Troubleshoot Transfers](/cctp/howtos/troubleshoot-transfers)
  * [Resolve Stuck Attestation](/cctp/howtos/resolve-stuck-attestation)
  * [Retry Failed Mint](/cctp/howtos/retry-failed-mint)
  * [Technical Guide](/cctp/references/technical-guide)
  * [Contract Addresses](/cctp/references/contract-addresses)
  * [Attestation Verification](/cctp/references/attestation-verification)
  * [Contract Interfaces](/cctp/references/contract-interfaces)
  * [Solana Programs](/cctp/references/solana-programs)
  * [Starknet Contracts](/cctp/references/starknet-contracts)
</Update>

<Update label="2026.01.08">
  Updated the [table of CCTP fees](/cctp/technical-guide#fees) to reflect the new
  finality-indexed pricing model.
</Update>


# Release Notes - Circle Mint - 2024
Source: https://developers.circle.com/release-notes/circle-mint-2024

2024 release notes for Circle Mint

## December 2024

<Update label="2024.12.23">
  The Accounts API is no longer supported.

  ### Documentation updates

  * Removed references to the Accounts API.

  ### API updates

  * Removed Accounts API endpoints.
</Update>

## October 2024

<Update label="2024.10.23">
  ### API additions

  * Support the CUBIX account type. Added the following endpoints:
    * [`GET /businessAccount/banks/cubix`](/api-reference/circle-mint/account/list-business-cubix-accounts)
    * [`POST /businessAccount/banks/cubix`](/api-reference/circle-mint/account/create-business-cubix-account)
    * [`GET /businessAccount/banks/cubix/{id}`](/api-reference/circle-mint/account/get-business-cubix-account)
    * [`GET /businessAccount/banks/cubix/{id}/instructions`](/api-reference/circle-mint/account/get-business-cubix-account-instructions)
</Update>

<Update label="2024.10.08">
  Added support for USDC on the Sui blockchain.

  ### Documentation Updates

  Updated the following documents to reflect USDC on Sui support:

  * [Blockchain Confirmations](/circle-mint/references/blockchain-confirmations#confirmations)
  * [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies#usdc)
</Update>

## September 2024

<Update label="2024.09.23">
  ### API additions

  * Added the
    [`GET /fees/redemption/net/dailyReports`](/api-reference/circle-mint/account/list-net-burn-fee-daily-calculations)
    endpoint.
</Update>

<Update label="2024.09.03">
  ### API additions

  * Add `transferTypesInfo` to the following endpoints:
    * [`GET /account/list-business-wire-accounts`](/api-reference/circle-mint/account/list-business-wire-accounts)
    * [`GET /account/get-business-wire-account`](/api-reference/circle-mint/account/get-business-wire-account)
</Update>


# Release Notes - Circle Mint - 2025
Source: https://developers.circle.com/release-notes/circle-mint-2025

2025 release notes for Circle Mint

## December 2025

<Update label="2025.12.11">
  Added support for EURC on World Chain.

  ### Documentation updates

  Updated the following documentation to reflect EURC support on World Chain:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

<Update label="2025.12.03">
  Added support for USDC on the Starknet blockchain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on Starknet:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

## November 2025

<Update label="2025.11.24">
  Added support for USDC on the Monad blockchain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on Monad:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

## September 2025

<Update label="2025.09.25">
  Added support for USDC on the Ink blockchain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on Ink:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

<Update label="2025.09.23">
  Added support for USDC on the Plume blockchain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on Plume:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

<Update label="2025.09.17">
  Added support for USDC on the XDC blockchain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on XDC:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

<Update label="2025.09.16">
  Added support for USDC on the HyperEVM blockchain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on HyperEVM:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

<Update label="2025.09.09">
  Relaunched the Crypto Payouts API.

  ### Documentation updates

  Updated the following topics to reflect changes to the Crypto Payouts API in the
  relaunch:

  * [Resource Data Models](/circle-mint/circle-api-resources)
  * [Notifications Data Models](/circle-mint/notifications-data-models)
  * [API and Entity Errors](/circle-mint/circle-apis-api-errors)
  * [Quickstart: Crypto Payouts](/circle-mint/crypto-payouts)

  ### API updates

  Made the following changes to the Crypto Payouts API endpoints:

  * Updated the [`/v1/payouts`](/api-reference/circle-mint/payouts/create-payout)
    endpoint with an accurate listing of supported currencies
  * Updated the enum of supported chains in the
    [`/v1/addressBook/recipients`](/api-reference/circle-mint/payouts/create-address-book-recipient)
    endpoint
</Update>

## July 2025

<Update label="2025.07.24">
  Added support for USDC on the Sei blockchain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on Sei:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

## June 2025

<Update label="2025.06.24">
  Added support for USDC on the Codex blockchain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on Codex:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

<Update label="2025.06.12">
  Added support for USDC on Ripple Ledger (XRPL).

  ### Documentation updates

  Updated the following documentation to reflect USDC support on XRPL:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

<Update label="2025.06.11">
  Added support for USDC on World Chain.

  ### Documentation updates

  Updated the following documentation to reflect USDC support on World Chain:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

## May 2025

<Update label="2025.05.13">
  Added support for USDC bridge to native upgrade for Sonic.

  ### Documentation updates

  Updated the following documentation to reflect Sonic support:

  * [Circle Mint Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Circle Mint Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

## April 2025

<Update label="2025.04.03">
  Ensure API documentation accurately reflects available features of Circle Mint.

  ### API updates

  * Removed APIs for deprecated products and products that never officially
    launched. The following APIs were removed:
    * Pull Crypto Payments
    * Cards
    * Payment Tokens
    * Settlements
    * Checkout Sessions

  * The following endpoints were deprecated and removed from the Crypto Deposits
    API:
    * `POST /payments`
    * `POST /payments/{id}/capture`
    * `POST /payments/{id}/cancel`
    * `POST /payments/{id}/refund`

  * Renamed the Payments API to the Crypto Deposits API

  * Renamed the Payouts API to the Crypto Payouts API

  * Removed unsupported blockchains listed in the following endpoints:
    * [`POST /addressBook/recipients`](/api-reference/circle-mint/payouts/create-address-book-recipient)
    * [`POST /paymentIntents`](/api-reference/circle-mint/payments/create-payment-intent)
</Update>

## March 2025

<Update label="2025.03.26">
  Added support for USDC on the Linea blockchain.

  ### Documentation updates

  Updated the following documents to reflect USDC on Linea support:

  * [Blockchain Confirmations](/circle-mint/references/blockchain-confirmations#confirmations)
  * [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies#usdc)

  ### API updates

  * Added `LINEA` to the list of supported chains.
  * Added `UNI` to the list of supported chains.
</Update>

<Update label="2025.03.06">
  Major clean up of the Circle Mint documentation. Removed references to
  deprecated products and updated out-of-date information.
</Update>

## February 2025

<Update label="2025.02.11">
  Added support for USDC on the Unichain blockchain.

  ### Documentation updates

  Updated the following documents to reflect USDC on Unichain support:

  * [Blockchain Confirmations](/circle-mint/references/blockchain-confirmations#confirmations)
  * [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies#usdc)
</Update>

## January 2025

<Update label="2025.01.30">
  Added support for USDC on the Aptos blockchain.

  ### Documentation Updates

  Updated the following documents to reflect USDC on Aptos support:

  * [Blockchain Confirmations](/circle-mint/references/blockchain-confirmations#confirmations)
  * [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies#usdc)

  ### API updates

  * Added `APTOS` to the list of supported chains
</Update>

<Update label="2025.01.09">
  France is now available as a travel rule entity. Began deprecating CBIT support.

  ### API additions

  * Added France to the
    [`POST /businessAccount/wallets/addresses/recipient`](/api-reference/circle-mint/account/create-business-recipient-address)
    endpoint
  * Added `SUI` and `ZKS` to the list of supported chains

  ### API updates

  * Removed CBIT endpoint documentation
  * Removed `FLOW` and `TRX` from the list of supported chains
</Update>


# Release Notes - Circle Payments Network - 2025
Source: https://developers.circle.com/release-notes/cpn-2025

2025 release notes for Circle Payments Network

## August 2025

<Update label="2025.08.29">
  ### Documentation additions

  * Added a topic on detailed
    [payment failure codes](/cpn/references/errors/payment-failure-codes) to help
    explain why a payment failed and how to resolve the issue

  ### Documentation updates

  * Updated
    [payment failure reasons](/cpn/references/errors/payment-and-transaction-failure-reasons#payments)
    with new values
  * Added new [magic values](/cpn/references/testing/magic-values) for testing
    refund workflows
  * Added a new [payment error code](/cpn/references/errors/error-codes#payment)
    (`290207`) for missing required parameters
  * Added new [RFI error codes](/cpn/references/errors/error-codes#rfi) (`290302`,
    `290303`, `290304`, `290305`) for RFI verification failures

  ### API updates

  * Added the optional `quoteOptions` field to the
    [`POST /v1/cpn/quotes`](/api-reference/cpn/cpn-platform/create-quotes)
    endpoint to support additional quote options when creating a quote.
  * Updated the allowed values for `failureReason` for payments and transactions
    to reflect new failure reasons.
  * Added `failureCode` to the response of the following endpoints:
    * [`POST /v1/cpn/payments`](/api-reference/cpn/cpn-platform/create-payment)
    * [`GET /v1/cpn/payments`](/api-reference/cpn/cpn-platform/list-payments)
    * [`GET /v1/cpn/payments/{paymentId}`](/api-reference/cpn/cpn-platform/get-payment)
</Update>

## July 2025

<Update label="2025.07.25">
  Added full DevDocs for OFIs for Circle Payments network:

  ### Documentation additions

  Added the following topics for CPN:

  * [CPN Overview](/cpn)
  * [API Integration Concepts](/cpn/concepts/api/api-integration)
  * [Quickstart: Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi)
  * [How-to: Set up Webhook Notifications](/cpn/guides/webhooks/setup-webhook-notifications)
  * [How-to: Verify Webhook Signatures](/cpn/guides/webhooks/verify-webhook-signatures)
  * [How-to: Request Payment Configurations and Routes](/cpn/guides/payments/request-payment-config)
  * [How-to: Integrate with JSON Schema](/cpn/guides/payments/integrate-with-json-schema)
  * [How-to: Encrypt Travel Rule and Beneficiary Data](/cpn/guides/payments/encrypt-travel-rule-beneficiary-data)
  * [How-to: Create an Onchain Transaction](/cpn/guides/transactions/create-an-onchain-txn)
  * [How-to: Encrypt Files for RFI Transmission](/cpn/guides/payments/encrypt-files)
  * [How-to: Create a Support Ticket](/cpn/guides/supports/create-support-ticket)
  * [Supported Blockchains](/cpn/references/blockchains/supported-blockchains)
  * [Wallet Provider Compatibility](/cpn/references/blockchains/wallet-provider-compatibility)
  * [Component States and Workflows](/cpn/concepts/payments/component-states-and-workflows)
  * [Magic Values for Testing](/cpn/references/testing/magic-values)
  * [Webhook Events](/cpn/references/webhooks/webhook-events)
  * [Webhook Retries](/cpn/concepts/webhooks/webhook-retries)
  * [Payment and Transaction Failure Reasons](/cpn/references/errors/payment-and-transaction-failure-reasons)
  * [Error Codes](/cpn/references/errors/error-codes)
  * [JSON Schema](/cpn/concepts/api/json-schema)
  * [RFI Levels](/cpn/references/compliance/rfi-levels)
  * [Travel Rule Requirements](/cpn/references/compliance/travel-rule-requirements)
  * [Payment Reference](/cpn/concepts/payments/payment-reference)
  * [Validating Brazilian Tax ID and Bank Account Numbers](/cpn/references/compliance/validating-brazil-tax-account-id)

  ### API additions

  Added the following CPN endpoints:

  * [`GET /v1/cpn/configurations/overview`](/api-reference/cpn/cpn-platform/get-payment-configurations-overview)
  * [`GET /v1/cpn/configurations/routes`](/api-reference/cpn/cpn-platform/list-routes)
  * [`POST /v1/cpn/quotes`](/api-reference/cpn/cpn-platform/create-quotes)
  * [`GET /v1/cpn/quotes/{quoteId}`](/api-reference/cpn/cpn-platform/get-quote)
  * [`GET /v1/cpn/payments`](/api-reference/cpn/cpn-platform/list-payments)
  * [`POST /v1/cpn/payments`](/api-reference/cpn/cpn-platform/create-payment)
  * [`GET /v1/cpn/payments/{paymendId}`](/api-reference/cpn/cpn-platform/get-payment)
  * [`GET /v1/cpn/payments/{paymentId}/refunds/{refundId}`](/api-reference/cpn/cpn-platform/get-refund)
  * [`GET /v1/cpn/payments/requirements`](/api-reference/cpn/cpn-platform/get-payment-requirements)
  * [`POST /v1/cpn/payments/{paymentId}/transactions`](/api-reference/cpn/cpn-platform/create-transaction)
  * [`GET /v1/cpn/payments/{paymentId}/transactions/{transactionId}`](/api-reference/cpn/cpn-platform/get-transaction)
  * [`POST /v1/cpn/payments/{paymentId}/transactions/{transactionId}/submit`](/api-reference/cpn/cpn-platform/submit-transaction)
  * [`POST /v1/cpn/payments/{paymentId}/transactions/accelerate`](/api-reference/cpn/cpn-platform/accelerate-transaction)
  * [`GET /v1/cpn/payments/{paymentId}/rfis/{rfiId}`](/api-reference/cpn/cpn-platform/get-rfi)
  * [`POST /v1/cpn/payments/{paymentId}/rfis/{rfiId}/submit`](/api-reference/cpn/cpn-platform/submit-rfi)
  * [`POST /v1/cpn/payments/{paymentId}/rfis/{rfiId}/files`](/api-reference/cpn/cpn-platform/upload-rfi-file)
  * [`POST /v1/cpn/supportTickets`](/api-reference/cpn/cpn-platform/create-support-ticket)
</Update>


# Release Notes - Circle Payments Network - 2026
Source: https://developers.circle.com/release-notes/cpn-2026

2026 release notes for Circle Payments Network

## April 2026

<Update label="2026.04.28">
  ### Documentation additions

  Added the following new topic for Managed Payments webhook events:

  * [Webhook Events](/cpn/managed-payments/references/webhook-events)
</Update>

<Update label="2026.04.16">
  ### API updates

  Added and corrected the following Managed Payments endpoints:

  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/deposits`](/api-reference/cpn/managed-payments/deposits/list-account-deposits)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/deposits/{depositId}`](/api-reference/cpn/managed-payments/deposits/get-account-deposit)
  * [`POST /v1/cpn/managedPayments/accounts/{accountId}/wireAccounts`](/api-reference/cpn/managed-payments/wires/create-account-wire-account)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/wireAccounts/{wireAccountId}/instructions`](/api-reference/cpn/managed-payments/wires/get-account-wire-account-instructions)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/wireAccounts/{wireAccountId}`](/api-reference/cpn/managed-payments/wires/get-account-wire-account)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/wireAccounts`](/api-reference/cpn/managed-payments/wires/list-account-wire-accounts)
  * [`POST /v1/cpn/managedPayments/accounts/{accountId}/withdrawals`](/api-reference/cpn/managed-payments/withdrawals/create-account-withdrawal)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/withdrawals`](/api-reference/cpn/managed-payments/withdrawals/list-account-withdrawals)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/withdrawals/{withdrawalId}`](/api-reference/cpn/managed-payments/withdrawals/get-account-withdrawal)
</Update>

<Update label="2026.04.15">
  ### API additions

  Added the following Managed Payments credit endpoints:

  * [`POST /v1/cpn/managedPayments/credit/transfers`](/api-reference/cpn/managed-payments/credit/create-managed-payments-credit-transfer)
  * [`GET /v1/cpn/managedPayments/credit/line`](/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-line)
  * [`GET /v1/cpn/managedPayments/credit/transfers/{transferId}`](/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-transfer)
  * [`GET /v1/cpn/managedPayments/credit/wireInstructions`](/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-wire-instructions)
  * [`GET /v1/cpn/managedPayments/credit/transfers`](/api-reference/cpn/managed-payments/credit/list-managed-payments-credit-transfers)
</Update>

<Update label="2026.04.08">
  Added documentation for CPN Managed Payments. With Managed Payments, Circle
  handles licensing, compliance, minting, and settlement so you can offer
  stablecoin payments without building these systems yourself.

  ### Documentation additions

  Added the following topics for Managed Payments:

  * [CPN Managed Payments Overview](/cpn/managed-payments)
  * [Quickstart: Receive Stablecoin Payins](/cpn/managed-payments/quickstarts/receive-stablecoin-payins)
  * [Quickstart: Send Stablecoin Payouts](/cpn/managed-payments/quickstarts/send-stablecoin-payouts)
  * [Settlement Flows](/cpn/managed-payments/concepts/settlement-flows)
  * [Sub-Wallet Architecture](/cpn/managed-payments/concepts/sub-wallet-architecture)

  ### API additions

  Added the following Managed Payments endpoints:

  * [`GET /v1/cpn/managedPayments/accounts`](/api-reference/cpn/managed-payments/accounts/list-accounts)
  * [`POST /v1/cpn/managedPayments/accounts`](/api-reference/cpn/managed-payments/accounts/create-account)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}`](/api-reference/cpn/managed-payments/accounts/get-account)
  * [`GET /v1/cpn/managedPayments/paymentIntents`](/api-reference/cpn/managed-payments/payment-intents/list-payment-intents)
  * [`POST /v1/cpn/managedPayments/paymentIntents`](/api-reference/cpn/managed-payments/payment-intents/create-payment-intent)
  * [`GET /v1/cpn/managedPayments/paymentIntents/{paymentIntentId}`](/api-reference/cpn/managed-payments/payment-intents/get-payment-intent)
  * [`POST /v1/cpn/managedPayments/paymentIntents/{paymentIntentId}/expire`](/api-reference/cpn/managed-payments/payment-intents/expire-payment-intent)
  * [`POST /v1/cpn/managedPayments/paymentIntents/{paymentIntentId}/refund`](/api-reference/cpn/managed-payments/payment-intents/refund-payment-intent)
  * [`GET /v1/cpn/managedPayments/payments`](/api-reference/cpn/managed-payments/payments/list-payments)
  * [`GET /v1/cpn/managedPayments/payments/{paymentId}`](/api-reference/cpn/managed-payments/payments/get-payment)
  * [`POST /v1/cpn/managedPayments/accounts/{accountId}/withdrawals`](/api-reference/cpn/managed-payments/withdrawals/create-account-withdrawal)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/withdrawals`](/api-reference/cpn/managed-payments/withdrawals/list-account-withdrawals)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/withdrawals/{withdrawalId}`](/api-reference/cpn/managed-payments/withdrawals/get-account-withdrawal)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/deposits`](/api-reference/cpn/managed-payments/deposits/list-account-deposits)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/deposits/{depositId}`](/api-reference/cpn/managed-payments/deposits/get-account-deposit)
  * [`POST /v1/cpn/managedPayments/accounts/{accountId}/wireAccounts`](/api-reference/cpn/managed-payments/wires/create-account-wire-account)
  * [`GET /v1/cpn/managedPayments/accounts/{accountId}/wireAccounts/{wireAccountId}/instructions`](/api-reference/cpn/managed-payments/wires/get-account-wire-account-instructions)
  * [`GET /v1/cpn/managedPayments/addressBook/recipients`](/api-reference/cpn/managed-payments/address-book/list-address-book-recipients)
  * [`POST /v1/cpn/managedPayments/addressBook/recipients`](/api-reference/cpn/managed-payments/address-book/create-address-book-recipient)
  * [`GET /v1/cpn/managedPayments/addressBook/recipients/{recipientId}`](/api-reference/cpn/managed-payments/address-book/get-address-book-recipient)
  * [`PATCH /v1/cpn/managedPayments/addressBook/recipients/{recipientId}`](/api-reference/cpn/managed-payments/address-book/modify-address-book-recipient)
  * [`DELETE /v1/cpn/managedPayments/addressBook/recipients/{recipientId}`](/api-reference/cpn/managed-payments/address-book/delete-address-book-recipient)
  * [`GET /v1/cpn/managedPayments/payouts`](/api-reference/cpn/managed-payments/payouts/list-payouts)
  * [`POST /v1/cpn/managedPayments/payouts`](/api-reference/cpn/managed-payments/payouts/create-payout)
  * [`GET /v1/cpn/managedPayments/payouts/{payoutId}`](/api-reference/cpn/managed-payments/payouts/get-payout)
</Update>

<Update label="2026.04.01">
  Documentation updates for **CPN Console 2.0**: expanded and clarified developer
  docs for Circle Payments Network (CPN), including new how-tos, navigation
  updates, a refreshed landing page, webhook guidance, and quickstart
  improvements.

  ### Documentation additions

  * [How-to: Set Up a Circle Wallet for CPN Payments](/cpn/guides/wallets/setup-circle-wallet-for-cpn-payments)
  * [How-to: Set Up Circle On/Off-Ramps for CPN Payments](/cpn/guides/circle-liquidity/setup-circle-on-off-ramps-for-cpn-payments)
  * [Bring Your Own Wallet for CPN](/cpn/concepts/wallets/bring-your-own-wallet)

  ### Documentation updates

  * [CPN Overview](/cpn)
  * [Quickstart: Integrate with CPN as an OFI](/cpn/quickstarts/integrate-with-cpn-ofi)
  * [Webhook Events](/cpn/references/webhooks/webhook-events)
</Update>


# Release Notes - EURC - 2026
Source: https://developers.circle.com/release-notes/eurc-2026

2026 release notes for EURC

## January 2026

<Update label="2026.01.23">
  ### Documentation updates

  Updated the transfer EURC quickstart to show all supported EVM chains:

  * [Transfer EURC on EVM chains](/stablecoins/quickstarts/transfer-eurc-evm)
</Update>


# Release Notes - Gateway - 2026
Source: https://developers.circle.com/release-notes/gateway-2026

2026 release notes for Gateway

## May 2026

<Update label="2026.05.05">
  Added Gateway webhook documentation and subscription management API references.

  ### Documentation additions

  The following documentation was created:

  * [Gateway Webhooks](/gateway/webhooks)
  * [Gateway Webhook Events](/gateway/references/webhook-events)

  ### API additions

  Added the following endpoints to support Gateway webhook subscriptions:

  * [`POST /v2/notifications/subscriptions/permissionless`](/api-reference/gateway/all/create-permissionless-subscription)
  * [`GET /v2/notifications/subscriptions/permissionless`](/api-reference/gateway/all/get-permissionless-subscriptions)
  * [`GET /v2/notifications/subscriptions/permissionless/{id}`](/api-reference/gateway/all/get-permissionless-subscription)
  * [`PUT /v2/notifications/subscriptions/permissionless/{id}`](/api-reference/gateway/all/update-permissionless-subscription)
  * [`DELETE /v2/notifications/subscriptions/permissionless/{id}`](/api-reference/gateway/all/delete-permissionless-subscription)
  * [`POST /v2/notifications/subscriptions/permissionless/{id}/test`](/api-reference/gateway/all/test-permissionless-subscription-connection)
  * [`POST /v2/notifications/subscriptions/permissionless/{id}/test-notification`](/api-reference/gateway/all/send-permissionless-subscription-test-notification)
  * [`GET /v2/notifications/signatures/{notificationId}`](/api-reference/gateway/all/get-permissionless-notification-signature)
</Update>

<Update label="2026.05.04">
  Added a new quickstart for making gasless Gateway deposits with Eco.

  ### Documentation additions

  The following documentation was created:

  * [Quickstart: Gasless Gateway Deposits with Eco](/gateway/quickstarts/eco-gasless-deposits)
</Update>

## April 2026

<Update label="2026.04.29">
  Updated nanopayments documentation to reflect mainnet launch support.

  ### Documentation updates

  The following documentation was updated:

  * [Supported Networks](/gateway/nanopayments/supported-networks)
  * [Gateway Supported Blockchains](/gateway/references/supported-blockchains)
</Update>

<Update label="2026.04.24">
  Expanded the nanopayments documentation with additional buyer, seller,
  facilitator, and x402 integration guidance.

  ### Documentation updates

  The following documentation was updated:

  * [Quickstart: Pay for Resources with Nanopayments](/gateway/nanopayments/quickstarts/buyer)
  * [Quickstart: Accept Payments with Nanopayments](/gateway/nanopayments/quickstarts/seller)
  * [How-to: Integrate Nanopayments into Your Existing Facilitator](/gateway/nanopayments/howtos/facilitator-integration)
  * [How-to: Add Nanopayments to an x402 Buyer](/gateway/nanopayments/howtos/x402-buyer)
  * [How-to: Add Nanopayments to an x402 Seller](/gateway/nanopayments/howtos/x402-seller)
  * [How-to: Use Nanopayments with x402](/gateway/nanopayments/howtos/x402-integration)
  * [How-to: Sign EIP-3009 Payment Authorizations](/gateway/nanopayments/howtos/eip-3009-signing)
</Update>

<Update label="2026.04.17">
  Updated Gateway on Solana documentation to support transfers with the Forwarding
  Service and automatic ATA creation.

  ### Documentation updates

  The following documentation was updated:

  * [How-to: Transfer with the Forwarding Service](/gateway/howtos/forwarding-service)
  * [Quickstart: Create and Transfer a Unified USDC Balance on Solana](/gateway/quickstarts/unified-balance-solana)
  * [Gateway Fees](/gateway/references/fees)
  * [Circle Forwarding Service for Gateway](/gateway/references/forwarding-service)
  * [Technical Guide for Gateway on Solana](/gateway/references/solana)
</Update>

## March 2026

<Update label="2026.03.19">
  Updated the Gateway unified balance quickstarts to support both Circle Wallets
  and permissionless implementations on the same page.

  ### Documentation updates

  The following documentation was updated:

  * [Quickstart: Create and Transfer a Unified USDC Balance on EVM](/gateway/quickstarts/unified-balance-evm#circle-wallets)
  * [Quickstart: Create and Transfer a Unified USDC Balance on Solana](/gateway/quickstarts/unified-balance-solana#circle-wallets)
</Update>

## February 2026

<Update label="2026.02.11">
  Added Forwarding Service support for Gateway. The following new topic was
  created:

  * [Gateway Forwarding Service](/gateway/references/forwarding-service)
</Update>

<Update label="2026.02.07">
  Added support for managing delegates for Smart Contract Account (SCA) wallets.

  ### Documentation additions

  The following documentation was created:

  * [How-to: Manage Delegates for Smart Contract Wallets](/gateway/howtos/manage-delegates)
</Update>

<Update label="2026.02.02">
  Updated Gateway quickstart guides and how-tos to use consistent script structure
  and console output patterns.

  ### Documentation updates

  The following documentation were updated:

  * [Quickstart: Create and Transfer a Unified USDC Balance (EVM)](/gateway/quickstarts/unified-balance-evm)
  * [Quickstart: Create and Transfer a Unified USDC Balance (Solana)](/gateway/quickstarts/unified-balance-solana)
  * [How-to: Create a Unified USDC Balance](/gateway/howtos/create-unified-usdc-balance)
  * [How-to: Transfer a Unified USDC Balance Instantly](/gateway/howtos/transfer-unified-usdc-balance)
</Update>

## January 2026

<Update label="2026.01.30">
  ### API additions

  Added the following endpoints to support Circle Gateway:

  * [`POST /v1/deposits`](/api-reference/gateway/all/get-deposits)
</Update>

<Update label="2026.01.14">
  Added support for Gateway on Solana. The following new topics were created:

  * [Gateway Technical Guide](/gateway/references/solana)
  * [Gateway Solana Programs and Interfaces](/gateway/references/solana-programs)
  * [Gateway Solana Quickstart](/gateway/quickstarts/unified-balance-solana)
</Update>


# Release Notes - Mint - 2026
Source: https://developers.circle.com/release-notes/mint-2026

2026 release notes for Mint

## May 2026

<Update label="2026.05.01">
  ### Documentation updates

  Rewrote the Circle Mint documentation to improve onboarding, product framing,
  quickstarts, and core reference material for supported chains, countries, and
  sandbox testing.

  The following topics were added or updated:

  * [Set Up Your Mint Account](/circle-mint/quickstarts/getting-started)
  * [Quickstart: Mint and Redeem USDC](/circle-mint/quickstarts/mint-and-redeem)
  * [How Stablecoin Payins and Payouts Work](/circle-mint/how-stablecoin-payins-and-payouts-work)
  * [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Supported Countries](/circle-mint/references/supported-countries)
  * [Sandbox and Testing](/circle-mint/references/sandbox-and-testing)
</Update>

## April 2026

<Update label="2026.04.27">
  ### Documentation additions

  Added the following new topic for treasury reconciliation workflows:

  * [CAMT.053 Daily Statements for Reconciliation](/circle-mint/camt053-statements)
</Update>

<Update label="2026.04.03">
  **Crypto Payouts** and **Crypto Address Book** docs now include Singapore
  (**CIRCLE\_SG**) coverage. They add Travel Rule notes, payment reason codes, and
  `VASP` data for hosted custody.

  ### Documentation additions

  * [Crypto Payouts payment reason codes](/circle-mint/crypto-payouts-payment-reason-codes)

  ### Documentation updates

  * **Crypto Payouts API:** Documented `purposeOfTransfer` on create and get.
    Singapore (**CIRCLE\_SG**) customers must send a payment reason code to create
    a payout.
  * **Crypto Address Book API:** Documented request and response shapes for
    General and Singapore (**CIRCLE\_SG**) customer entities.
</Update>

<Update label="2026.04.02">
  Continuous payment intents are now the default type when
  [creating a payment intent](/api-reference/circle-mint/payments/create-payment-intent).

  ### Documentation additions

  Added the following new topic to explain how stablecoin payins and payouts work,
  including continuous and transient payment intents:

  * [How Stablecoin Payins and Payouts Work](/circle-mint/how-stablecoin-payins-and-payouts-work)

  ### Documentation updates

  Updated the following quickstarts to align terminology and structure with the
  stablecoin payins and payouts flow, and to make the steps easier to follow
  end-to-end:

  * [Quickstart: Receive a Stablecoin Payin](/circle-mint/receive-stablecoin-payin)
    (formerly "Quickstart: Crypto Deposits")
  * [Quickstart: Refund a Stablecoin Payin](/circle-mint/refund-stablecoin-payin)
    (formerly "Quickstart: Crypto Refunds")
  * [Quickstart: Send a Stablecoin Payout](/circle-mint/send-stablecoin-payout)
    (formerly "Send USDC from your Circle Mint Account")
</Update>

<Update label="2026.04.01">
  Launched the Credit API, enabling programmatic access to Settlement Advance and
  Line of Credit products. You can now initiate draws, track transfer status,
  manage fees, and process repayments through endpoints under `/v1/credit/`.

  ### Documentation updates

  Added the following topics for the Credit API:

  * [Credit API Overview](/circle-mint/credit-api/overview)
  * [Quickstart: Settlement Advance](/circle-mint/credit-api/quickstart-settlement-advance)
  * [Quickstart: Line of Credit](/circle-mint/credit-api/quickstart-line-of-credit)
</Update>

## March 2026

<Update label="2026.03.10">
  Added support for USDC on the Morph blockchain.

  ### Documentation updates

  Updated the following topics to reflect USDC support on Morph:

  * [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>

<Update label="2026.03.10">
  Added support for USDC on the EDGE blockchain.

  ### Documentation updates

  Updated the following topics to reflect USDC support on EDGE:

  * [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies)
  * [Blockchain Confirmations](/circle-mint/references/blockchain-confirmations)
</Update>


# Release Notes - Stablecoins - 2024
Source: https://developers.circle.com/release-notes/stablecoins-2024

2024 release notes for Stablecoins

## December 2024

<Update label="2024.12.17">
  Added support for CCTP V1 on the Sui blockchain.

  ### Documentation additions

  Added the following document to reflect CCTP V1 support on Sui:

  * [CCTP Sui Packages and Interfaces](/cctp/v1/sui-packages)

  ### Documentation updates

  Updated the following documents to reflect CCTP V1 support on Sui:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Blockchains V1](/cctp/v1/cctp-supported-blockchains)
  * [CCTP Block Confirmations V1](/cctp/v1/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces V1](/cctp/v1/evm-smart-contracts)
  * [CCTP Chain Domains V1](/cctp/v1/supported-domains)
</Update>

## October 2024

<Update label="2024.10.08">
  Added Quickstart for USDC on Sui, featuring a web app that transfers USDC.

  ### Documentation additions

  * [Quickstart: Set up and transfer USDC on Sui](/stablecoins/quickstart-setup-transfer-usdc-sui)
</Update>

## September 2024

<Update label="2024.09.17">
  Added support for USDC on Sui mainnet and testnet.

  ### Documentation updates

  Updated the following docs to include USDC contract addresses for Sui:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)
</Update>


# Release Notes - Stablecoins - 2025
Source: https://developers.circle.com/release-notes/stablecoins-2025

2025 release notes for Stablecoins

## December 2025

<Update label="2025.12.18">
  Added support for USDCx on the Stacks mainnet and testnet through xReserve.

  ### Documentation updates

  Updated the following topic to reflect support for USDCx on Stacks:

  * [xReserve Supported Blockchains and Domains](/xreserve/references/supported-blockchains-and-domains)
</Update>

<Update label="2025.12.11">
  Added support for EURC on World Chain.

  ### Documentation updates

  Updated the following documentation to reflect support for World Chain:

  * [EURC Contract Addresses](/stablecoins/eurc-contract-addresses)
</Update>

<Update label="2025.12.04">
  Launched xReserve with Canton as a remote blockchain partner. Canton provides
  USDCx through xReserve.

  ### Documentation additions

  Added the following new topics to support the launch of xReserve and USDCx on
  Canton:

  * [Quickstart: Deposit USDC into xReserve](/xreserve/tutorials/deposit-usdc-into-xreserve)
  * [Initiate a Withdrawal from xReserve as a Remote Blockchain](/xreserve/tutorials/initiate-a-withdrawal-as-a-remote-blockchain)
  * [xReserve Withdrawal Fees](/xreserve/references/fees)

  ### Documentation updates

  Updated the following topics to reflect support for USDCx on Canton:

  * [xReserve Supported Blockchains and Domains](/xreserve/references/supported-blockchains-and-domains)

  ### API additions

  Added the following new API endpoints:

  * [`GET /v1/attestations/{depositMessageHash}`](/api-reference/xreserve/all/get-attestation)
  * [`GET /v1/remote-domains/{remoteDomain}/attestations`](/api-reference/xreserve/all/list-attestations)
  * [`GET /v1/balances/{remoteDomain}`](/api-reference/xreserve/all/get-balances)
  * [`GET /v1/info`](/api-reference/xreserve/all/get-info)
  * [`POST /v1/prepare-withdrawal`](/api-reference/xreserve/all/prepare-withdrawal)
  * [`POST /v1/withdraw`](/api-reference/xreserve/all/submit-withdrawal)
  * [`GET /v1/withdrawal/{withdrawalId}`](/api-reference/xreserve/all/get-withdrawal-status)
</Update>

<Update label="2025.12.03">
  Added support for CCTP on the Starknet mainnet.

  ### Documentation updates

  Updated the following documentation to reflect support for Starknet mainnet:

  * [USDC Contract Addresses: Mainnet](/stablecoins/usdc-contract-addresses#mainnet)
  * [CCTP Starknet Contracts and Interfaces](/cctp/starknet-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

## November 2025

<Update label="2025.11.18">
  Announced the upcoming launch of xReserve.

  ### Documentation additions

  Created the following new topics to support xReserve:

  * [xReserve Overview](/xreserve)
  * [xReserve Technical Guide](/xreserve/concepts/technical-guide)
  * [How xReserve Works](/xreserve/concepts/how-xreserve-works)
  * [xReserve Supported Blockchains and Domains](/xreserve/references/supported-blockchains-and-domains)
</Update>

<Update label="2025.11.24">
  * Added support for USDC on the Monad mainnet.
  * Added support for CCTP on the Monad mainnet.

  ### Documentation additions

  Added a quickstart to showcase how to transfer USDC on Monad:

  * [Quickstart: Set up and transfer USDC on Monad](/stablecoins/quickstart-setup-transfer-usdc-monad)

  ### Documentation updates

  Updated the following documentation to include the USDC contract address for
  Monad mainnet:

  * [USDC Contract Addresses: Mainnet](/stablecoins/usdc-contract-addresses#mainnet)

  Updated the following documentation to reflect CCTP support on Monad mainnet:

  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
</Update>

<Update label="2025.11.12">
  * Added support for USDC on the Starknet testnet.
  * Added support for CCTP V2 on the Starknet testnet.

  ### Documentation additions

  Added the following documentation to reflect CCTP V2 support on Starknet
  testnet:

  * [CCTP Starknet Contracts and Interfaces](/cctp/starknet-contracts)

  ### Documentation updates

  Updated the following documentation to include the USDC contract address for
  Starknet testnet:

  * [USDC Contract Addresses: Testnet](/stablecoins/usdc-contract-addresses#testnet)

  Updated the following documentation to reflect CCTP V2 support on Starknet
  testnet:

  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
</Update>

## October 2025

<Update label="2025.10.31">
  * Added support for USDC on the Monad Testnet
  * Added support for CCTP V2 on the Monad Testnet

  ### Documentation updates

  Updated the following documentation to include the USDC contract address for
  Monad testnet:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)

  Updated the following documentation to reflect support for Monad testnet:

  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
</Update>

<Update label="2025.10.27">
  * Added support for USDC and EURC on Arc testnet
  * Added support for CCTP V2 on Arc testnet

  ### Documentation updates

  Updated the following documentation to include USDC and EURC contract addresses
  for Arc testnet:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)
  * [EURC Contract Addresses](/stablecoins/eurc-contract-addresses)

  Updated the following documentation to reflect support for Arc testnet:

  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
</Update>

## September 2025

<Update label="2025.09.25">
  Added support for CCTP V2 on the Ink blockchain.

  ### Documentation additions

  Added a quickstart to showcase how to transfer USDC on Ink:

  * [Quickstart: Set up and transfer USDC on Ink](/stablecoins/quickstart-setup-transfer-usdc-ink)

  ### Documentation updates

  Updated the following documentation to reflect support for Ink mainnet and
  testnet:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.09.23">
  Added support for CCTP V2 on the Plume mainnet.

  ### Documentation additions

  Added a quickstart to showcase how to transfer USDC on Plume:

  * [Quickstart: Set up and transfer USDC on Plume](/stablecoins/quickstart-setup-transfer-usdc-plume)

  ### Documentation updates

  Updated the following documentation to reflect support for Plume mainnet:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.09.17">
  Added support for CCTP V2 on the XDC mainnet.

  ### Documentation additions

  Added a quickstart to showcase how to transfer USDC on XDC:

  * [Quickstart: Set up and transfer USDC on XDC](/stablecoins/quickstart-setup-transfer-usdc-xdc)

  ### Documentation updates

  Updated the following documentation to reflect support for XDC mainnet:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.09.16">
  * Added support for USDC on the HyperEVM blockchain.
  * Added support for CCTP V2 on the HyperEVM blockchain.

  ### Documentation additions

  Added a quickstart to showcase how to transfer USDC on HyperEVM:

  * [Quickstart: Set up and transfer USDC on HyperEVM](/stablecoins/quickstart-setup-transfer-usdc-hyperevm)

  ### Documentation updates

  Updated the following documentation to include USDC contract addresses for
  HyperEVM mainnet and testnet:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)

  Updated the following documentation to reflect support for HyperEVM mainnet and
  testnet:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.09.04">
  * Added support for USDC on the Plume blockchain.
  * Added support for CCTP V2 on the Plume testnet.

  ### Documentation updates

  Updated the following documentation to include USDC contract addresses for Plume
  mainnet and testnet:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)

  Updated the following documentation to reflect support for Plume testnet:

  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
</Update>

## August 2025

<Update label="2025.08.26">
  * Added support for USDC on the XDC blockchain.
  * Added support for CCTP V2 on the XDC Apothem testnet.

  ### Documentation updates

  Updated the following documentation to include USDC contract addresses for XDC
  mainnet and testnet:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)

  Updated the following documentation to reflect support for XDC Apothem testnet:

  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
</Update>

## July 2025

<Update label="2025.07.24">
  * Added support for CCTP V2 on the Sei mainnet.
  * Updated CCTP V2 Fast Transfer fee and standard message attestation time for
    Codex.

  ### Documentation additions

  Added the following Quickstart to showcase how to transfer USDC on the Sei
  testnet:

  * [Quickstart: Set up and transfer USDC on Sei](/stablecoins/quickstart-setup-transfer-usdc-sei)

  ### Documentation updates

  Updated the following documentation to reflect support for Sei:

  * [CCTP Overview](/cctp)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)

  Updated the following documentation to reflect updates to Codex:

  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.07.23">
  Added support on CCTP V2 for [USYC](/tokenized/usyc/overview) transfers between
  Ethereum and BNB Smart Chain.

  ### Documentation updates

  Updated documentation to reflect support for USYC transfers between Ethereum and
  BNB Smart Chain using CCTP V2:

  * [CCTP V2 Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP V2 Block Confirmations](/cctp/required-block-confirmations)
</Update>

<Update label="2025.07.10">
  * Added support for USDC on the Sei mainnet and testnet.
  * Added support for CCTP V2 on the Sei testnet.
  * Added support for CCTP V2 Standard Transfer fee switch.

  ### Documentation updates

  Updated the following documentation to reflect support for USDC on Sei and CCTP
  V2 on Sei testnet:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)

  Updated the following documentation to reflect support for the CCTP V2 Standard
  Transfer fee switch, including an explainer, a new `getMinFeeAmount` function,
  and a new security audit, respectively:

  * [CCTP Standard Transfer Fee Switch](/cctp/technical-guide#standard-transfer-fee-switch)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts#getminfeeamount)
  * [CCTP FAQ](/cctp/cctp-faq#have-the-cctp-smart-contracts-undergone-security-audits)
</Update>

## June 2025

<Update label="2025.06.27">
  Added support for CCTP V2 on the Polygon PoS mainnet.

  ### Documentation updates

  Updated the following documentation to reflect support for Polygon:

  * [CCTP Overview](/cctp)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.06.26">
  Added support for CCTP V2 on the Unichain mainnet.

  ### Documentation updates

  Updated the following documentation to reflect support for Unichain mainnet:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.06.24">
  Added support for CCTP V2 on the Codex mainnet.

  ### Documentation updates

  Updated the following documentation to reflect support for Codex mainnet:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.06.20">
  Added support for CCTP V2 on the Solana mainnet.

  ### Documentation updates

  Updated the following documentation to reflect support for Solana mainnet:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Solana Programs and Interfaces](/cctp/solana-programs)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
</Update>

<Update label="2025.06.13">
  Added support for CCTP V2 on the OP Mainnet.

  ### Documentation updates

  Updated the following documentation to reflect support for OP Mainnet:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
</Update>

<Update label="2025.06.12">
  * Added support for USDC on the Ripple Ledger (XRPL).
  * Added a Quickstart for USDC on XRPL, featuring a script that demonstrates how
    to set up a USDC trustline, and prepare the wallet to receive USDC.

  ### Documentation updates

  Updated the following documentation to reflect support for XRPL:

  * [USDC Contract Addresses - Mainnet](/stablecoins/usdc-contract-addresses#mainnet)
  * [USDC Contract Addresses - Testnet](/stablecoins/usdc-contract-addresses#testnet)

  ### Documentation additions

  Added the following documentation to reflect support for XRPL:

  * [Quickstart: Set up a USDC trustline on XRPL](/stablecoins/quickstart-setup-usdc-trustline-xrpl)
</Update>

<Update label="2025.06.10">
  * Added support for CCTP V2 on the following chains: Unichain Sepolia, Solana
    Devnet, Polygon PoS Amoy.
  * Added a new CCTP V2 endpoint that retrieves both Fast and Standard Transfer
    fees, and deprecated the endpoint that retrieves Fast Transfer fees only.

  ### Documentation updates

  Updated the following documentation to reflect support for Unichain Sepolia
  testnet:

  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)

  Updated the following documentation to reflect support for the Solana Devnet:

  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP Solana Programs and Interfaces](/cctp/solana-programs)

  Updated the following documentation to reflect support for the Polygon PoS Amoy
  testnet:

  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)

  ### API additions

  Added the following CCTP V2 API endpoint:

  * [`GET /v2/burn/USDC/fees/:sourceDomainId/:destDomainId`](/api-reference/cctp/all/get-burn-usdc-fees)

  ### API updates

  Deprecated the following CCTP V2 API endpoint:

  * `GET /v2/fastBurn/USDC/fees/:sourceDomainId/:destDomainId`
</Update>

<Update label="2025.06.09">
  * Added support for USDC and CCTP V2 on the Codex mainnet and testnet.
  * Added support for CCTP V2 on the OP Sepolia testnet.

  ### Documentation updates

  Updated the following documentation to reflect support for Codex chain and OP
  Sepolia testnet:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)
  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
</Update>

<Update label="2025.06.03">
  * Added support for USDC bridge-to-native upgrade on World Chain.
  * Added support for CCTP V2 on World Chain mainnet and Sepolia testnet.

  ### Documentation updates

  Updated the following documentation to reflect support for World Chain:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)
  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
</Update>

## May 2025

<Update label="2025.05.13">
  * Added support for USDC bridge-to-native upgrade on Sonic.
  * Added CCTP V2 support for Sonic.

  ### Documentation additions

  Added the following documentation on Sonic support:

  * [Quickstart: Set up and Transfer USDC on Sonic](/stablecoins/quickstart-setup-transfer-usdc-sonic)

  ### Documentation updates

  Updated the following documentation to reflect support for Sonic:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
</Update>

## March 2025

<Update label="2025.03.27">
  The following Circle Products have been renamed:

  | Previous Product name         | New Product name |
  | ----------------------------- | ---------------- |
  | Cross-Chain Transfer Protocol | CCTP             |

  This name change is part of a broader effort to simplify and align our product
  naming, creating a more unified developer experience across the Circle platform.
</Update>

<Update label="2025.03.26">
  Added support for CCTP V2 on the Linea mainnet.

  ### Documentation updates

  Updated the following documentation to reflect CCTP V2 support on the Linea
  mainnet:

  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
</Update>

<Update label="2025.03.21">
  Added support for CCTP V2 on the Linea Sepolia testnet.

  ### Documentation updates

  Updated the following documentation to reflect CCTP V2 support on the Linea
  Sepolia testnet:

  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
</Update>

<Update label="2025.03.17">
  Added support for USDC on the Linea blockchain.

  ### Documentation updates

  Updated the following documentation to include USDC contract addresses for
  Linea:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)
</Update>

<Update label="2025.03.11">
  Added CCTP V2 support, featuring Fast Transfer mode, to the following mainnets:

  * Avalanche
  * Base
  * Ethereum

  ### Documentation additions

  * Added the CCTP V2 white paper URL to the [CCTP Getting Started](/cctp) page.
  * Added CCTP V2 fast transfer support to the
    [CCTP Sample App](/sample-projects#cctp).

  ### Documentation updates

  Updated the following documentation to reflect CCTP V2 support on the newly
  added mainnets:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)
  * [CCTP FAQ](/cctp/cctp-faq)
</Update>

## February 2025

<Update label="2025.02.28">
  ### Documentation updates

  Removed the Ecosystem Catalog. For sample apps, visit the
  [Sample Projects](/sample-projects) page.
</Update>

<Update label="2025.02.21">
  ### Documentation updates

  Added CCTP V2 fast transfer support to the CCTP Quickstart:

  * [Quickstart: Transfer USDC on testnet from Ethereum to Avalanche](/cctp/transfer-usdc-on-testnet-from-ethereum-to-avalanche)
</Update>

<Update label="2025.02.11">
  Added support for CCTP V1 on the Unichain blockchain.

  ### Documentation updates

  Updated the following documentation to reflect CCTP V1 support on Unichain:

  * [CCTP Overview](/cctp)
  * [CCTP Supported Blockchains V1](/cctp/v1/cctp-supported-blockchains)
  * [CCTP Block Confirmations V1](/cctp/v1/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces V1](/cctp/v1/evm-smart-contracts)
  * [CCTP Chain Domains V1](/cctp/v1/supported-domains)
</Update>

<Update label="2025.02.04">
  Launched CCTP V2, featuring **Fast Transfer** mode, on the following testnets:

  * Avalanche Fuji
  * Base Sepolia
  * Ethereum Sepolia

  ### Documentation additions

  Added the following documentation to reflect support for CCTP V2:

  * [CCTP API Hosts and Endpoints](/cctp/technical-guide#cctp-api-hosts-and-endpoints)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Fees](/cctp/technical-guide#cctp-fees)

  ### Documentation updates

  Updated the following documentation to reflect CCTP V2 support:

  * [CCTP Overview](/cctp)
  * [CCTP Message Passing](/cctp/technical-guide#cctp-message-passing)
  * [CCTP Supported Chains and Domains](/cctp/cctp-supported-blockchains)
  * [CCTP Block Confirmations](/cctp/required-block-confirmations)
  * [CCTP EVM Contracts and Interfaces](/cctp/evm-smart-contracts)
  * [CCTP limits for burning and minting](/cctp/v1/limits)
  * [CCTP Message Format](/cctp/technical-guide#cctp-message-format)
  * [CCTP FAQ](/cctp/cctp-faq)

  ### API additions

  Added the following CCTP V2 API endpoints:

  * [`GET /v2/publicKeys`](/api-reference/cctp/all/get-public-keys-v2)
  * [`GET /v2/messages/:sourceDomainId`](/api-reference/cctp/all/get-messages-v2)
  * [`POST /v2/reattest/:nonce`](/api-reference/cctp/all/reattest-message)
  * [`GET /v2/fastBurn/USDC/allowance`](/api-reference/cctp/all/get-fast-burn-usdc-allowance)
  * `GET /v2/fastBurn/USDC/fees/:sourceDomainId/:destDomainId`
</Update>

## January 2025

<Update label="2025.01.30">
  Added a Quickstart for USDC on Aptos, featuring a web app that demonstrates how
  to transfer USDC.

  ### Documentation additions

  * [Quickstart: Set up and transfer USDC on Aptos](/stablecoins/quickstart-setup-transfer-usdc-aptos)
</Update>

<Update label="2025.01.23">
  Launched the Paymaster solution.

  ### Documentation additions

  Added the following documentation to support the Paymaster launch:

  * [Paymaster Overview](/paymaster)
  * [Quickstart: Circle Paymaster](/paymaster/pay-gas-fees-usdc)
  * [Paymaster Addresses and Events](/paymaster/addresses-and-events)
</Update>

<Update label="2025.01.09">
  Added support for CCTP V1 on the Aptos blockchain.

  ### Documentation additions

  Added the following documentation to reflect CCTP V1 support on Aptos:

  * [CCTP Aptos Packages and Interfaces](/cctp/v1/aptos-packages)
  * [Quickstart: Transfer USDC on testnet between Aptos and Base using CCTP V1](/cctp/v1/transfer-usdc-on-testnet-from-aptos-to-base)

  ### Documentation updates

  Updated the following documentation to reflect CCTP V1 support on Aptos:

  * [CCTP Overview](/cctp)
  * [CCTP Message Passing V1](/cctp/v1/generic-message-passing)
  * [CCTP Supported Blockchains V1](/cctp/v1/cctp-supported-blockchains)
  * [CCTP Block Confirmations V1](/cctp/v1/required-block-confirmations)
  * [CCTP Chain Domains V1](/cctp/v1/supported-domains)
</Update>

<Update label="2025.01.07">
  Added support for USDC on the Aptos mainnet.

  ### Documentation updates

  Updated the following documentation to include USDC contract addresses for
  Aptos:

  * [USDC Contract Addresses](/stablecoins/usdc-contract-addresses)
</Update>


# Release Notes - StableFX - 2025
Source: https://developers.circle.com/release-notes/stablefx-2025

2025 release notes for StableFX

## November 2025

<Update label="2025.11.13">
  Launched StableFX, an institutional-grade stablecoin FX engine built on Arc that
  combines Request-for-Quote (RFQ) execution with onchain settlement.

  ### Documentation additions

  Added the following documentation to support the StableFX launch:

  * [StableFX Overview](/stablefx)
  * [StableFX Technical Guide](/stablefx/concepts/technical-guide)
  * [Create an FX Trade as a Taker](/stablefx/quickstarts/fx-trade-taker)
  * [Fulfill an FX Trade as a Maker](/stablefx/quickstarts/fx-trade-maker)
  * [Grant USDC Allowance with Permit2](/stablefx/howtos/grant-usdc-allowance-permit2)
  * [Test StableFX Integration as a Taker](/stablefx/tutorials/test-stablefx-integration-taker)
  * [Test StableFX Integration as a Maker](/stablefx/tutorials/test-stablefx-integration-maker)
  * [StableFX Contract Interfaces](/stablefx/references/contract-interfaces)
  * [StableFX Supported Currencies](/stablefx/references/supported-currencies)

  ### API additions

  Added the following StableFX API endpoints:

  * [`POST /v1/stablefx/quotes`](/api-reference/stablefx/all/create-quote)
  * [`POST /v1/stablefx/trades`](/api-reference/stablefx/all/create-trade)
  * [`GET /v1/stablefx/trades`](/api-reference/stablefx/all/list-trades)
  * [`GET /v1/stablefx/trades/{tradeId}`](/api-reference/stablefx/all/get-trade-by-id)
  * [`POST /v1/stablefx/trades/{tradeId}/signature-data`](/api-reference/stablefx/all/generate-trade-signature-data)
  * [`POST /v1/stablefx/trades/{tradeId}/signatures`](/api-reference/stablefx/all/register-trade-signature)
  * [`POST /v1/stablefx/trades/{tradeId}/fund`](/api-reference/stablefx/all/fund-trade)
</Update>


# Release Notes - StableFX - 2026
Source: https://developers.circle.com/release-notes/stablefx-2026

2026 release notes for StableFX

## April 2026

<Update label="2026.04.14">
  ### Documentation additions

  Added the following new topic for StableFX API limits:

  * [StableFX API Rate Limits](/stablefx/references/api-rate-limits)
</Update>

## February 2026

<Update label="2026.02.06">
  ### Documentation additions

  Added the following new topic to document the StableFX trade lifecycle:

  * [StableFX Trade States](/stablefx/references/trade-states)
</Update>

<Update label="2026.02.04">
  Added StableFX webhook documentation and subscription management API references.

  ### Documentation additions

  The following documentation was created:

  * [Setup StableFX Webhook Notifications](/stablefx/howtos/setup-webhook-notifications)
  * [Verify Webhook Signatures for StableFX](/stablefx/howtos/verify-webhook-signatures)

  ### API additions

  Added the following endpoints to support StableFX webhook subscriptions:

  * [`POST /v1/stablefx/notifications/subscriptions`](/api-reference/stablefx/all/create-subscription)
  * [`GET /v1/stablefx/notifications/subscriptions`](/api-reference/stablefx/all/get-subscriptions)
  * [`GET /v1/stablefx/notifications/subscriptions/{id}`](/api-reference/stablefx/all/get-subscription)
  * [`PUT /v1/stablefx/notifications/subscriptions/{id}`](/api-reference/stablefx/all/update-subscription)
  * [`DELETE /v1/stablefx/notifications/subscriptions/{id}`](/api-reference/stablefx/all/delete-subscription)
  * [`GET /v1/stablefx/notifications/signatures/{notificationId}`](/api-reference/stablefx/all/get-notification-signature)
</Update>

## January 2026

<Update label="2026.01.22">
  Updated StableFX documentation to reflect the latest API environments.

  ### Documentation updates

  The following documentation was updated:

  * [StableFX Technical Guide](/stablefx/concepts/technical-guide)
  * [Fulfill an FX Trade as a Maker](/stablefx/quickstarts/fx-trade-maker)
  * [Create an FX Trade as a Taker](/stablefx/quickstarts/fx-trade-taker)
  * [Test StableFX Integration as a Maker](/stablefx/tutorials/test-stablefx-integration-maker)
  * [Test StableFX Integration as a Taker](/stablefx/tutorials/test-stablefx-integration-taker)
</Update>


# Release Notes - Tokenized Funds - 2025
Source: https://developers.circle.com/release-notes/tokenized-funds-2025

2025 release notes for Tokenized Funds

## June 2025

<Update label="2025.06.11">
  ### Documentation additions

  Added USYC [Smart Contract Addresses](/tokenized/usyc/smart-contracts).
</Update>

## May 2025

<Update label="2025.05.28">
  ### Documentation additions

  Added the following documentation for USYC:

  * [USYC Overview](/tokenized/usyc/overview)
  * [Quickstart: Subscribe and Redeem USYC Using the Teller Smart Contract](/tokenized/usyc/subscribe-and-redeem)
  * [Web2 API Endpoints](/tokenized/usyc/web2-apis)
</Update>


# Release Notes - USDC - 2026
Source: https://developers.circle.com/release-notes/usdc-2026

2026 release notes for USDC

## April 2026

<Update label="2026.04.15">
  Added support for USDC on Pharos mainnet.

  ### Documentation updates

  Added the USDC contract address for Pharos mainnet:

  * [USDC Contract Addresses: Mainnet](/stablecoins/usdc-contract-addresses#mainnet)
</Update>

## May 2026

<Update label="2026.05.05">
  Added support for USDC on Injective mainnet.

  ### Documentation updates

  Added the USDC contract address for Injective mainnet:

  * [USDC Contract Addresses: Mainnet](/stablecoins/usdc-contract-addresses#mainnet)
</Update>

## March 2026

<Update label="2026.03.17">
  Added support for USDC on Injective Testnet.

  ### Documentation updates

  Added the USDC contract address for Injective Testnet:

  * [USDC Contract Addresses: Testnet](/stablecoins/usdc-contract-addresses#testnet)
</Update>

<Update label="2026.03.10">
  Added EDGE testnet support in Transfer USDC on EVM chains Quickstart.

  ### Documentation updates

  * [Quickstart: Transfer USDC on EVM chains](/stablecoins/quickstarts/transfer-usdc-evm)
</Update>

<Update label="2026.03.09">
  Added support for USDC on EDGE mainnet.

  ### Documentation updates

  * [USDC Contract Addresses: Mainnet](/stablecoins/usdc-contract-addresses#mainnet)
  * [Quickstart: Transfer USDC on EVM chains](/stablecoins/quickstarts/transfer-usdc-evm)
</Update>

<Update label="2026.03.04">
  Added support for USDC on Morph mainnet.

  ### Documentation updates

  Added the USDC contract address for Morph mainnet:

  * [USDC Contract Addresses: Mainnet](/stablecoins/usdc-contract-addresses#mainnet)
</Update>

## February 2026

<Update label="2026.02.26">
  Added support for USDC on Morph Hoodi testnet.

  ### Documentation updates

  Added the USDC contract address for Morph Hoodi testnet:

  * [USDC Contract Addresses: Testnet](/stablecoins/usdc-contract-addresses#testnet)
</Update>

<Update label="2026.02.09">
  Added support for USDC on EDGE testnet.

  ### Documentation updates

  Added the USDC contract address for EDGE testnet:

  * [USDC Contract Addresses: Testnet](/stablecoins/usdc-contract-addresses#testnet)
</Update>

## January 2026

<Update label="2026.01.23">
  ### Documentation updates

  Consolidated transfer quickstarts for EVM chains into a single quickstart
  (previous quickstarts now redirect to this quickstart):

  * [Transfer USDC on EVM chains](/stablecoins/quickstarts/transfer-usdc-evm)
</Update>


# Release Notes - Developer Services - 2024
Source: https://developers.circle.com/release-notes/w3s-2024

2024 release notes for Circle's Developer Services platform

## December 2024

<Update label="2024.12.18">
  API documentation update.

  ### API updates

  * Updated various Travel Rule API request bodies to include descriptions and
    examples for all fields.
</Update>

<Update label="2024.12.10">
  Travel Rule (Beta), part of Circle's Compliant Engine solution, has been
  released.

  ### Documentation updates

  The following docs have been updated to support Travel Rule (Beta):

  * [Compliance Engine Overview](/wallets/compliance-engine)
  * [Travel Rule Overview](/release-notes/w3s-2025#20250613)
  * [Travel Rule Quickstart](/release-notes/w3s-2025#20250613)
</Update>

<Update label="2024.12.09">
  API documentation update.

  ### API additions

  * Fix response schema for following APIs:
    * `GET /user`
    * `POST /users/`
    * `GET /users/{id}`

  ### API updates

  * Update request bodies for following APIs:
    * `POST /compliance/travelRule/validityCheck`
    * `POST /compliance/travelRule/receivePii`
</Update>

## November 2024

<Update label="2024.11.12">
  Updated description for USDC Access API endpoints, and added Unichain Sepolia
  enum values for several endpoints.

  ### API additions

  * Added enum values `UNI-SEPOLIA` to the `blockchain` request field for the
    following APIs:
    * `POST /developer/wallets`
    * `POST /user/wallets`
    * `GET /wallets`
    * `GET /transactions`
    * `POST /transactions/validateAddress`
    * `POST /user/initialize`
    * `GET /config/entity/monitoredTokens`
    * `GET /contracts`
    * `POST /contracts/deploy`
    * `POST /contracts/deploy/estimateFee`
    * `POST /templates/{id}/deploy`
    * `POST /templates/{id}/deploy/estimateFee`

  * Added `401 Unauthorized` response to all endpoints that require `API_KEY`

  * Added `404 Not Found` response to all endpoints that interact with a resource:
    wallet, walletSet, token, transaction or challenge.

  ### API updates

  * Updated API description for USDC Access endpoints.
  * Fix response schema for the following APIs:
    * `GET /user`
    * `POST /users/`
    * `GET /users/{id}`
</Update>

<Update label="2024.11.06">
  USDC Access and API documentation updates.

  ### Documentation additions

  Added the following docs to support USDC Access:

  * About USDC Access Integration Flows
  * About USDC Access Sessions

  ### Documentation updates

  The USDC Access content has been moved to its own dedicated section in the Web3
  Services section of the site.

  ### API updates

  * Updated descriptions of query parameters, request body fields and response
    body fields.
    * `walletIds` query parameter
    * `address` request field
    * `tokenAddress`, `walletAddress`, `destinationAddress` response fields
      updated and consolidated
    * `tokenId`, `walletId` response fields updated and consolidated
    * `name` response field
  * Renamed `ContractExecutionTxnPinCodeRequest` schema to
    `CreateContractExecutionTransactionForEndUserRequest`
</Update>

## October 2024

<Update label="2024.10.31">
  * Added support to the new Travel Rule (early access) feature of the Compliance
    Engine product.
  * The Smart Contract Platform now supports Event Monitoring via Webhooks and new
    API endpoints.
  * The sign transaction API endpoints now support EVM wallets.

  ### Documentation updates

  Added a new section Event Monitoring to the Smart Contract Platform page from
  the Getting Started category:

  * [Event Monitoring](/contracts#event-monitoring)

  Added a new quickstart to the Smart Contract Platform category:

  * [Event Monitoring for Smart Contracts](/contracts/scp-event-monitoring)

  ### Documentation additions

  The following docs have been added to support the new Travel Rule (early access)
  feature:

  * [Travel Rule](/release-notes/w3s-2025#20250613)
    * [Quickstart](/release-notes/w3s-2025#20250613)
    * [Testing Guide](/release-notes/w3s-2025#20250613)

  Added new how-to guide:

  * [Sign Transactions on EVM chains](/wallets/sign-tx-evm)

  Added new reference guide:

  * [Chain IDs for Signing Transactions](/wallets/sign-tx-chain-id)

  ### API additions

  Added new Travel Rule API endpoints for Compliance Engine:

  * `POST` `/compliance/travelRule/eligibilityCheck`
  * `POST` `/compliance/travelRule/messages`
  * `POST` `/compliance/travelRule/receivePii`
  * `POST` `/compliance/travelRule/sendPii`
  * `POST` `/compliance/travelRule/uploadOwnershipProof`
  * `POST` `/compliance/travelRule/validityCheck`
  * `PUT` `/compliance/travelRule/{travelRuleId}`

  Added new API endpoints for Event Monitoring:

  * `GET` `/contracts/monitors`
  * `POST` `/contracts/monitors`
  * `DELETE` `/contracts/monitors/{id}`
  * `PUT` `/contracts/monitors/{id}`
  * `GET` `/contracts/events`

  Added new error codes for Event Monitoring:

  * Added predefined error `EXT_EVENT_SUBSCRIPTION_NOT_FOUND` (code: `175301`)
  * Added predefined error `EXT_EVENT_SUBSCRIPTION_ALREADY_EXISTS` (code:
    `175302`)
  * Added predefined error `EXT_EVENT_SIGNATURE_DOES_NOT_EXIST` (code: `175303`)

  Added enum values `EVM` and `EVM-TESTNET` to the `blockchain` request and
  response fields for the following API endpoint:

  * `POST` `/developer/wallets`

  Added sign transaction support for `EVM` and `EVM-TESTNET` wallets for the
  following API endpoint:

  * `POST` `/developer/sign/transaction`
  * `POST` `/developer/sign/typedData`
  * `POST` `/developer/sign/message`

  Added new [errors](/wallets/error-codes) related to signing APIs using `EVM` and
  `EVM-TESTNET` blockchain:

  * 155807: The typed data or transaction chainID is not supported for EVM signing
  * 155808: The chainID is missing from typed data or transaction for EVM signing

  Added optional `initialPublicKey` field in the wallet response for NEAR chains
  in the following API endpoints:

  * `POST` `/developer/wallets`
  * `GET` `/developer/wallets`
  * `GET` `/developer/wallets/{id}`

  Added optional `txHash` field in sign transaction response for `NEAR`,
  `NEAR-TESTNET`, `EVM`, and `EVM-TESTNET` chains in the following API endpoint:

  * `POST` `/developer/sign/transaction`
</Update>

<Update label="2024.10.24">
  * The quickstarts now have a simpler way to encrypt/register the Entity Secret
    using SDK methods.
  * The sign transaction API endpoints now support both `SOL` and `SOL-DEVNET`
    wallets.

  ### Documentation updates

  The Entity Secret registration step was refactored from:

  * [Create Your First Developer-Controlled Wallet](/wallets/dev-controlled/create-your-first-wallet)

  and moved into its own quickstart (see below), thereby simplifying the developer
  journey.

  ### Documentation additions

  Added a new quickstart about developer-controlled wallets:

  * [Register Your Entity Secret](/wallets/dev-controlled/register-entity-secret)

  featuring various ways to register the Entity Secret, including via SDK methods.

  Added new how-to guide:

  * [Sign Transactions on Solana](/wallets/sign-tx-solana)

  ### API updates

  Added sign transaction support for the Solana (`SOL`) blockchain for the
  following API endpoints:

  * `/developer/sign/transaction`
  * `/user/sign/transaction`
</Update>

<Update label="2024.10.21">
  USDC Access is now available to integrate into your application. Use the hosted,
  end-to-end USDC Access widget to enable your users to buy or sell USDC.

  ### Documentation additions

  * About USDC Access - A comprehensive, conceptual guide that describes the
    on-ramp and off-ramp integration flow and user flow, widget features, the
    concept of sessions, and the webhook notifications sent for session events.
  * Integrate with USDC Access - A step-by-step tutorial that walks you through
    how to integrate USDC Access into your application. Includes code examples.

  ### API additions

  Added the following API endpoints:

  * `POST` `/ramp/sessions`
  * `GET` `/ramp/tradeConfigurations`
  * `GET` `/ramp/sessions`
  * `POST` `/ramp/quotes`
  * `GET` `/ramp/sessions`
</Update>

<Update label="2024.10.14">
  ### API updates

  New functionality was added that now allows you to override your gas limit for
  EOA wallets.

  Note that this changed functionality applies to EOA wallets only.

  You can now use `gasLimit` together with `feeLevel` to customize and override
  your `gasLimit` for the following API endpoints:

  * `POST` `/developer/transactions/contractExecution`
  * `POST` `/developer/transactions/transfer`
  * `POST` `/user/transactions/contractExecution`
  * `POST` `/user/transactions/transfer`
</Update>

<Update label="2024.10.02">
  We have heard your feedback and have launched a new and improved developer
  documentation platform. It brings the following features:

  * **New revamped home page**: to find all of our developer-centric resources in
    one place
  * **Interactive API Playground**: to quickly test API endpoints
  * **Unified developer portal**: combining docs and APIs - learn.circle.com is
    now available under developers.circle.com
  * **Improved User Experience (UX)**: for easier and faster navigation

  And many more features all designed to dramatically improve your experience.
</Update>

## September 2024

<Update label="2024.09.24">
  Adds support to the new Compliance Engine product, including the new Transaction
  Screening feature and some necessary API additions and updates.

  ### Documentation additions

  The following docs have been added to support the new Compliance Engine release
  with the new Transaction Screening feature:

  * [Compliance Engine](/wallets/compliance-engine)
    * [Transaction Screening](/wallets/compliance-engine/tx-screening)
      * [Quickstart](/wallets/compliance-engine/tx-screening-quickstart)
      * [Testing Guide](/wallets/compliance-engine/tx-screening-testing)
      * [Rule Management](/wallets/compliance-engine/tx-screening-rule-management)
      * [Alert Management](/wallets/compliance-engine/tx-screening-alert-management)

  ### API additions

  Added new Compliance Engine APIs:

  * `POST` `/compliance/screening/addresses`

  Added new optional `transactionScreeningEvaluation` field to `Transaction`
  schema. The new field contains transaction screening results from the new
  Compliance Engine. It is available for the following API endpoints:

  * `GET` `/transactions`
  * `GET` `/transactions/{id}`
</Update>

<Update label="2024.09.11">
  Made some API additions to support the Arbitrum blockchain.

  ### API additions

  Added enum values `ARB` and `ARB-SEPOLIA` to the `blockchain` request field for
  the following APIs:

  * `POST` `/developer/wallets`
  * `POST` `/user/wallets`
  * `GET` `/wallets`
  * `GET` `/transactions`
  * `POST` `/transactions/validateAddress`
  * `POST` `/user/initialize`
  * `GET` `/config/entity/monitoredTokens`
  * `GET` `/contracts`
  * `POST` `/contracts/deploy`
  * `POST` `/contracts/deploy/estimateFee`
  * `POST` `/templates/{id}/deploy`
  * `POST` `/templates/{id}/deploy/estimateFee`

  Added new `networkFee` field to the `TransactionFee` schema, representing the
  maximum value of native token needed for a transaction. The new field is
  available for the `transaction.estimatedFee` field and all `estimateFee`
  endpoints:

  * `POST` `/transactions/transfer/estimateFee`
  * `POST` `/transactions/contractExecution/estimateFee`
  * `POST` `/transactions/contractDeployment/estimateFee`
  * `POST` `/contracts/deploy/estimateFee`
  * `POST` `/templates/{id}/deploy/estimateFee`
</Update>

<Update label="2024.09.09">
  Made some API additions and updates for improved parameter preconditions and
  better error handling.

  ### API additions

  Added new sign transaction error `SignTransactionRawTransactionTooLarge` for
  Programmable wallet sign transaction APIs when the `rawTransaction` size exceeds
  blockchain limit.

  * `POST` `/user/sign/transaction`
  * `POST` `/developer/sign/transaction`

  ### API updates

  Fixed a typo in the description of `monitoredTokens` API endpoint.

  * `GET` `/config/entity/monitoredTokens`

  Updated description for contract name field to clarify it only accepts
  alphanumeric characters.

  * `POST` `/contracts/import`
  * `POST` `/contracts/deploy`
  * `PATCH` `/contracts/{id}`
</Update>

<Update label="2024.09.05">
  Circle's API platform now supports Arbitrum.

  ### Documentation additions

  For a list of APIs that support Arbitrum, see
  [Blockchain Compatibility for Developer Services APIs](/wallets/supported-blockchains).
</Update>

## August 2024

<Update label="2024.08.22">
  Made some restructuring of the documentation navigation for improved browsing.

  ### Documentation updates

  A new category section was added to our documentation navigation:

  * [SDKs and Sample Apps](/sdks)

  All existing documentation for our SDKs and sample apps was moved to this new
  section.
</Update>

<Update label="2024.08.14">
  Made some necessary API additions and updates to support Solana NFTs and Zero
  balance tokens.

  ### Documentation additions

  The following docs have been updated to reflect the supported changes on the
  Solana network:

  * [API Compatibility](/wallets/supported-blockchains) for supported blockchains

  ### API additions

  The following new enum values for the `standard` query parameters and response
  fields were added:

  * `FungibleAsset`
  * `NonFungible`
  * `NonFungibleEdition`
  * `ProgrammableNonFungible`
  * `ProgrammableNonFungibleEdition`

  for the following API endpoints:

  * `GET` `/wallets/{id}/nfts`
  * `GET` `/tokens/{id}`
  * `POST` `/user/transactions/transfer`
  * `POST` `/developer/transactions/transfer`
  * `GET` `/transactions`
  * `GET` `/transactions/{id}`
  * `GET` `/config/entity/monitoredTokens`
  * `POST` `/config/entity/monitoredTokens`
  * `PUT` `/config/entity/monitoredTokens`

  ### API updates

  Made `nftTokenId` an optional field in the response of the following API
  endpoints, since Solana doesn't have `nftTokenId`:

  * `GET` `/wallets/{id}/nfts`

  Modified the behavior of several API endpoints related to token balances in a
  wallet. In particular, tokens with a balance of zero will no longer be included
  in the API responses for the following endpoints:

  * `GET` `/wallets/{id}/balances`
  * `GET` `/wallets/{id}/nfts`

  **Note**: If you have enabled the [monitored token](/wallets/monitored-tokens)
  feature, tokens that have a zero balance will still be included in the response.
</Update>

## July 2024

<Update label="2024.07.25">
  Added two new sign transaction API endpoints for SOL-DEVNET wallets.

  ### API additions

  The following endpoints have been added:

  * `POST` `/user/sign/transaction`
  * `POST` `/developer/sign/transaction`
</Update>

<Update label="2024.07.23">
  User-controlled wallets now offer two new authentication methods: social login
  and email authentication.

  ### Documentation additions

  See the following new docs:

  * [Authentication Types](/wallets/user-controlled/authentication-methods)
  * [Confirmation UIs](/wallets/user-controlled/confirmation-uis)
  * [Quickstarts for Social Logins or Email Authentication](/wallets/user-controlled/create-your-first-wallet-with-social-logins)

  ### API additions

  The following new API endpoints have been added:

  * `POST` `/users/social/token`
  * `POST` `/users/email/token`
  * `POST` `/users/resendOTP`
  * `POST` `/user/token/refresh`

  ### API updates

  The following API endpoints have been updated for social logins and email
  authentication:

  * `POST` `/users/social/token`
  * `POST` `/users/email/token`
  * `POST` `/user/initialize`
  * `POST` `/user/token/refresh`
  * `POST` `/users/resendOTP`

  The following API endpoints have been updated for PIN authentication:

  * `POST` `/users`
  * `POST` `/users/token`
  * `POST` `/user/initialize`
  * `GET` `/user`
  * `POST` `/user/pin`
  * `PUT` `/user/pin`
  * `POST` `/user/pin/restore`

  The following API endpoints have been updated for users:

  * `GET` `/users`
  * `GET` `/users/{id}`
  * `GET` `/user/challenges`
  * `GET` `/user/challenges/{id}`
</Update>

<Update label="2024.07.19">
  Renamed the `FT` enum to `Fungible` in the standard query parameters and
  response fields across multiple API endpoints.

  ### API updates

  The `FT` enum is now the `Fungible` enum in the standard query parameters and
  response fields for the following endpoints:

  * `GET` `wallets/{id}/balances`
  * `GET` `tokens/{id}`
  * `GET`, `POST`, `PUT` `config/entity/monitoredTokens`
</Update>

## June 2024

<Update label="2024.06.26">
  Included the `FT` enum in the `standard` query parameters and response fields in
  multiple API endpoints.

  ### API additions

  Added the `FT` enum to the `standard` query parameters and response fields in
  the following endpoints:

  * `GET` `wallets/{id}/balances`
  * `GET` `wallets/{id}/nfts`
  * `GET` `tokens/{id}`
  * `GET` `config/entity/monitoredTokens`
  * `POST` `config/entity/monitoredTokens`
  * `PUT` `config/entity/monitoredTokens`
</Update>

<Update label="2024.06.20">
  Added a new field to the `/contracts/deploy/estimateFee` endpoint.

  ### API additions

  Added new `AbiJson` field in the following API endpoint:

  * `POST` `/contracts/deploy/estimatefee`
</Update>

<Update label="2024.06.18">
  A new Smart Contract template is available for Airdrop.

  ### Documentation additions

  To learn more about the new Airdrop template, see [Airdrop](/contracts/airdrop).
</Update>

<Update label="2024.06.13">
  This fix updates the signTypedData API response for both user-controlled wallets
  and developer-controlled wallets.

  ### Documentation updates

  The `v` value in the signature response has changed from `0/1` to `27/28` to
  ensure compatibility with most verification methods in the following API calls:

  * `POST` `/user/sign/typedData`
  * `POST` `/developer/sign/typedData`
</Update>

<Update label="2024.06.12">
  New server-side SDKs are available for Node.js and Python.

  ### Documentation updates

  A new version of the Node.js SDK is available. To set up the server-side Node.js
  SDK in your application. See the [Node.js SDK](/sdks).

  A new server-side Python SDK is available. To set up the Python SDK in your
  application. See the [Python SDK](/sdks).
</Update>

<Update label="2024.06.11">
  Programmable Wallets is now available on Solana.

  ### Documentation additions

  To see what's available, see the
  [Programmable Wallets on Solana](/wallets/wallets-on-solana) guide.

  ### API additions

  Added enum values `SOL` and `SOL-DEVNET` to the `blockchain` request and
  response fields for the following APIs:

  * `POST` `/faucet/drips`
  * `POST` `/developer/wallets`
  * `POST` `/user/wallets`
  * `GET` `/wallets`
  * `GET` `/transactions`
  * `POST` `/transactions/validateAddress`
  * `POST` `/user/initialize`
  * `GET` `/config/entity/monitoredTokens`

  ### API updates

  Updated description of `fee` parameters for Solana use case.

  Updated description of `AccountType` for Solana use case.

  Fixed `blockchain` request field to be string enum for the following APIs:

  * `POST` `/user/transactions/transfer`
  * `POST` `/developer/transactions/transfer`
  * `POST` `/transactions/transfer/estimateFee`
</Update>


# Release Notes - Developer Services - 2025
Source: https://developers.circle.com/release-notes/w3s-2025

2025 release notes for Circle's Developer Services platform

## December 2025

<Update label="2025.12.19">
  Deprecated the Bridge Kit `calculateFee` function and replaced it with a new
  `computeFee` function. When using `computeFee`, update your fee policy to expect
  the `amount` parameter in human units (e.g., `"10.50"`) instead of base units
  (e.g., `"10500000"`). `calculateFee` will continue to work until it's removed in
  a future release.

  ### Documentation updates

  Updated the following documentation to reflect the deprecation of the
  `calculateFee` function in favor of `computeFee`:

  * [Collect a Transfer Fee](https://docs.arc.io/app-kit/tutorials/bridge/collect-bridge-fee)
  * [Bridge Kit SDK Reference](https://docs.arc.io/app-kit/references/sdk-reference)
</Update>

<Update label="2025.12.08">
  Added support for HyperCore to CCTP.

  ### Documentation additions

  Created the following new topics to support HyperCore CCTP transfers:

  * [CCTP-Enabled HyperCore Transfers](/cctp/concepts/cctp-on-hypercore)
  * [HyperCore CCTP-Enablement Contract Addresses](/cctp/references/hypercore-contract-addresses)
  * [Core Deposit Wallet Contract Interface](/cctp/references/coredepositwallet-contract-interface)
  * [Transfer USDC from Arbitrum to HyperCore](/cctp/howtos/transfer-usdc-from-arbitrum-to-hypercore)
  * [Transfer USDC from Ethereum to HyperCore](/cctp/howtos/transfer-usdc-from-ethereum-to-hypercore)
  * [Transfer USDC from Solana to HyperCore](/cctp/howtos/transfer-usdc-from-solana-to-hypercore)
  * [Transfer USDC from HyperEVM to HyperCore](/cctp/howtos/transfer-usdc-from-hyperevm-to-hypercore)
  * [Withdraw USDC from HyperCore to EVM chains](/cctp/howtos/withdraw-usdc-from-hypercore-to-evm)
  * [Withdraw USDC from HyperCore to HyperEVM](/cctp/howtos/withdraw-usdc-from-hypercore-to-hyperevm)
</Update>

## November 2025

<Update label="2025.11.25">
  Expanded Contracts support to include the Arc testnet.

  ### Documentation updates

  Updated the following documentation for Contracts to reflect Arc testnet
  support:

  * [Circle Contracts Supported Blockchains](/contracts/supported-blockchains)
</Update>

<Update label="2025.11.24">
  Expanded Wallets support to include the Monad blockchain.

  ### Documentation updates

  Updated the following documentation for Wallets to reflect Monad support:

  * [Account Types](/wallets/account-types)
  * [Blockchain Compatibility for Developer Services APIs](/wallets/supported-blockchains)
  * [Blockchain Confirmations](/wallets/blockchain-confirmations)
  * [Blockchain Infrastructure](/wallets/blockchain-infrastructure)
  * [Gas Fees](/wallets/gas-fees)
  * [Gas Station](/wallets/gas-station)
  * [Gas Station Contract Addresses](/wallets/gas-station/contract-addresses)
  * [Gas Station Policy Management](/wallets/gas-station/policy-management)
  * [Modular Wallets Quickstart](/wallets/modular/create-a-wallet-and-send-gasless-txn)
  * [Modular Wallets Web SDK](/wallets/modular/web-sdk)
  * [Modular Wallets iOS SDK](/wallets/modular/ios-sdk)
  * [Modular Wallets Android SDK](/wallets/modular/android-sdk)
  * [Receive an Inbound Transfer: Dev-controlled](/wallets/dev-controlled/receive-an-inbound-transfer)
  * [Receive an Inbound Transfer: User-controlled](/wallets/user-controlled/receive-inbound-transfer)
  * [Send a Gasless Transaction](/wallets/gas-station/send-a-gasless-transaction)
  * [Supported Blockchains](/wallets/supported-blockchains)

  ### API updates

  Added enum values `MONAD` and `MONAD-TESTNET` to the `blockchain` request field
  for the following APIs:

  * `POST /developer/wallets`
  * `POST /user/wallets`
  * `GET /wallets`
  * `GET /transactions`
  * `POST /transactions/contractExecution`
  * `POST /transactions/contractExecution/estimateFee`
  * `POST /transactions/transfer`
  * `POST /transactions/transfer/estimateFee`
  * `POST /transactions/validateAddress`
  * `GET /config/entity/monitoredTokens`
  * `POST /developer/sign/message`
  * `POST /user/sign/message`
  * `POST /developer/sign/typedData`
  * `POST /user/sign/typedData`
  * `GET /v1/w3s/developer/wallets/balances`
</Update>

<Update label="2025.11.17">
  Added Circle Wallets adapter to Bridge Kit.

  ### Documentation additions

  Created the following new topics to support the Circle Wallets adapter on Bridge
  Kit:

  * [Quickstart: Bridge USDC between Solana and EVM](https://docs.arc.io/app-kit/quickstarts/bridge-between-solana-and-evm)
  * [Supported Blockchains](https://docs.arc.io/app-kit/references/supported-blockchains)

  ### Documentation updates

  Updated the following documentation to reflect support for the Circle Wallets
  adapter on Bridge Kit:

  * [Bridge Kit Installation](https://docs.arc.io/app-kit/tutorials/installation)
  * [Adapter Setups](https://docs.arc.io/app-kit/tutorials/adapter-setups)
</Update>

## October 2025

<Update label="2025.10.27">
  * Expanded Gateway support to include Arc testnet.
  * Expanded Paymaster support to include Arc testnet.
  * Expanded Wallets support to include Arc testnet.

  ### Documentation updates

  Updated the following documentation to reflect Gateway support for Arc testnet:

  * [Gateway Smart Contract Addresses](/gateway/references/contract-addresses)
  * [Gateway Supported Blockchains](/gateway/references/supported-blockchains)

  Updated the following documentation to reflect Paymaster support for Arc
  testnet:

  * [Addresses and Events](/paymaster/addresses-and-events)

  Updated the following documentation for Wallets to reflect Arc testnet support:

  * [Account Types](/wallets/account-types)
  * [Blockchain Compatibility for Developer Services APIs](/wallets/supported-blockchains)
  * [Blockchain Confirmations](/wallets/blockchain-confirmations)
  * [Blockchain Infrastructure](/wallets/blockchain-infrastructure)
  * [Gas Fees](/wallets/gas-fees)
  * [Gas Station](/wallets/gas-station)
  * [Gas Station Contract Addresses](/wallets/gas-station/contract-addresses)
  * [Gas Station Policy Management](/wallets/gas-station/policy-management)
  * [Modular Wallets Quickstart](/wallets/modular/create-a-wallet-and-send-gasless-txn)
  * [Modular Wallets Web SDK](/wallets/modular/web-sdk)
  * [Modular Wallets iOS SDK](/wallets/modular/ios-sdk)
  * [Modular Wallets Android SDK](/wallets/modular/android-sdk)
  * [Receive an Inbound Transfer: Dev-controlled](/wallets/dev-controlled/receive-an-inbound-transfer)
  * [Receive an Inbound Transfer: User-controlled](/wallets/user-controlled/receive-inbound-transfer)
  * [Send a Gasless Transaction](/wallets/gas-station/send-a-gasless-transaction)
  * [Supported Blockchains](/wallets/supported-blockchains)

  ### API updates

  Added enum values `ARC-TESTNET` to the `blockchain` request field for the
  following APIs:

  * `POST /developer/wallets`
  * `POST /user/wallets`
  * `GET /wallets`
  * `GET /transactions`
  * `POST /transactions/contractExecution`
  * `POST /transactions/contractExecution/estimateFee`
  * `POST /transactions/transfer`
  * `POST /transactions/transfer/estimateFee`
  * `POST /transactions/validateAddress`
  * `GET /config/entity/monitoredTokens`
  * `POST /developer/sign/message`
  * `POST /user/sign/message`
  * `POST /developer/sign/typedData`
  * `POST /user/sign/typedData`
</Update>

<Update label="2025.10.14">
  Launched the Bridge Kit SDK.

  ### Documentation additions

  Created the following new topics to support Bridge Kit:

  * [Bridge Kit Overview](https://docs.arc.io/app-kit/bridge)
  * [Adapter Setups](https://docs.arc.io/app-kit/tutorials/adapter-setups)
  * [Quickstart: Bridge USDC Between EVM Chains](https://docs.arc.io/app-kit/quickstarts/bridge-between-evm-chains)
  * [Quickstart: Bridge USDC between Solana and EVM](https://docs.arc.io/app-kit/quickstarts/bridge-between-solana-and-evm)
  * [Bridge Kit Installation](https://docs.arc.io/app-kit/tutorials/installation)
  * [Collect a Transfer Fee](https://docs.arc.io/app-kit/tutorials/bridge/collect-bridge-fee)
  * [Configure Transfer Speed and Maximum Cost](https://docs.arc.io/app-kit/tutorials/bridge/configure-transfer-speed)
  * [Estimate Costs Before Transferring](https://docs.arc.io/app-kit/tutorials/bridge/estimate-costs)
  * [Specify Recipient Address](https://docs.arc.io/app-kit/tutorials/bridge/specify-recipient-address)
  * [Bridge Kit SDK Reference](https://docs.arc.io/app-kit/references/sdk-reference)
  * [Event Handling](https://docs.arc.io/app-kit/references/sdk-reference)
  * [Error Recovery and Troubleshooting](https://docs.arc.io/app-kit/references/bridge-error-recovery)
</Update>

<Update label="2025.10.08">
  Expanded Gateway support to include HyperEVM, Sei, Sonic, and World Chain.

  ### Documentation updates

  Updated the following documentation to reflect Gateway support for HyperEVM,
  Sei, Sonic, and World Chain:

  * [Gateway Fees](/gateway/references/fees)
  * [Gateway Smart Contract Addresses](/gateway/references/contract-addresses)
  * [Gateway Supported Blockchains](/gateway/references/supported-blockchains)
</Update>

## August 2025

<Update label="2025.08.26">
  ### API updates

  Updated the following Gateway endpoints:

  * Added `expirationBlock` to the
    [`POST /v1/transfer`](/api-reference/gateway/all/create-transfer-attestation)
    response
  * Added `processedHeight` and `burnIntentExpirationHeight` to the
    [`GET /v1/info`](/api-reference/gateway/all/get-gateway-info) response
</Update>

<Update label="2025.08.07">
  ### API updates

  Replaced the transaction state `PENDING_RISK_SCREENING` with `CLEARED`
</Update>

<Update label="2025.08.04">
  ### API additions

  Added `networkFeeRaw` to the response of the following endpoints:

  * [`POST /transactions/contractExecution/estimateFee`](/api-reference/wallets/developer-controlled-wallets/create-transaction-estimate-fee)
  * [`POST /transactions/transfer/estimateFee`](/api-reference/wallets/developer-controlled-wallets/create-transfer-estimate-fee)
  * [`POST /contracts/deploy/estimateFee`](/api-reference/contracts/smart-contract-platform/estimate-contract-deploy)
</Update>

## July 2025

<Update label="2025.07.23">
  Expanded Developer Services support for Avalanche Mainnet and Avalanche Fuji
  Testnet to include smart contract accounts (SCAs), modular wallets, and Gas
  Station sponsorship.

  ### Documentation updates

  Updated the following documentation for Wallets to reflect Avalanche support:

  * [Account Types](/wallets/account-types)
  * [Blockchain Compatibility for Developer Services APIs](/wallets/supported-blockchains)
  * [Blockchain Confirmations](/wallets/blockchain-confirmations)
  * [Blockchain Infrastructure](/wallets/blockchain-infrastructure)
  * [Gas Fees](/wallets/gas-fees)
  * [Gas Station](/wallets/gas-station)
  * [Gas Station Contract Addresses](/wallets/gas-station/contract-addresses)
  * [Gas Station Policy Management](/wallets/gas-station/policy-management)
  * [Modular Wallets Quickstart](/wallets/modular/create-a-wallet-and-send-gasless-txn)
  * [Modular Wallets Web SDK](/wallets/modular/web-sdk)
  * [Modular Wallets iOS SDK](/wallets/modular/ios-sdk)
  * [Modular Wallets Android SDK](/wallets/modular/android-sdk)
  * [Send a Gasless Transaction](/wallets/gas-station/send-a-gasless-transaction)
  * [Supported Blockchains](/wallets/supported-blockchains)

  ### API updates

  Added enum values `AVAX`, `AVAX-FUJI` to the `blockchain` request field for the
  following Circle Contracts APIs:

  * `POST /contracts/deploy`
  * `POST /contracts/deploy/estimateFee`
  * `POST /contracts/import`
  * `POST /contracts/query`
  * `POST /templates/{id}/deploy`
  * `POST /templates/{id}/deploy/estimateFee`
</Update>

<Update label="2025.07.22">
  Launched Circle Gateway on testnet.

  ### Documentation additions

  Created the following new topics to support Circle Gateway:

  * [Gateway Overview](/gateway)
  * [Gateway Technical Guide](/gateway/concepts/technical-guide)
  * [Quickstart: Create and Transfer a Unified USDC Balance (EVM)](/gateway/quickstarts/unified-balance-evm)
  * [Quickstart: Create and Transfer a Unified USDC Balance (Solana)](/gateway/quickstarts/unified-balance-solana)
  * [Gateway Supported Blockchains](/gateway/references/supported-blockchains)
  * [Gateway Contract Addresses](/gateway/references/contract-addresses)
  * [Gateway Contract Interfaces and Events](/gateway/references/contract-interfaces-and-events)
  * [Gateway Fees](/gateway/references/fees)

  ### API additions

  Added the following endpoints to support Circle Gateway:

  * [`POST /v1/balances`](/api-reference/gateway/all/get-token-balances)
  * [`GET /v1/info`](/api-reference/gateway/all/get-gateway-info)
  * [`POST /v1/transfer`](/api-reference/gateway/all/create-transfer-attestation)
</Update>

<Update label="2025.07.11">
  Added an optional `delayReason` field to CCTP transfer status responses to
  provide context for delayed transfers.

  ### API updates

  The `delayReason` field is now returned in the following CCTP Iris endpoints:

  * `GET /v2/messages` - Get messages and attestations
</Update>

<Update label="2025.07.08">
  Added support for the `order` request parameter (`ASC` or `DESC`) to enable
  sorting by `createDate` for improved client-side data handling.

  ### API updates

  The `order` parameter is now supported in the following endpoints:

  * `GET /v1/w3s/walletSets` - Get all wallet sets (developer-controlled)
  * `GET /v1/w3s/transactions` - List transactions (user/developer-controlled)
  * `GET /v1/w3s/wallets` - List wallets (user/developer-controlled)
  * `GET /v1/w3s/users` - List users (user-controlled)
</Update>

## June 2025

<Update label="2025.06.25">
  Launched Developer Services support for Aptos Mainnet and Testnet.

  ### Documentation updates

  Updated the following documentation for Wallets to reflect Aptos support:

  * [Account Types](/wallets/account-types)
  * [Blockchain Infrastructure](/wallets/blockchain-infrastructure)
  * [Blockchain Compatibility for Developer Services APIs](/wallets/supported-blockchains)
  * [Blockchain Confirmations](/wallets/blockchain-confirmations)
  * [Gas Fees](/wallets/gas-fees)
  * [Gas Station](/wallets/gas-station)
  * [Gas Station Contract Addresses](/wallets/gas-station/contract-addresses)
  * [Gas Station Policy Management](/wallets/gas-station/policy-management)
  * [Supported Blockchains](/wallets/supported-blockchains)
  * [Receive an Inbound Transfer: Dev-controlled](/wallets/dev-controlled/receive-an-inbound-transfer)
  * [Receive an Inbound Transfer: Dev-controlled](/wallets/dev-controlled/receive-an-inbound-transfer)
  * [Receive an Inbound Transfer: User-controlled](/wallets/user-controlled/receive-inbound-transfer)
  * [Send a Gasless Transaction](/wallets/gas-station/send-a-gasless-transaction)

  ### API updates

  Added enum values `APTOS`, `APTOS-TESTNET` to the `blockchain` request field for
  the following APIs:

  * `POST /developer/wallets`
  * `POST /user/wallets`
  * `GET /wallets`
  * `GET /transactions`
  * `POST /transactions/transfer`
  * `POST /transactions/transfer/estimateFee`
  * `POST /transactions/validateAddress`
  * `POST /user/initialize`
</Update>

<Update label="2025.06.17">
  Added programmatic gas price optimization to modular wallets web SDK.

  ### Documentation updates

  Updated the following documentation to reflect programmatic gas price
  optimization support in modular wallets web SDK:

  * [Modular Wallets Web SDK](/wallets/modular/web-sdk):
    * Added `GetUserOperationGasPriceReturnType` interface.
    * Added `GetUserOperationGasPriceRpcSchema` type.
    * Added `getUserOperationGasPrice` function.
</Update>

<Update label="2025.06.13">
  Removed Compliance Engine's **Travel Rule** from the developer documentation as
  it's been deprecated.
</Update>

## May 2025

<Update label="2025.05.15">
  Added support for Avalanche and Unichain to Paymaster v0.8.

  ### Documentation updates

  Updated the following documentation to reflect Avalanche and Unichain support in
  Paymaster v0.8:

  * [Paymaster Overview](/paymaster)
  * [Paymaster Addresses and Events](/paymaster/addresses-and-events)
</Update>

<Update label="2025.05.07">
  Added Paymaster v0.8 documentation.

  ### Documentation updates

  Updated the following pages to reflect support for EntryPoint v0.8 of the
  ERC-4337 contract in Paymaster:

  * [Paymaster Overview](/paymaster)
  * [Quickstart: Build a Wallet to Pay Gas Fees with USDC](/paymaster/pay-gas-fees-usdc)
  * [Paymaster Addresses and Events](/paymaster/addresses-and-events)
</Update>

## April 2025

<Update label="2025.04.17">
  Added passkey recovery support to modular wallets web SDK.

  ### Documentation additions

  Added the following documentation to support passkey recovery using the modular
  wallets web SDK:

  * [How To Set Up Passkey Recovery](/wallets/modular/recover-passkey).

  ### Documentation updates

  Updated the following documentation to support passkey recovery in modular
  wallets:

  * [Modular Wallets Web SDK](/wallets/modular/web-sdk):
    * Added `estimateExecuteRecoveryGas` function.
    * Added `estimateRegisterRecoveryAddressGas` function.
    * Added `executeRecovery` function.
    * Added `recoveryActions` function.
    * Added `registerRecoveryAddress` function.
  * [Modular Wallets Passkey](/wallets/modular/passkeys)
</Update>

<Update label="2025.04.11">
  ### Documentation updates

  Updated the following documentation to reflect the removed API and the new
  **[Derive a Wallet API](/api-reference/wallets/developer-controlled-wallets/derive-wallet)**
  endpoint:

  * [Programmable Wallet API Rate Limits](/wallets/api-rate-limits)

  ### API updates

  * Removed API for products that never officially launched. The following APIs
    were removed:
    * **Backfill a Wallet API**: `PUT /developer/wallets/:id/backfill`

  * Added content schema, description, and the X-Request-Id header to the **201**
    response for the following APIs:
    * [`POST /v1/w3s/user/initialize`](/api-reference/wallets/user-controlled-wallets/create-user-with-pin-challenge)
    * [`POST /v1/w3s/user/pin`](/api-reference/wallets/user-controlled-wallets/create-user-pin-challenge)
    * [`PUT /v1/w3s/user/pin`](/api-reference/wallets/user-controlled-wallets/update-user-pin-challenge)
    * [`POST /v1/w3s/user/pin/restore`](/api-reference/wallets/user-controlled-wallets/create-user-pin-restore-challenge)
    * [`POST /v1/w3s/user/wallets`](/api-reference/wallets/user-controlled-wallets/create-user-wallet)
    * [`POST /v1/w3s/user/transactions/{id}/accelerate`](/api-reference/wallets/user-controlled-wallets/create-user-transaction-accelerate-challenge)
    * [`POST /v1/w3s/user/transactions/{id}/cancel`](/api-reference/wallets/user-controlled-wallets/create-user-transaction-cancel-challenge)
    * [`POST /v1/w3s/user/transactions/walletUpgrade`](/api-reference/wallets/user-controlled-wallets/create-user-transaction-wallet-upgrade-challenge)

  ### API additions

  * Added the new
    **[Derive a Wallet API](/api-reference/wallets/developer-controlled-wallets/derive-wallet)**:
    `PUT /developer/wallets/:id/blockchains/:blockchain`
</Update>

<Update label="2025.04.08">
  * Launched Developer Services, including Circle Contracts, on Optimism (OP) and
    Base (BASE) blockchains.
  * Added modular wallets and Circle Contracts support on Unichain (UNI)
    blockchain.
  * Added a new tutorial in modular wallets to showcase how to add Externally
    Owned Account (EOA) signers for Circle Smart Accounts.

  ### Documentation additions

  Added the following documents:

  * [Dynamic Integration Tutorial](/wallets/modular/dynamic-integration)

  ### Documentation updates

  Added Optimism (OP) and Base (BASE) blockchains to tables of support:

  * [Account Types](/wallets/account-types)
  * [Blockchain Compatibility for Developer Services APIs](/wallets/supported-blockchains)
  * [Blockchain Confirmations](/wallets/blockchain-confirmations)
  * [Gas Fees](/wallets/gas-fees)
  * [Gas Station](/wallets/gas-station)
  * [Gas Station Contract Addresses](/wallets/gas-station/contract-addresses)
  * [Gas Station Policy Management](/wallets/gas-station/policy-management)
  * [Modular Wallets Android SDK](/wallets/modular/android-sdk)
  * [Modular Wallets iOS SDK](/wallets/modular/ios-sdk)
  * [Modular Wallets Quickstart](/wallets/modular/create-a-wallet-and-send-gasless-txn)
  * [Receive an Inbound Transfer (User-Controlled Wallets)](/wallets/user-controlled/receive-inbound-transfer)
  * [Receive an Inbound Transfer (Developer-Controlled Wallets)](/wallets/dev-controlled/receive-an-inbound-transfer)
  * [Send a Gasless Transaction](/wallets/gas-station/send-a-gasless-transaction)
  * [Supported Blockchains](/wallets/supported-blockchains)

  ### API additions

  * Added enum values `BASE`, `BASE-SEPOLIA`, `OP`, `OP-SEPOLIA` to the
    `blockchain` request field for the following APIs:
    * `POST /developer/wallets`
    * `POST /user/wallets`
    * `GET /wallets`
    * `GET /transactions`
    * `POST /transactions/contractExecution/estimateFee`
    * `POST /transactions/transfer`
    * `POST /transactions/transfer/estimateFee`
    * `POST /transactions/validateAddress`
    * `POST /user/initialize`
    * `GET /config/entity/monitoredTokens`
    * `GET /contracts`
    * `POST /contracts/deploy`
    * `POST /contracts/deploy/estimateFee`
    * `POST /contracts/import`
    * `POST /contracts/query`
    * `POST /templates/{id}/deploy`
    * `POST /templates/{id}/deploy/estimateFee`
    * `GET /contracts/monitors`
    * `POST /contracts/monitors`
    * `GET /contracts/events`

  * Added enum values `UNI` and `UNI-SEPOLIA` to the `blockchain` request field
    for the following APIs:
    * `GET /contracts`
    * `POST /contracts/deploy`
    * `POST /contracts/deploy/estimateFee`
    * `POST /contracts/import`
    * `POST /contracts/query`
    * `POST /templates/{id}/deploy`
    * `POST /templates/{id}/deploy/estimateFee`
    * `GET /contracts/monitors`
    * `POST /contracts/monitors`
    * `GET /contracts/events`
</Update>

## March 2025

<Update label="2025.03.27">
  The following Circle Product Lines have been renamed:

  | Previous Product Line name | New Product Line name |
  | -------------------------- | --------------------- |
  | Web3 Services              | Developer Services    |

  The following Circle Products have been renamed:

  | Previous Product name         | New Product name |
  | ----------------------------- | ---------------- |
  | Programmable Wallets          | Circle Wallets   |
  | Smart Contract Platform (SCP) | Circle Contracts |

  These name changes are part of a broader effort to simplify and align our
  product naming, creating a more unified developer experience across the Circle
  platform.
</Update>

<Update label="2025.03.24">
  ### Documentation updates

  Updated the following document to reflect the new **Backfill a wallet** API
  endpoint:

  * [Programmable Wallet API Rate Limits](/wallets/api-rate-limits)

  ### API additions

  Added new API endpoints:

  * [`GET /v1/w3s/developer/wallets/balances`](/api-reference/wallets/developer-controlled-wallets/get-wallets-with-balances)
  * `PUT /v1/w3s/developer/wallets/{id}/backfill`
</Update>

<Update label="2025.03.21">
  Removed USDC Access from the developer documentation as it's no longer available
  for new users.
</Update>

## February 2025

<Update label="2025.02.22">
  ### API updates

  * Updated description for the following APIs:
    * `POST /developer/sign/message`
    * `POST /developer/sign/typeData`
    * `POST /user/sign/message`
    * `POST /user/sign/typeData`

  ### API additions

  * Added example for `Address` and `ContractAddress`
</Update>

<Update label="2025.02.21">
  ### API updates

  * Updated `abiFunctionSignature` to be optional for the
    `POST /transactions/contractExecution/estimateFee` API.
</Update>

<Update label="2025.02.19">
  ### API additions

  * Added enum values `UNI` and `UNI-SEPOLIA` to the `chain` request field for the
    following API:
    * `POST /compliance/screening/addresses`
</Update>

<Update label="2025.02.12">
  Added EIP-1193 example for modular wallets

  ### Documentation additions

  Added a code example for EIP-1193:

  * [Key Features](/wallets/modular/key-features)
</Update>

<Update label="2025.02.11">
  Launched Web3 Services on Unichain mainnet

  ### Documentation updates

  Added Unichain mainnets to tables of support:

  * [Supported Blockchains](/wallets/supported-blockchains)
  * [Blockchain Compatibility for Web3 Services APIs](/wallets/supported-blockchains)
  * [Blockchain Confirmations](/wallets/blockchain-confirmations)
  * [Gas Fees](/wallets/gas-fees)
  * [Gas Station Contract Addresses](/wallets/gas-station/contract-addresses)
  * [Gas Station](/wallets/gas-station)
</Update>

## January 2025

<Update label="2025.01.30">
  Added information on batching user-ops with the Circle API.

  ### Documentation updates

  Updated information on batch operations:

  * [Account Types](/wallets/account-types)
  * [Batch Operations](/wallets/batch-operations)
</Update>

<Update label="2025.01.29">
  ### API additions

  * Added enum value `UNI` to the `blockchain` request field for the following
    APIs:
    * `POST /developer/wallets`
    * `POST /user/wallets`
    * `GET /wallets`
    * `GET /transactions`
    * `POST /transactions/validateAddress`
    * `POST /user/initialize`
    * `GET /config/entity/monitoredTokens`
    * `POST /developer/transactions/transfer`
    * `POST /transactions/transfer/estimateFee`
    * `POST /user/transactions/transfer`
    * `POST /user/transactions/transfer/estimateFee`
</Update>

<Update label="2025.01.25">
  Launched user-controlled wallets signing on EVM chains.

  ### Documentation updates

  Added information for signing transactions with user-controlled wallets:

  * [Confirmation UIs](/wallets/user-controlled/confirmation-uis)
  * [Signing APIs](/wallets/signing-apis)
  * [Supported Blockchains](/wallets/supported-blockchains)
</Update>

<Update label="2025.01.24">
  ### API updates

  * Updated the description of error code `155236`: The provided fee in request is
    invalid.
</Update>

<Update label="2025.01.17">
  Launched modular wallets.

  ### Documentation additions

  Added modular wallets content to the Wallets section of the Developer Services
  pillar:

  * [Modular Wallets Quickstart](/wallets/modular/create-a-wallet-and-send-gasless-txn)
  * [Modular Wallets SDKs](/sdks)
  * [Modular Wallets Sample App](/sample-projects)

  ### API additions

  Added modular wallets endpoints:

  * `GET buidl/transfers`
  * `GET buidl/userOps`
  * `GET buidl/wallets/balances`
  * `GET buidl/wallets/nfts`
</Update>

<Update label="2025.01.14">
  Launched Web3 Services on Unichain testnet.

  ### Documentation updates

  Added Unichain testnet to tables of support:

  * [Supported Blockchains](/wallets/supported-blockchains)
  * [Blockchain Compatibility for Web3 Services APIs](/wallets/supported-blockchains)
  * [Blockchain Confirmations](/wallets/blockchain-confirmations)
  * [Gas Fees](/wallets/gas-fees)
  * [Gas Station Contract Addresses](/wallets/gas-station/contract-addresses)
  * [Gas Station](/wallets/gas-station)
</Update>


# Release Notes - Wallets - 2026
Source: https://developers.circle.com/release-notes/wallets-2026

2026 release notes for Wallets

## May 2026

<Update label="2026.05.05">
  ### Documentation updates

  Rewrote the dev-controlled wallet quickstarts for wallet creation, token
  transfers, and transaction signing to improve clarity, consistency, and
  developer usability.

  The following topics were updated:

  * [Quickstart: Create a Dev-Controlled Wallet](/wallets/dev-controlled/create-your-first-wallet)
  * [Send Tokens Across Wallets](/wallets/dev-controlled/transfer-tokens-across-wallets)
  * [Sign and Submit a Transaction](/wallets/sign-transactions)
</Update>

<Update label="2026.05.01">
  ### Documentation updates

  Rewrote entity secret management and signing documentation to clarify
  authorization, key management, and signing API flows for dev-controlled wallets.

  The following topics were updated:

  * [How the Entity Secret Works](/wallets/dev-controlled/entity-secret-management)
  * [How-to: Generate and Register Your Entity Secret](/wallets/dev-controlled/register-entity-secret)
  * [Key Management](/wallets/key-management)
  * [Transaction Signing and Authorization](/wallets/signing-and-authorization-models)
  * [How Signing APIs Work](/wallets/signing-apis)
</Update>

## April 2026

<Update label="2026.04.30">
  ### Documentation additions

  Added the following new topics for batch creation and pre-creation of
  dev-controlled wallets:

  * [How-to: Batch-Create Wallets for Existing Users](/wallets/dev-controlled/batch-create-wallets)
  * [How-to: Pre-Create Wallets and Assign on Demand](/wallets/dev-controlled/pre-create-wallets)
</Update>

<Update label="2026.04.23">
  ### Documentation updates

  Updated the Wallets overview and account selection documentation to clarify the
  differences between dev-controlled, modular, and user-controlled wallets and to
  improve guidance for choosing wallet and account types.

  The following topics were updated:

  * [Wallets Overview](/wallets)
  * [Dev-Controlled Wallets](/wallets/dev-controlled)
  * [Modular Wallets](/wallets/modular)
  * [User-Controlled Wallets](/wallets/user-controlled)
  * [Choose Wallet and Account Types](/wallets/account-types)
</Update>

<Update label="2026.04.14">
  ### Documentation updates

  Updated Wallets documentation across core concepts, wallet types, signing, and
  developer workflows to improve the overall developer journey.

  The following topics were updated:

  * [Wallets Overview](/wallets)
  * [Choose Wallet and Account Types](/wallets/account-types)
  * [Key Management](/wallets/key-management)
  * [Transaction Signing and Authorization](/wallets/signing-and-authorization-models)
  * [How Signing APIs Work](/wallets/signing-apis)
</Update>

## March 2026

<Update label="2026.03.12">
  ### Documentation additions

  Created the following new topic for creating and funding a Solana Associated
  Token Account (ATA) when Gas Station does not sponsor ATA creation:

  * [Quickstart: Create and Fund a Solana Associated Token Account (ATA)](/wallets/gas-station/create-solana-ata)
</Update>

<Update label="2026.03.04">
  ### Documentation updates

  Documentation for the **React Native SDK** (user-controlled wallets) was updated
  to reflect the latest SDK and to separate legacy V1 content:

  * The main page now covers installation, social login configuration, upgrading
    from V1, and the full SDK API references.
  * `addListener`, `removeAllListeners`, and `EventListener` are marked deprecated
    but still supported in V1.
  * Now the preferred way to subscribe to SDK events (such as forgot PIN, resend
    OTP) is via Expo's `NativeModule.addListener()` using the `CIRCLE_PW_ON_EVENT`
    constant and the `CirclePwEventPayload` interface.
  * A dedicated legacy page was added for V1-only setups.

  The following topics were updated and added, respectively:

  * [React Native SDK](/wallets/user-controlled/react-native-sdk)
  * [React Native SDK V1 (Legacy)](/wallets/user-controlled/react-native-sdk-v1)
</Update>

## January 2026

<Update label="2026.01.28">
  Added Gas Station support for Solana ATA sponsorship.

  ### Documentation additions

  Created the following new topic to support Solana ATA sponsorship in Gas
  Station:

  * [Solana ATA sponsorship](/wallets/gas-station/solana-ata-sponsorship)
</Update>

<Update label="2026.01.20">
  ### Documentation updates

  Complete rewrites of the **user-controlled wallet quickstarts** for **Social
  Login**, **Email OTP**, and **PIN** to improve clarity, consistency, and
  developer usability. The new quickstarts emphasize building a runnable
  end-to-end app that demonstrates authentication, wallet creation, and onchain
  actions. Backend routes were restructured to clearly map frontend actions to the
  corresponding Circle API endpoints. The updates make the wallet lifecycle, SDK
  usage, and backend integration patterns more explicit and easier to follow for
  first-time integrators.

  The following topics were updated and renamed:

  * [Create User Wallets with Social Login](/wallets/user-controlled/create-user-wallets-with-social-login)
  * [Create User Wallets with Email OTP](/wallets/user-controlled/create-user-wallets-with-email)
  * [Create User Wallets with PIN](/wallets/user-controlled/create-user-wallets-with-pin)
</Update>


# Release Notes - xReserve - 2026
Source: https://developers.circle.com/release-notes/xreserve-2026

2026 release notes for xReserve

## April 2026

<Update label="2026.04.13">
  Added Arc Testnet as a source chain and domain for xReserve.

  ### Documentation updates

  Updated the following topic to reflect Arc Testnet support:

  * [xReserve Supported Blockchains and Domains](/xreserve/references/supported-blockchains-and-domains)
</Update>

## March 2026

<Update label="2026.03.24">
  Added support for USDCx through xReserve on the Movement mainnet and testnet.

  ### Documentation updates

  Updated the following topics to reflect support for USDCx on Movement:

  * [xReserve Supported Blockchains and Domains](/xreserve/references/supported-blockchains-and-domains)
  * [Quickstart: Deposit USDC into xReserve](/xreserve/tutorials/deposit-usdc-into-xreserve#movement)
</Update>

## February 2026

<Update label="2026.02.27">
  Added support for USDCx through xReserve on the Cardano mainnet and preprod
  testnet.

  ### Documentation updates

  Updated the following topics to reflect support for USDCx on Cardano:

  * [xReserve Supported Blockchains and Domains](/xreserve/references/supported-blockchains-and-domains)
  * [Quickstart: Deposit USDC into xReserve](/xreserve/tutorials/deposit-usdc-into-xreserve#cardano)
</Update>

## January 2026

<Update label="2026.01.27">
  Added support for USDCx through xReserve on the Aleo mainnet and testnet.

  ### Documentation updates

  Updated the following topic to reflect support for USDCx on Aleo:

  * [xReserve Supported Blockchains and Domains](/xreserve/references/supported-blockchains-and-domains)
</Update>

<Update label="2026.01.15">
  ### Documentation additions

  Added the following xReserve topic:

  * [USDC-backed Stablecoin Specification](/xreserve/concepts/usdc-backed-stablecoin-specification)
</Update>


# Browse Sample Projects
Source: https://developers.circle.com/sample-projects



The following projects serve as reference implementations for features of Circle
developer tools. These projects include examples that you can use as a
foundation to build your own projects.

## Wallets

Wallets provides a comprehensive solution for you to build flexible, secure, and
scalable embedded wallets within your applications. For more information, see
the [Wallets documentation](/wallets).

<SDKCard title="Create escrow contracts for the gig economy using AI and USDC" description="Sample project demonstrating  for the integration of AI agents with blockchain to manage escrow services autonomously." />

<SDKCard title="Autonomous payments with AI agents" description="Sample app for autonomous USDC payments with AI agents using the developer-controlled wallets SDK" />

<SDKCard title="Create a smart account and send a gasless transaction" description="Sample app showcasing how to use the modular wallets web SDK to register for and log in to a Circle smart account with passkeys, and send a user operation using this account on Polygon Amoy" />

<SDKCard title="User account creation, social and email login, and PIN authorization flow" description="Sample app for experiencing user account creation, login UX, and PIN authorization flow powered by the user-controlled wallets SDK (client)" />

<SDKCard title="User account creation and social login" description="Sample app for experiencing user account creation and login UX powered by the user-controlled wallets SDK (client)" />

<SDKCard title="Manage user sessions" description="Test server to manage user sessions and requests powered by the user-controlled wallets SDK (server)" />

<SDKCard title="Telegram bot with Wallets" description="Sample app that demonstrates the use of developer-controlled wallets to perform USDC operations on Telegram." />

## Paymaster

Circle Paymaster allows your users to pay for network (gas) fees using USDC
tokens, instead of chain native tokens.

<SDKCard title="Pay for network fees with USDC" description="Sample app that demonstrates the use of Circle Paymaster to pay for network fees in USDC." />

## Circle Mint

Circle Mint is a fast and cost-effective way to access and redeem USDC and EURC.
For more information, see the [Circle Mint documentation](/circle-mint).

<SDKCard title="Test payment flows" description="Sample app to demonstrate features of the Mint Payments API" />

## CCTP

Cross-Chain Transfer Protocol (CCTP) is an on-chain utility that allows for USDC
transfers between blockchains via native burning and minting. For more
information, see the [CCTP documentation](/cctp).

<SDKCard title="Fast and Standard Transfer USDC between blockchains" description="Sample app that demonstrates the fast transfer capabilities of CCTP" />

<SDKCard title="Cross-chain USDC Telegram bot with CCTP and Wallets" description="Sample app that demonstrates the use of developer-controlled wallets and CCTP to move USDC across chains on Telegram." />

## Circle Research

Circle Research develops cutting-edge insights and reference materials. For more
information see the
[Circle Research homepage](https://circle.com/circle-research).

<Warning>
  Circle Research projects are experimental. Make sure you test your code
  thoroughly if you are integrating ideas from these repositories.
</Warning>

<Banner>
  Circle Research projects are experimental. Make sure you test your code
  thoroughly if you are integrating ideas from these repositories.
</Banner>

<SDKCard title="Evaluate a fast confirmation rule on Ethereum" description="Sample script to evaluate a fast confirmation rule for transaction settlement on Ethereum" />

<SDKCard title="Execute onchain transactions with intents and AI" description="Reference implementation of Circle Research's TXT2TXN project" />

<SDKCard title="Create credit apps powered by USDC" description="Reference implementation for building credit apps using USDC and Circle Research's Perimeter Protocol" />


# Browse SDKs
Source: https://developers.circle.com/sdks

Explore Circle's SDKs to learn and simplify your development with the Circle Platform

<div>
  <SDKCard title="Developer-Controlled Wallets SDK" description="Server SDK for creating and managing developer-controlled wallets" icon="wallet" />

  <SDKCard title="Modular Wallets SDK" description="Client SDK for creating and managing modular wallets" icon="template" />

  <SDKCard title="User-Controlled Wallets SDK (Client)" description="Client SDK for creating and managing user-controlled wallets" icon="wallet" />

  <SDKCard title="User-Controlled Wallets SDK (Server)" description="Server SDK for creating and managing user-controlled wallets" icon="wallet" />

  <SDKCard title="Contracts SDK" description="Server SDK for creating and managing smart contracts" icon="contract" />

  <SDKCard title="Mint Payouts SDK" description="Server SDK for creating and managing stablecoin payouts" icon="library" />
</div>


# Getting Started with the Contracts Node.js SDK
Source: https://developers.circle.com/sdks/contracts-nodejs-sdk



Use the
[Node.js SDK](https://www.npmjs.com/package/@circle-fin/smart-contract-platform)
to interact with [Contracts APIs](/api-reference/contracts/common/ping), which
allow you interact with smart contracts on the blockchain using the Developer
Services platform.

This page provides short examples of how to install and use the Contracts SDK.
For complete examples, see the [Sample Projects](/sample-projects) page. For
more information see the [Contracts documentation](/contracts).

## Prerequisites

To use the Node.js SDK, ensure you have:

* [Node.js v22+](https://nodejs.org/) installed
* A [Circle Developer Console](https://console.circle.com) account
* An [API key](/build/keys) created in the Console:\
  **Keys → Create a key → API key → Standard Key**
* Your
  [Entity Secret registered](https://developers.circle.com/wallets/dev-controlled/register-entity-secret)

## Install the SDK

Use the following commands to install the SDK. You can
[view the package information on the npm site](https://www.npmjs.com/package/@circle-fin/smart-contract-platform).

<CodeGroup>
  ```shell npm theme={null}
  npm install @circle-fin/smart-contract-platform --save
  ```

  ```shell yarn theme={null}
  yarn add @circle-fin/smart-contract-platform
  ```
</CodeGroup>

## Contracts client

To start using the SDK, you first need to configure a client. Import the
`initiateSmartContractPlatformClient` factory from the SDK, and then initialize
the client using your API key and entity secret.

### Import the client

The following example shows how to import the client and configure it to use
your API key and entity secret:

<CodeGroup>
  ```javascript CommonJS theme={null}
  const {
    initiateSmartContractPlatformClient,
  } = require("@circle-fin/smart-contract-platform");
  const client = initiateSmartContractPlatformClient({
    apiKey: "<your-api-key>",
    entitySecret: "<your-entity-secret>",
  });
  ```

  ```javascript ES Module theme={null}
  import { initiateSmartContractPlatformClient } from "@circle-fin/smart-contract-platform";
  const client = initiateSmartContractPlatformClient({
    apiKey: "<your-api-key>",
    entitySecret: "<your-entity-secret>",
  });
  ```
</CodeGroup>

### Deploy a smart contract

The following example shows how to deploy a smart contract using the client:

```javascript theme={null}
const response = await client.deployContract({
  name: "First Contract",
  description: "My first hello world contract",
  walletId: "004735f6-d9fc-44f8-933c-672cdf3d240d",
  abiJson:
    "[\n\t{\n\t\t'inputs': [],\n\t\t'stateMutability': 'nonpayable',\n\t\t'type': 'constructor'\n\t},\n\t...",
  bytecode: "0x60806040523480156200001157600080fd5b50604051806040...",
  constructorParameters: ["TICK", 10000],
  feeLevel: "MEDIUM",
});
console.log(response.data);
```

## Client configuration options

The client for the Contracts SDK accepts the following configuration parameters:

| **Option**     | **Required?** | **Description**                                                                                        |
| -------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| `apiKey`       | Yes           | The API key used to authenticate requests to the Circle API.                                           |
| `entitySecret` | Yes           | Your configured entity secret.                                                                         |
| `storage`      | No            | Optional custom storage solution for persisting data. If not provided, the SDK uses in-memory storage. |


# Getting Started with the Contracts Python SDK
Source: https://developers.circle.com/sdks/contracts-python-sdk



Use the [Python SDK](https://pypi.org/project/circle-smart-contract-platform/)
to interact with [Contracts APIs](/api-reference/contracts/common/ping), which
allow you interact with smart contracts on the blockchain using the Developer
Services platform.

This page provides short examples of how to install and use the Smart Contract
Platform SDK. For complete examples, see the [Sample Projects](/sample-projects)
page. For more information see the [Contracts documentation](/contracts).

<Warning>
  **Pydantic v2 upgrade**

  Starting from major version 9, the Python SDK uses Pydantic v2. This change
  brings performance improvements, enhanced features, and bug fixes.

  If you are already using the SDK, and choose to upgrade to major version 9, you
  may need to make some changes to your code.

  For more information, see
  [Server-side SDK Pydantic v2 Upgrade](/sdks/pydantic-v2-upgrade).
</Warning>

## Prerequisites

To use the Python SDK, ensure you have:

* Python installed.
* A [Circle Developer Console](https://console.circle.com) account
* An [API key](/build/keys) created in the Console:\
  **Keys → Create a key → API key → Standard Key**
* Your
  [Entity Secret registered](https://developers.circle.com/wallets/dev-controlled/register-entity-secret)

Although not a requirement for using the SDK, Circle recommends that you
[use a virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
for development. A Python virtual environment is an isolated environment that
you can use to silo your project from the global Python environment.

## Install the SDK

Use the following command to install the SDK with
[pip](https://pypi.org/project/pip/):

```shell theme={null}
pip install circle-smart-contract-platform
```

## Contracts client

To start using the SDK, you first need to configure a client and initialize it
with your API key and entity secret.

### Import the client

The following example shows how to import the client and configure it to use
your API key and entity secret:

```python theme={null}
from circle.web3 import utils

client = utils.init_smart_contract_platform_client(
  api_key="Your API KEY",
  entity_secret="Your entity secret"
)
```

### Import a smart contract

The following example shows how to import a smart contract using the client:

```python theme={null}
from circle.web3 import smart_contract_platform

api_instance = smart_contract_platform.DeployImportApi(client)

# import contract
try:
    request = smart_contract_platform.ImportContractRequest.from_dict({
        "name": "UChildERC20Proxy",
        "address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
        "blockchain": "MATIC"
    })
    response = api_instance.import_contract(request)
    print(response)
except smart_contract_platform.ApiException as e:
    print("Exception when calling DeployImportApi->import_contract: %s\n" % e)
```

## Client configuration options

The client for the Contracts SDK accepts the following configuration parameters:

| **Option**      | **Required?** | **Description**                                                                                 |
| --------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| `api_key`       | Yes           | The API key used to authenticate requests to the Circle API.                                    |
| `entity_secret` | Yes           | Your configured entity secret.                                                                  |
| `host`          | No            | The base URL that overrides the default API URL of `https://api.circle.com/v1/w3s`.             |
| `user_agent`    | No            | Custom user agent request header. If provided, it's added before the default user agent header. |


# Getting Started with the Developer-Controlled Wallets Node.js SDK
Source: https://developers.circle.com/sdks/developer-controlled-wallets-nodejs-sdk



Use the
[Node.js SDK](https://www.npmjs.com/package/@circle-fin/developer-controlled-wallets)
to interact with
[Circle's Developer-Controlled Wallet APIs](/api-reference/wallets/developer-controlled-wallets/get-wallet-sets),
which allow you to embed secure wallets in your applications and create
blockchain transactions using the Developer Services platform.

This page provides short examples of how to install and use the
developer-controlled wallets SDK. For complete examples, see the
[Sample Projects](/sample-projects) page. For more information see the
[developer-controlled wallets documentation](/wallets/dev-controlled).

## Prerequisites

To use the Node.js SDK, ensure you have:

* [Node.js v22+](https://nodejs.org/) installed
* A [Circle Developer Console](https://console.circle.com) account
* An [API key](/build/keys) created in the Console:\
  **Keys → Create a key → API key → Standard Key**
* Your
  [Entity Secret registered](https://developers.circle.com/wallets/dev-controlled/register-entity-secret)

## Install the SDK

Use the following commands to install the SDK. You can
[view the package information on the npm site](https://www.npmjs.com/package/@circle-fin/developer-controlled-wallets).

<CodeGroup>
  ```shell npm theme={null}
  npm install @circle-fin/developer-controlled-wallets --save
  ```

  ```shell yarn theme={null}
  yarn add @circle-fin/developer-controlled-wallets
  ```
</CodeGroup>

## Developer-controlled wallets client

To start using the SDK, you first need to configure a client. Import the
`initiateDeveloperControlledWalletsClient` factory from the SDK, and then
initialize the client using your API key and entity secret.

### Import the client

The following example shows how to import the client and configure it to use
your API key and entity secret:

<CodeGroup>
  ```ts ES Module theme={null}
  import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
  const client = initiateDeveloperControlledWalletsClient({
    apiKey: "<your-api-key>",
    entitySecret: "<your-entity-secret>",
  });
  ```

  ```ts CommonJS theme={null}
  const {
    initiateDeveloperControlledWalletsClient,
  } = require("@circle-fin/developer-controlled-wallets");
  const client = initiateDeveloperControlledWalletsClient({
    apiKey: "<your-api-key>",
    entitySecret: "<your-entity-secret>",
  });
  ```
</CodeGroup>

### Create a wallet

The following example shows how to create a wallet using the client:

```ts TypeScript theme={null}
// Create a wallet set
const walletSetResponse = await client.createWalletSet({
  name: "Wallet Set 1",
});
console.log("Created WalletSet", walletSetResponse.data?.walletSet);

// Create a wallet on Arc Testnet
const walletsResponse = await client.createWallets({
  blockchains: ["ARC-TESTNET"],
  count: 1,
  walletSetId: walletSetResponse.data?.walletSet?.id ?? "",
});
console.log("Created Wallets", walletsResponse.data?.wallets);
```

### Create a transaction

The following example shows how to create a transaction using the client:

```ts TypeScript theme={null}
const response = await client.createTransaction({
  amounts: ["0.01"],
  destinationAddress: "0xa51c9c604b79a0fadbfed35dd576ca1bce71da0a",
  tokenId: "738c8a6d-8896-46d1-b2cb-083600c1c69b",
  walletId: "a635d679-4207-4e37-b12e-766afb9b3892",
  fee: { type: "level", config: { feeLevel: "HIGH" } },
});
console.log(response.data);
```

## Client configuration options

The client for the developer-controlled wallets SDK accepts the following
configuration parameters:

| **Option**     | **Required?** | **Description**                                                                                        |
| -------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| `apiKey`       | Yes           | The API key used to authenticate requests to the Circle API.                                           |
| `entitySecret` | Yes           | Your configured entity secret.                                                                         |
| `storage`      | No            | Optional custom storage solution for persisting data. If not provided, the SDK uses in-memory storage. |


# Getting Started with the Developer-Controlled Wallets Python SDK
Source: https://developers.circle.com/sdks/developer-controlled-wallets-python-sdk



Use the
[Python SDK](https://pypi.org/project/circle-developer-controlled-wallets/) to
interact with
[Circle's Developer-Controlled Wallet APIs](/api-reference/wallets/developer-controlled-wallets/get-wallet-sets),
which allow you to embed secure wallets in your applications and create
blockchain transactions using the Developer Services platform.

This page provides short examples of how to install and use the
developer-controlled wallets SDK. For complete examples, see the
[Sample Projects](/sample-projects) page. For more information see the
[developer-controlled wallets documentation](/wallets/dev-controlled).

<Warning>
  **Pydantic v2 upgrade**

  Starting from major version 9, the Python SDK uses Pydantic v2. This change
  brings performance improvements, enhanced features, and bug fixes.

  If you are already using the SDK, and choose to upgrade to major version 9, you
  may need to make some changes to your code.

  For more information, see
  [Server-side SDK Pydantic v2 Upgrade](/sdks/pydantic-v2-upgrade).
</Warning>

## Prerequisites

To use the Python SDK, ensure you have:

* Python installed.
* A [Circle Developer Console](https://console.circle.com) account
* An [API key](/build/keys) created in the Console:\
  **Keys → Create a key → API key → Standard Key**
* Your
  [Entity Secret registered](https://developers.circle.com/wallets/dev-controlled/register-entity-secret)

Although not a requirement for using the SDK, Circle recommends that you
[use a virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
for development. A Python virtual environment is an isolated environment that
you can use to silo your project from the global Python environment.

## Install the SDK

Use the following command to install the SDK with
[pip](https://pypi.org/project/pip/):

```shell theme={null}
pip install circle-developer-controlled-wallets
```

## Developer-controlled wallets client

To start using the SDK, you first need to configure a client and initialize it
with your API key and entity secret.

### Import the client

The following example shows how to import the client and configure it to use
your API key and entity secret:

```python theme={null}
from circle.web3 import utils

client = utils.init_developer_controlled_wallets_client(
  api_key="Your API KEY",
  entity_secret="Your entity secret"
)
```

### Create a wallet

The following example shows how to create a wallet using the client:

```python theme={null}
from circle.web3 import developer_controlled_wallets

api_instance = developer_controlled_wallets.WalletSetsApi(client)

# create wallet sets
try:
    request = developer_controlled_wallets.CreateWalletSetRequest.from_dict({
        "name": "my_wallet_set"
    })
    api_instance.create_wallet_set(request)
except developer_controlled_wallets.ApiException as e:
    print("Exception when calling WalletSetsApi->create_wallet_set: %s\n" % e)

# get wallet sets
try:
    response = api_instance.get_wallet_sets()
    for wallet_set in response.data.wallet_sets:
        print(wallet_set.actual_instance.id)
except developer_controlled_wallets.ApiException as e:
    print("Exception when calling WalletSetsApi->get_wallet_sets: %s\n" % e)
```

## Client configuration options

The client for the developer-controlled wallets SDK accepts the following
configuration parameters:

| **Option**      | **Required?** | **Description**                                                                                 |
| --------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| `api_key`       | Yes           | The API key used to authenticate requests to the Circle API.                                    |
| `entity_secret` | Yes           | Your configured entity secret.                                                                  |
| `host`          | No            | The base URL that overrides the default API URL of `https://api.circle.com/v1/w3s`.             |
| `user_agent`    | No            | Custom user agent request header. If provided, it's added before the default user agent header. |


# Server-side SDK Pydantic v2 Upgrade
Source: https://developers.circle.com/sdks/pydantic-v2-upgrade



This guide provides information about the Pydantic v2 upgrade for the
Server-side Python SDKs for
[developer-controlled wallets](/sdks/developer-controlled-wallets-python-sdk),
[user-controlled wallets](/sdks/user-controlled-wallets-python-sdk), and
[Contracts](/sdks/contracts-python-sdk). Pydantic is a Python library for data
modeling and validation that uses type hints to enforce structure, parse input,
and serialize output.

As of version 9.0.0, the Server-side Circle SDKs are upgrading to Pydantic v2
because the new `pydantic-core` package is built with Rust and delivers
significant performance improvements, better correctness, and more consistent
classes, methods, decorators and settings.

## Migration guidance

If you are using the Circle Python SDK and don't want to migrate your code, you
should not upgrade your SDK version past major version 8. Version 8 is in
maintenance mode and will only receive essential updates such as fixes for
critical security flaws.

If you want to upgrade to major version 9 and above, you may need to make some
changes to your code. Review the following sections to see if you are affected.

## No impact

Unless noted in the following section, function signatures in the Python SDK are
unchanged, including:

* API methods
* Core features such as wallet creation and transaction processing

For example, the following usage is unaffected between versions 8 and 9 of the
SDK:

```python theme={null}
from circle.web3.developer_controlled_wallets.api.wallets_api import WalletsApi
from circle.web3.developer_controlled_wallets.models.create_wallet_request import CreateWalletRequest
from circle.web3.developer_controlled_wallets.models.blockchain import Blockchain
from circle.web3.developer_controlled_wallets.models.account_type import AccountType
# These patterns are NOT affected
api_instance = WalletsApi(api_client=client)
request = CreateWalletRequest(
      blockchains=[Blockchain.ETH_MINUS_SEPOLIA],
      wallet_set_id="550e8400-e29b-41d4-a716-446655440002",
      account_type=AccountType.SCA,
      count=1
  )
response = api_instance.create_wallet(request)
wallet_id = response.data.wallet.actual_instance.id
result = api_instance.get_wallet(id=wallet_id)
```

## Summary of changes

The method names of model serialization methods that convert between model
objects and data formats are changing to match the Pydantic v2 naming pattern.
Deserialization methods are typically used to build API request payloads, where
serialization methods are used to parse API responses:

* `model.from_dict()`: deserialize a Python dictionary into a model instance
* `model.from_json()`: deserialize a JSON string into a model instance
* `model.to_dict()`: serialize a model instance to a Python dictionary
* `model.to_json()`: serialize a model instance to a JSON string

The following example shows how to use the new model serialization methods:

```python theme={null}
from circle.web3.developer_controlled_wallets.models.eoa_wallet import EOAWallet
from circle.web3.developer_controlled_wallets.models.blockchain import Blockchain
from circle.web3.developer_controlled_wallets.models.custody_type import CustodyType
from circle.web3.developer_controlled_wallets.models.wallet_state import WalletState


wallet_model = EOAWallet(
    id="550e8400-e29b-41d4-a716-446655440009",
    address="0x9876543210fedcba9876543210fedcba98765432",
    blockchain=Blockchain.ETH_MINUS_SEPOLIA,
    custody_type=CustodyType.DEVELOPER,
    state=WalletState.LIVE,
    wallet_set_id="550e8400-e29b-41d4-a716-446655440002",
    account_type="EOA",
    create_date="2023-01-01T10:00:00Z",
    update_date="2023-01-01T11:00:00Z"
)


wallet_dict = wallet_model.to_dict()
wallet_json = wallet_model.to_json()
wallet_from_dict = EOAWallet.from_dict(wallet_dict)
wallet_from_json = EOAWallet.from_json(wallet_json)
```


# Getting Started with the User-Controlled Wallets Node.js SDK
Source: https://developers.circle.com/sdks/user-controlled-wallets-nodejs-sdk



Use the
[Node.js SDK](https://www.npmjs.com/package/@circle-fin/user-controlled-wallets)
to interact with Circle's User-Controlled Wallet APIs, which allow you to embed
secure wallets in your applications and create blockchain transactions using the
Developer Services platform.

This page provides short examples of how to install and use the user-controlled
wallets SDK. For complete examples, see the [Sample Projects](/sample-projects)
page. For more information see the
[user-controlled wallets documentation](/wallets/user-controlled).

## Prerequisites

To use the Node.js SDK, ensure you have:

* [Node.js v22+](https://nodejs.org/) installed
* A [Circle Developer Console](https://console.circle.com) account
* An [API key](/build/keys) created in the Console:\
  **Keys → Create a key → API key → Standard Key**
* Your
  [Entity Secret registered](https://developers.circle.com/wallets/dev-controlled/register-entity-secret)

## Install the SDK

Use the following commands to install the SDK. You can
[view the package information on the npm site](https://www.npmjs.com/package/@circle-fin/user-controlled-wallets).

<CodeGroup>
  ```shell npm theme={null}
  npm install @circle-fin/user-controlled-wallets --save
  ```

  ```shell yarn theme={null}
  yarn add @circle-fin/user-controlled-wallets
  ```
</CodeGroup>

## User-controlled wallets client

To start using the SDK, you first need to configure a client. Import the
`initiateUserControlledWalletsClient` factory from the SDK, and then initialize
the client using your API key.

### Import the client

The following example shows how to import the client and configure it to use
your API key:

<CodeGroup>
  ```ts ES Module theme={null}
  import { initiateUserControlledWalletsClient } from "@circle-fin/user-controlled-wallets";
  const client = initiateUserControlledWalletsClient({
    apiKey: "<your-api-key>",
  });
  ```

  ```ts CommonJS theme={null}
  const {
    initiateUserControlledWalletsClient,
  } = require("@circle-fin/user-controlled-wallets");
  const client = initiateUserControlledWalletsClient({
    apiKey: "<your-api-key>",
  });
  ```
</CodeGroup>

## Create a transaction

The following example shows how to create a transaction using the client:

```javascript theme={null}
const response = await client.createTransaction({
  userToken: "dummy-user-token",
  amounts: ["0.01"],
  destinationAddress: "0xa51c9c604b79a0fadbfed35dd576ca1bce71da0a",
  tokenId: "738c8a6d-8896-46d1-b2cb-083600c1c69b",
  walletId: "a635d679-4207-4e37-b12e-766afb9b3892",
  fee: {
    type: "level",
    config: {
      feeLevel: "HIGH",
    },
  },
});
console.log(response.data?.challengeId);
```

## Client configuration options

The client for the user-controlled wallets SDK accepts the following
configuration parameters:

| **Option** | **Required?** | **Description**                                                                                        |
| ---------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| `apiKey`   | Yes           | The API key used to authenticate requests to the Circle API.                                           |
| `storage`  | No            | Optional custom storage solution for persisting data. If not provided, the SDK uses in-memory storage. |


# Getting Started with the User-Controlled Wallets Python SDK
Source: https://developers.circle.com/sdks/user-controlled-wallets-python-sdk



Use the [Python SDK](https://pypi.org/project/circle-user-controlled-wallets/)
to interact with
[Circle's User-Controlled Wallet APIs](/api-reference/wallets/user-controlled-wallets/create-user-with-pin-challenge),
which allow you to embed secure wallets in your applications and create
blockchain transactions using the Developer Services platform.

This page provides short examples of how to install and use the user-controlled
wallets SDK. For complete examples, see the [Sample Projects](/sample-projects)
page. For more information see the
[user-controlled wallets documentation](/wallets/user-controlled).

<Warning>
  **Pydantic v2 upgrade**

  Starting from major version 9, the Python SDK uses Pydantic v2. This change
  brings performance improvements, enhanced features, and bug fixes.

  If you are already using the SDK, and choose to upgrade to major version 9, you
  may need to make some changes to your code.

  For more information, see
  [Server-side SDK Pydantic v2 Upgrade](/sdks/pydantic-v2-upgrade).
</Warning>

## Prerequisites

To use the Python SDK, ensure you have:

* Python installed.
* A [Circle Developer Console](https://console.circle.com) account
* An [API key](/build/keys) created in the Console:\
  **Keys → Create a key → API key → Standard Key**
* Your
  [Entity Secret registered](https://developers.circle.com/wallets/dev-controlled/register-entity-secret)

Although not a requirement for using the SDK, Circle recommends that you
[use a virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
for development. A Python virtual environment is an isolated environment that
you can use to silo your project from the global Python environment.

## Install the SDK

Use the following command to install the SDK with
[pip](https://pypi.org/project/pip/):

```shell theme={null}
pip install circle-user-controlled-wallets
```

## User-controlled wallets client

To start using the SDK, you first need to configure a client and initialize it
with your API key.

### Import the client

The following example shows how to import the client and configure it to use
your API key:

```python theme={null}
from circle.web3 import utils

client = utils.init_user_controlled_wallets_client(
api_key="<your_api_key>"
)
```

### Create a transaction

The following example shows how to create a transaction using the client:

```python theme={null}
import uuid
from circle.web3 import user_controlled_wallets

# generate a user id
user_id = str(uuid.uuid4())

# create user
api_instance = user_controlled_wallets.UsersAndPinsApi(client)
try:
    request = user_controlled_wallets.CreateUserRequest(user_id=user_id)
    api_instance.create_user(request)
except user_controlled_wallets.ApiException as e:
    print("Exception when calling UsersAndPinsApi->create_user: %s\n" % e)

# get user
try:
    response = api_instance.get_user(id=user_id)
    print(response.data)
except user_controlled_wallets.ApiException as e:
    print("Exception when calling UsersAndPinsApi->get_user: %s\n" % e)

# get user token
try:
    request = user_controlled_wallets.GenerateUserTokenRequest.from_dict({"userId": user_id})
    response = api_instance.get_user_token(request)
    print(response.data.user_token)
except user_controlled_wallets.ApiException as e:
    print("Exception when calling UsersAndPinsApi->get_user_token: %s\n" % e)
```

## Client configuration options

The client for the user-controlled wallets SDK accepts the following
configuration parameters:

| **Option**   | **Required?** | **Description**                                                                                 |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------- |
| `api_key`    | Yes           | The API key used to authenticate requests to the Circle API.                                    |
| `host`       | No            | The base URL that overrides the default API URL of `https://api.circle.com/v1/w3s`.             |
| `user_agent` | No            | Custom user agent request header. If provided, it's added before the default user agent header. |


# EURC Contract Addresses
Source: https://developers.circle.com/stablecoins/eurc-contract-addresses



EURC is a euro-backed stablecoin that runs on multiple blockchains. EURC tokens
are controlled by a smart contract on the blockchain. The following sections
link to the contracts for EURC on every supported mainnet and testnet
blockchain.

## Mainnet

<Warning>
  **Mainnet Tokens have Financial Value**

  The blockchains listed below store and transfer tokens that have real financial
  value. When interacting with mainnet blockchains, you should thoroughly test
  your code, verify all addresses, and ensure the privacy of seed phrases and
  private keys.
</Warning>

| Blockchain        | EURC Mainnet Address                                                                                                                                                          |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Avalanche C-Chain | [`0xC891EB4cbdEFf6e073e859e987815Ed1505c2ACD`](https://snowtrace.io/token/0xc891eb4cbdeff6e073e859e987815ed1505c2acd)                                                         |
| Base              | [`0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42`](https://basescan.org/token/0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42)                                                         |
| Ethereum          | [`0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c`](https://etherscan.io/token/0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c)                                                         |
| Solana            | [`HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr`](https://explorer.solana.com/address/HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr)                                            |
| Stellar           | [`EURC-GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2`](https://stellar.expert/explorer/public/asset/EURC-GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2) |
| World Chain       | [`0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B`](https://worldscan.org/address/0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B)                                                      |

## Testnet

<Warning>
  **Testnet tokens have no financial value**

  Because the testnets listed below are used only for testing, the EURC tokens in
  circulation on these networks have no financial value, and **are not backed by
  real Euros**.

  Similarly, native testnet tokens have no financial value.
</Warning>

| Blockchain Network  | Token Address                                                                                                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Arc Testnet         | [`0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a`](https://testnet.arcscan.app/address/0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a)                                                                                                                          |
| Avalanche Fuji      | [`0x5E44db7996c682E92a960b65AC713a54AD815c6B`](https://testnet.snowtrace.io/token/0x5e44db7996c682e92a960b65ac713a54ad815c6b)                                                                                                                           |
| Ethereum Sepolia    | [`0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4`](https://sepolia.etherscan.io/address/0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4)                                                                                                                         |
| Base Sepolia        | [`0x808456652fdb597867f38412077A9182bf77359F`](https://base-sepolia.blockscout.com/address/0x808456652fdb597867f38412077A9182bf77359F)                                                                                                                  |
| Solana Devnet       | [`HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr`](https://explorer.solana.com/address/HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr?cluster=devnet)                                                                                                       |
| Stellar Testnet     | [`EURC-GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVO`](https://stellar.expert/explorer/testnet/asset/EURC-GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVO?asset\[]=EURC-GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVO-1) |
| World Chain Sepolia | [`0xe479EcA5740Ac65d6E1823bea2f1C08Bc14e954F`](https://sepolia.worldscan.org/address/0xe479EcA5740Ac65d6E1823bea2f1C08Bc14e954F)                                                                                                                        |


# Quickstart: Set up and transfer USDC on Aptos
Source: https://developers.circle.com/stablecoins/quickstart-setup-transfer-usdc-aptos



USDC provides the ability to transfer digital dollars over public blockchains
using smart contracts. The USDC smart contract allows you to send, receive, and
store digital dollars onchain with a wallet. This quickstart guide provides
step-by-step instructions to build an app for performing your first USDC
transfer on Aptos.

## Prerequisites

Before building the sample app for USDC transfer on Aptos, ensure you have the
following:

* **[Node.js](https://nodejs.org/en)** and **[npm](https://www.npmjs.com/)**:
  Ensure that you have `Node.js` and `npm` installed on your machine. You can
  download and install `Node.js` from [nodejs.org](http://nodejs.org). `npm`
  comes with `Node.js`.
* **[Aptos Wallet](https://aptosfoundation.org/ecosystem/project/aptos-connect)**:
  Install the Aptos Wallet browser extension and set up your wallet. Ensure that
  your wallet is funded with:
  * Some Aptos testnet tokens to cover transaction fees. You can use the
    [Aptos Faucet](https://aptos.dev/en/network/faucet).
  * USDC tokens for the transfer.
    ([USDC Testnet Faucet](https://faucet.circle.com/))

## Contract Addresses

You will need the following contract addresses:

* Testnet USDC -
  [`0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832`](https://explorer.aptoslabs.com/fungible_asset/0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832?network=testnet)

## Installation

Perform the following installation and setup steps:

1. Create a new project directory and initialize it with `npm`:

```shell Shell theme={null}
npx create-next-app@latest usdc-transfer-app
```

2. When prompted, choose the following options:
   * Use `TypeScript`: Yes
   * Use `ESLint`: Yes
   * Use `Tailwind CSS`: Yes
   * Use `src/` directory: Yes
   * Use `App Router`: Yes
   * Customize the default import alias: No

3. Navigate to the project directory:

```shell Shell theme={null}
cd usdc-transfer-app
```

4. Install additional dependencies:

```shell Shell theme={null}
npm install @aptos-labs/ts-sdk @aptos-labs/wallet-adapter-ant-design @aptos-labs/wallet-adapter-react
```

## Import Code and Setup

5. Copy the following code into the `src/app/page.tsx` file. This section
   imports necessary libraries and sets up the network configuration.

```javascript TypeScript theme={null}
"use client";
import { useState, useEffect } from "react";
import { WalletSelector } from "@aptos-labs/wallet-adapter-ant-design";
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { PetraWallet } from "petra-plugin-wallet-adapter";
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
import { useWallet } from "@aptos-labs/wallet-adapter-react";

// Initialize Aptos client
const config = new AptosConfig({ network: Network.TESTNET });
const aptos = new Aptos(config);

// Configure wallets for testnet
const wallets = [new PetraWallet()];
```

This component handles the main functionality of the application, including
wallet connection token definition, and token transfer.

**a. Define USDC testnet token contract**

```javascript TypeScript theme={null}
// Aptos USDC contract address on testnet
const USDC_ADDRESS =
  "0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832";
```

**b. State Management**

Define state variables to manage the connection status, amount, recipient
address, and transaction status.

```javascript TypeScript theme={null}
function HomeContent() {
  const [connected, setConnected] = useState(false);
  const [amount, setAmount] = useState('');
  const [recipientAddress, setRecipientAddress] = useState('');
  const [txStatus, setTxStatus] = useState('');
  const { account, signAndSubmitTransaction } = useWallet();
```

**c. Effect Hook for Connection Status**

Use `useEffect()` to update the connection status whenever the `currentAccount`
changes.

```javascript TypeScript theme={null}
// Update the connection status when the current account changes
useEffect(() => {
  setConnected(!!account?.address);
}, [account]);
```

**d. Token Sending Logic**

Define the function to handle sending tokens, including validation and
transaction execution.

```javascript TypeScript theme={null}
const handleSendTokens = async () => {
  if (!account?.address || !amount || !recipientAddress) {
    setTxStatus("Please connect wallet and fill all fields");
    return;
  }
  try {
    const transaction = {
      data: {
        function: "0x1::primary_fungible_store::transfer",
        typeArguments: ["0x1::fungible_asset::Metadata"],
        functionArguments: [
          USDC_ADDRESS,
          recipientAddress,
          parseFloat(amount) * 1_000_000, // Adjust decimals based on your token
        ],
      },
    };
    const result = await signAndSubmitTransaction(transaction);
    await aptos.waitForTransaction({ transactionHash: result.hash });

    setTxStatus(`Transaction successful. Hash: ${result.hash}`);
  } catch (error) {
    console.error("Error:", error);
    setTxStatus(
      `Error: ${error instanceof Error ? error.message : "Unknown error"}`,
    );
  }
};
```

**e. Rendering the UI**

Render the main UI components, including input fields for amount and recipient
address, and a button to send tokens.

```javascript TypeScript theme={null}
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <div className="z-10 w-full max-w-5xl items-center justify-between font-mono text-sm">
        <h1 className="text-4xl font-bold mb-8">Aptos USDC Sender (Testnet)</h1>
        <WalletSelector />
        {connected && account && (
          <p className="mt-4">Connected: {account.address}</p>
        )}
        <div className="mt-8">
          <input
            type="text"
            placeholder="Amount (in USDC)"
            value={amount}
            onChange={(e) => setAmount(e.target.value)}
            className="p-2 border rounded mr-2 text-black"
          />
          <input
            type="text"
            placeholder="Recipient Address"
            value={recipientAddress}
            onChange={(e) => setRecipientAddress(e.target.value)}
            className="p-2 border rounded mr-2 text-black"
          />
          <button
            onClick={handleSendTokens}
            disabled={!connected}
            className={`p-2 rounded ${
              connected && amount && recipientAddress
                ? 'bg-blue-200 text-black hover:bg-blue-300'
                : 'bg-gray-300 text-gray-500'
            } transition-colors duration-200`}
          >
            Send USDC
          </button>
        </div>
        {txStatus && <p className="mt-4">{txStatus}</p>}
      </div>
    </main>
  );
}
```

## Main Application Component

This component wraps the `HomeContent()` function with the necessary providers
for state management and wallet connection.

```javascript TypeScript theme={null}
export default function Home() {
  return (
    <AptosWalletAdapterProvider
      plugins={wallets}
      autoConnect={true}
      dappConfig={{ network: Network.TESTNET }}
      onError={(error) => {
        console.log("error", error);
      }}
    >
      <HomeContent />
    </AptosWalletAdapterProvider>
  );
}
```

6. Start the development server:

```shell Shell theme={null}
npm run dev
```

7. Open [http://localhost:3000](http://localhost:3000) in your browser.

## Connecting Your Wallet

* On the USDC Token Sender app, click the `Connect Wallet` button.
* Select your wallet from the list of available options.
* Approve the connection in your wallet extension.

## Performing a USDC Transfer

* Ensure you have USDC tokens in your wallet. You can get testnet tokens from
  Circle's [faucet](https://faucet.circle.com/) if needed.
* Click on `Request testnet Aptos Tokens` from your Aptos Wallet to source gas
  tokens.
* In the app, enter the amount of USDC you want to send and the recipient's
  address.
* Click the `Send Tokens` button.
* Your wallet will prompt you to approve the transaction. Review the details and
  confirm.
* Wait for the transaction to be processed. The app will display the transaction
  status.

## Sample App UI

<Frame>
  <img />
</Frame>

## Successful Transaction

You can use the
[Aptos Explorer](https://explorer.aptoslabs.com/txn/0xb559c9a68d4cd4f3351c9898ed023ac3b9c72cfba7f655cb087050759b43f300?network=testnet)
to check the status of the transaction.

<Frame>
  <img />
</Frame>


# Quickstart: Set up and transfer USDC on Starknet
Source: https://developers.circle.com/stablecoins/quickstart-setup-transfer-usdc-starknet



This quickstart guide helps you write a standalone `index.js` script that checks
your USDC balance and sends a test transfer on the Starknet Sepolia. It's
designed for developers looking to quickly get hands-on with
[USDC](/stablecoins/what-is-usdc) on Starknet.

## Prerequisites

Before you begin, make sure you have:

* Installed [**Node.js v18+**](https://nodejs.org/) and `npm`, which comes with
  `Node.js`.
  * Created a free [**Alchemy account**](https://alchemy.com/starknet) to get an
    API key for Starknet RPC access.
* Created a Starknet Sepolia wallet:
  * [**Braavos wallet (Recommended)**](https://braavos.app/) - Best
    compatibility for programmatic transactions.

    Alternatives: [Argent X](https://www.argent.xyz/argent-x/) (Note:
    Guardian-protected accounts may require additional configuration).

  * [Request testnet STRK from the faucet](https://starknet-faucet.vercel.app/).

  * [Request testnet USDC from the faucet](https://faucet.circle.com/)

### USDC contract address

Use the following contract address for USDC on the Starknet Sepolia Testnet:

USDC contract:
[`0x0512feAc6339Ff7889822cb5aA2a86C848e9D392bB0E3E237C008674feeD8343`](https://sepolia.voyager.online/contract/0x053b40a647cedfca6ca84f542a0fe36736031905a9639a7f19a3c1e66bfd5080)

## Part 1: Set up your project

Follow these steps to install dependencies and set up your script environment.

### 1.1. Initialize a project

Create a new directory and initialize it with `npm`:

```bash theme={null}
mkdir usdc-starknet-script
cd usdc-starknet-script
npm init -y
npm pkg set type=module
```

### 1.2. Install required dependencies

Install `starknet` (version 8.x) and `dotenv`:

```bash theme={null}
npm install starknet@^8.9.0 dotenv
```

### 1.3. Create your `.env` file

In the project root, create a `.env` file and add the following values:

```text Text theme={null}
# Your Starknet account address (felt252 format with 0x prefix)
ACCOUNT_ADDRESS=0x<YOUR_ACCOUNT_ADDRESS>

# Your private key (felt252 format with 0x prefix)
PRIVATE_KEY=0x<YOUR_PRIVATE_KEY>

# The address you want to send USDC to (felt252 format with 0x prefix)
RECIPIENT_ADDRESS=0x<RECIPIENT_ADDRESS>
```

<Info>
  **Important:** On Starknet, you need both your account address and private key
  because Starknet uses [account
  abstraction](https://www.starknet.io/blog/account-abstraction). Your private
  key alone doesn't derive your account address.
</Info>

## Part 2: Build your script

Create a file named `index.js`. You'll build your script step-by-step in the
following sections.

### 2.1. Import libraries and define constants

In `index.js`, start by importing dependencies and setting up the chain and
token configuration:

```javascript theme={null}
import "dotenv/config";
import { Account, Contract, RpcProvider, uint256 } from "starknet";

const provider = new RpcProvider({
  nodeUrl:
    "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_10/YOUR_API_KEY",
});

const USDC_ADDRESS =
  "0x053b40A647CEDfca6cA84f542A0fe36736031905A9639a7f19A3C1e66bFd5080";
const USDC_DECIMALS = 6;

const USDC_ABI = [
  {
    name: "balance_of",
    type: "function",
    inputs: [
      {
        name: "account",
        type: "core::starknet::contract_address::ContractAddress",
      },
    ],
    outputs: [{ name: "balance", type: "core::integer::u256" }],
    state_mutability: "view",
  },
  {
    name: "transfer",
    type: "function",
    inputs: [
      {
        name: "recipient",
        type: "core::starknet::contract_address::ContractAddress",
      },
      { name: "amount", type: "core::integer::u256" },
    ],
    outputs: [{ name: "success", type: "core::bool" }],
    state_mutability: "external",
  },
];
```

<Info>
  Replace `YOUR_API_KEY` with your Alchemy API key from
  [alchemy.com/starknet](https://alchemy.com/starknet)
</Info>

<Accordion title="Learn more: Why use a minimal ABI?" icon="circle-info">
  This ABI includes only the two methods needed for this script:

  * `balanceOf(address)` to check the token balance.
  * `transfer(to, amount)` to send USDC.

  This makes the ABI compact and easier to understand. Using a minimal ABI:

  * Reduces complexity by excluding unrelated functions.
  * Speeds up onboarding for new developers.
  * Avoids unnecessary contract data that would be unused in this context.

  <Info>
    **Note:** Starknet uses Cairo, so function names follow snake\_case convention
    (for example, `balance_of` instead of `balanceOf`).
  </Info>
</Accordion>

### 2.2. Set up Starknet account and contract

Set up the Starknet account and contract instances:

```javascript theme={null}
const account = new Account({
  provider,
  address: process.env.ACCOUNT_ADDRESS,
  signer: process.env.PRIVATE_KEY,
});

const usdcContract = new Contract({
  abi: USDC_ABI,
  address: USDC_ADDRESS,
  providerOrAccount: account,
});
```

<Accordion title="Learn more: account abstraction on Starknet" icon="circle-info">
  Unlike Ethereum, Starknet uses **account abstraction** by default:

  * Every wallet is a smart contract (not an EOA).
  * You need both the account address AND private key.
  * The private key signs transactions, but the account contract validates them.

  This enables features like:

  * Multi-signature wallets
  * Social recovery
  * Custom transaction validation logic
  * Gasless transactions (meta-transactions)
</Accordion>

### 2.3. Check balance and send USDC

Now add the logic to check your balance and send tokens:

```javascript theme={null}
(async () => {
  try {
    const balanceResult = await usdcContract.balance_of(account.address);
    const balance = uint256.uint256ToBN(balanceResult.balance);
    const balanceFormatted = Number(balance) / 10 ** USDC_DECIMALS;

    console.log("Sender:", account.address);
    console.log("Recipient:", process.env.RECIPIENT_ADDRESS);
    console.log("USDC balance:", balanceFormatted.toFixed(2));

    const amount = 0.1;
    const amountU256 = uint256.bnToUint256(amount * 10 ** USDC_DECIMALS);

    const tx = await usdcContract.transfer(
      process.env.RECIPIENT_ADDRESS,
      amountU256,
    );

    await provider.waitForTransaction(tx.transaction_hash);

    console.log("Transfer successful!");
    console.log("Tx hash:", tx.transaction_hash);
    console.log(
      "Explorer:",
      `https://sepolia.voyager.online/tx/${tx.transaction_hash}`,
    );
  } catch (err) {
    console.error("Transfer failed:", err.message || err);
    process.exit(1);
  }
})();
```

## Part 3: Run your script

To run your script, use the following command:

```bash theme={null}
node index.js
```

### Sample output

If the script runs successfully, your terminal will print a transaction summary
like this:

```text Text theme={null}
Sender: 0x025c0197095dff110edc45fd171c498b167fbe1c803294d22483064b0207a465
Recipient: 0x043ccE75C31169455E07B19265024107B067700BB711DEeffecE32766d7bf5c7
USDC balance: 10.00
Transfer successful!
Tx hash: 0xabc123def456789...
Explorer: https://sepolia.voyager.online/tx/0xabc123def456789...
```

You can open the explorer link in your browser to view the transaction on
Voyager.

## Additional notes

* **Testnet only:** This guide runs on the Starknet Sepolia testnet. Tokens and
  transfers here are not real and hold no value.
* **Security best practices:** Always store sensitive data like private keys in
  environment variables. Never hardcode or commit `.env` files to version
  control. Add `.env` to your `.gitignore` file.
* **Gas fees:** Starknet requires STRK tokens for gas. Be sure to request
  testnet STRK from the faucet so your transactions can be processed.
* **Lightweight ABI:** The ABI used here is minimal. It includes only the
  functions necessary for balance checks and transfers, which keeps the script
  lean.
* **V3 transactions:** Starknet.js v8 uses V3 transactions by default, which
  include resource bounds for L1 gas, L2 gas, and L1 data gas.
* **Wallet compatibility:** Braavos wallet is recommended for programmatic
  transactions. Argent accounts with guardians may require additional
  configuration.


# Quickstart: Set up and transfer USDC on Sui
Source: https://developers.circle.com/stablecoins/quickstart-setup-transfer-usdc-sui



USDC provides the ability to transfer US dollars over public blockchains using
smart contracts. The smart contract allows users to send, receive, and store
dollars onchain with a wallet. Here's a quickstart guide for developers to build
a web app to perform their first USDC transfer on Sui.

## Prerequisites

Before you start building the sample app to perform a USDC transfer, make sure
you meet the following prerequisites:

* **[Node.js](https://nodejs.org/en)** and **[npm](https://www.npmjs.com/)**:
  Make sure that you have `Node.js` and `npm` installed on your machine. You can
  download and install `Node.js` from [nodejs.org](https://nodejs.org). `npm`
  comes with `Node.js`.
* **[Sui Wallet](https://chromewebstore.google.com/detail/sui-wallet/opcgpfmipidbgpenhmajoajpbobppdil)**:
  Install the Sui Wallet browser extension and set up your wallet. Make sure
  that your wallet is funded with:
  * Some SUI testnet tokens to cover transaction fees.
  * USDC tokens for the transfer.
    ([USDC Testnet Faucet](https://faucet.circle.com/))

## Contract Addresses

You will need the following contract addresses:

* Testnet -
  [0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC](https://suiscan.xyz/testnet/coin/0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC/txs)
* Mainnet -
  [0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC](https://suiscan.xyz/mainnet/coin/0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC/txs)

## Installation

Perform the following installation and setup steps:

1. **Project Setup**: Create a new project directory and initialize it with
   `npm`:

```shell Shell theme={null}
npx create-next-app@latest usdc-transfer-app
```

2. When prompted, choose the following options:
   * Use `TypeScript`: Yes
   * Use `ESLint`: Yes
   * Use `Tailwind CSS`: Yes
   * Use `src/` directory: Yes
   * Use `App Router`: Yes
   * Customize the default import alias: No

3. Navigate to the project directory:

```shell Shell theme={null}
cd usdc-transfer-app
```

4. Install additional dependencies:

```shell Shell theme={null}
npm install @mysten/dapp-kit @mysten/sui @mysten/wallet-kit @tanstack/react-query
```

## Import Code and Setup

5. The code provided will be updated in the `src/app/page.tsx` file. This
   section imports necessary libraries and sets up the network configuration.

```javascript TypeScript theme={null}
"use client";
import { useState, useEffect } from "react";
import {
  ConnectButton,
  useWalletKit,
  WalletKitProvider,
} from "@mysten/wallet-kit";
import { SuiClientProvider, useSuiClient } from "@mysten/dapp-kit";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { TransactionBlock } from "@mysten/sui.js/transactions";

// Define the network we're connecting to (testnet in this case)
const networks = {
  testnet: { url: "https://fullnode.testnet.sui.io:443" },
};

// Create a new QueryClient for managing and caching asynchronous queries
const queryClient = new QueryClient();
```

This component handles the main functionality of the application, including
wallet connection token definition, and token transfer.

**a. Define USDC testnet token contract**

```javascript TypeScript theme={null}
// Define the USDC token type on Sui testnet
// This is the unique identifier for the USDC token on Sui
const USDC_TYPE =
  "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC";
```

**b. State Management**

Define state variables to manage the connection status, amount, recipient
address, and transaction status.

```javascript TypeScript theme={null}
function HomeContent() {
  // Use the wallet kit to get the current account and transaction signing function
  const { currentAccount, signAndExecuteTransactionBlock } = useWalletKit();
  // Get the Sui client for interacting with the Sui network
  const suiClient = useSuiClient();
  const [connected, setConnected] = useState(false);
  const [amount, setAmount] = useState('');
  const [recipientAddress, setRecipientAddress] = useState('');
  const [txStatus, setTxStatus] = useState('');
```

**c. Effect Hook for Connection Status**

Use `useEffect()` to update the connection status whenever the `currentAccount`
changes.

```javascript TypeScript theme={null}
// Update the connection status when the current account changes
useEffect(() => {
  setConnected(!!currentAccount);
}, [currentAccount]);
```

**d. Token Sending Logic**

Define the function to handle sending tokens, including validation and
transaction execution.

```javascript TypeScript theme={null}
const handleSendTokens = async () => {
  if (!currentAccount || !amount || !recipientAddress) {
    setTxStatus("Please connect wallet and fill all fields");
    return;
  }
  try {
    // Fetch USDC coins owned by the current account
    // This uses the SuiClient to get coins of the specified type owned by the current address
    const { data: coins } = await suiClient.getCoins({
      owner: currentAccount.address,
      coinType: USDC_TYPE,
    });
    if (coins.length === 0) {
      setTxStatus("No USDC coins found in your wallet");
      return;
    }
    // Create a new transaction block
    // TransactionBlock is used to construct and execute transactions on Sui
    const tx = new TransactionBlock();
    // Split the coin and get a new coin with the specified amount
    // This creates a new coin object with the desired amount to be transferred
    const [coin] = tx.splitCoins(coins[0].coinObjectId, [
      tx.pure(BigInt(amount)),
    ]);
    // Transfer the split coin to the recipient
    // This adds a transfer operation to the transaction block
    tx.transferObjects([coin], tx.pure(recipientAddress));
    // Sign and execute the transaction block
    // This sends the transaction to the network and waits for it to be executed
    const result = await signAndExecuteTransactionBlock({
      transactionBlock: tx,
    });
    console.log("Transaction result:", result);
    setTxStatus(`Transaction successful. Digest: ${result.digest}`);
  } catch (error) {
    console.error("Error sending tokens:", error);
    setTxStatus(
      `Error: ${error instanceof Error ? error.message : "Unknown error"}`,
    );
  }
};
```

**e. Rendering the UI**

Render the main UI components, including input fields for amount and recipient
address, and a button to send tokens.

```javascript TypeScript theme={null}
   return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <div className="z-10 w-full max-w-5xl items-center justify-between font-mono text-sm">
        <h1 className="text-4xl font-bold mb-8">Sui USDC Sender (Testnet)</h1>
        <ConnectButton />
        {connected && currentAccount && (
          <p className="mt-4">Connected: {currentAccount.address}</p>
        )}
        <div className="mt-8">
          <input
            type="text"
            placeholder="Amount (in USDC)"
            value={amount}
            onChange={(e) => setAmount(e.target.value)}
            className="p-2 border rounded mr-2 text-black"
          />
          <input
            type="text"
            placeholder="Recipient Address"
            value={recipientAddress}
            onChange={(e) => setRecipientAddress(e.target.value)}
            className="p-2 border rounded mr-2 text-black"
          />
          <button
            onClick={handleSendTokens}
            disabled={!connected}
            className={`p-2 rounded ${
              connected && amount && recipientAddress
                ? 'bg-blue-200 text-black hover:bg-blue-300'
                : 'bg-gray-300 text-gray-500'
            } transition-colors duration-200`}
          >
            Send USDC
          </button>
        </div>
        {txStatus && <p className="mt-4">{txStatus}</p>}
      </div>
    </main>
  );
}
```

## Main Application Component

This component wraps the `HomeContent()` function with the necessary providers
for state management and wallet connection.

```javascript TypeScript theme={null}
export default function Home() {
  return (
    // Wrap the app with necessary providers
    // QueryClientProvider: Provides React Query context for managing async queries
    // SuiClientProvider: Provides the Sui client context for interacting with the Sui network
    // WalletKitProvider: Provides wallet connection and interaction capabilities
    <QueryClientProvider client={queryClient}>
      <SuiClientProvider networks={networks} defaultNetwork="testnet">
        <WalletKitProvider>
          <HomeContent />
        </WalletKitProvider>
      </SuiClientProvider>
    </QueryClientProvider>
  );
}
```

6. Start the development server:

```shell Shell theme={null}
npm run dev
```

7. Open [http://localhost:3000](http://localhost:3000) in your browser.

## Connecting Your Wallet

* On the USDC Token Sender app, click the “Connect Wallet” button.
* Select your wallet from the list of available options.
* Approve the connection in your wallet extension.

## Performing a USDC Transfer

* Ensure you have USDC tokens in your wallet. You can get testnet tokens from
  our [faucet](https://faucet.circle.com/) if needed.
* Click the `Request testnet SUI Tokens` from your Sui Wallet to source gas
  tokens.
* In the app, enter the amount of USDC you want to send and the recipient's
  address.
* Click the `Send Tokens` button.
* Your wallet will prompt you to approve the transaction. Review the details and
  confirm.
* Wait for the transaction to be processed. The app will display the transaction
  to status.

## Sample App UI

<Frame>
  <img />
</Frame>

## Successful Transaction

You can use the [Sui Explorer](https://suiscan.xyz/) to check the status of the
transaction.

<Frame>
  <img />
</Frame>


# Quickstart: Set up a USDC Trustline on Stellar
Source: https://developers.circle.com/stablecoins/quickstart-setup-usdc-trustline-stellar

Fund a wallet on Stellar Testnet and open a USDC trustline so the account can hold USDC.

On Stellar, an account must add a USDC trustline before it can hold USDC. This
is an explicit opt-in that authorizes the account to hold a specific asset. For
more details, see Stellar's
[trustline documentation](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#trustlines).

In this quickstart, you create a TypeScript script that uses
[`@stellar/stellar-sdk`](https://github.com/stellar/js-stellar-sdk) to:

* Create and fund a Stellar Testnet wallet
* Establish a USDC trustline so the wallet can receive USDC

<Note>
  This quickstart funds the account with Friendbot's HTTP API from your script.
  You can use [Stellar Lab](https://lab.stellar.org/account/fund) to fund on
  Stellar Testnet in the browser.
</Note>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/) or later
* Set up a terminal and code editor for running commands and editing files

## Step 1. Set up the project

This step shows you how to prepare your project and environment.

### 1.1. Create the project and install dependencies

Create a new directory and install the required dependencies:

```bash Shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir xlm-usdc-trustline
cd xlm-usdc-trustline
npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="npx tsx main.ts"

# Install runtime dependencies
npm install @stellar/stellar-sdk typescript

# Install dev dependencies
npm install --save-dev @types/node
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

## Step 2: Create the trustline script

Add `main.ts` at the project root. The script generates a keypair, requests test
XLM from Friendbot (Stellar's faucet), submits a `changeTrust` for testnet USDC,
and posts the transaction to
[Horizon](https://developers.stellar.org/docs/data/apis/horizon) (Stellar's HTTP
API for submitting transactions).

```typescript main.ts theme={null}
import {
  Horizon,
  Keypair,
  TransactionBuilder,
  Operation,
  Asset,
  Networks,
  BASE_FEE,
} from "@stellar/stellar-sdk";

const HORIZON_TESTNET_URL = "https://horizon-testnet.stellar.org";
const FRIENDBOT_URL = "https://friendbot.stellar.org";
const USDC_ISSUER = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";
const USDC_CODE = "USDC";
const TX_EXPLORER_BASE = "https://stellar.expert/explorer/testnet/tx";

async function main() {
  const server = new Horizon.Server(HORIZON_TESTNET_URL);

  console.log("Creating and funding a user wallet...");
  const keypair = Keypair.random();
  const publicKey = keypair.publicKey();
  const secretKey = keypair.secret();

  const friendbotResponse = await fetch(`${FRIENDBOT_URL}?addr=${publicKey}`);
  if (!friendbotResponse.ok) {
    throw new Error(
      `Friendbot funding failed: ${friendbotResponse.status} ${friendbotResponse.statusText}`,
    );
  }

  console.log("======= User wallet details =======");
  console.log("Address:", publicKey);
  console.log("Secret key:", secretKey);
  console.log("NOTE: DO NOT SHARE THE SECRET KEY WITH ANYONE!");
  console.log("===================================");
  console.log("");

  console.log("Creating a trustline for USDC...");
  const account = await server.loadAccount(publicKey);
  const usdcAsset = new Asset(USDC_CODE, USDC_ISSUER);

  const transaction = new TransactionBuilder(account, {
    fee: BASE_FEE,
    networkPassphrase: Networks.TESTNET,
  })
    .addOperation(Operation.changeTrust({ asset: usdcAsset }))
    .setTimeout(30)
    .build();

  transaction.sign(keypair);
  const response = await server.submitTransaction(transaction);

  if (!response.successful) {
    throw new Error(`Transaction failed: ${JSON.stringify(response)}`);
  }

  console.log(`Transaction succeeded: ${TX_EXPLORER_BASE}/${response.hash}`);

  console.log("Trustline established. This account can now receive USDC.");
}

main().catch(console.error);
```

<Info>
  Common errors you might encounter:

  * **`Friendbot funding failed: 400`** — The Friendbot rate limit was exceeded.
    Wait a few seconds and try again.
  * **`Transaction failed`** — The account may not be funded, or the USDC issuer
    address may be incorrect. Verify the `USDC_ISSUER` constant matches the
    [Stellar Testnet USDC issuer](/stablecoins/usdc-contract-addresses).
</Info>

## Step 3: Run the script

From the project directory, run:

```bash Shell theme={null}
npm run start
```

Your output should look similar to the following (addresses and hashes will
differ):

```bash Shell theme={null}
Creating and funding a user wallet...
======= User wallet details =======
Address: GCDE7JAXEY6Z2L6H4H5Z6Y7X8Y9Z0A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
Secret key: SABCDEFGHIJKLMNOPQRSTUVWXYZ234567890ABCDEFGHIJKLMNOPQRSTUVW
NOTE: DO NOT SHARE THE SECRET KEY WITH ANYONE!
===================================

Creating a trustline for USDC...
Transaction succeeded: https://stellar.expert/explorer/testnet/tx/abc123def456...
Trustline established. This account can now receive USDC.
```

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>


# Quickstart: Set up a USDC trustline on XRPL
Source: https://developers.circle.com/stablecoins/quickstart-setup-usdc-trustline-xrpl



This guide shows you how to set up a trustline for USDC on the XRPL Testnet
using TypeScript. You'll use the XRPL JavaScript SDK to:

* Create and fund a wallet
* Establish a trustline with the USDC issuer
* Prepare the wallet to receive USDC

## Prerequisites

Before you begin, ensure you have the following:

* [Node.js 16 or later](https://nodejs.org/)
* A terminal or code editor

## Part 1: Set up your project

Perform the following steps to set up your project.

### 1.1. Create a project directory

Run the following commands to create and initialize your project:

```shell Shell theme={null}
mkdir xrpl-usdc-trustline
cd xrpl-usdc-trustline
npm init -y
```

### 1.2. Install dependencies

Run the following command to install the required libraries:

```shell Shell theme={null}
npm i xrpl typescript ts-node
```

## Part 2: Configure your project

Perform the following steps to configure your project.

### 2.1. Update the `package.json` file

Open your `package.json` file and make the following updates:

* Remove the `"type": "commonjs"` line if it was automatically added.
* Add or update the `start` script to use `ts-node` to run your `main.ts` file.

Your updated `package.json` should look similar to the following:

```json package.json theme={null}
{
  "name": "xrpl-usdc-trustline",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "ts-node main.ts"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "ts-node": "^10.9.2",
    "typescript": "^5.8.3",
    "xrpl": "^4.2.5"
  }
}
```

### 2.2. Add a `tsconfig.json` file

Create a `tsconfig.json` file with the following configuration:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./"
  },
  "include": ["*.ts"],
  "exclude": ["node_modules"]
}
```

## Part 3: Write your app code

Create a `main.ts` file and paste the following code:

```ts theme={null}
import {
  Client,
  IssuedCurrencyAmount,
  TransactionMetadata,
  TrustSetFlags,
  Wallet,
} from "xrpl";

const USDC: IssuedCurrencyAmount = {
  currency: "5553444300000000000000000000000000000000",
  issuer: "rHuGNhqTG32mfmAvWA8hUyWRLV3tCSwKQt",
  value: "1000000000",
};

async function main() {
  const client = new Client("wss://s.altnet.rippletest.net:51233");
  await client.connect();

  try {
    // Creating and funding a user wallet
    console.log("Creating and funding a user wallet...");
    const userWallet = Wallet.generate();
    await client.fundWallet(userWallet);

    console.log("======= User wallet details =======");
    console.log("Address:", userWallet.address);
    console.log("Seed:", userWallet.seed);
    console.log("NOTE: DO NOT SHARE THE SEED WITH ANYONE!");
    console.log("===================================");
    console.log("");

    // Creating a trustline for USDC
    console.log("Creating a trustline for USDC...");
    const response = await client.submitAndWait(
      {
        TransactionType: "TrustSet",
        Account: userWallet.address,
        LimitAmount: USDC,
        Flags: TrustSetFlags.tfSetNoRipple,
      },
      { autofill: true, wallet: userWallet },
    );

    if (
      response.result.validated &&
      (response.result.meta as TransactionMetadata).TransactionResult !==
        "tesSUCCESS"
    ) {
      throw new Error(`Transaction failed: ${JSON.stringify(response)}`);
    }

    console.log(
      `Transaction succeeded: https://testnet.xrpl.org/transactions/${response.result.hash}`,
    );

    // Receiving USDC
    console.log("Receiving USDC...");
  } finally {
    await client.disconnect();
  }
}

main().catch(console.error);
```

## Part 4: Run your application

Run the following from your project folder:

```shell Shell theme={null}
npm start
```

After you run the script, the terminal should display your wallet's public
address, the wallet seed, and a transaction link that confirms the successful
creation of the trustline. Your wallet is now ready to receive USDC on the XRPL
Testnet.


# Quickstart: Transfer USDC on Solana
Source: https://developers.circle.com/stablecoins/quickstart-transfer-10-usdc-on-solana

Transfer USDC between wallets on Solana Devnet using a Node.js script

This guide demonstrates how to transfer USDC between two wallets on Solana
Devnet using a Node.js script. You use the
[Solana Kit](https://github.com/anza-xyz/kit) library to interact with the
Solana blockchain and perform SPL token transfers.

<Note>
  All transactions in this guide take place on the Solana Devnet testnet. No real
  funds are transferred. You can adapt this code for mainnet transactions by
  changing the RPC endpoint and using mainnet contract addresses.
</Note>

## Prerequisites

Before you start building the sample app to perform a USDC transfer, ensure you
have:

* **Node.js** and **npm** installed on your development machine. You can
  [download and install Node.js directly](https://nodejs.org), or use a version
  manager like [nvm](https://github.com/nvm-sh/nvm). The npm binary comes with
  Node.js.
* Created two Solana wallets: a sender wallet (with the private key available)
  and a receiver wallet (you only need the public address).
* Funded your sender wallet with the following testnet tokens:
  * Solana Devnet SOL (native token) from a
    [public faucet](https://faucet.solana.com/).
  * Solana Devnet USDC from the [Circle Faucet](https://faucet.circle.com).

## Part 1: Project setup

Set up your project environment and install the required dependencies.

### 1.1. Create a new project

Create a new directory and initialize a new Node.js project with default
settings:

```shell Shell theme={null}
mkdir solana-usdc-transfer
cd solana-usdc-transfer
npm init -y
npm pkg set type=module
```

### 1.2. Install dependencies

Install the required dependencies for Solana interactions:

```shell Shell theme={null}
npm install @solana/kit @solana-program/token ws dotenv
```

### 1.3. Configure environment variables

Create a `.env` file in your project directory and add your wallet private key
and the receiver address:

```shell Shell theme={null}
echo "SOLANA_PRIVATE_KEY=[your-solana-private-key-array]" > .env
echo "RECEIVER_ADDRESS=your-receiver-wallet-address" >> .env
```

The `SOLANA_PRIVATE_KEY` should be a JSON array of bytes representing your
private key. You can export this from most Solana wallets.

<Accordion title="Converting Base58 private key to JSON array">
  Some wallets export Solana private keys as Base58 encoded strings. If you have a
  Base58 encoded private key, you can convert it to a JSON array with the
  following Node.js script:

  ```javascript JavaScript theme={null}
  const fs = require("fs");
  const bs58 = require("bs58");
  const privateKeyBase58 = "YOUR_BASE58_PRIVATE_KEY";

  try {
    // Decode the Base58 string to a Uint8Array
    const privateKeyBytes = bs58.decode(privateKeyBase58);

    // The result is a Uint8Array. Convert it to a JSON array string.
    const privateKeyJsonString = JSON.stringify(Array.from(privateKeyBytes));

    console.log("JSON Array:", privateKeyJsonString);
  } catch (error) {
    console.error("Error converting key. Check if the Base58 key is valid.");
  }
  ```
</Accordion>

<Warning>
  This is strictly for testing purposes. **Never share your private keys** or
  commit them to version control.
</Warning>

## Part 2: Configure the script

Define the configuration constants for interacting with Solana Devnet.

### 2.1. Define configuration constants

The script predefines the RPC endpoints, USDC mint address, and transfer
parameters:

```javascript JavaScript theme={null}
import {
  address,
  createKeyPairSignerFromBytes,
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  createTransactionMessage,
  getAddressEncoder,
  getProgramDerivedAddress,
  getSignatureFromTransaction,
  pipe,
  sendAndConfirmTransactionFactory,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
} from "@solana/kit";
import {
  TOKEN_PROGRAM_ADDRESS,
  getTransferInstruction,
  findAssociatedTokenPda,
} from "@solana-program/token";
import dotenv from "dotenv";

dotenv.config();

// Solana Devnet configuration
const SOLANA_RPC = "https://api.devnet.solana.com";
const SOLANA_WS = "wss://api.devnet.solana.com";
const rpc = createSolanaRpc(SOLANA_RPC);
const rpcSubscriptions = createSolanaRpcSubscriptions(SOLANA_WS);

// Parse Solana keypair from environment variable
const solanaPrivateKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY);
const senderKeypair = await createKeyPairSignerFromBytes(
  Uint8Array.from(solanaPrivateKey),
);

// USDC Mint Address (Devnet)
const USDC_MINT = address("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");

// Transfer parameters
const RECEIVER_ADDRESS = address(process.env.RECEIVER_ADDRESS);
const AMOUNT = 1_000_000n; // 1 USDC (6 decimals)
```

<Note>
  USDC uses 6 decimal places. To transfer 1 USDC, you specify `1_000_000` (1 \*
  10<sup>6</sup>) as the amount.
</Note>

## Part 3: Implement the transfer logic

The following sections outline the core transfer logic for sending USDC on
Solana.

### 3.1. Get token accounts

Derive the Associated Token Account (ATA) addresses for both the sender and
receiver. These accounts are program-derived addresses that hold SPL tokens for
a specific wallet:

```javascript JavaScript theme={null}
async function getTokenAccounts() {
  // Derive sender's USDC token account
  const [senderTokenAccount] = await findAssociatedTokenPda({
    mint: USDC_MINT,
    owner: senderKeypair.address,
    tokenProgram: TOKEN_PROGRAM_ADDRESS,
  });

  // Derive receiver's USDC token account
  const [receiverTokenAccount] = await findAssociatedTokenPda({
    mint: USDC_MINT,
    owner: RECEIVER_ADDRESS,
    tokenProgram: TOKEN_PROGRAM_ADDRESS,
  });

  return { senderTokenAccount, receiverTokenAccount };
}
```

### 3.2. Transfer USDC

Build and send the transfer transaction using the SPL Token program's transfer
instruction:

```javascript JavaScript theme={null}
async function transferUSDC() {
  console.log("Transferring USDC on Solana Devnet...");
  console.log(`From: ${senderKeypair.address}`);
  console.log(`To: ${RECEIVER_ADDRESS}`);
  console.log(`Amount: ${Number(AMOUNT) / 1_000_000} USDC`);

  const { senderTokenAccount, receiverTokenAccount } = await getTokenAccounts();

  // Create the transfer instruction
  const transferInstruction = getTransferInstruction({
    source: senderTokenAccount,
    destination: receiverTokenAccount,
    authority: senderKeypair,
    amount: AMOUNT,
  });

  // Get the latest blockhash for transaction lifetime
  const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

  // Build the transaction message
  const transactionMessage = pipe(
    createTransactionMessage({ version: 0 }),
    (tx) => setTransactionMessageFeePayerSigner(senderKeypair, tx),
    (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
    (tx) => appendTransactionMessageInstruction(transferInstruction, tx),
  );

  // Sign and send the transaction
  const signedTransaction =
    await signTransactionMessageWithSigners(transactionMessage);

  const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
    rpc,
    rpcSubscriptions,
  });

  await sendAndConfirmTransaction(signedTransaction, {
    commitment: "confirmed",
  });

  const signature = getSignatureFromTransaction(signedTransaction);
  console.log(`\nTransaction successful!`);
  console.log(`Signature: ${signature}`);
  console.log(
    `View on explorer: https://explorer.solana.com/tx/${signature}?cluster=devnet`,
  );

  return signature;
}
```

## Part 4: Complete script

Create a `transfer.js` file in your project directory and populate it with the
complete code below.

```javascript transfer.js expandable theme={null}
import {
  address,
  createKeyPairSignerFromBytes,
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  createTransactionMessage,
  getSignatureFromTransaction,
  pipe,
  sendAndConfirmTransactionFactory,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
} from "@solana/kit";
import {
  TOKEN_PROGRAM_ADDRESS,
  getTransferInstruction,
  findAssociatedTokenPda,
} from "@solana-program/token";
import dotenv from "dotenv";

dotenv.config();

// Solana Devnet configuration
const SOLANA_RPC = "https://api.devnet.solana.com";
const SOLANA_WS = "wss://api.devnet.solana.com";
const rpc = createSolanaRpc(SOLANA_RPC);
const rpcSubscriptions = createSolanaRpcSubscriptions(SOLANA_WS);

// Parse Solana keypair from environment variable
const solanaPrivateKey = JSON.parse(process.env.SOLANA_PRIVATE_KEY);
const senderKeypair = await createKeyPairSignerFromBytes(
  Uint8Array.from(solanaPrivateKey),
);

// USDC Mint Address (Devnet)
const USDC_MINT = address("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");

// Transfer parameters
const RECEIVER_ADDRESS = address(process.env.RECEIVER_ADDRESS);
const AMOUNT = 1_000_000n; // 1 USDC (6 decimals)

async function getTokenAccounts() {
  // Derive sender's USDC token account
  const [senderTokenAccount] = await findAssociatedTokenPda({
    mint: USDC_MINT,
    owner: senderKeypair.address,
    tokenProgram: TOKEN_PROGRAM_ADDRESS,
  });

  // Derive receiver's USDC token account
  const [receiverTokenAccount] = await findAssociatedTokenPda({
    mint: USDC_MINT,
    owner: RECEIVER_ADDRESS,
    tokenProgram: TOKEN_PROGRAM_ADDRESS,
  });

  return { senderTokenAccount, receiverTokenAccount };
}

async function transferUSDC() {
  console.log("Transferring USDC on Solana Devnet...");
  console.log(`From: ${senderKeypair.address}`);
  console.log(`To: ${RECEIVER_ADDRESS}`);
  console.log(`Amount: ${Number(AMOUNT) / 1_000_000} USDC`);

  const { senderTokenAccount, receiverTokenAccount } = await getTokenAccounts();

  // Create the transfer instruction
  const transferInstruction = getTransferInstruction({
    source: senderTokenAccount,
    destination: receiverTokenAccount,
    authority: senderKeypair,
    amount: AMOUNT,
  });

  // Get the latest blockhash for transaction lifetime
  const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

  // Build the transaction message
  const transactionMessage = pipe(
    createTransactionMessage({ version: 0 }),
    (tx) => setTransactionMessageFeePayerSigner(senderKeypair, tx),
    (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
    (tx) => appendTransactionMessageInstruction(transferInstruction, tx),
  );

  // Sign and send the transaction
  const signedTransaction =
    await signTransactionMessageWithSigners(transactionMessage);

  const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
    rpc,
    rpcSubscriptions,
  });

  await sendAndConfirmTransaction(signedTransaction, {
    commitment: "confirmed",
  });

  const signature = getSignatureFromTransaction(signedTransaction);
  console.log(`\nTransaction successful!`);
  console.log(`Signature: ${signature}`);
  console.log(
    `View on explorer: https://explorer.solana.com/tx/${signature}?cluster=devnet`,
  );

  return signature;
}

transferUSDC().catch(console.error);
```

## Part 5: Test the script

Run the following command to execute the script:

```shell Shell theme={null}
node transfer.js
```

Once the script runs and the transfer is finalized, a confirmation message is
logged in the console:

```text theme={null}
Transferring USDC on Solana Devnet...
From: YourSenderAddress
To: YourReceiverAddress
Amount: 1 USDC

Transaction successful!
Signature: 5abc123...
View on explorer: https://explorer.solana.com/tx/5abc123...?cluster=devnet
```

You can verify the transaction by visiting the Solana Explorer link in the
output, or by checking the USDC balance in the receiver's wallet.

<Note>
  If the receiver's wallet has never held USDC before, you may need to create
  their Associated Token Account first. The transfer will fail if the destination
  token account does not exist. You can use the
  `getOrCreateAssociatedTokenAccount` pattern to handle this automatically.
</Note>


# Quickstart: Transfer USDC on Stellar
Source: https://developers.circle.com/stablecoins/quickstart-transfer-usdc-stellar

Send USDC between accounts on Stellar Testnet using the Stellar SDK.

USDC on Stellar is a native asset issued by Circle. Transferring USDC between
Stellar accounts uses a standard payment operation, submitted through
[Horizon](https://developers.stellar.org/docs/data/apis/horizon), Stellar's HTTP
API for submitting transactions. To transfer USDC crosschain between Stellar and
other blockchains, see
[Transfer USDC to and from Stellar](/cctp/quickstarts/transfer-usdc-stellar-arc).

The [`@stellar/stellar-sdk`](https://github.com/stellar/js-stellar-sdk) script
you build in this guide will:

* Create and fund a recipient Stellar Testnet wallet
* Establish a USDC trustline on the recipient account
* Transfer USDC from your existing sender wallet to the recipient

<Note>
  Before a Stellar account can receive USDC, it must establish a trustline for the
  asset. See
  [Set up a USDC trustline on Stellar](/stablecoins/quickstart-setup-usdc-trustline-stellar)
  for more detail. This quickstart handles trustline setup automatically as part
  of the script.
</Note>

## Prerequisites

Before you begin, ensure that you have:

* Installed [Node.js v22+](https://nodejs.org/)
* Set up a terminal and code editor for running commands and editing files
* Created a Stellar Testnet wallet with the secret key (`S...`) available
  * Funded with testnet XLM (for transaction fees) from
    [Stellar Friendbot](https://lab.stellar.org/account/fund)
  * Funded with testnet USDC from the [Circle Faucet](https://faucet.circle.com)

## Contract addresses

You need the following Stellar Testnet USDC issuer address:

* Testnet:
  [`GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5`](https://stellar.expert/explorer/testnet/asset/USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5)

## Step 1: Set up the project

### 1.1. Create the project and install dependencies

Create a new directory and install the required dependencies:

```bash Shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir stellar-usdc-transfer
cd stellar-usdc-transfer
npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="npx tsx --env-file=.env main.ts"

# Install runtime dependencies
npm install @stellar/stellar-sdk

# Install dev dependencies
npm install --save-dev typescript @types/node
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.3. Configure environment variables

Create a `.env` file in your project directory and add your sender's secret key:

```text .env theme={null}
STELLAR_SECRET_KEY=YOUR_SENDER_SECRET_KEY
```

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>

## Step 2: Create the transfer script

Add `main.ts` at the project root. The script:

1. Loads your existing sender wallet from the environment variable
2. Creates and funds a new recipient wallet using Friendbot
3. Establishes a USDC trustline on the recipient account
4. Submits a USDC payment from the sender to the recipient

```typescript main.ts theme={null}
import {
  Asset,
  BASE_FEE,
  Horizon,
  Keypair,
  Networks,
  Operation,
  TransactionBuilder,
} from "@stellar/stellar-sdk";

const HORIZON_URL = "https://horizon-testnet.stellar.org";
const FRIENDBOT_URL = "https://friendbot.stellar.org";
const USDC_ISSUER = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";
const USDC_CODE = "USDC";
const TRANSFER_AMOUNT = "10"; // 10 USDC
const TX_EXPLORER_BASE = "https://stellar.expert/explorer/testnet/tx";

const server = new Horizon.Server(HORIZON_URL);
const usdc = new Asset(USDC_CODE, USDC_ISSUER);

async function fundWithFriendbot(publicKey: string): Promise<void> {
  const response = await fetch(`${FRIENDBOT_URL}?addr=${publicKey}`);
  if (!response.ok) {
    throw new Error(
      `Friendbot funding failed: ${response.status} ${response.statusText}`,
    );
  }
}

async function establishTrustline(keypair: Keypair): Promise<void> {
  const account = await server.loadAccount(keypair.publicKey());
  const tx = new TransactionBuilder(account, {
    fee: BASE_FEE,
    networkPassphrase: Networks.TESTNET,
  })
    .addOperation(Operation.changeTrust({ asset: usdc }))
    .setTimeout(30)
    .build();

  tx.sign(keypair);
  const result = await server.submitTransaction(tx);
  if (!result.successful) {
    throw new Error(`Trustline transaction failed: ${JSON.stringify(result)}`);
  }
  console.log(`Trustline established: ${TX_EXPLORER_BASE}/${result.hash}`);
}

async function transferUsdc(
  sender: Keypair,
  recipientPublicKey: string,
): Promise<void> {
  const account = await server.loadAccount(sender.publicKey());
  const tx = new TransactionBuilder(account, {
    fee: BASE_FEE,
    networkPassphrase: Networks.TESTNET,
  })
    .addOperation(
      Operation.payment({
        destination: recipientPublicKey,
        asset: usdc,
        amount: TRANSFER_AMOUNT,
      }),
    )
    .setTimeout(30)
    .build();

  tx.sign(sender);
  const result = await server.submitTransaction(tx);
  if (!result.successful) {
    throw new Error(`Payment transaction failed: ${JSON.stringify(result)}`);
  }
  console.log(`Transfer successful: ${TX_EXPLORER_BASE}/${result.hash}`);
}

async function main() {
  // Load the sender wallet from the environment variable
  const sender = Keypair.fromSecret(process.env.STELLAR_SECRET_KEY as string);
  console.log("Sender address:", sender.publicKey());

  // Create and fund a new recipient wallet via Friendbot
  console.log("\nCreating recipient wallet...");
  const recipient = Keypair.random();
  console.log("Recipient address:", recipient.publicKey());

  console.log("Funding recipient with testnet XLM...");
  await fundWithFriendbot(recipient.publicKey());
  console.log("Recipient funded with XLM.");

  // Establish a USDC trustline on the recipient account
  console.log("\nEstablishing USDC trustline on recipient account...");
  await establishTrustline(recipient);

  // Transfer USDC from sender to recipient
  console.log(`\nTransferring ${TRANSFER_AMOUNT} USDC to recipient...`);
  await transferUsdc(sender, recipient.publicKey());

  // Confirm recipient balance
  const recipientAccount = await server.loadAccount(recipient.publicKey());
  const usdcBalance = recipientAccount.balances.find(
    (b) =>
      b.asset_type === "credit_alphanum4" &&
      b.asset_code === USDC_CODE &&
      b.asset_issuer === USDC_ISSUER,
  );
  console.log(`\nRecipient USDC balance: ${usdcBalance?.balance ?? "0"} USDC`);
}

main().catch(console.error);
```

## Step 3: Run the script

From the project directory, run:

```bash Shell theme={null}
npm run start
```

Your output should look similar to the following (addresses and hashes will
differ):

```bash Shell theme={null}
Sender address: GAXYZ...

Creating recipient wallet...
Recipient address: GDEFG...
Funding recipient with testnet XLM...
Recipient funded with XLM.

Establishing USDC trustline on recipient account...
Trustline established: https://stellar.expert/explorer/testnet/tx/abc123...

Transferring 10 USDC to recipient...
Transfer successful: https://stellar.expert/explorer/testnet/tx/def456...

Recipient USDC balance: 10.0000000 USDC
```

<Info>
  Common errors you might encounter:

  * **`Friendbot funding failed: 400`** — The Friendbot rate limit was exceeded.
    Wait a few seconds and try again.
  * **`op_no_trust`** — The recipient account does not have a USDC trustline. The
    script establishes one automatically, but if you're adapting this example for
    your own recipient address, ensure the trustline exists first. See
    [Set up a USDC trustline on Stellar](/stablecoins/quickstart-setup-usdc-trustline-stellar).
  * **`op_underfunded`** — The sender does not have enough USDC. Ensure your
    sender wallet is funded with testnet USDC from the
    [Circle Faucet](https://faucet.circle.com) before running the script.
</Info>

For more detail on Stellar-specific USDC behavior in CCTP, including address
encoding and decimal precision, see [CCTP on Stellar](/cctp/references/stellar).


# Quickstart: Transfer EURC on EVM chains
Source: https://developers.circle.com/stablecoins/quickstarts/transfer-eurc-evm

Transfer EURC between wallets on EVM chains using a Node.js script

This guide walks you through transferring EURC on EVM testnets using Viem and
Node.js. You'll build a simple script that checks your balance and sends test
transfers.

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)
* Prepared a testnet wallet on the selected chain funded with:
  * Testnet EURC for the transfer
  * Testnet native tokens for gas fees

<Note>
  You can get testnet EURC from [Circle's faucet](https://faucet.circle.com/).
</Note>

## Step 1. Set up the project

This step shows you how to prepare your project and environment.

### 1.1. Create the project and install dependencies

Create a new directory and install the required dependencies:

```bash Shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir transfer-eurc-evm
cd transfer-eurc-evm
npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="npx tsx --env-file=.env index.ts"

# Install runtime dependencies
npm install viem tsx

# Install dev dependencies
npm install --save-dev typescript @types/node
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.3. Set environment variables

Create a `.env` file in the project directory and add your wallet private key,
replacing `{YOUR_PRIVATE_KEY}` with the private key from your EVM wallet and
`{YOUR_RECIPIENT_ADDRESS}` with the address of the recipient.

```text theme={null}
PRIVATE_KEY={YOUR_PRIVATE_KEY}
RECIPIENT_ADDRESS={YOUR_RECIPIENT_ADDRESS}
```

* `PRIVATE_KEY` is the private key for the EVM wallet sending the transfer.
* `RECIPIENT_ADDRESS` is the EVM wallet address that will receive the EURC.

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

The `npm run start` command loads variables from `.env` using Node.js native
env-file support.

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>

## Step 2. Create the transfer script

In this step, you'll build a script in TypeScript that transfers EURC on the
selected EVM testnet. The script includes a single list of supported chains,
prompts you to choose one at runtime, and then runs the same transfer flow for
that chain.

### 2.1. Create the script file

```shell theme={null}
touch index.ts
```

### 2.2. Add the script

In `index.ts`, add the following script. It keeps the per-chain data in one
`CHAIN_CONFIGS` list so supporting another EVM testnet only requires one new
entry.

```typescript TypeScript expandable theme={null}
import { createInterface } from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";
import {
  createPublicClient,
  createWalletClient,
  formatUnits,
  http,
  isAddress,
  isHex,
  parseUnits,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import {
  arcTestnet,
  avalancheFuji,
  baseSepolia,
  sepolia,
  worldchainSepolia,
} from "viem/chains";

const EURC_DECIMALS = 6;
const EURC_ABI = [
  {
    name: "balanceOf",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "account", type: "address" }],
    outputs: [{ name: "", type: "uint256" }],
  },
  {
    name: "transfer",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [
      { name: "to", type: "address" },
      { name: "amount", type: "uint256" },
    ],
    outputs: [{ name: "", type: "bool" }],
  },
] as const;

// Store each supported chain in one place so the transfer flow stays shared.
const CHAIN_CONFIGS = [
  {
    id: "arc-testnet",
    name: "Arc Testnet",
    chain: arcTestnet,
    tokenAddress: "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
  },
  {
    id: "avalanche-fuji",
    name: "Avalanche Fuji",
    chain: avalancheFuji,
    tokenAddress: "0x5E44db7996c682E92a960b65AC713a54AD815c6B",
  },
  {
    id: "base-sepolia",
    name: "Base Sepolia",
    chain: baseSepolia,
    tokenAddress: "0x808456652fdb597867f38412077A9182bf77359F",
  },
  {
    id: "ethereum-sepolia",
    name: "Ethereum Sepolia",
    chain: sepolia,
    tokenAddress: "0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4",
  },
  {
    id: "world-chain-sepolia",
    name: "World Chain Sepolia",
    chain: worldchainSepolia,
    tokenAddress: "0xe479EcA5740Ac65d6E1823bea2f1C08Bc14e954F",
  },
] as const;

const { PRIVATE_KEY, RECIPIENT_ADDRESS } = process.env;

if (!PRIVATE_KEY || !isHex(PRIVATE_KEY) || PRIVATE_KEY.length !== 66) {
  throw new Error(
    "PRIVATE_KEY must be a 0x-prefixed 32-byte hex string (66 chars)",
  );
}

if (!RECIPIENT_ADDRESS || !isAddress(RECIPIENT_ADDRESS)) {
  throw new Error("RECIPIENT_ADDRESS must be a valid EVM address");
}

const privateKey: `0x${string}` = PRIVATE_KEY;
const recipientAddress: `0x${string}` = RECIPIENT_ADDRESS;

async function selectChain() {
  // Prompt for a chain so one script can support every listed testnet.
  const chainList = CHAIN_CONFIGS.map(
    (chain, index) => `${index + 1}. ${chain.name}`,
  ).join("\n");
  const readline = createInterface({ input, output });

  try {
    const answer = await readline.question(
      "Select a chain for your EURC transfer:\n" +
        chainList +
        "\n\nEnter a number: ",
    );

    const selectedIndex = Number.parseInt(answer, 10) - 1;
    const selectedChain = CHAIN_CONFIGS[selectedIndex];

    if (!selectedChain) {
      throw new Error("Invalid chain selection");
    }

    return selectedChain;
  } finally {
    readline.close();
  }
}

async function main() {
  try {
    const selectedChain = await selectChain();
    const account = privateKeyToAccount(privateKey);

    // Create clients for the selected chain.
    const publicClient = createPublicClient({
      chain: selectedChain.chain,
      transport: http(),
    });

    const walletClient = createWalletClient({
      account,
      chain: selectedChain.chain,
      transport: http(),
    });

    // Read the sender's token balance before attempting the transfer.
    const balance = await publicClient.readContract({
      address: selectedChain.tokenAddress,
      abi: EURC_ABI,
      functionName: "balanceOf",
      args: [account.address],
    });

    const balanceFormatted = Number(
      formatUnits(balance as bigint, EURC_DECIMALS),
    );
    const amount = 1; // Send 1 EURC in this example.

    console.log("Chain:", selectedChain.name);
    console.log("Sender:", account.address);
    console.log("Recipient:", recipientAddress);
    console.log("Balance:", balanceFormatted, "EURC");

    if (amount > balanceFormatted) {
      throw new Error("Insufficient balance");
    }

    const amountInDecimals = parseUnits(amount.toString(), EURC_DECIMALS);

    // Submit the transfer transaction.
    const hash = await walletClient.writeContract({
      address: selectedChain.tokenAddress,
      abi: EURC_ABI,
      functionName: "transfer",
      args: [recipientAddress, amountInDecimals],
    });

    console.log("Transaction submitted.");
    console.log("Tx hash:", hash);
    console.log(
      "Explorer:",
      `${selectedChain.chain.blockExplorers?.default.url}/tx/${hash}`,
    );

    // Wait for the transaction to be confirmed onchain.
    const receipt = await publicClient.waitForTransactionReceipt({ hash });

    if (receipt.status !== "success") {
      throw new Error("Transaction reverted");
    }

    console.log("Transfer confirmed!");
  } catch (err) {
    console.error("Transfer failed:", err instanceof Error ? err.message : err);
    process.exit(1);
  }
}

main();
```

## Step 3. Run the script

Run the script using the following command:

```shell Shell theme={null}
npm start
```

You'll see output similar to the following:

```text theme={null}
Select a chain for your EURC transfer:
1. Arc Testnet
2. Avalanche Fuji
...

Enter a number: 3
Chain: Base Sepolia
Sender: 0x1A2b...7890
Recipient: 0x9F8f...1234
Balance: 250.0 EURC
Transaction submitted.
Tx hash: 0xabc123...def456
Explorer: https://sepolia.basescan.org/tx/0xabc123...def456
Transfer confirmed!
```

To verify the transfer, copy the transaction hash URL from the `Explorer:` line
and open it in your browser. This will take you to the testnet's block explorer,
where you can view full transaction details.

<Tip>
  **Tip:** If your script doesn't output a full explorer URL, you can manually
  paste the transaction hash into the testnet's block explorer.
</Tip>

## Summary

In this quickstart, you learned how to check balances and transfer EURC on EVM
testnets using one multi-chain Viem script in Node.js. Here are the key points
to remember:

* **Testnet only**. Testnet EURC has no real value.
* **Gas fees**. You need a small amount of the testnet's native token for gas.
* **Security**. Keep your private key in `.env`. Never commit secrets.
* **Single script**. The same script works across all supported EVM testnets.
* **Minimal ABI**. The script only uses `balanceOf` and `transfer` for
  simplicity.


# Quickstart: Transfer USDC on EVM chains
Source: https://developers.circle.com/stablecoins/quickstarts/transfer-usdc-evm

Transfer USDC between wallets on EVM chains using a Node.js script

This guide walks you through transferring USDC on EVM testnets using Viem and
Node.js. You'll build a simple script that checks your balance and sends test
transfers.

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/)
* Prepared a testnet wallet on the selected chain funded with:
  * Testnet USDC for the transfer
  * Testnet native tokens for gas fees

<Note>
  You can get testnet USDC from [Circle's faucet](https://faucet.circle.com/).
</Note>

## Step 1. Set up the project

This step shows you how to prepare your project and environment.

### 1.1. Create the project and install dependencies

Create a new directory and install the required dependencies:

```bash Shell theme={null}
# Set up your directory and initialize a Node.js project
mkdir transfer-usdc-evm
cd transfer-usdc-evm
npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="npx tsx --env-file=.env index.ts"

# Install runtime dependencies
npm install viem tsx

# Install dev dependencies
npm install --save-dev typescript @types/node
```

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.3. Set environment variables

Create a `.env` file in the project directory and add your wallet private key,
replacing `{YOUR_PRIVATE_KEY}` with the private key from your EVM wallet and
`{YOUR_RECIPIENT_ADDRESS}` with the address of the recipient.

```text theme={null}
PRIVATE_KEY={YOUR_PRIVATE_KEY}
RECIPIENT_ADDRESS={YOUR_RECIPIENT_ADDRESS}
```

* `PRIVATE_KEY` is the private key for the EVM wallet sending the transfer.
* `RECIPIENT_ADDRESS` is the EVM wallet address that will receive the USDC.

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

The `npm run start` command loads variables from `.env` using Node.js native
env-file support.

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>

## Step 2. Create the transfer script

In this step, you'll build a script in TypeScript that transfers USDC on the
selected EVM testnet. The script includes a single list of supported chains,
prompts you to choose one at runtime, and then runs the same transfer flow for
that chain.

### 2.1. Create the script file

```shell theme={null}
touch index.ts
```

### 2.2. Add the script

In `index.ts`, add the following script. It keeps the per-chain data in one
`CHAIN_CONFIGS` list so supporting another EVM testnet only requires one new
entry.

```typescript TypeScript expandable theme={null}
import { createInterface } from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";
import {
  createPublicClient,
  createWalletClient,
  defineChain,
  formatUnits,
  http,
  isAddress,
  isHex,
  parseUnits,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import {
  arcTestnet,
  arbitrumSepolia,
  avalancheFuji,
  baseSepolia,
  celoSepolia,
  codexTestnet,
  hyperliquidEvmTestnet,
  injectiveTestnet,
  inkSepolia,
  lineaSepolia,
  monadTestnet,
  optimismSepolia,
  plumeSepolia,
  polygonAmoy,
  seiTestnet,
  sepolia,
  sonicTestnet,
  unichainSepolia,
  worldchainSepolia,
  xdcTestnet,
  zkSyncSepoliaTestnet,
} from "viem/chains";

const USDC_DECIMALS = 6;
const USDC_ABI = [
  {
    name: "balanceOf",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "account", type: "address" }],
    outputs: [{ name: "", type: "uint256" }],
  },
  {
    name: "transfer",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [
      { name: "to", type: "address" },
      { name: "amount", type: "uint256" },
    ],
    outputs: [{ name: "", type: "bool" }],
  },
] as const;

// Store each supported chain in one place so the transfer flow stays shared.
const CHAIN_CONFIGS = [
  {
    id: "arc-testnet",
    name: "Arc Testnet",
    chain: arcTestnet,
    tokenAddress: "0x3600000000000000000000000000000000000000",
  },
  {
    id: "arbitrum-sepolia",
    name: "Arbitrum Sepolia",
    chain: arbitrumSepolia,
    tokenAddress: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
  },
  {
    id: "avalanche-fuji",
    name: "Avalanche Fuji",
    chain: avalancheFuji,
    tokenAddress: "0x5425890298aed601595a70AB815c96711a31Bc65",
  },
  {
    id: "base-sepolia",
    name: "Base Sepolia",
    chain: baseSepolia,
    tokenAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  },
  {
    id: "celo-sepolia",
    name: "Celo Sepolia",
    chain: celoSepolia,
    tokenAddress: "0x01C5C0122039549AD1493B8220cABEdD739BC44E",
  },
  {
    id: "codex-testnet",
    name: "Codex Testnet",
    chain: codexTestnet,
    tokenAddress: "0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f",
  },
  {
    id: "edge-testnet",
    name: "Edge Testnet",
    chain: defineChain({
      id: 33431,
      name: "Edge Testnet",
      nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
      rpcUrls: {
        default: { http: ["https://edge-testnet.g.alchemy.com/public"] },
      },
      blockExplorers: {
        default: {
          name: "Edge Testnet Explorer",
          url: "https://edge-testnet.explorer.alchemy.com",
        },
      },
    }),
    tokenAddress: "0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B",
  },
  {
    id: "ethereum-sepolia",
    name: "Ethereum Sepolia",
    chain: sepolia,
    tokenAddress: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
  },
  {
    id: "hyperevm-testnet",
    name: "HyperEVM Testnet",
    chain: hyperliquidEvmTestnet,
    tokenAddress: "0x2B3370eE501B4a559b57D449569354196457D8Ab",
  },
  {
    id: "injective-testnet",
    name: "Injective Testnet",
    chain: injectiveTestnet,
    tokenAddress: "0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d",
  },
  {
    id: "ink-sepolia",
    name: "Ink Sepolia",
    chain: inkSepolia,
    tokenAddress: "0xFabab97dCE620294D2B0b0e46C68964e326300Ac",
  },
  {
    id: "linea-sepolia",
    name: "Linea Sepolia",
    chain: lineaSepolia,
    tokenAddress: "0xFEce4462D57bD51A6A552365A011b95f0E16d9B7",
  },
  {
    id: "monad-testnet",
    name: "Monad Testnet",
    chain: monadTestnet,
    tokenAddress: "0x534b2f3A21130d7a60830c2Df862319e593943A3",
  },
  {
    id: "morph-hoodi",
    name: "Morph Hoodi",
    chain: defineChain({
      id: 2910,
      name: "Morph Hoodi",
      nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
      rpcUrls: {
        default: { http: ["https://rpc-hoodi.morph.network"] },
      },
      blockExplorers: {
        default: {
          name: "Morph Hoodi Explorer",
          url: "https://explorer-hoodi.morph.network",
        },
      },
    }),
    tokenAddress: "0x7433b41C6c5e1d58D4Da99483609520255ab661B",
  },
  {
    id: "optimism-sepolia",
    name: "Optimism Sepolia",
    chain: optimismSepolia,
    tokenAddress: "0x5fd84259d66Cd46123540766Be93DFE6D43130D7",
  },
  {
    id: "pharos-atlantic",
    name: "Pharos Atlantic",
    chain: defineChain({
      id: 688689,
      name: "Pharos Atlantic",
      nativeCurrency: { name: "PHRS", symbol: "PHRS", decimals: 18 },
      rpcUrls: {
        default: { http: ["https://atlantic.dplabs-internal.com"] },
      },
      blockExplorers: {
        default: {
          name: "Pharos Testnet Explorer",
          url: "https://atlantic.pharosscan.xyz",
        },
      },
      testnet: true,
    }),
    tokenAddress: "0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B",
  },
  {
    id: "plume-sepolia",
    name: "Plume Sepolia",
    chain: plumeSepolia,
    tokenAddress: "0xcB5f30e335672893c7eb944B374c196392C19D18",
  },
  {
    id: "polygon-amoy",
    name: "Polygon Amoy",
    chain: polygonAmoy,
    tokenAddress: "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
  },
  {
    id: "sei-testnet",
    name: "Sei Testnet",
    chain: seiTestnet,
    tokenAddress: "0x4fCF1784B31630811181f670Aea7A7bEF803eaED",
  },
  {
    id: "sonic-testnet",
    name: "Sonic Testnet",
    chain: sonicTestnet,
    tokenAddress: "0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51",
  },
  {
    id: "unichain-sepolia",
    name: "Unichain Sepolia",
    chain: unichainSepolia,
    tokenAddress: "0x31d0220469e10c4E71834a79b1f276d740d3768F",
  },
  {
    id: "world-chain-sepolia",
    name: "World Chain Sepolia",
    chain: worldchainSepolia,
    tokenAddress: "0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88",
  },
  {
    id: "xdc-apothem",
    name: "XDC Apothem",
    chain: xdcTestnet,
    tokenAddress: "0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4",
  },
  {
    id: "zksync-era-testnet",
    name: "ZKsync Era Testnet",
    chain: zkSyncSepoliaTestnet,
    tokenAddress: "0xAe045DE5638162fa134807Cb558E15A3F5A7F853",
  },
] as const;

const { PRIVATE_KEY, RECIPIENT_ADDRESS } = process.env;

if (!PRIVATE_KEY || !isHex(PRIVATE_KEY) || PRIVATE_KEY.length !== 66) {
  throw new Error(
    "PRIVATE_KEY must be a 0x-prefixed 32-byte hex string (66 chars)",
  );
}

if (!RECIPIENT_ADDRESS || !isAddress(RECIPIENT_ADDRESS)) {
  throw new Error("RECIPIENT_ADDRESS must be a valid EVM address");
}

const privateKey: `0x${string}` = PRIVATE_KEY;
const recipientAddress: `0x${string}` = RECIPIENT_ADDRESS;

async function selectChain() {
  // Prompt for a chain so one script can support every listed testnet.
  const chainList = CHAIN_CONFIGS.map(
    (chain, index) => `${index + 1}. ${chain.name}`,
  ).join("\n");
  const readline = createInterface({ input, output });

  try {
    const answer = await readline.question(
      "Select a chain for your USDC transfer:\n" +
        chainList +
        "\n\nEnter a number: ",
    );

    const selectedIndex = Number.parseInt(answer, 10) - 1;
    const selectedChain = CHAIN_CONFIGS[selectedIndex];

    if (!selectedChain) {
      throw new Error("Invalid chain selection");
    }

    return selectedChain;
  } finally {
    readline.close();
  }
}

async function main() {
  try {
    const selectedChain = await selectChain();
    const account = privateKeyToAccount(privateKey);

    // Create clients for the selected chain.
    const publicClient = createPublicClient({
      chain: selectedChain.chain,
      transport: http(),
    });

    const walletClient = createWalletClient({
      account,
      chain: selectedChain.chain,
      transport: http(),
    });

    // Read the sender's token balance before attempting the transfer.
    const balance = await publicClient.readContract({
      address: selectedChain.tokenAddress,
      abi: USDC_ABI,
      functionName: "balanceOf",
      args: [account.address],
    });

    const balanceFormatted = Number(
      formatUnits(balance as bigint, USDC_DECIMALS),
    );
    const amount = 1; // Send 1 USDC in this example.

    console.log("Chain:", selectedChain.name);
    console.log("Sender:", account.address);
    console.log("Recipient:", recipientAddress);
    console.log("Balance:", balanceFormatted, "USDC");

    if (amount > balanceFormatted) {
      throw new Error("Insufficient balance");
    }

    const amountInDecimals = parseUnits(amount.toString(), USDC_DECIMALS);

    // Submit the transfer transaction.
    const hash = await walletClient.writeContract({
      address: selectedChain.tokenAddress,
      abi: USDC_ABI,
      functionName: "transfer",
      args: [recipientAddress, amountInDecimals],
    });

    console.log("Transaction submitted.");
    console.log("Tx hash:", hash);
    console.log(
      "Explorer:",
      `${selectedChain.chain.blockExplorers?.default.url}/tx/${hash}`,
    );

    // Wait for the transaction to be confirmed onchain.
    const receipt = await publicClient.waitForTransactionReceipt({ hash });

    if (receipt.status !== "success") {
      throw new Error("Transaction reverted");
    }

    console.log("Transfer confirmed!");
  } catch (err) {
    console.error("Transfer failed:", err instanceof Error ? err.message : err);
    process.exit(1);
  }
}

main();
```

## Step 3. Run the script

Run the script using the following command:

```shell Shell theme={null}
npm start
```

You'll see output similar to the following:

```text theme={null}
Select a chain for your USDC transfer:
1. Arc Testnet
2. Arbitrum Sepolia
...

Enter a number: 4
Chain: Base Sepolia
Sender: 0x1A2b...7890
Recipient: 0x9F8f...1234
Balance: 250.0 USDC
Transaction submitted.
Tx hash: 0xabc123...def456
Explorer: https://sepolia.basescan.org/tx/0xabc123...def456
Transfer confirmed!
```

To verify the transfer, copy the transaction hash URL from the `Explorer:` line
and open it in your browser. This will take you to the testnet's block explorer,
where you can view full transaction details.

<Tip>
  **Tip:** If your script doesn't output a full explorer URL, you can manually
  paste the transaction hash into the testnet's block explorer.
</Tip>

## Summary

In this quickstart, you learned how to check balances and transfer USDC on EVM
testnets using one multi-chain Viem script in Node.js. Here are the key points
to remember:

* **Testnet only**. Testnet USDC has no real value.
* **Gas fees**. You need a small amount of the testnet's native token for gas.
* **Security**. Keep your private key in `.env`. Never commit secrets.
* **Single script**. The same script works across all supported EVM testnets.
* **Minimal ABI**. The script only uses `balanceOf` and `transfer` for
  simplicity.


# USDC Contract Addresses
Source: https://developers.circle.com/stablecoins/usdc-contract-addresses



USDC is a dollar-backed stablecoin that runs on multiple blockchains. USDC
tokens are controlled by a smart contract on the blockchain. The following
sections link to the contracts for USDC on every supported mainnet and testnet
blockchain.

## Mainnet

<Warning>
  **Mainnet Tokens have Financial Value**

  The blockchains listed below store and transfer tokens that have real financial
  value. When interacting with mainnet blockchains, you should thoroughly test
  your code, verify all addresses, and ensure the privacy of seed phrases and
  private keys.
</Warning>

| Blockchain         | USDC Mainnet Address                                                                                                                                                                                     |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Algorand           | [`31566704`](https://explorer.perawallet.app/asset/31566704)                                                                                                                                             |
| Aptos              | [`0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b`](https://explorer.aptoslabs.com/fungible_asset/0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b?network=mainnet) |
| Arbitrum           | [`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`](https://arbiscan.io/token/0xaf88d065e77c8cC2239327C5EDb3A432268e5831)                                                                                     |
| Avalanche C-Chain  | [`0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`](https://snowtrace.io/token/0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E)                                                                                    |
| Base               | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)                                                                                    |
| Codex              | [`0xd996633a415985DBd7D6D12f4A4343E31f5037cf`](https://explorer.codex.xyz/address/0xd996633a415985DBd7D6D12f4A4343E31f5037cf)                                                                            |
| Celo               | [`0xcebA9300f2b948710d2653dD7B07f33A8B32118C`](https://celoscan.io/token/0xcebA9300f2b948710d2653dD7B07f33A8B32118C)                                                                                     |
| EDGE               | [`0x98d2919b9A214E6Fa5384AC81E6864bA686Ad74c`](https://pro.edgex.exchange/en-US/explorer/address/0x98d2919b9A214E6Fa5384AC81E6864bA686Ad74c)                                                             |
| Ethereum           | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)                                                                                    |
| Hedera             | [`0.0.456858`](https://hashscan.io/mainnet/token/0.0.456858)                                                                                                                                             |
| HyperEVM           | [`0xb88339CB7199b77E23DB6E890353E22632Ba630f`](https://hyperscan.com/token/0xb88339CB7199b77E23DB6E890353E22632Ba630f)                                                                                   |
| Injective          | [`0xa00C59fF5a080D2b954d0c75e46E22a0c371235a`](https://blockscout.injective.network/address/0xa00C59fF5a080D2b954d0c75e46E22a0c371235a)                                                                  |
| Ink                | [`0x2D270e6886d130D724215A266106e6832161EAEd`](https://explorer.inkonchain.com/address/0x2D270e6886d130D724215A266106e6832161EAEd)                                                                       |
| Linea              | [`0x176211869cA2b568f2A7D4EE941E073a821EE1ff`](https://lineascan.build/token/0x176211869ca2b568f2a7d4ee941e073a821ee1ff)                                                                                 |
| Monad              | [`0x754704Bc059F8C67012fEd69BC8A327a5aafb603`](https://monadvision.com/token/0x754704Bc059F8C67012fEd69BC8A327a5aafb603)                                                                                 |
| Morph              | [`0xCfb1186F4e93D60E60a8bDd997427D1F33bc372B`](https://explorer.morph.network/token/0xCfb1186F4e93D60E60a8bDd997427D1F33bc372B)                                                                          |
| NEAR               | [`17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1`](https://nearblocks.io/token/17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1)                                       |
| Noble              | [`uusdc`](http://mintscan.io/noble/assets)                                                                                                                                                               |
| OP Mainnet         | [`0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85`](https://optimistic.etherscan.io/token/0x0b2c639c533813f4aa9d7837caf62653d097ff85)                                                                         |
| Pharos             | [`0xC879C018dB60520F4355C26eD1a6D572cdAC1815`](https://pharos.socialscan.io/address/0xC879C018dB60520F4355C26eD1a6D572cdAC1815)                                                                          |
| Plume              | [`0x222365EF19F7947e5484218551B56bb3965Aa7aF`](https://explorer.plume.org/address/0x222365EF19F7947e5484218551B56bb3965Aa7aF)                                                                            |
| Polkadot Asset Hub | [`1337`](https://assethub-polkadot.subscan.io/assets/1337)                                                                                                                                               |
| Polygon PoS        | [`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`](https://polygonscan.com/token/0x3c499c542cef5e3811e1192ce70d8cc03d5c3359)                                                                                 |
| Sei                | [`0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392`](https://seiscan.io/address/0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392)                                                                                    |
| Solana             | [`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`](https://solscan.io/token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)                                                                                  |
| Sonic              | [`0x29219dd400f2Bf60E5a23d13Be72B486D4038894`](https://sonicscan.org/token/0x29219dd400f2bf60e5a23d13be72b486d4038894)                                                                                   |
| Starknet           | [`0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb`](https://voyager.online/token/0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb)                                  |
| Stellar            | [`USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN`](https://stellar.expert/explorer/public/asset/USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN)                            |
| Sui                | [`0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC`](https://suiscan.xyz/mainnet/coin/0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC/txs)  |
| Unichain           | [`0x078D782b760474a361dDA0AF3839290b0EF57AD6`](https://uniscan.xyz/token/0x078d782b760474a361dda0af3839290b0ef57ad6)                                                                                     |
| World Chain        | [`0x79A02482A880bCe3F13E09da970dC34dB4cD24D1`](https://worldscan.org/address/0x79A02482A880bCe3F13E09da970dC34dB4cD24D1)                                                                                 |
| XDC                | [`0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1`](https://xdcscan.com/address/0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1)                                                                                   |
| XRPL               | [`5553444300000000000000000000000000000000.rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE`](https://livenet.xrpl.org/token/5553444300000000000000000000000000000000.rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE)              |
| ZKsync Era         | [`0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4`](https://explorer.zksync.io/address/0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4)                                                                            |

## Testnet

<Warning>
  **Testnet tokens have no financial value**

  Because the testnets listed below are used only for testing, the USDC tokens in
  circulation on these networks have no financial value, and **are not backed by
  real US dollars**.

  Similarly, native testnet tokens have no financial value.
</Warning>

| Blockchain          | Token Address                                                                                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Algorand Testnet    | [`10458941`](https://testnet.explorer.perawallet.app/asset/10458941)                                                                                                                                     |
| Aptos Testnet       | [`0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832`](https://explorer.aptoslabs.com/fungible_asset/0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832?network=testnet) |
| Arbitrum Sepolia    | [`0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d`](https://sepolia.arbiscan.io/address/0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d)                                                                           |
| Arc Testnet         | [`0x3600000000000000000000000000000000000000`](https://testnet.arcscan.app/address/0x3600000000000000000000000000000000000000)                                                                           |
| Avalanche Fuji      | [`0x5425890298aed601595a70AB815c96711a31Bc65`](https://testnet.snowtrace.io/token/0x5425890298aed601595a70ab815c96711a31bc65)                                                                            |
| Base Sepolia        | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://base-sepolia.blockscout.com/address/0x036CbD53842c5426634e7929541eC2318f3dCF7e)                                                                   |
| Celo Sepolia        | [`0x01C5C0122039549AD1493B8220cABEdD739BC44E`](https://celo-sepolia.blockscout.com/token/0x01C5C0122039549AD1493B8220cABEdD739BC44E)                                                                     |
| Codex Testnet       | [`0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f`](https://explorer.codex-stg.xyz/address/0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f)                                                                        |
| Ethereum Sepolia    | [`0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238`](https://sepolia.etherscan.io/address/0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238)                                                                          |
| EDGE Testnet        | [`0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B`](https://edge-testnet.explorer.alchemy.com/address/0x2d9F7CAD728051AA35Ecdc472a14cf8cDF5CFD6B)                                                             |
| Hedera Testnet      | [`0.0.429274`](https://hashscan.io/testnet/token/0.0.429274)                                                                                                                                             |
| HyperEVM Testnet    | `0x2B3370eE501B4a559b57D449569354196457D8Ab`                                                                                                                                                             |
| Injective Testnet   | [`0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d`](https://testnet.blockscout.injective.network/address/0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d)                                                          |
| Ink Testnet         | [`0xFabab97dCE620294D2B0b0e46C68964e326300Ac`](https://explorer-sepolia.inkonchain.com/address/0xFabab97dCE620294D2B0b0e46C68964e326300Ac)                                                               |
| Linea Sepolia       | [`0xFEce4462D57bD51A6A552365A011b95f0E16d9B7`](https://sepolia.lineascan.build/address/0xfece4462d57bd51a6a552365a011b95f0e16d9b7)                                                                       |
| Monad Testnet       | [`0x534b2f3A21130d7a60830c2Df862319e593943A3`](https://testnet.monadexplorer.com/token/0x534b2f3A21130d7a60830c2Df862319e593943A3)                                                                       |
| Morph Hoodi Testnet | [`0x7433b41C6c5e1d58D4Da99483609520255ab661B`](https://explorer-hoodi.morph.network/address/0x7433b41C6c5e1d58D4Da99483609520255ab661B)                                                                  |
| NEAR Testnet        | [`3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af`](https://testnet.nearblocks.io/token/3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af)                               |
| Noble Testnet       | [`uusdc`](https://www.mintscan.io/noble-testnet/assets)                                                                                                                                                  |
| OP Sepolia          | [`0x5fd84259d66Cd46123540766Be93DFE6D43130D7`](https://sepolia-optimism.etherscan.io/address/0x5fd84259d66Cd46123540766Be93DFE6D43130D7)                                                                 |
| Pharos Testnet      | [`0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B`](https://pharos-testnet.socialscan.io/address/0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B)                                                                  |
| Plume Testnet       | [`0xcB5f30e335672893c7eb944B374c196392C19D18`](https://testnet-explorer.plume.org/address/0xcB5f30e335672893c7eb944B374c196392C19D18)                                                                    |
| Polkadot Westmint   | [`Asset ID 31337`](https://assethub-westend.subscan.io/asset/31337)                                                                                                                                      |
| Polygon PoS Amoy    | [`0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582`](https://amoy.polygonscan.com/address/0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582)                                                                          |
| Sei Testnet         | [`0x4fCF1784B31630811181f670Aea7A7bEF803eaED`](https://testnet.seiscan.io/address/0x4fCF1784B31630811181f670Aea7A7bEF803eaED)                                                                            |
| Solana Devnet       | [`4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`](https://explorer.solana.com/address/4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU?cluster=devnet)                                                        |
| Sonic Testnet       | [`0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51`](https://testnet.sonicscan.org/address/0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51)                                                                         |
| Sonic Blaze Testnet | [`0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6`](https://blaze.soniclabs.com/address/0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6)                                                                           |
| Starknet Sepolia    | [`0x0512feAc6339Ff7889822cb5aA2a86C848e9D392bB0E3E237C008674feeD8343`](https://sepolia.voyager.online/token/0x0512feAc6339Ff7889822cb5aA2a86C848e9D392bB0E3E237C008674feeD8343)                          |
| Stellar Testnet     | [`USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5`](https://stellar.expert/explorer/testnet/asset/USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5)                           |
| Sui Testnet         | [`0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC`](https://suiscan.xyz/testnet/coin/0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC/txs)  |
| Unichain Sepolia    | [`0x31d0220469e10c4E71834a79b1f276d740d3768F`](https://unichain-sepolia.blockscout.com/token/0x31d0220469e10c4E71834a79b1f276d740d3768F)                                                                 |
| World Chain Sepolia | [`0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88`](https://sepolia.worldscan.org/address/0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88)                                                                         |
| XDC Apothem         | [`0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4`](https://testnet.xdcscan.com/address/0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4)                                                                           |
| XRPL Testnet        | [`5553444300000000000000000000000000000000.rHuGNhqTG32mfmAvWA8hUyWRLV3tCSwKQt`](https://testnet.xrpl.org/token/5553444300000000000000000000000000000000.rHuGNhqTG32mfmAvWA8hUyWRLV3tCSwKQt)              |
| ZKsync Era Testnet  | [`0xAe045DE5638162fa134807Cb558E15A3F5A7F853`](https://sepolia.explorer.zksync.io/address/0xAe045DE5638162fa134807Cb558E15A3F5A7F853)                                                                    |


# What is EURC?
Source: https://developers.circle.com/stablecoins/what-is-eurc



EURC is a digital euro issued by Circle, also known as a stablecoin, and
operates on several leading public blockchains. Designed to represent euros on
the internet, EURC is backed 100% by euro-denominated reserves so that it's
always redeemable 1:1 for EUR.

Circle publishes monthly attestation reports for EURC reserve holdings on
[Circle's Transparency page](https://www.circle.com/transparency).

<Note>
  **You may be interested in MiCA-compliant EURC**

  EURC is one of the first fully compliant stablecoins under the EU's Markets in
  Crypto-Assets (MiCA) regulation. Learn more about how EURC meets these standards
  and what it means for builders and businesses in the EU and beyond on
  [Circle's EURC page](https://www.circle.com/eurc).
</Note>

## EURC brings the euro into the world of onchain finance

Circle launched EURC to bring the stability and global utility of the euro into
a programmable, interoperable, and internet-native form. EURC combines the trust
and compliance of the traditional financial system with the speed and
composability of blockchain networks.

* **Regulated and transparent**
* **Redeemable 1:1 for euros**
* **Available on multiple chains**
* **Instant, low-cost transactions**

Before EURC, businesses looking to transact in euros onchain had limited
options. Traditional systems for euro payments are fragmented, slow, and often
costly. EURC helps bridge that gap, offering seamless access to the euro in the
digital economy.

By leveraging EURC, developers and businesses can settle transactions, power
DeFi applications, and move money globally using a currency that is widely
trusted and regulated.

## How to access EURC

Qualified businesses can apply for a
[Circle Mint](https://www.circle.com/eurc#circle-mint) account to convert euros
to and from EURC with zero fees and near-instant settlement.

Developers can integrate EURC into their applications across supported public
blockchains:

* Developers with smart contract experience can integrate EURC smart contracts
  directly on [mainnet](/stablecoins/eurc-contract-addresses#mainnet) or
  [testnet](/stablecoins/eurc-contract-addresses#testnet) to build
  euro-denominated flows.
* Developers can use [Circle's APIs](/api-reference) and developer tools to
  integrate EURC into wallets, marketplaces, and financial applications.


# What is USDC?
Source: https://developers.circle.com/stablecoins/what-is-usdc



USDC is a digital dollar issued by Circle, also known as a stablecoin, running
on many of the world's leading blockchains. Designed to represent US dollars on
the internet, USDC is backed 100% by highly liquid cash and cash-equivalent
assets so that it's always redeemable 1:1 for USD.

Circle publishes monthly attestation reports for USDC reserve holdings on
[Circle's Transparency page](http://circle.com/transparency).

<Note>
  **You may be interested in CCTP**

  Cross-Chain Transfer Protocol (CCTP) is a permissionless onchain utility that
  enables USDC to move securely between supported blockchain networks. Just like
  USDC, CCTP is open and free for [anyone to build upon](/cctp).
</Note>

## USDC revolutionizes commerce and financial services

Circle developed USDC to usher in a world where the US dollar is accessible to
businesses and people around the globe without needing a traditional bank
account. Digital currencies like USDC inherit the speed, efficiency, and
security of public blockchain networks to bring about transformative benefits:

* **Open and programmable**
* **Globally accessible**
* **Available 24/7/365**
* **Instant settlement at low cost**

Before USDC, businesses needed traditional banking solutions to accept payments,
send remittances to vendors and suppliers, and manage their corporate
treasuries. In contrast to USDC, legacy payment methods are slow, expensive, and
limited by their lack of interoperability with other systems.

USDC makes money programmable, providing businesses and developers the ability
to build innovative applications and services on an open platform that anyone
can connect to -- globally, quickly, and cost-effectively.

## How to access USDC

Qualified businesses can apply for a [Circle Mint](/circle-mint) account to
readily convert USD to and from USDC at no additional cost.

Developers can add support for USDC in their applications on a variety of public
blockchain networks:

* Crypto-native developers often choose to integrate directly with the
  [USDC smart contract](/stablecoins/quickstart-transfer-10-usdc-on-chain) to
  design customizable funds flows for their applications.
* Developers new to the blockchain industry can benefit from
  [Circle's Developer Services](/wallets) product suite, designed to make it
  easy to build applications that leverage the power of USDC.
* Developers can use [CCTP](/cctp) to build novel crosschain apps that stack
  together the various functionalities of trading, lending, payments, NFTs,
  gaming, and more, all while keeping things simple for users.

<Note>
  For more information about USDC, visit [usdc.com](https://www.usdc.com).
</Note>


# StableFX
Source: https://developers.circle.com/stablefx

Institutional-grade stablecoin FX engine built on Arc

StableFX is an institutional-grade stablecoin FX engine built on Arc that
combines Request-for-Quote (RFQ) execution with onchain settlement. This
permissioned platform is designed for financial institutions including payment
service providers, fintechs, crypto OTC desks, and prime brokers.

StableFX supports USDC and EURC and will expand to a broad range of local
stablecoin pairs.

## Key features

<CardGroup>
  <Card title="Aggregated Liquidity" icon="chart-network">
    Access competitive rates from multiple liquidity providers through a single
    API call
  </Card>

  <Card title="24/7 Settlement" icon="clock">
    Trade and settle around the clock with sub-second finality on Arc
  </Card>

  <Card title="Simplified Operations" icon="layer-group">
    Replace multiple bilateral agreements with one integration
  </Card>
</CardGroup>

StableFX reduces settlement risk through smart contract escrow that ensures both
sides of a trade settle simultaneously or not at all. With API and SDK-based
integration, you can implement programmatic quote requests and automated
settlement directly into your institutional workflows.

## What you can build

As a vetted institution, you can integrate StableFX to power a range of
financial services. Here are some common use cases:

<AccordionGroup>
  <Accordion title="Cross-border payment flows" icon="globe">
    Build payment systems with real-time currency conversion and settlement that
    enable instant international transfers without traditional correspondent banking
    delays. Your customers can send funds across borders with sub-second finality
    and transparent pricing.
  </Accordion>

  <Accordion title="Institutional treasury management" icon="building-columns">
    Implement automated treasury operations for managing multi-currency stablecoin
    positions. Set up programmatic rebalancing rules and execute trades 24/7 to
    maintain optimal currency allocations across your organization.
  </Accordion>

  <Accordion title="Embedded FX liquidity services" icon="arrows-rotate">
    Offer FX liquidity directly in your platform without building your own matching
    engine or sourcing liquidity. Your customers get seamless access to competitive
    rates and instant settlement while you maintain control over the user
    experience.
  </Accordion>

  <Accordion title="Next-generation remittance solutions" icon="paper-plane">
    Eliminate T+2 settlement delays and counterparty risk by leveraging smart
    contract escrow. Build remittance services with guaranteed simultaneous
    settlement on both sides, reducing operational risk and capital requirements.
  </Accordion>
</AccordionGroup>

## How it works

StableFX operates on a Request-for-Quote (RFQ) model that combines offchain
execution with onchain settlement:

<Steps>
  <Step title="Request a quote">
    Takers request quotes through the API, specifying the currency pair and amount.
    Multiple liquidity providers compete to offer the best rate.
  </Step>

  <Step title="Execute the trade">
    Accept a quote through the API. Execution happens offchain for speed and
    efficiency.
  </Step>

  <Step title="Settle onchain">
    Settlement occurs automatically through smart contract escrow on Arc, ensuring
    payment-versus-payment where both sides settle or neither does.
  </Step>
</Steps>

<Note>
  The StableFX API handles both offchain and onchain steps, so you don't need to
  interact with smart contracts directly.
</Note>

## Get started

<Info>
  Reach out to your [Circle representative](mailto:sales@circle.com) to get an
  API key for StableFX.
</Info>

Try StableFX in the testing environment. Whether you're looking to consume
liquidity as a **taker** or provide liquidity as a **maker**, these quickstart
guides will help you integrate:

<CardGroup>
  <Card title="Create an FX trade as a taker" icon="arrow-right-arrow-left" href="/stablefx/quickstarts/fx-trade-taker">
    Request and execute a USDC to EURC trade
  </Card>

  <Card title="Fulfill an FX trade as a maker" icon="coins" href="/stablefx/quickstarts/fx-trade-maker">
    Fulfill existing trades and provide liquidity
  </Card>

  <Card title="Use the StableFX Console" icon="browser" href="/stablefx/concepts/console-overview">
    Trade, settle, and manage your account from the browser. No code required.
  </Card>
</CardGroup>


# StableFX Console
Source: https://developers.circle.com/stablefx/concepts/console-overview

A self-service interface for trading stablecoins, managing API keys, and settling trades onchain — no code required.

The [StableFX](/stablefx) Console gives you a browser-based alternative to the
API—useful for manual trading, onboarding verification, and exploring the
platform before automating with code. To get started immediately, see
[Execute your first trade](/stablefx/quickstarts/console-first-trade).

<CardGroup>
  <Card title="Live FX Rates" icon="chart-line">
    View real-time exchange rates for all supported currency pairs, updated
    every 30 seconds.
  </Card>

  <Card title="Trade Execution" icon="arrow-right-arrow-left">
    Request quotes, lock rates, and create trades through a guided side-panel
    workflow.
  </Card>

  <Card title="Wallet Connection" icon="wallet">
    Connect an EVM-compatible wallet to sign trades and fund settlements
    directly from the console.
  </Card>

  <Card title="Trade Management" icon="table">
    View, filter, and manage your trade history. Settle individual trades or
    batch-fund multiple trades at once.
  </Card>
</CardGroup>

## Who is the console for?

The console serves two primary user types:

* **Takers** request quotes, create trades, and fund settlements. This is the
  primary trading experience.
* **Makers** review confirmed trades, sign them to confirm intent, and fund
  their side of the settlement.

You can switch between Taker and Maker views at any time using the account type
dropdown in the sidebar navigation. For details on what each role can access,
see [Roles and permissions](/stablefx/references/console-roles-permissions).

<Note>
  The console requires an active StableFX account. If you haven't onboarded yet,
  contact your Circle representative or visit the console to begin the
  onboarding process. To complete onboarding and execute your first trade, see
  [Get started with the console](/stablefx/quickstarts/console-first-trade).
</Note>

## Console pages

<Frame>
  <img />
</Frame>

The console has four main areas:

| Page           | Route                | Description                                                                   |
| -------------- | -------------------- | ----------------------------------------------------------------------------- |
| **Home**       | `/fx/home`           | Dashboard with onboarding status, live rates, and a quick-access trade form.  |
| **Overview**   | `/fx/overview`       | Live rates card and a preview of your recent trades.                          |
| **Trades**     | `/fx/trades`         | Full trade history with filtering, sorting, pagination, and batch settlement. |
| **Onboarding** | `/fx/onboarding/kyb` | Complete your KYB verification to unlock trading capabilities.                |

## How trading works in the console

Trading in the console follows the same three-phase model as the API, presented
as a guided workflow in a side panel:

<Steps>
  <Step title="Request a quote">
    Enter the currency pair, amount, and settlement tenor. The console fetches a
    live quote and displays the exchange rate, fees, and collateral
    requirements.
  </Step>

  <Step title="Connect wallet and sign">
    Connect an EVM-compatible wallet (such as MetaMask). The console prompts you
    to sign EIP-712 typed data to authorize the trade and any required token
    approvals via the Permit2 contract. See [Connect your
    wallet](/stablefx/howtos/connect-wallet-console) for setup instructions.
  </Step>

  <Step title="Fund and settle">
    After both parties have signed, fund your side of the trade. The console
    generates Permit2 signature data, which you sign with your wallet. Once both
    sides are funded, the FxEscrow smart contract on Arc settles the trade
    automatically.
  </Step>
</Steps>

For detailed step-by-step instructions, see:

* [Create a trade as a taker](/stablefx/howtos/create-trade-console): Request a
  quote, sign, and create a trade through the console.
* [Fulfill a trade as a maker](/stablefx/howtos/fulfill-trade-console): Sign and
  fund confirmed trades from the maker view.
* [Settle trades](/stablefx/howtos/settle-trades-console): Fund individual or
  batch trades for onchain settlement.

<Frame>
  <img />
</Frame>

## Console vs. API

The console and the [StableFX API](/stablefx) provide the same underlying
capabilities. Choose the approach that fits your workflow:

|                      | Console                                         | API                                                                |
| -------------------- | ----------------------------------------------- | ------------------------------------------------------------------ |
| **Best for**         | Manual trading, testing, exploring StableFX     | Automated trading, programmatic integration                        |
| **Authentication**   | Browser session (Circle account login)          | API key (`Bearer` token)                                           |
| **Wallet signing**   | Built-in wallet connection (Dynamic.xyz)        | Your own signing infrastructure                                    |
| **Batch settlement** | Visual multi-select and one-click funding       | `POST /v1/exchange/stablefx/fund` with multiple contract trade IDs |
| **Rate streaming**   | Auto-refreshing rates card (30-second interval) | Poll `POST /v1/exchange/stablefx/quotes` with `type: reference`    |

<Tip>
  You can use both the console and the API with the same StableFX account.
  Trades created via the API appear in the console, and vice versa.
</Tip>

## Supported currencies

The console supports the same currency pairs as the StableFX API. One side of
every trade must be USDC.

See [Supported Currencies](/stablefx/references/supported-currencies) for the
current list.


# StableFX Talos Integration for Makers
Source: https://developers.circle.com/stablefx/concepts/maker-talos-integration

Integrate with StableFX as a maker on Talos

StableFX uses the [Talos platform](https://www.talos.com/our-solutions/trading)
as a vendor for routing quote requests and trade orders to market makers.
StableFX maintains a configurable list of market makers for each stablecoin
pair.

The following is an example of a Talos quote request for the EURC/USDC trading
pair to makerA and makerB:

```json theme={null}
{
  "Symbol": "EURC-USDC",
  "QuoteReqID": "1157ac1a-59d4-4191-841a-7f1706e0434c",
  "OrderQty": "10",
  "Markets": ["makerA", "makerB"],
  "TransactTime": "2020-05-29T14:29:38.000000Z"
}
```

If you are a market maker integrated with Talos, StableFX can support routing
taker [RFQs](/stablefx/concepts/technical-guide#quote-request) for the
stablecoin pairs you wish to support.

Talos will return a list of market quotes and StableFX will then select the best
quote to return to the taker. The taker uses the quote ID (Talos RFQ ID) to
create a trade by calling the StableFX
[Create trade API](/api-reference/stablefx/all/create-trade).

StableFX calls Talos's orders API to create the order between StableFX and the
maker. Upon successful confirmation, StableFX will proceed to recording the
trade on the smart contract.


# StableFX Risk Buffers
Source: https://developers.circle.com/stablefx/concepts/risk-buffers

Understand how risk buffers protect counterparties during StableFX trade execution

Risk buffers add a layer of protection to StableFX trades. During trade
execution, StableFX holds a proportional amount of the trade as buffer from both
the taker and maker in escrow.

This buffer manages counterparty risk, meaning one party fails to fund the trade
after agreeing to it. By holding funds in escrow upfront, StableFX ensures both
sides commit to the trade. This reduces exposure and improves settlement
integrity.

## Risk buffer calculation

StableFX defines risk buffer settings per maker and currency pair. Each setting
controls how much of the taker's and maker's notional amounts are reserved as
buffers for that trading pair.

| Parameter             | Description                                                        |
| --------------------- | ------------------------------------------------------------------ |
| Taker risk buffer %   | Percentage of the sell currency amount held as the taker's buffer. |
| Taker risk buffer min | Minimum value of the taker's risk buffer in absolute terms.        |
| Maker risk buffer %   | Percentage of the buy currency amount held as the maker's buffer.  |
| Maker risk buffer min | Minimum value of the maker's risk buffer in absolute terms.        |

A value of 0% is valid for any risk buffer. If no setting exists for a given
maker-taker pair, both risk buffers default to 0.

When a taker requests a quote, StableFX:

1. Retrieves the risk buffer configuration for the maker and currency pair.
2. Calculates both taker and maker risk buffers based on the configuration
   parameters.
3. Returns the taker's risk buffer in the quote response as the `collateral`
   parameter.

This gives the taker full visibility into the total funds required before trade
execution.

## Trade broadcast

After StableFX registers signatures for both the taker and maker, it broadcasts
the [`recordTrade`](/stablefx/references/contract-interfaces) function to the
settlement contract. This function withdraws trade collateral from each trader's
wallet using the Permit2 protocol.

<Warning>
  Both traders must have sufficient balance for their collateral amount specified
  on the quote and
  [Permit2 approval](/stablefx/howtos/grant-usdc-allowance-permit2) for their
  funding token to successfully record the trade onchain.
</Warning>

## Where to find the risk buffer

The risk buffer amount appears in several places:

* **Create Quote API response**: Returned as the `collateral` field for the
  taker. See [Create a quote](/api-reference/stablefx/all/create-quote).
* **Get Trade API response**: Makers can find the `collateral` field in the
  trade response. See
  [Get a trade](/api-reference/stablefx/all/get-trade-by-id).
* **Typed data for signing**: Available in the `message.permitted.amount` field
  of the EIP-712 typed data.

The currency of the collateral is always the currency that the trader is
responsible for funding.

## How risk buffers affect settlement

### Breach scenarios

If a trade reaches maturity but remains unsettled, StableFX calls the escrow
contract's breach function to expire the trade. The outcome depends on which
party has funded:

**Neither party funds**

If neither the taker nor the maker funds before expiry, the smart contract
returns both parties' risk buffers from escrow. No breach compensation is
applied.

**One party funds**

If only one party funds the trade before expiry, the non-funding party is
treated as the breaching party. The contract:

* Awards the non-funding party's risk buffer to the funding party as
  compensation.
* Returns the funding party's own buffer and trade funds to them.

This keeps the process fair regardless of which side funds first. The party who
funds is protected, while the party who doesn't bears the cost of their
collateral.

### Funding

Parties are only required to fund the difference between their collateral and
the trade amount. This calculation is built into the StableFX Fund APIs.


# StableFX Technical Guide
Source: https://developers.circle.com/stablefx/concepts/technical-guide

Technical implementation details for StableFX

StableFX is a foreign exchange (FX) platform that enables onchain stablecoin
conversion between fiat-backed currencies such as USDC and EURC.

Built on [Arc](https://docs.arc.io), StableFX combines offchain
Request-for-Quote (RFQ) execution with onchain settlement. This allows you to
execute stablecoin FX transactions that are fast, auditable, and programmable.

<Note>
  **Note:** The StableFX execution engine provides offchain API methods for
  performing the onchain settlements. It's possible to integrate with StableFX
  without broadcasting any onchain transactions.
</Note>

## Architecture

StableFX is composed of modular layers that form the FX infrastructure:

<Frame>
  <img />
</Frame>

StableFX uses an RFQ model for pricing. A taker (for example, a fintech,
exchange, or corporate treasury) requests a quote for a supported stablecoin
pair. Approved makers (liquidity providers) return executable quotes.

### Execution engine

The execution engine is the offchain API that manages RFQ distribution,
validation, and quote ranking between takers and makers. It provides an offchain
API that can be used for price discovery, quote creation, and trade execution.

The execution engine collects signatures and broadcasts them to the onchain
contract for participants in StableFX.

### Settlement contract

The settlement contract is the smart contract on Arc that performs onchain
escrow and delivery of both sides of a trade. Participants in StableFX can use
the execution engine to submit their onchain transactions, or integrate with the
smart contract directly, depending on their technical requirements.

## Quote request and trade execution

The following sections describe the quote request and trade execution process.

### API keys

The StableFX API uses your API key for authentication and to determine which
data to use and which blockchain to execute against. You will initially receive
a `TEST` API key which executes against Arc testnet. When you are ready to move
to production, you can request a `LIVE` API key which executes against Arc
mainnet.

### Quote request

Takers use the StableFX API to request quotes. The taker can specify the amount
of the sell currency or the buy currency in the quote request. The full quote
request has the following properties:

* `from.currency`: The currency of the sell currency
* `from.amount`: The amount of the sell currency
* `to.currency`: The currency of the buy currency
* `to.amount`: The amount of the buy currency
* `tenor`: The settlement schedule for the trade

The `tenor` parameter specifies how long the trade should take to settle. The
available settlement schedules are `instant`, `hourly`, and `daily`.

* `instant`: the settlement window is 30 minutes from trade creation
* `hourly`: the settlement window is 1 hour from trade creation
* `daily`: the settlement window is 1 day from trade creation

The taker receives a quote response from the execution engine, depending on the
maker responses. The response time from RFQ submission to quote response is less
than 500 ms. The execution engine takes the best priced quote from all maker
responses. The quote response contains a summary of the quote, the StableFX fee,
and the expiry of the quote.

For a full specification of the quote request and response, see the
[Request a quote](/api-reference/stablefx/all/create-quote) endpoint.

Quote requests can fail. Common reasons for failure include:

* Invalid currency pair
* Amount less than the minimum trade amount (\< 10 USDC)

### Quote flow and fee calculation

The quote flow varies depending on what the taker specifies in their quote
request.

**If the taker specifies an amount of the buy currency:**

1. StableFX calculates the taker fee in the sell currency and adds the fee on
   top of the requested buy amount when requesting a quote from Talos
2. Talos returns a quote for the combined amount
3. StableFX returns to the taker the quoted combined amount and the fee in the
   buy currency; the taker understands that they receive the combined amount
   minus the fee

This flow ensures that the maker and the taker view the same quote amount, while
the fee is transparent to the taker.

**If the taker specifies an amount of the sell currency:**

1. StableFX sends the requested sell amount to Talos with no fee adjustment
2. Talos returns a quote for the requested sell amount
3. StableFX returns both the from and to amounts to the taker and separately
   adds the taker fee in the sell currency

The maker fee is not shown to the taker.

### Maker quote response

StableFX requests quotes from makers via the Talos platform. Makers choose the
rate of exchange for their quote response.

Circle has a subaccount in Talos for each settlement tenor. For makers, each
subaccount is a unique customer, so through Talos they must support each of the
settlement tenor customers.

### Quote acceptance

The taker accepts the quote by creating a trade through the execution engine.
Creating the trade requires the quote ID and a randomly generated idempotency
key. At this point, the quoted rate is locked in. This rate lock lasts until the
trade expires, is settled, or is breached.

## Trade signature broadcasting

After the taker confirms the quote, the maker and taker submit their trade
signatures to StableFX. StableFX verifies the signatures and broadcasts a
contract function call to the smart contract. There is a 10 minute window for
the maker and taker to submit signatures, or the trade will expire.

The broadcast parameters include the maker and taker details including the trade
consideration and signatures.

## Trade settlement

The `FxEscrow` smart contract is used to settle the trade. This contract uses
the `Permit2` contract to allow it to pull a specified amount of currency from
the maker and taker wallets to the contract.

### Settlement model

StableFX implements a settlement model that is characterized by:

* Explicit taker funding
* Maker-triggered settlement

When settlement occurs, the StableFX smart contract makes the following token
transfers:

* **To the taker**: the buy currency minus the taker fee
* **To the maker**: the sell currency minus the maker fee
* **To the StableFX fee wallet**: the StableFX taker fee in the buy currency and
  the StableFX maker fee in the sell currency

This ensures net settlement while maintaining transparency and alignment with
the quote presented to both parties.

### Wallets and funding

Makers and takers can use any Arc supported wallet to fund trades. Both makers
and takers must use the same wallet throughout the course of a single trade.
Wallets must be individually owned and not omnibus wallets.

Wallets must support the
[`Permit2`](https://docs.uniswap.org/contracts/permit2/overview) contract and be
capable of signing EIP-712 typed data without broadcasting the transaction.
Users must approve the `Permit2` contract through the specific token contract
they're using to fund trades.

### Taker funding

To fund trades, the taker submits a signed `Permit2` request to the `FxEscrow`
smart contract for trades with `pending_settlement` status using the contract
trade identifiers. This can be done with the StableFX API or by directly
transacting with the `FxEscrow` contract. The contract holds the taker funded
tokens until the trade is settled or breached.

### Maker funding

The maker initiates a settlement transaction by funding trades that have been
taker funded. When a maker identifies trades with status `taker_funded` they can
submit a fund request to the FxEscrow smart contract. This can be done with the
StableFX API or by directly transacting with the FxEscrow contract.

#### Maker net funding

Makers can fund the net position of their accumulated trades with a given taker.
This is done by calculating the net position and only submitting the funds
required to cover the net position. For example, if a maker has an open trade
with a taker where they are selling 100 USDC and buying 90 EURC, and another
open trade with the same taker where they are selling 90 EURC and buying 100
USDC, their net position is 0. They would not need to submit any funds to the
`FxEscrow` contract.


# How-to: Connect Your Wallet
Source: https://developers.circle.com/stablefx/howtos/connect-wallet-console

Connect an EVM-compatible wallet to the StableFX Console for signing and funding trades.

Connect an EVM-compatible wallet (such as MetaMask or a WalletConnect-supported
wallet) to the [StableFX Console](/stablefx/concepts/console-overview) for
signing trades and funding settlements onchain. The console uses
[Dynamic.xyz](https://www.dynamic.xyz/) for wallet connection and supports any
wallet that can sign EIP-712 typed data.

## Prerequisites

Before you begin:

* You have a Circle account with StableFX access. Contact your Circle
  representative if you do not have one.
* You have an EVM-compatible wallet (such as MetaMask or any
  WalletConnect-supported wallet).
* You have the wallet browser extension installed and unlocked, or a mobile
  wallet with WalletConnect support.

## Supported wallets

The console supports wallets that are compatible with the EVM and can sign
EIP-712 typed data (a standard for structured, human-readable signing requests
used by DeFi applications). Common options include:

* **MetaMask** (browser extension or mobile)
* **WalletConnect**-compatible wallets (Rainbow, Trust Wallet, Coinbase Wallet,
  etc.)
* **Hardware wallets** connected through MetaMask (Ledger, Trezor)

## Network requirements

Your wallet must be configured for the correct network:

| Environment | Network     | Chain ID  | RPC URL                           |
| ----------- | ----------- | --------- | --------------------------------- |
| Testnet     | Arc Testnet | `5042002` | `https://rpc.testnet.arc.network` |
| Production  | Arc Mainnet | —         | Contact Circle for details        |

<Note>
  If your wallet does not have the Arc network configured, the console may
  prompt you to add it automatically. Alternatively, you can add it manually in
  your wallet's network settings.
</Note>

<Frame>
  <img />
</Frame>

## Connect during a trade flow

The most common way to connect your wallet is during the trade flow:

<Steps>
  <Step title="Start a trade">
    Open the trade form and configure your trade (currencies, amount, and
    tenor—the settlement period for the trade). Click **Continue**.
  </Step>

  <Step title="Connect wallet">
    The **Select Wallet** panel appears. Click **Connect Wallet** to open the
    wallet selector.
  </Step>

  <Step title="Choose your wallet">
    Select your wallet provider from the list. If using a browser extension like
    MetaMask, the extension popup appears. If using WalletConnect, scan the QR
    code with your mobile wallet.
  </Step>

  <Step title="Approve the connection">
    In your wallet, approve the connection request from the StableFX Console.
  </Step>

  <Step title="Confirm your address">
    The console displays your connected wallet address. Verify it is correct and
    click **Continue** to proceed to trade confirmation.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

## Token requirements

Before you can sign and fund trades, your wallet needs:

### Sufficient token balance

Your wallet must hold enough tokens to cover:

* The **trade amount** (the currency you are selling)
* The **collateral** (risk buffer), if applicable

The console checks your balance before allowing you to proceed.

### Permit2 approval

StableFX uses the [Permit2](https://github.com/Uniswap/permit2) contract for
gas-efficient token transfers. You must approve the Permit2 contract to spend
your tokens.

* **First-time setup**: The console detects if you have not approved Permit2 and
  prompts you to do so during the trade flow. Your wallet displays a standard
  ERC-20 approval transaction.
* **One-time per token**: You only need to approve Permit2 once per token. After
  approval, all subsequent trades use Permit2 signatures (no additional onchain
  approval transactions).
* **Manual approval**: You can also approve Permit2 ahead of time. See
  [Grant USDC allowance to Permit2](/stablefx/howtos/grant-usdc-allowance-permit2).

The Permit2 contract address is `0x000000000022D473030F116dDEE9F6B43aC78BA3`.

## Wallet persistence

Your wallet connection persists across page loads in the same browser session.
If you close the browser or clear cookies, you will need to reconnect.

The wallet address used for a trade is recorded as the **signer address** in the
trade details. You must use the same wallet to fund the trade.

## Troubleshooting

| Issue                            | Solution                                                                                                                                  |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Wallet not appearing in selector | Ensure the browser extension is installed and unlocked, or refresh the page.                                                              |
| Wrong network                    | Switch your wallet to the Arc network (testnet or mainnet). The console may prompt you to switch automatically.                           |
| Insufficient balance             | Add tokens to your wallet. On testnet, use the [Circle Faucet](https://faucet.circle.com/) to obtain USDC and EURC.                       |
| Permit2 approval fails           | Ensure you have enough ETH (or the native Arc token) for gas fees. Try resetting your wallet's transaction history if the nonce is stale. |
| Signature rejected               | If you reject a signature in your wallet, the console displays an error. You can retry by clicking the sign button again.                 |

Once your wallet is connected and funded, you are ready to execute trades. For a
guided walkthrough of your first trade, see
[Execute your first trade in the console](/stablefx/quickstarts/console-first-trade).
For the full taker trade creation flow, see
[Create a trade in the console](/stablefx/howtos/create-trade-console).


# How-to: Create a Trade in the Console
Source: https://developers.circle.com/stablefx/howtos/create-trade-console

Request a quote, sign with your wallet, and execute a trade from the StableFX Console.

Create a taker trade in the StableFX Console by requesting a quote, connecting
your wallet, locking the exchange rate, and signing the trade. Use this workflow
when you want to execute a trade through the console UI without integrating with
the StableFX API directly.

## Prerequisites

Before you begin:

* You have an active StableFX account with **Taker** access.
* You have connected an EVM-compatible wallet to Arc (testnet or mainnet).
* You have a sufficient token balance for the trade amount plus collateral.
* You have granted Permit2 contract approval for the token you are selling. See
  [Grant USDC allowance to Permit2](/stablefx/howtos/grant-usdc-allowance-permit2).

<Frame>
  <img />
</Frame>

## Open the trade form

You can start a new trade from multiple entry points:

* **Home page**: Click **Trade** in the trade card.
* **Overview page**: Click **New Trade** in the toolbar.
* **Trades page**: Click **New Trade** in the top-right corner.

The trade form opens in a side panel on the right.

## Configure the trade

### Select currencies

Choose the **From** and **To** currencies using the dropdowns. One side of every
pair must be USDC.

Supported pairs include:

* USDC / EURC
* EURC / USDC

<Note>
  Additional currency pairs (such as USDC/MXNB and USDC/AUDF) may be available
  depending on your account configuration and the current StableFX network.
</Note>

### Enter the amount

Enter an amount in either the **From** or **To** field—not both. The console
fetches a reference quote and auto-fills the other side based on the current
exchange rate.

* Amounts support up to **6 decimal places**.
* There is a minimum trade amount enforced by the API. If your amount is too
  low, the console displays an error.
* The quote refreshes automatically every **3 seconds** while the form is open.

### Choose a settlement tenor

Select how quickly the trade should settle:

| Tenor       | Settlement window | Description                                             |
| ----------- | ----------------- | ------------------------------------------------------- |
| **Instant** | 30 minutes        | Both parties must fund in 30 minutes of trade creation. |
| **Hourly**  | 1 hour            | Settlement deadline is 1 hour after trade creation.     |
| **Daily**   | 24 hours          | Settlement deadline is 24 hours after trade creation.   |

<Tip>
  Shorter tenors reduce counterparty risk but require faster funding. `instant`
  is a good default for your first trade.
</Tip>

### Review the rate

The **Quote Rate Card** at the bottom of the form shows the current exchange
rate. This is a reference rate—the final rate is locked when you create the
trade in the confirmation step.

## Connect your wallet

Click **Continue** to proceed to wallet selection.

If you haven't connected a wallet yet, see
[Connect your wallet to the StableFX Console](/stablefx/howtos/connect-wallet-console)
for step-by-step instructions. The console uses
[Dynamic.xyz](https://www.dynamic.xyz/) for wallet connection and supports any
EVM-compatible wallet.

Once connected, verify that the displayed wallet address is correct and click
**Continue**.

<Warning>
  Your connected wallet must have:

  * Sufficient balance for the trade amount **plus** collateral (risk buffer).
  * An active Permit2 approval for the token you are selling. The console prompts
    you to approve if needed.
</Warning>

## Lock the rate and create the trade

<Frame>
  <img />
</Frame>

The confirmation panel shows a live **tradable quote** with the exact terms of
the trade:

* **Rate**: The current exchange rate, refreshing every 3 seconds.
* **From / To amounts**: The exact token amounts for both sides.
* **Fee**: The trading fee, denominated in the "to" currency.
* **Collateral**: The risk buffer amount held temporarily to cover potential
  non-settlement (denominated in the "from" currency), if applicable. See
  [Risk Buffers](/stablefx/concepts/risk-buffers).
* **Settlement tenor**: The selected settlement window.
* **Expiration**: When the quote expires.

When you are ready:

1. Click **Lock Rate & Continue**.
2. If this is your first trade with this token, your wallet prompts you to
   approve the Permit2 contract (a one-time ERC-20 approval).
3. Your wallet then prompts you to sign **EIP-712 typed data**. This signature
   authorizes the trade at the displayed rate. Review the details in your wallet
   and confirm.

The console submits the signed trade and displays the result:

<Frame>
  <img />
</Frame>

* **Success**: The trade is created with status `pending_settlement`. You can
  proceed to [fund the trade](/stablefx/howtos/settle-trades-console).
* **Failure**: If the quote expired or another error occurred, the console
  displays an error message. You can retry with a new quote.

## Alternative: manual signature

If you prefer to sign the typed data outside the console (for example, using a
hardware wallet or a custom signing tool):

1. In the confirmation panel, click **Sign manually** to view the raw EIP-712
   typed data.
2. Copy the typed data and sign it with your preferred tool.
3. Paste the resulting signature back into the console and submit.

## See also

* [Trade states](/stablefx/references/trade-states): Full state machine and
  status definitions.
* [Settle trades in the console](/stablefx/howtos/settle-trades-console): Fund
  individual or batch trades after creation.
* [Fulfill a trade as a maker](/stablefx/howtos/fulfill-trade-console): The
  maker-side workflow for signing and funding.
* [Grant USDC allowance to Permit2](/stablefx/howtos/grant-usdc-allowance-permit2):
  Set up the onchain token approval.
* [Console overview](/stablefx/concepts/console-overview): Console features,
  pages, and how trading works.


# How-to: Fulfill a Trade as a Maker
Source: https://developers.circle.com/stablefx/howtos/fulfill-trade-console

Review, sign, and fund confirmed trades from the maker view in the StableFX Console.

As a maker in the StableFX Console, you switch to the maker view to see trades
where you are the counterparty, sign confirmed trades with your EVM wallet to
authorize fulfillment, then fund your side of the settlement so the FxEscrow
contract can settle the trade onchain.

## Prerequisites

Before you begin:

* You have an active StableFX account with
  [**Maker** access](/stablefx/references/console-roles-permissions).
* You have connected an EVM-compatible wallet to Arc (testnet or mainnet). See
  [Connect your wallet](/stablefx/howtos/connect-wallet-console).
* You have funded your wallet with sufficient token balance for the trade amount
  plus [collateral](/stablefx/concepts/risk-buffers).
* You have approved the Permit2 contract for your funding token. See
  [Grant USDC allowance to Permit2](/stablefx/howtos/grant-usdc-allowance-permit2).

## Switch to maker view

The console defaults to the Taker view. To switch:

1. Navigate to the **Overview** or **Trades** page.
2. In the left sidebar, click the **account type dropdown** (labeled "Taker" or
   "Maker").
3. Select **Maker**.

The page refreshes to show maker-specific data. The trades table now displays
trades where you are the counterparty.

<Note>
  Your account type selection is stored as a session preference. It persists
  across page loads but resets when you switch browsers or clear cookies.
</Note>

## Review confirmed trades

In the **Trades** page (maker view), look for trades with `confirmed` status.
These are trades where a taker has accepted a quote and created the trade, but
the maker has not yet signed.

Click on a confirmed trade to open the **Trade Details** side panel. The panel
has two tabs:

<Frame>
  <img />
</Frame>

* **Details**: Shows the trade terms (currency pair, amounts, rate, fee,
  collateral, tenor, and maturity time).
* **Activity**: Shows the settlement path and onchain transaction history.

<Note>
  In the maker view, the console swaps the display of trade direction to match
  your perspective: the top of the trade card shows the currency and amount you
  are delivering, and the bottom shows what you receive. This is the inverse of
  the taker's view for the same trade.
</Note>

## Sign the trade

Signing a trade confirms your intent to fulfill it. This is required before
either party can fund.

<Steps>
  <Step title="Click Sign">
    In the trade details panel, click **Sign**. The console opens the signing flow.
  </Step>

  <Step title="Connect your wallet">
    If your wallet is not already connected, the console prompts you to
    [connect it](/stablefx/howtos/connect-wallet-console). The wallet address
    you connect is the address that will fund and receive settlement tokens.
  </Step>

  <Step title="Review and sign">
    Your wallet displays EIP-712 typed data containing the trade details. Review:

    * The token amounts and currencies
    * The trade ID and contract trade ID
    * The spender (FxEscrow contract address)

    Confirm the signature in your wallet.
  </Step>

  <Step title="Confirm submission">
    The console submits your signature. The trade status updates to
    `pending_settlement`, meaning both sides can now fund.
  </Step>
</Steps>

### Manual signature option

If you prefer to sign outside the console:

1. Click **Sign manually** to view the raw EIP-712 typed data (the "presign"
   data).
2. Copy the typed data and sign it with your preferred signing tool.
3. Return to the console, click **Register signature**, paste the signature, and
   submit.

<Tip>
  Makers who integrate via [Talos](/stablefx/concepts/maker-talos-integration)
  can receive trade notifications directly and sign via the API. The console
  provides a complementary manual interface.
</Tip>

## Fund the trade

After both parties have signed, the trade moves to `pending_settlement`. You can
now fund your side.

<Steps>
  <Step title="Open the trade">
    On the Trades page, click a trade with `pending_settlement` or
    `taker_funded` status.
  </Step>

  <Step title="Click Fund">
    In the trade details panel, click **Fund**. The funding side panel opens.
  </Step>

  <Step title="Choose funding mode">
    As a maker, you can choose a **funding mode**:

    * **Gross**: Fund each trade individually at its full amount.
    * **Net**: Fund the net position across multiple trades. To fund net across
      multiple trades, see
      [Settle trades in batch](/stablefx/howtos/settle-trades-console).
  </Step>

  <Step title="Review deliverables and receivables">
    The panel shows:

    * **Deliverables**: The tokens and amounts you send to the FxEscrow contract.
    * **Receivables**: The tokens and amounts you receive after settlement.
  </Step>

  <Step title="Sign and submit">
    Click **Fund Trade**. Your wallet prompts you to sign Permit2 typed data.
    Permit2 is a token-approval contract that lets you authorize token transfers
    with a single offchain signature rather than a separate onchain approve
    transaction. Confirm in your wallet.
  </Step>
</Steps>

Once you fund, the trade status updates:

* If the taker has already funded → trade moves to `complete`.
* If the taker has not funded yet → trade moves to `maker_funded`, and the taker
  must fund before the maturity deadline.
* If the maturity deadline passes before both sides fund → trade moves to
  `breaching` and then `breached`.

<Warning>
  **If your wallet rejects or the signing flow fails**: Close the panel and reopen
  the trade to restart the signing or funding step. No state is written onchain
  until you confirm in your wallet, so the trade remains in its current status.

  **If the trade reaches its maturity deadline before both parties fund**: The
  trade is no longer eligible for settlement and moves to `breached` status. You
  must create a new trade.
</Warning>

## See also

* [Settle trades in batch](/stablefx/howtos/settle-trades-console)
* [Trade states](/stablefx/references/trade-states)
* [Risk buffers](/stablefx/concepts/risk-buffers)


# Grant USDC Allowance to Permit2
Source: https://developers.circle.com/stablefx/howtos/grant-usdc-allowance-permit2

Use Uniswap's Permit2 contract to grant USDC allowance to the StableFX FxEscrow contract

This guide shows an example of how to grant a USDC token allowance to the
`Permit2` contract using a Circle Wallets developer-controlled wallet. The
[`Permit2` documentation](https://docs.uniswap.org/contracts/permit2/overview)
provides additional examples of how to grant this allowance.

When using the [StableFX API](/stablefx/concepts/technical-guide) to deliver the
funds onchain for an FX trade, you must grant an allowance to the
[`Permit2` contract](https://docs.arc.io/arc/references/contract-addresses#permit2)
for the token you are funding. This allows the `Permit2` contract to transfer
the token from your wallet to the `FxEscrow` contract.

## Prerequisites

Before you begin, ensure you have:

* A [Circle Developer Console](https://console.circle.com/) account.

* A
  [developer-controlled wallet](/wallets/dev-controlled/create-your-first-wallet)

* [Node.js 18+](https://nodejs.org/) installed.

* A project set up as described in the below section

### Set up your project

1. Initialize a new Node.js project and install dependencies:

   ```shell theme={null}
   npm init -y
   npm pkg set type=module
   npm install viem dotenv
   ```

2. In the project root, create a `.env` file and add the following variables:

   ```shell theme={null}
   USDC_CONTRACT_ADDRESS=<USDC_CONTRACT_ADDRESS>
   PERMIT2_CONTRACT_ADDRESS=<PERMIT2_CONTRACT_ADDRESS>
   APPROVAL_AMOUNT=<APPROVAL_AMOUNT>
   WALLET_ADDRESS=<WALLET_ADDRESS>
   ```

   The `PERMIT2_CONTRACT_ADDRESS` is the same across all EVM blockchains
   (`0x000000000022D473030F116dDEE9F6B43aC78BA3`), but you should verify it with
   the blockchain explorer on the chain you are using. You can find the
   `USDC_CONTRACT_ADDRESS` on the
   [USDC contract address page](/stablecoins/usdc-contract-addresses).

   <Note>
     The USDC token has 6 decimals. To approve \$100 USDC, set `APPROVAL_AMOUNT` to
     `100000000` (100 \* 10<sup>6</sup>).
   </Note>

   If you are following the Circle Wallets example, you will also need to add
   the following variables:

   ```shell theme={null}
   CIRCLE_WALLET_ID=<CIRCLE_WALLET_ID>
   CIRCLE_WALLETS_API_KEY=<CIRCLE_WALLETS_API_KEY>
   ENTITY_SECRET=<ENTITY_SECRET>
   ```

   If you are not funding USDC, you need to grant allowance using the contract
   address of the token you are funding.

3. Create an `index.js` file. You'll add code step by step in the following
   sections.

### Grant a USDC token allowance to the `Permit2` contract

Add the following code to your `index.js` file to grant a USDC token allowance
to the `Permit2` contract using a Circle Wallets developer-controlled wallet on
supported EVM blockchains.

```javascript theme={null}
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
import { randomUUID } from "crypto";
import dotenv from "dotenv";

dotenv.config();

/**
 * Approves a specified amount of USDC for the Permit2 contract using
 * a developer-controlled wallet managed by Circle.
 *
 * This function sends an on-chain transaction to call the ERC-20 `approve`
 * method on the USDC contract, allowing the Permit2 contract to spend
 * the specified amount on behalf of the wallet.
 *
 * @async
 * @function approveUSDCWithCircleWallets
 * @returns {Promise<object>} The transaction response data returned by Circle's API.
 */
export async function approveUSDCWithCircleWallets() {
  const client = initiateDeveloperControlledWalletsClient({
    apiKey: process.env.CIRCLE_WALLETS_API_KEY,
    entitySecret: process.env.ENTITY_SECRET,
  });

  const response = await client.createContractExecutionTransaction({
    walletId: process.env.CIRCLE_WALLET_ID,
    contractAddress: process.env.USDC_CONTRACT_ADDRESS,
    abiFunctionSignature: "approve(address,uint256)",
    abiParameters: [
      process.env.PERMIT2_CONTRACT_ADDRESS,
      process.env.APPROVAL_AMOUNT,
    ],
    idempotencyKey: randomUUID(),
    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
  });

  return response.data;
}

/* -------- Example usage with Circle ---------

// For auth and wallet creation, see: https://developers.circle.com/interactive-quickstarts/dev-controlled-wallets
const response = await approveUSDCWithCircleWallets();
console.log('Response:', response);

---------------------------------- */
```


# How-to: Settle Trades in the Console
Source: https://developers.circle.com/stablefx/howtos/settle-trades-console

Fund individual trades or batch-settle multiple trades from the StableFX Console.

After you have [created a trade](/stablefx/howtos/create-trade-console) and
[both parties have signed](/stablefx/howtos/fulfill-trade-console), the trade
needs to be funded onchain for settlement to occur. The StableFX Console
provides two ways to fund: **individual funding** for a single trade, or **batch
funding** to settle multiple trades in a single transaction.

## Prerequisites

Before you begin:

* You have connected an EVM wallet with sufficient token balance.
* You have granted Permit2 approval for the funding token.
  [Permit2](https://docs.uniswap.org/contracts/permit2/overview) is a
  token-approval contract that lets you authorize token transfers with a single
  offchain signature rather than a separate onchain approve transaction.
* You have one or more trades in a fundable status (`pending_settlement`,
  `taker_funded`, or `maker_funded`, depending on your role). See
  [Trade states](/stablefx/references/trade-states) for a description of each
  status.

<Frame>
  <img />
</Frame>

## Individual trade funding

<Steps>
  <Step title="Navigate to Trades">
    Go to the **Trades** page from the sidebar navigation.
  </Step>

  <Step title="Open a fundable trade">
    Click on any trade that shows the **Fund** action. Fundable trades have one of
    these statuses:

    | Your role | Fundable when status is                |
    | --------- | -------------------------------------- |
    | Taker     | `pending_settlement` or `maker_funded` |
    | Maker     | `pending_settlement` or `taker_funded` |
  </Step>

  <Step title="Click Fund">
    In the trade details side panel, click **Fund** to open the funding flow.
  </Step>

  <Step title="Review and sign">
    The funding panel displays your deliverables (what you send to escrow) and
    receivables (what you get after settlement). Click **Fund Trade** and confirm
    the Permit2 signature in your wallet.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

<Frame>
  <img />
</Frame>

## Batch funding

Batch funding lets you settle multiple trades in a single wallet signature. This
is especially useful for makers who accumulate many trades throughout a
settlement window.

<Steps>
  <Step title="Enter batch mode">
    <Frame>
      <img />
    </Frame>

    On the **Trades** page, click **Batch fund** in the toolbar. The table
    switches to selection mode with checkboxes on each row.
  </Step>

  <Step title="Select trades">
    Check the trades you want to fund. Only trades in a fundable status appear as
    selectable. The console automatically filters out trades that are not eligible.
  </Step>

  <Step title="Review the batch">
    A summary bar at the bottom shows:

    * Number of selected trades
    * Total deliverables (aggregated by currency)
    * Total receivables (aggregated by currency)
  </Step>

  <Step title="Choose funding mode">
    If you are a **maker**, choose between:

    * **Gross**: Fund each trade at its full amount. The total deliverable is the
      sum of all individual trade amounts.
    * **Net**: Fund the net position across all selected trades. If you have
      offsetting trades (for example, selling USDC in one trade and buying USDC in
      another), the net amount is reduced accordingly.

    <Tip>
      Netting applies across all selected trades regardless of counterparty. You
      cannot net at the individual counterparty level.
    </Tip>

    If you are a **taker**, skip this step. Takers always fund in gross mode.
  </Step>

  <Step title="Sign and submit">
    Click **Fund All**. Your wallet prompts you to sign Permit2 batch typed data
    covering all selected trades. Confirm the signature.
  </Step>
</Steps>

## Funding modes explained

| Mode      | Behavior                                                                              | Best for                                                                |
| --------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Gross** | Each trade is funded at its full notional amount.                                     | Takers (always gross), or makers who want explicit per-trade funding.   |
| **Net**   | Opposing positions in the same currency are offset. You fund only the net difference. | Makers with many trades in the same pair. Reduces capital requirements. |

<Note>
  Takers always fund in gross mode. The net funding option is available only to
  makers.
</Note>

## What happens after funding

Once you submit your funding signature:

1. The console broadcasts the transaction through the StableFX execution engine.
2. The FxEscrow smart contract on Arc receives and holds your tokens in escrow.
3. When both parties have funded, the contract settles the trade automatically:
   * The taker receives the "to" currency minus the taker fee.
   * The maker receives the "from" currency minus the maker fee.
   * Fees are sent to the fee wallet.

The trade status updates to `complete`, and the settlement tokens appear in your
wallet.

## Monitoring settlement

<Frame>
  <img />
</Frame>

You can track each trade's onchain progress in the **Activity** tab of the trade
details panel. It shows:

* The contract trade ID
* Each onchain transaction (record, taker deliver, maker deliver, settle)
* Transaction hashes and timestamps
* Current status of each step

The trades table on the main page auto-refreshes every **30 seconds**. Click
into a specific trade for faster polling (every **3 seconds**).

## Handling breaches

If one or both parties fail to fund before the settlement deadline (determined
by the tenor, which is the agreed duration of the trade from creation to
settlement expiry), the trade enters a `breaching` state and eventually becomes
`breached`. See [Trade states](/stablefx/references/trade-states) for details on
these statuses.

When a trade is breached:

* The funded party's tokens are returned from escrow.
* Any collateral (risk buffer) from the non-funding party is forfeited.
* The trade cannot be retried. You must create a new trade.

See [Risk Buffers](/stablefx/concepts/risk-buffers) for details on how
collateral protects against breaches.

## See also

* [Creating a trade](/stablefx/howtos/create-trade-console)
* [Fulfilling a trade](/stablefx/howtos/fulfill-trade-console)
* [Trade states](/stablefx/references/trade-states)
* [Risk buffers](/stablefx/concepts/risk-buffers)


# Setup StableFX Webhook Notifications
Source: https://developers.circle.com/stablefx/howtos/setup-webhook-notifications

Configure a notification subscriber endpoint and be notified when events occur

During the trade lifecycle, StableFX can send notifications to your subscriber
endpoint using webhooks. These asynchronous notifications inform you on the
progress of the trade and any issues that may arise.

This guide demonstrates how to subscribe to StableFX webhook notifications. This
applies to both takers and makers. See the Webhooks section of the
[API reference](/api-reference/stablefx/all/trade-confirmed) for a complete list
of the StableFX notifications that are sent over webhooks. See the
[Trade States](/stablefx/references/trade-states) page for a summary of the
lifecycle of a trade.

## Steps

Use the following steps to set up a webhook endpoint and subscribe to
notifications using the StableFX API.

### Step 1: Set up a subscriber endpoint

To receive notifications on changes in trade status, you must expose a publicly
accessible subscriber endpoint on your side. The endpoint must handle both
`HEAD` and `POST` requests over HTTPS. When a `POST` request is received, the
endpoint must respond with a `200 OK` status code.

For testing purposes, you can create an endpoint using
[webhook.site](https://webhook.site/).

### Step 2: Subscribe to notifications

Set up your subscriber endpoint to receive notifications from the StableFX API
using the [Create subscription](/api-reference/stablefx/all/create-subscription)
endpoint.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v2/stablefx/notifications/subscriptions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endpoint": "${YOUR_WEBHOOK_ENDPOINT}",
  "notificationTypes": ["*"]
}
'
```

**Example response**

```json theme={null}
{
  "data": {
    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "name": "Transactions Webhook",
    "endpoint": "https://example.org/handler/for/notifications",
    "enabled": true,
    "createDate": "2026-01-01T12:04:05Z",
    "updateDate": "2026-01-01T12:04:05Z",
    "notificationTypes": ["*"],
    "restricted": false
  }
}
```


# Verify Webhook Signatures for StableFX
Source: https://developers.circle.com/stablefx/howtos/verify-webhook-signatures

Verify the integrity of StableFX webhook notifications

Every webhook notification sent by StableFX is digitally signed with an
asymmetric key. This guide demonstrates how to use the key and signature to
verify that a webhook notification was sent by Circle. Validating webhooks in
this way can reduce the risk of person-in-the-middle attacks on your subscriber
endpoint.

## Steps

Use the following steps to verify the Circle signature on a webhook
notification.

### Step 1: Verify the request came from an allowlisted IP address

StableFX webhooks are sent only from a fixed set of Circle IP addresses. Before
processing or verifying the payload, confirm that the incoming request’s source
IP is one of the following:

* `3.230.111.7`
* `3.90.127.28`
* `35.169.154.32`
* `54.88.227.75`

Reject requests from any other IP with an appropriate error response (for
example, 403 Forbidden). This reduces exposure to requests that do not originate
from Circle.

### Step 2: Get the digital signature and ID of the notification

Every webhook notification is digitally signed with an asymmetric key. The
asymmetric key is random for each webhook, so you must perform this full
authentication flow to validate the key. This signature is available in the
header of the message. Each message contains the following headers:

* `X-Circle-Signature`: the digital signature generated by Circle
* `X-Circle-Key-Id`: the public key ID in UUID format

Extract those values from the header of the webhook message.

### Step 3: Fetch the public key and verify the signature

Using the `X-Circle-Key-Id` value, query the
[`/v2/stablefx/notifications/publicKey/{id}`](/api-reference/stablefx/all/get-notification-signature)
endpoint to retrieve the public key, then use it to verify the signature.

<Tip>
  Ensure that you read the raw request body as a string for signature
  verification. Parsing and re-serializing the JSON can change whitespace or key
  ordering, causing verification to fail.
</Tip>

The following TypeScript code demonstrates a complete webhook verification flow:

```typescript TypeScript theme={null}
import { createVerify, createPublicKey, KeyObject } from "crypto";

const CIRCLE_API_KEY = process.env.CIRCLE_API_KEY!;

// StableFX webhooks are sent only from these IP addresses
const ALLOWLISTED_IPS = new Set([
  "3.230.111.7",
  "3.90.127.28",
  "35.169.154.32",
  "54.88.227.75",
]);

// Cache for public keys to avoid repeated API calls
const publicKeyCache = new Map<string, KeyObject>();

async function getPublicKey(keyId: string): Promise<KeyObject> {
  // Check cache first
  const cachedKey = publicKeyCache.get(keyId);
  if (cachedKey) {
    return cachedKey;
  }

  // Fetch the public key from Circle's API
  const response = await fetch(
    `https://api.circle.com/v2/stablefx/notifications/publicKey/${keyId}`,
    {
      headers: {
        Accept: "application/json",
        Authorization: `Bearer ${CIRCLE_API_KEY}`,
      },
    },
  );

  if (!response.ok) {
    throw new Error(`Failed to fetch public key: ${response.statusText}`);
  }

  const { data } = await response.json();
  const publicKeyDer = Buffer.from(data.publicKey, "base64");

  // Convert DER-encoded public key to a KeyObject
  const publicKey = createPublicKey({
    key: publicKeyDer,
    format: "der",
    type: "spki",
  });

  // Cache the key for future use
  publicKeyCache.set(keyId, publicKey);

  return publicKey;
}

function verifySignature(
  publicKey: KeyObject,
  signature: string,
  payload: string,
): boolean {
  const signatureBytes = Buffer.from(signature, "base64");

  const verifier = createVerify("SHA256");
  verifier.update(payload);
  verifier.end();

  return verifier.verify(publicKey, signatureBytes);
}

// Example webhook handler
async function handleWebhook(request: Request): Promise<Response> {
  // Step 1: Verify the request came from an allowlisted IP
  // In production, get the client IP from your platform (e.g. X-Forwarded-For,
  // X-Real-IP, or request connection remoteAddress)
  const clientIp =
    request.headers.get("X-Forwarded-For")?.split(",")[0]?.trim() ??
    request.headers.get("X-Real-IP") ??
    "unknown";
  if (!ALLOWLISTED_IPS.has(clientIp)) {
    return new Response("Forbidden", { status: 403 });
  }

  // Step 2: Extract signature headers
  const signature = request.headers.get("X-Circle-Signature");
  const keyId = request.headers.get("X-Circle-Key-Id");

  if (!signature || !keyId) {
    return new Response("Missing signature headers", { status: 401 });
  }

  // Get the raw request body
  const payload = await request.text();

  try {
    // Step 3: Fetch the public key and verify the signature
    const publicKey = await getPublicKey(keyId);
    const isValid = verifySignature(publicKey, signature, payload);

    if (!isValid) {
      return new Response("Invalid signature", { status: 401 });
    }

    // Signature is valid - process the webhook
    const webhookData = JSON.parse(payload);
    console.log("Verified webhook:", webhookData.notificationType);

    // Handle the webhook event...

    return new Response("OK", { status: 200 });
  } catch (error) {
    console.error("Webhook verification failed:", error);
    return new Response("Verification failed", { status: 401 });
  }
}
```

<Note>
  The example includes a simple in-memory cache for public keys. In a production
  environment, consider using a more robust caching solution like Redis.
</Note>


# Execute Your First Trade in the Console
Source: https://developers.circle.com/stablefx/quickstarts/console-first-trade

Go from zero to your first StableFX trade using the console UI — no code required.

By the end of this quickstart, you will have requested a quote, signed a trade
with your wallet, and funded a settlement onchain.

## Prerequisites

Before you begin, ensure you have:

* Created a **Circle account** with StableFX access. If you don't have one,
  contact your Circle representative.
* Connected an **EVM-compatible wallet** (such as MetaMask or any
  WalletConnect-supported wallet) with a balance on the Arc network.
* Funded your wallet with **USDC or EURC** tokens on Arc.
* Granted **Permit2 approval** for your tokens. Permit2 is a smart contract that
  enables offchain signature-based token approvals, reducing the number of
  onchain transactions required. If you haven't done this, see
  [Granting USDC allowance with Permit2](/stablefx/howtos/grant-usdc-allowance-permit2).
  The console also prompts you during the trade flow if approval is missing.

<Note>
  For testnet, your wallet must be connected to Arc Testnet (chain ID `5042002`,
  RPC `https://rpc.testnet.arc.network`). You can obtain test USDC and EURC from
  the [Circle Faucet](https://faucet.circle.com/).
</Note>

## Step 1: Sign in and complete onboarding

<Steps>
  <Step title="Navigate to the console">
    Go to the [StableFX Console](https://portal.circle.com/fx/home) and sign in
    with your Circle account credentials.
  </Step>

  <Step title="Complete KYB verification">
    If this is your first time, the Home page displays your onboarding status.
    Click **Start onboarding** to begin the KYB (Know Your Business)
    verification process. You will be redirected to the onboarding portal to
    submit required documents.
  </Step>

  <Step title="Return to the console">
    Once your application is approved, return to the console. Your Home page now
    shows live FX rates and the trade form.

    <Frame>
      <img />
    </Frame>
  </Step>
</Steps>

## Step 2: Request a quote

<Steps>
  <Step title="Open the trade form">
    On the Home page, locate the **Trade** card. You can also navigate to
    **Overview** or **Trades** and click the **New Trade** button.
  </Step>

  <Step title="Configure your trade">
    In the trade form side panel:

    * Select the **From** currency and enter the amount you want to sell (for
      example, `1000 USDC`).
    * Select the **To** currency (for example, `EURC`). One side of the pair
      must always be USDC.
    * Choose a **settlement tenor** (the time window in which both parties
      must fund the trade before it expires): `instant` (30 min), `hourly`
      (1 hr), or `daily` (24 hrs).

    The console automatically fetches a reference quote and displays the estimated
    exchange rate and the amount you will receive.
  </Step>

  <Step title="Continue to wallet selection">
    Click **Continue** to proceed to the wallet connection step.
  </Step>
</Steps>

## Step 3: Connect your wallet

<Steps>
  <Step title="Select or connect a wallet">
    The console prompts you to connect an EVM-compatible wallet. If you have already
    connected a wallet in a previous session, it may be pre-selected.

    Click **Connect Wallet** and follow the prompts from your wallet provider. For
    detailed instructions, see
    [Connecting your wallet to the console](/stablefx/howtos/connect-wallet-console).
  </Step>

  <Step title="Confirm the wallet">
    Verify that the displayed wallet address is correct, then click **Continue**.
  </Step>
</Steps>

<Warning>
  The wallet you connect must hold sufficient tokens for the trade amount plus
  any collateral (risk buffer). The console checks your balance before
  proceeding.
</Warning>

## Step 4: Lock the rate and create the trade

<Steps>
  <Step title="Review the tradable quote">
    The confirmation panel displays:

    * The live exchange **rate** (refreshed every 3 seconds)
    * The exact **amounts** for both sides of the trade
    * The **fee** (denominated in the "to" currency)
    * The **collateral** (risk buffer) amount, if applicable
    * The **settlement tenor** and expiration time
  </Step>

  <Step title="Approve the Permit2 contract">
    If this is your first trade with this token, the console prompts you to approve
    the Permit2 contract. Your wallet will display an ERC-20 approval transaction.
    Confirm it in your wallet.
  </Step>

  <Step title="Sign the trade">
    Click **Lock Rate & Continue**. Your wallet prompts you to sign EIP-712 typed
    data. This signature authorizes the trade at the locked rate. Confirm the
    signature in your wallet.

    The console submits the trade and displays the result.
  </Step>
</Steps>

<Warning>
  Quotes expire after a short window. If your wallet takes too long to confirm
  the signature, the console displays a "Quote expired" error. Click **Refresh
  Quote** to fetch a new rate, then sign again. If your wallet shows an
  insufficient-balance error, add funds to cover the trade amount plus any
  collateral before retrying.
</Warning>

## Step 5: Fund the trade

After the trade is created and both parties have signed, the trade moves to
`pending_settlement` status. You can now fund your side. The maker (your
counterparty) funds their side independently through their own console session.
For details, see
[Fulfill trades as a maker](/stablefx/howtos/fulfill-trade-console).

<Steps>
  <Step title="Open the trade">
    Navigate to the **Trades** page and find your trade. Click on it to open the
    trade details side panel.
  </Step>

  <Step title="Click Fund">
    If the trade is ready for funding, the **Fund** button is available. Click
    it.
  </Step>

  <Step title="Review deliverables and receivables">
    The funding panel shows:

    * **You deliver**: The token and amount you send to escrow.
    * **You receive**: The token and amount you receive after settlement.
  </Step>

  <Step title="Sign and submit funding">
    Click **Fund Trade**. Your wallet prompts you to sign Permit2 typed data.
    This signature authorizes the token transfer to the FxEscrow contract.
    Confirm it in your wallet.
  </Step>

  <Step title="Confirm settlement">
    Once both parties have funded, the FxEscrow contract settles the trade
    automatically. The trade status updates to `complete`, and you receive the
    settlement tokens in your wallet.
  </Step>
</Steps>

<Tip>
  You can monitor the trade status in real time on the Trades page. The status
  column updates automatically every 30 seconds, or you can click a trade to see
  live updates every 3 seconds. For more on managing trade settlement, see
  [Settle trades in the console](/stablefx/howtos/settle-trades-console).
</Tip>


# Quickstart: Fulfill an FX Trade as a Maker
Source: https://developers.circle.com/stablefx/quickstarts/fx-trade-maker

Use the StableFX API to fulfill an FX trade on the maker side

This guide walks you through the steps to fulfill and execute a trade from the
maker side on StableFX.

## Prerequisites

Before you begin this quickstart, ensure you have:

* Obtained an API key for StableFX from Circle
* Set up a web3 provider or wallet that supports EIP-712 signatures
* Granted a USDC allowance to the `Permit2` contract. See
  [How-to: Grant USDC Allowance to Permit2](/stablefx/howtos/grant-usdc-allowance-permit2)
  for more information.
* cURL installed on your development machine

This quickstart provides API request examples in cURL format, along with example
responses.

<Note>
  StableFX uses a single endpoint for all API requests. The base URL is
  `https://api.circle.com/`. The StableFX API uses your API key for authentication
  and to determine which environment to use. The `TEST` environment executes
  against Arc testnet and returns mock data.

  When developing or testing your integration, you should use your `TEST` API key.
  When you are ready to move to production, just update your code to use your
  `LIVE` API key.
</Note>

## Part 1: Query for available trades

Query for trades with the `confirmed` status using the
[get trades](/api-reference/stablefx/all/list-trades) endpoint. These are trades
created by takers that are ready for maker fulfillment.

```shell theme={null}
curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/trades?type=maker&status=confirmed \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json theme={null}
{
  "data": [
    {
      "id": "c2558cd1-98b5-4ccd-90b8-96891512af20",
      "contractTradeId": "b4cdae0f-9285-48bf-8abf-109ae0177621",
      "status": "confirmed",
      "rate": "0.915",
      "from": {
        "currency": "USDC",
        "amount": "1000.00"
      },
      "to": {
        "currency": "EURC",
        "amount": "915.00"
      },
      "createDate": "2025-08-07T11:01:00Z",
      "updateDate": "2025-08-07T11:01:00Z",
      "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
    }
  ],
  "pagination": {
    "next": "",
    "previous": ""
  }
}
```

## Part 2: Select a trade to fulfill

Choose a trade from the available confirmed trades that you want to fulfill as a
maker. You'll need the trade ID for the subsequent steps.

## Part 3: Confirm trade intent

Confirm your trade intent through the StableFX API before submitting the trade
on the blockchain.

### 3.1. Generate maker signature data

To submit the trade onchain, you must first sign the trade intent with an
EIP-712 signature. To get the data to sign, call the
[generate trade presign data](/api-reference/stablefx/all/generate-trade-signature-data)
endpoint. Your request must include the ID of the trade you want to fulfill.

```shell theme={null}
curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/signatures/presign/${stablefx_trade_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json theme={null}
{
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 5042002,
      "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
    },
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "TokenPermissions": [
        { "name": "token", "type": "address" },
        { "name": "amount", "type": "uint256" }
      ],
      "Consideration": [
        { "name": "quoteId", "type": "bytes32" },
        { "name": "base", "type": "address" },
        { "name": "quote", "type": "address" },
        { "name": "baseAmount", "type": "uint256" },
        { "name": "quoteAmount", "type": "uint256" },
        { "name": "maturity", "type": "uint256" }
      ],
      "TradeWitness": [
        { "name": "consideration", "type": "Consideration" },
        { "name": "fee", "type": "uint256" }
      ],
      "PermitWitnessTransferFrom": [
        { "name": "permitted", "type": "TokenPermissions" },
        { "name": "spender", "type": "address" },
        { "name": "nonce", "type": "uint256" },
        { "name": "deadline", "type": "uint256" },
        { "name": "witness", "type": "TradeWitness" }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0x3600000000000000000000000000000000000000",
        "amount": 429000000
      },
      "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
      "nonce": 309585810,
      "deadline": 1770302983,
      "witness": {
        "consideration": {
          "quoteId": "0x00000000000000000000000000000000c4d1da72111e4d52bdbf2e74a2d803d5",
          "base": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
          "quote": "0x3600000000000000000000000000000000000000",
          "baseAmount": "915000000",
          "quoteAmount": "1000000000",
          "maturity": 1752148800
        },
        "fee": 80000
      }
    }
  }
}
```

### 3.2. Sign the data

Using an EIP-712 compatible wallet or application, sign the data returned in the
previous step.

### 3.3. Submit the trade signature

Confirm your trade intent by submitting the signed data to the
[submit trade signature](/api-reference/stablefx/all/register-trade-signature)
endpoint. This request must include the trade ID, the address of the wallet that
signed the payload, the typed data `details`, and the `signature`.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/signatures \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tradeId": "${stablefx_trade_id}",
  "address": "0xYOUR_WALLET_ADDRESS",
  "details": {
    "permitted": {
      "token": "0x3600000000000000000000000000000000000000",
      "amount": 429000000
    },
    "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
    "nonce": 309585810,
    "deadline": 1770302983,
    "witness": {
      "consideration": {
        "quoteId": "0x00000000000000000000000000000000c4d1da72111e4d52bdbf2e74a2d803d5",
        "base": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
        "quote": "0x3600000000000000000000000000000000000000",
        "baseAmount": "915000000",
        "quoteAmount": "1000000000",
        "maturity": 1752148800
      },
      "fee": 80000
    }
  },
  "signature": "0xsignature"
}
'
```

If the signed data is accepted, the API returns a blank `200` response.

## Part 4: Submit the funds onchain

Next, you need to deliver the funds onchain to complete the trade. The StableFX
API can handle the onchain transaction for you using the `Permit2` contract.

### 4.1. Get the funding signature data

To use the StableFX API to deliver the funds onchain, you must first sign the
funding typed data with an EIP-712 signature. To get the data to sign, call the
[generate funding presign data](/api-reference/stablefx/all/generate-funding-presign-data)
endpoint. Your request must include the contract ID of the trade and the side of
the trade that you are taking. The following is an example request:

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/signatures/funding/presign \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contractTradeIds": ["${stablefx_trade_id}"],
  "type": "maker"
}
'
```

**Response**

```json theme={null}
{
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 11155111,
      "verifyingContract": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE"
    },
    "types": {
      "EIP712Domain": [
        {
          "name": "name",
          "type": "string"
        },

        {
          "name": "chainId",
          "type": "uint256"
        },

        {
          "name": "verifyingContract",
          "type": "address"
        }
      ],
      "TokenPermissions": [
        {
          "name": "token",
          "type": "address"
        },

        {
          "name": "amount",
          "type": "uint256"
        }
      ],
      "SingleTradeWitness": [
        {
          "name": "id",
          "type": "uint256"
        }
      ],
      "PermitWitnessTransferFrom": [
        {
          "name": "permitted",
          "type": "TokenPermissions"
        },

        {
          "name": "spender",
          "type": "address"
        },

        {
          "name": "nonce",
          "type": "uint256"
        },

        {
          "name": "deadline",
          "type": "uint256"
        },

        {
          "name": "witness",
          "type": "SingleTradeWitness"
        }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0xTOKEN",
        "amount": "1000"
      },
      "spender": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE",
      "nonce": "42",
      "deadline": "1735689600",
      "witness": {
        "id": "10"
      }
    }
  },
  "deliverables": [
    {
      "currency": "EURC",
      "amount": "915.00"
    }
  ],
  "receivables": [
    {
      "currency": "USDC",
      "amount": "1000.00"
    }
  ]
}
```

The `deliverables` array lists the token and amount you must deliver as the
maker. The `receivables` array lists the token and amount you receive after
settlement.

### 4.2. Sign the funding data

Using a `Permit2`-compliant EIP-712 compatible wallet or application, sign the
data returned in the previous step.

### 4.3. Submit the funding signature

To deliver the funds onchain, you must submit the maker-specific `Permit2` data
along with your signature to the
[fund trade](/api-reference/stablefx/all/fund-trade) endpoint. The endpoint
allows you to submit either a single object or a batch of objects along with the
required signatures.

The following is an example request for a single trade:

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/fund \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "maker",
  "signature": "0xsignature",
  "permit2": {
    "permitted": {
      "token": "0xTOKEN1",
      "amount": "915"
    },
    "spender": "0xTOKEN1",
    "nonce": "123456",
    "deadline": 1752149700,
    "witness": {
      "id": "123456"
    }
  }
}
'
```

If the signed data is accepted, the API returns a blank `200` response.

<Note>
  It's not required to submit the funding transaction through the StableFX API.
  You can submit the transaction onchain using your own web3 provider or wallet by
  calling the appropriate maker contract methods directly.
</Note>

### 4.4. Confirm the trade is funded

To confirm that the trade is funded, call the
[get a trade by ID](/api-reference/stablefx/all/get-trade-by-id) endpoint. The
trade is funded when the status is `maker_funded`.

```shell theme={null}
curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/trades/${stablefx_trade_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
```


# Quickstart: Create an FX Trade as a Taker
Source: https://developers.circle.com/stablefx/quickstarts/fx-trade-taker

Use the StableFX API to create an FX trade on the taker side

This guide walks you through the steps to create and execute a trade from the
taker side on StableFX.

## Prerequisites

Before you begin this quickstart, ensure you have:

* Obtained an API key for StableFX from Circle
* Set up a web3 provider or wallet that supports EIP-712 signatures and Permit2
* Granted a token allowance to the `Permit2` contract. See
  [How-to: Grant USDC Allowance to Permit2](/stablefx/howtos/grant-usdc-allowance-permit2)
  for more information.
* Installed cURL on your development machine

This quickstart provides API request examples in cURL format, along with example
responses.

<Note>
  StableFX uses a single endpoint for all API requests. The base URL is
  `https://api.circle.com/`. The StableFX API uses your API key for authentication
  and to determine which environment to use. The `TEST` environment executes
  against Arc testnet and returns mock data.

  When developing or testing your integration, you should use your `TEST` API key.
  When you are ready to move to production, just update your code to use your
  `LIVE` API key.
</Note>

## Part 1: Request a tradable quote

Request a tradable quote for a USDC to EURC trade using the
[create a quote](/api-reference/stablefx/all/create-quote) endpoint. Provide a
value for the `amount` parameter in either the `to` or `from` fields, but not
both. Set `type` to `tradable` to receive an executable quote that includes
EIP-712 typed data for signing. Include a `recipientAddress` for the wallet that
receives the destination currency after the trade settles.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/quotes \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "currency": "USDC",
    "amount": "1000.00"
  },
  "to": {
    "currency": "EURC"
  },
  "tenor": "instant",
  "type": "tradable",
  "recipientAddress": "0xYOUR_WALLET_ADDRESS"
}
'
```

**Response**

The response includes the standard quote fields and a `typedData` object
containing the Permit2 EIP-712 typed data you need to sign before creating the
trade.

```json theme={null}
{
  "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "rate": "0.9150",
  "from": {
    "currency": "USDC",
    "amount": "1000.00"
  },
  "to": {
    "currency": "EURC",
    "amount": "915.00"
  },
  "createdAt": "2025-08-07T11:00:00Z",
  "expiresAt": "2025-08-07T11:05:00Z",
  "fee": {
    "currency": "USDC",
    "amount": "1.50"
  },
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 5042002,
      "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
    },
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "Consideration": [
        { "name": "quoteId", "type": "string" },
        { "name": "base", "type": "address" },
        { "name": "quote", "type": "address" },
        { "name": "baseAmount", "type": "uint256" },
        { "name": "quoteAmount", "type": "uint256" },
        { "name": "maturity", "type": "uint256" }
      ],
      "TakerDetails": [
        { "name": "consideration", "type": "Consideration" },
        { "name": "recipient", "type": "address" },
        { "name": "fee", "type": "uint256" }
      ],
      "TokenPermissions": [
        { "name": "token", "type": "address" },
        { "name": "amount", "type": "uint256" }
      ],
      "PermitWitnessTransferFrom": [
        { "name": "permitted", "type": "TokenPermissions" },
        { "name": "spender", "type": "address" },
        { "name": "nonce", "type": "uint256" },
        { "name": "deadline", "type": "uint256" },
        { "name": "witness", "type": "TakerDetails" }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0x3600000000000000000000000000000000000000",
        "amount": 1000000000
      },
      "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
      "nonce": 309585810,
      "deadline": 1770302983,
      "witness": {
        "consideration": {
          "quoteId": "0x00000000000000000000000000000000c4d1da72111e4d52bdbf2e74a2d803d5",
          "base": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
          "quote": "0x3600000000000000000000000000000000000000",
          "baseAmount": "915000000",
          "quoteAmount": "1000000000",
          "maturity": 1752148800
        },
        "recipient": "0x379c868f6064d9c0564df05dcca170d64f8aa5e3",
        "fee": 80000
      }
    }
  }
}
```

## Part 2: Sign and create the trade

### 2.1. Sign the typed data

Using a `Permit2`-compliant EIP-712 compatible wallet or application, sign the
`typedData` object returned in the quote response. Use the `domain`, `types`,
`primaryType`, and `message` fields to construct the EIP-712 signature.

After signing, you have a hex-encoded signature string (for example,
`0x1234...`). You use this signature in the next step to create the trade.

### 2.2. Create the trade

Accept the quote and create a trade on StableFX using the
[create a trade](/api-reference/stablefx/all/create-trade) endpoint. You need to
provide the quote ID, your wallet address, the `message` from the quote
response's `typedData.message` field, the `signature` from the previous step,
and a randomly generated idempotency key in UUIDv4 format.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/trades \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "${randomUUID}",
  "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "address": "0xYOUR_WALLET_ADDRESS",
  "message": {
    "permitted": {
      "token": "0x3600000000000000000000000000000000000000",
      "amount": 1000000000
    },
    "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
    "nonce": 309585810,
    "deadline": 1770302983,
    "witness": {
      "consideration": {
        "quoteId": "0x00000000000000000000000000000000c4d1da72111e4d52bdbf2e74a2d803d5",
        "base": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
        "quote": "0x3600000000000000000000000000000000000000",
        "baseAmount": "915000000",
        "quoteAmount": "1000000000",
        "maturity": 1752148800
      },
      "recipient": "0x379c868f6064d9c0564df05dcca170d64f8aa5e3",
      "fee": 80000
    }
  },
  "signature": "0xsignature"
}
'
```

**Response**

```json theme={null}
{
  "id": "c2558cd1-98b5-4ccd-90b8-96891512af20",
  "contractTradeId": "24",
  "from": {
    "currency": "USDC",
    "amount": "1000.00"
  },
  "to": {
    "currency": "EURC",
    "amount": "915.00"
  },
  "status": "pending_settlement",
  "createDate": "2025-08-07T11:01:00Z",
  "updateDate": "2025-08-07T11:01:00Z",
  "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "rate": "0.9150"
}
```

Verify that the response contains `"status": "pending_settlement"`. This
confirms that the trade was created and is awaiting funding from both parties.

## Part 3: Submit the funds onchain

Deliver the funds onchain to complete the trade. The StableFX API can handle the
onchain transaction for you using the `Permit2` contract.

### 3.1. Get the funding signature data

To use the StableFX API to deliver the funds onchain, you must first sign the
funding typed data with an EIP-712 signature. To get the data to sign, call the
[generate funding presign data](/api-reference/stablefx/all/generate-funding-presign-data)
endpoint. Your request must include the contract ID of the trade (the
`contractTradeId` value from the Part 2 response) and the side of the trade that
you are taking. The following is an example request:

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/signatures/funding/presign \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contractTradeIds": ["${stablefx_contract_trade_id}"],
  "type": "taker"
}
'
```

**Response**

```json theme={null}
{
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 11155111,
      "verifyingContract": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE"
    },
    "types": {
      "EIP712Domain": [
        {
          "name": "name",
          "type": "string"
        },

        {
          "name": "chainId",
          "type": "uint256"
        },

        {
          "name": "verifyingContract",
          "type": "address"
        }
      ],
      "TokenPermissions": [
        {
          "name": "token",
          "type": "address"
        },

        {
          "name": "amount",
          "type": "uint256"
        }
      ],
      "SingleTradeWitness": [
        {
          "name": "id",
          "type": "uint256"
        }
      ],
      "PermitWitnessTransferFrom": [
        {
          "name": "permitted",
          "type": "TokenPermissions"
        },

        {
          "name": "spender",
          "type": "address"
        },

        {
          "name": "nonce",
          "type": "uint256"
        },

        {
          "name": "deadline",
          "type": "uint256"
        },

        {
          "name": "witness",
          "type": "SingleTradeWitness"
        }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0xTOKEN",
        "amount": "1000"
      },
      "spender": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE",
      "nonce": "42",
      "deadline": "1735689600",
      "witness": {
        "id": "10"
      }
    }
  },
  "deliverables": [
    {
      "currency": "USDC",
      "amount": "1000.00"
    }
  ],
  "receivables": [
    {
      "currency": "EURC",
      "amount": "915.00"
    }
  ]
}
```

### 3.2. Sign the funding data

Using a `Permit2`-compliant EIP-712 compatible wallet or application, sign the
data from the `typedData` field returned in the previous step.

### 3.3. Submit the funding signature

To deliver the funds onchain, you must submit the taker-specific `Permit2` data
along with your signature to the
[fund trade](/api-reference/stablefx/all/fund-trade) endpoint. The endpoint
allows you to submit either a single object or a batch of objects along with the
required signatures.

The following is an example request for a single trade:

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/fund \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "taker",
  "signature": "0xsignature",
  "permit2": {
    "permitted": {
      "token": "0xTOKEN1",
      "amount": "1000"
    },
    "spender": "0xTOKEN1",
    "nonce": "123456",
    "deadline": 1752149700,
    "witness": {
      "id": "123456"
    }
  }
}
'
```

If the signed data is accepted, the API returns a blank `200` response.

<Note>
  It's not required to submit the funding transaction through the StableFX API.
  You can submit the transaction onchain using your own web3 provider or wallet.
</Note>

### 3.4. Confirm the trade is funded

To confirm that the trade is funded, call the
[get a trade by ID](/api-reference/stablefx/all/get-trade-by-id) endpoint. A
trade is funded when the status is `taker_funded`.

```shell theme={null}
curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/trades/${stablefx_trade_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json theme={null}
{
  "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "contractTradeId": "24",
  "status": "taker_funded",
  "rate": 0.915,
  "from": {
    "currency": "USDC",
    "amount": "1000"
  },
  "to": {
    "currency": "EURC",
    "amount": "915"
  },
  "createDate": "2023-01-01T12:04:05Z",
  "updateDate": "2023-01-01T12:04:05Z",
  "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
}
```


# StableFX API Rate Limits
Source: https://developers.circle.com/stablefx/references/api-rate-limits

Per-entity rate limits and throttling behavior for all StableFX API endpoints.

Rate limits control how many requests you can make per second to each StableFX
endpoint. Limits apply per entity. Your **entity ID** is the unique identifier
assigned to your organization when you register with Circle.

StableFX counts requests with a **sliding window** algorithm. The window is one
second long. If you send more requests than the limit allows in any rolling
one-second span, the API returns an HTTP `429 Too Many Requests` response until
your rate drops below the limit.

<Note>
  If you receive a `429` response, wait briefly and retry. Use exponential delay
  between retries. Sending requests at the same rate extends the throttle.
</Note>

The following table lists the per-entity rate limits for all StableFX API
endpoints. For examples of calling these endpoints, see the
[taker quickstart](/stablefx/quickstarts/fx-trade-taker) and
[maker quickstart](/stablefx/quickstarts/fx-trade-maker). To set up the
notifications endpoint, see
[Set up webhook notifications](/stablefx/howtos/setup-webhook-notifications).

| Method | Endpoint                               | Maximum requests per second |
| ------ | -------------------------------------- | --------------------------- |
| `POST` | `/v1/exchange/stablefx/quotes`         | 10                          |
| `POST` | `/v1/exchange/stablefx/trades`         | 10                          |
| `GET`  | `/v1/exchange/stablefx/trades`         | 15                          |
| `GET`  | `/v1/exchange/stablefx/signatures/*`   | 10                          |
| `POST` | `/v1/exchange/stablefx/signatures/*`   | 10                          |
| `POST` | `/v1/exchange/stablefx/fund`           | 10                          |
| `GET`  | `/v1/exchange/stablefx/fees/{tradeId}` | 15                          |
| `POST` | `/v1/exchange/stablefx/notifications`  | 25                          |


# Console Roles and Permissions
Source: https://developers.circle.com/stablefx/references/console-roles-permissions

Understand user roles, permissions, and access controls in the StableFX Console.

Role-based access control (RBAC) in the
[StableFX Console](/stablefx/concepts/console-overview) governs what each user
can see and do, with roles assigned at the account level across all users in an
organization.

## Account types

The console supports two account types that determine the trading perspective:

| Account type | Description                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| **Taker**    | Requests quotes, creates trades, and funds settlements. This is the primary trading role.              |
| **Maker**    | Reviews incoming trades, signs them to confirm intent, and funds the counterparty side of settlements. |

Users with access to both types can switch between them using the **account type
dropdown** in the sidebar navigation. The selection controls which data is
displayed and which actions are available.

## User roles

Each user is assigned one or more roles that control their permissions in the
console:

### Taker roles

| Role                     | View trades | Create trades | Sign & fund | Manage team |
| ------------------------ | :---------: | :-----------: | :---------: | :---------: |
| **Taker (Read & Write)** |     Yes     |      Yes      |     Yes     |      No     |
| **Taker (Read Only)**    |     Yes     |       No      |      No     |      No     |
| **Taker (Limited AR)**   |     Yes     |    Limited    |   Limited   |      No     |

**Limited AR** (Auto-Rate) roles can create trades and fund settlements only up
to the pre-approved auto-rate limits configured for the account. Actions that
exceed those limits require approval from an Admin.

### Maker roles

| Role                     | View trades | Sign trades | Fund trades | Manage team |
| ------------------------ | :---------: | :---------: | :---------: | :---------: |
| **Maker (Read & Write)** |     Yes     |     Yes     |     Yes     |      No     |
| **Maker (Read Only)**    |     Yes     |      No     |      No     |      No     |
| **Maker (Limited AR)**   |     Yes     |   Limited   |   Limited   |      No     |

**Limited AR** (Auto-Rate) roles can sign and fund trades only up to the
pre-approved auto-rate limits configured for the account. Actions that exceed
those limits require approval from an Admin.

### Admin capabilities

Account administrators can:

* Add and remove team members
* Assign roles and permissions to users
* Generate, rotate, and revoke API keys
* Configure trading parameters (for example, risk buffer percentages)

<Note>
  The Admin role is typically assigned to the account owner during onboarding.
  Additional admins can be added through the team management interface.
</Note>

## Permission-gated features

Certain features in the console are only visible or accessible based on your
role:

| Feature                                                                  | Required permission                           |
| ------------------------------------------------------------------------ | --------------------------------------------- |
| View live rates                                                          | Any StableFX role                             |
| View trade history                                                       | Any StableFX role                             |
| Open trade form (taker)                                                  | Taker write role                              |
| [Create a trade](/stablefx/howtos/create-trade-console)                  | Taker write role                              |
| [Sign a confirmed trade](/stablefx/howtos/fulfill-trade-console) (maker) | Maker write role + trade signature permission |
| Fund a trade                                                             | Write role (taker or maker)                   |
| [Batch settle trades](/stablefx/howtos/settle-trades-console)            | Write role (taker or maker)                   |
| Access onboarding                                                        | KYB application permission                    |
| Download trade reports (CSV)                                             | Any StableFX role                             |

If a feature is not available, you see a read-only view without action buttons.
Contact your account administrator to request additional permissions.

## API key permissions

API keys generated through the console inherit permissions based on their type:

| Key type         | Can create quotes | Can create trades | Can read trades |
| ---------------- | :---------------: | :---------------: | :-------------: |
| **Read & Write** |        Yes        |        Yes        |       Yes       |
| **Read Only**    |         No        |         No        |       Yes       |

<Warning>
  Maker accounts cannot create quotes or trades via API, even with a Read &
  Write key. These operations are restricted to taker accounts.
</Warning>

For details on API key management, see [API Keys](/api-reference/keys).

To use these permissions in practice, see:

* [StableFX Console overview](/stablefx/concepts/console-overview): An
  introduction to the console interface and account types.
* [Create a trade in the console](/stablefx/howtos/create-trade-console):
  Requires Taker write role.
* [Fulfill a trade as a maker](/stablefx/howtos/fulfill-trade-console): Requires
  Maker write role and trade signature permission.

## Onboarding requirements by role

| Role                         | KYB required |    Individual screening   |      Wallet required      |
| ---------------------------- | :----------: | :-----------------------: | :-----------------------: |
| Admin                        |      Yes     | Yes (testnet and mainnet) |             No            |
| Taker / Maker (Read & Write) |      Yes     |            Yes            | Yes (for signing/funding) |
| Taker / Maker (Read Only)    |      No      |             No            |             No            |

<Note>
  Users with a Read Only role are exempt from individual KYC screening. All
  other roles require screening before access is granted.
</Note>

## Compliance controls

The console enforces several compliance controls:

* **IP-based geo-blocking**: Access is restricted from sanctioned and high-risk
  jurisdictions.
* **Sanctions screening**: All non-viewer users undergo automated sanctions
  screening during onboarding and on an ongoing basis.
* **Mainnet gating**: Users cannot access mainnet if any sanctions screening
  alerts are unresolved.
* **Activity logging**: All actions (trades, signatures, API key changes, role
  assignments) are logged with user ID and timestamp for audit purposes.

## See also

* [Console overview](/stablefx/concepts/console-overview): Capabilities and UI
  layout of the StableFX Console.
* [Connect your wallet](/stablefx/howtos/connect-wallet-console): Link an EVM
  wallet for signing and funding.
* [Create a trade](/stablefx/howtos/create-trade-console): Taker trade creation
  workflow.
* [Fulfill a trade](/stablefx/howtos/fulfill-trade-console): Maker signing and
  funding workflow.
* [Settle trades](/stablefx/howtos/settle-trades-console): Individual and batch
  settlement.
* [Trade states](/stablefx/references/trade-states): Lifecycle states a trade
  moves through.


# StableFX Contract Interfaces
Source: https://developers.circle.com/stablefx/references/contract-interfaces

User-facing methods of the StableFX contract

The StableFX smart contract (`FxEscrow`) has a set of interfaces you can use to
execute trades either as a maker or a taker. This page describes the user-facing
methods of the StableFX contract.

## Contract address

The `FxEscrow` contract is deployed at
[`0x867650F5eAe8df91445971f14d89fd84F0C9a9f8`](https://testnet.arcscan.app/address/0x867650F5eAe8df91445971f14d89fd84F0C9a9f8)
on the [Arc testnet](https://docs.arc.io).

## Interfaces

### `recordTrade`

Records a trade agreement onchain. Returns the contract ID of the trade.

```solidity theme={null}
function recordTrade(
  address taker,
  TakerDetails calldata takerDetails,
  bytes calldata takerSignature,
  address maker,
  MakerDetails calldata makerDetails,
  bytes calldata makerSignature
) external returns (uint256);
```

**Parameters**

| Name             | Type           | Description                |
| ---------------- | -------------- | -------------------------- |
| `taker`          | `address`      | The address of the taker   |
| `takerDetails`   | `TakerDetails` | The details of the taker   |
| `takerSignature` | `bytes`        | The signature of the taker |
| `maker`          | `address`      | The address of the maker   |
| `makerDetails`   | `MakerDetails` | The details of the maker   |
| `makerSignature` | `bytes`        | The signature of the maker |

**Returns**

| Name | Type      | Description                  |
| ---- | --------- | ---------------------------- |
| `id` | `uint256` | The contract ID of the trade |

### `takerDeliver`

Delivers quote currency for a single trade using `Permit2` on the taker side.

```solidity theme={null}
function takerDeliver(uint256 id, IPermit2.PermitTransferFrom memory permit, bytes calldata signature) external;
```

**Parameters**

| Name        | Type                                    | Description                             |
| ----------- | --------------------------------------- | --------------------------------------- |
| `id`        | `uint256`                               | The ID of the trade                     |
| `permit`    | [`IPermit2.PermitTransferFrom`][permit] | The `Permit2`-compliant transfer permit |
| `signature` | `bytes`                                 | The signature for the transfer permit   |

[permit]: https://github.com/Uniswap/permit2/blob/cc56ad0f3439c502c246fc5cfcc3db92bb8b7219/src/interfaces/ISignatureTransfer.sol#L30

### `takerBatchDeliver`

Delivers quote currency for multiple trades using `Permit2` on the taker side.

```solidity theme={null}
function takerBatchDeliver(uint256[] calldata ids, IPermit2.PermitBatchTransferFrom memory permit, bytes calldata signature) external;
```

**Parameters**

| Name        | Type                                               | Description                                   |
| ----------- | -------------------------------------------------- | --------------------------------------------- |
| `ids`       | `uint256[]`                                        | An array of trade IDs                         |
| `permit`    | [`IPermit2.PermitBatchTransferFrom`][permit_batch] | The `Permit2`-compliant batch transfer permit |
| `signature` | `bytes`                                            | The signature for the batch permit            |

[permit_batch]: https://github.com/Uniswap/permit2/blob/cc56ad0f3439c502c246fc5cfcc3db92bb8b7219/src/interfaces/ISignatureTransfer.sol#L51

### `makerDeliver`

Delivers base currency for a single trade using `Permit2` on the maker side.

```solidity theme={null}
function makerDeliver(uint256 id, IPermit2.PermitTransferFrom memory permit, bytes calldata signature) external
```

**Parameters**

| Name        | Type                                    | Description                             |
| ----------- | --------------------------------------- | --------------------------------------- |
| `id`        | `uint256`                               | The ID of the trade                     |
| `permit`    | [`IPermit2.PermitTransferFrom`][permit] | The `Permit2`-compliant transfer permit |
| `signature` | `bytes`                                 | The signature for the transfer permit   |

### `makerBatchDeliver`

Delivers quote currency for multiple trades using `Permit2` on the maker side.

```solidity theme={null}
function makerBatchDeliver(uint256[] calldata ids, IPermit2.PermitBatchTransferFrom memory permit, bytes calldata signature) external;
```

**Parameters**

| Name        | Type                                               | Description                                   |
| ----------- | -------------------------------------------------- | --------------------------------------------- |
| `ids`       | `uint256[]`                                        | An array of trade IDs                         |
| `permit`    | [`IPermit2.PermitBatchTransferFrom`][permit_batch] | The `Permit2`-compliant batch transfer permit |
| `signature` | `bytes`                                            | The signature for the batch permit            |

### `makerNetDeliver`

Net settlement for multiple trades on the maker side.

```solidity theme={null}
function makerNetDeliver(uint256[] calldata ids, IPermit2.PermitBatchTransferFrom memory permit, bytes calldata signature) external
```

**Parameters**

| Name        | Type                                               | Description                                   |
| ----------- | -------------------------------------------------- | --------------------------------------------- |
| `ids`       | `uint256[]`                                        | An array of trade IDs                         |
| `permit`    | [`IPermit2.PermitBatchTransferFrom`][permit_batch] | The `Permit2`-compliant batch transfer permit |
| `signature` | `bytes`                                            | The signature for the batch permit            |

### `breach`

Marks a trade as breached after maturity.

```solidity theme={null}
function breach(uint256 id) external;
```

**Parameters**

| Name | Type      | Description         |
| ---- | --------- | ------------------- |
| `id` | `uint256` | The ID of the trade |

### `breach` (batch)

Marks multiple trades as breached after maturity.

```solidity theme={null}
function breach(uint256[] ids) external;
```

**Parameters**

| Name  | Type        | Description           |
| ----- | ----------- | --------------------- |
| `ids` | `uint256[]` | An array of trade IDs |

### `calculateMakerNet`

Calculate maker net token positions for batch operations. Returns an array of
Balance structs representing net positions.

```solidity theme={null}
function calculateMakerNet(address maker, uint256[] calldata ids) public view returns (Balance[] memory balances);
```

**Parameters**

| Name    | Type        | Description              |
| ------- | ----------- | ------------------------ |
| `maker` | `address`   | The address of the maker |
| `ids`   | `uint256[]` | An array of trade IDs    |

**Returns**

| Name       | Type        | Description                                            |
| ---------- | ----------- | ------------------------------------------------------ |
| `balances` | `Balance[]` | An array of Balance structs representing net positions |


# StableFX Supported Currencies
Source: https://developers.circle.com/stablefx/references/supported-currencies

The currencies supported by StableFX for FX swaps

StableFX supports the following currencies for FX swaps:

* USDC
* EURC


# Magic Numbers for Testing StableFX
Source: https://developers.circle.com/stablefx/references/testing-magic-numbers

Magic numbers you can use to create certain trade outcomes for testing

If you are a maker or taker on StableFX, you can use magic numbers to create
certain trade outcomes for testing. These outcomes allow you to test specific
scenarios where a trade fails or becomes stuck.

## Using magic numbers

When testing your integration, can you use the magic numbers to create specific
failure scenarios:

* If you are a taker, you can accept a quote where either the `from.amount` or
  the `to.amount` is equal to one of the magic numbers
* If you are maker, seeded trades will be available to you with the magic
  numbers as either the `from.amount` or the `to.amount`

When you accept a quote with a magic number as the `from.amount` or `to.amount`,
the resulting trade will have the outcome described in the next section.

For more information on testing your integration, see the
[Test your StableFX Integration as a Taker](/stablefx/tutorials/test-stablefx-integration-taker)
and
[Test your StableFX Integration as a Maker](/stablefx/tutorials/test-stablefx-integration-maker)
tutorials.

## Magic numbers

| Magic Number | Trade outcome                                                                       |
| ------------ | ----------------------------------------------------------------------------------- |
| `23.66`      | Opposite party signature won't be registered during trade recording on the contract |
| `23.67`      | Opposite party funding won't be provided                                            |


# StableFX Trade States
Source: https://developers.circle.com/stablefx/references/trade-states

Learn about the different states a StableFX trade can be in

StableFX trades can be in a number of states that indicate the progress of the
trade. Most of these states have a corresponding notification that is sent to
subscribers over [webhooks](/stablefx/howtos/setup-webhook-notifications) (if
configured).

| State                                                                        | Description                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`                                                                    | Trade is in an initial or transitional state where it's being created, processed, or sent to the exchange provider. The trade has not yet been confirmed by the provider.                                           |
| [`confirmed`](/api-reference/stablefx/all/trade-confirmed)                   | Trade has been successfully confirmed by the exchange provider and is awaiting signatures from both the taker and maker parties to proceed with onchain recording.                                                  |
| [`pending_settlement`](/api-reference/stablefx/all/trade-pending-settlement) | Trade has been recorded onchain and is awaiting funding from both the taker and maker parties. This state indicates the trade is in progress but not yet fully funded.                                              |
| [`taker_funded`](/api-reference/stablefx/all/trade-taker-funded)             | The taker party has successfully delivered their funds onchain. The trade is now waiting for the maker party to deliver their funds to complete the exchange.                                                       |
| [`maker_funded`](/api-reference/stablefx/all/trade-maker-funded)             | The maker party has successfully delivered their funds onchain. The trade is now waiting for the taker party to deliver their funds to complete the exchange.                                                       |
| [`refunded`](/api-reference/stablefx/all/trade-refunded)                     | Funds delivered onchain have been returned to the respective parties because the trade was canceled or only one party funded before the deadline. This is a terminal state—the trade does not proceed further.      |
| `breaching`                                                                  | The trade's maturity date has passed and the system is actively processing a breach. This is a transitional state indicating the trade is being expired because at least one party did not deliver by the deadline. |
| [`breached`](/api-reference/stablefx/all/trade-breached)                     | The maturity date passed without full settlement—at least one party did not deliver funds. This is a terminal state—the trade has expired and does not proceed.                                                     |
| [`failed`](/api-reference/stablefx/all/trade-failed)                         | The trade has expired before being recorded onchain. This is a terminal state indicating the trade timed out during the signature collection phase and was never broadcast to the blockchain.                       |
| [`complete`](/api-reference/stablefx/all/trade-completed)                    | The StableFX contract has successfully settled token fund transfers between the taker, maker, and fee recipient. This is a terminal state indicating successful trade completion.                                   |

<Note>
  Terminal states (`complete`, `failed`, `breached`, `refunded`) are final—trades
  cannot transition out of them.

  States linked to an API reference page have a corresponding webhook
  notification. `pending` and `breaching` are transitional states with no webhook.
</Note>


# Test your StableFX Integration as a Maker
Source: https://developers.circle.com/stablefx/tutorials/test-stablefx-integration-maker

Test your integration with the StableFX API and smart contracts on the maker side

This tutorial walks you through the steps to test your StableFX integration as a
maker. This tutorial contains general instructions on testing your integration
with successful trades. If you want to test specific failure scenarios, see
[Magic Numbers for Testing StableFX](/stablefx/references/testing-magic-numbers).

## Prerequisites

Before you begin, ensure that you have:

* Obtained an API key for StableFX from Circle
* Obtained testnet USDC in a supported wallet on Arc
* Installed cURL on your development machine

This guide provides API requests in cURL format, along with example responses.

<Note>
  StableFX uses a single endpoint for all API requests. The base URL is
  `https://api.circle.com/`. The StableFX API uses your API key for authentication
  and to determine which environment to use. The `TEST` environment executes
  against Arc testnet and returns mock data.

  When developing or testing your integration, you should use your `TEST` API key.
  When you are ready to move to production, just update your code to use your
  `LIVE` API key.
</Note>

## Part 1: Query for trades

Query for trades with the `confirmed` status using the
[get all trades](/api-reference/stablefx/all/list-trades) endpoint. The
following is an example request:

```shell theme={null}
curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/trades?type=maker&status=confirmed \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
```

**Response**

```json theme={null}
{
  "data": [
    {
      "id": "c2558cd1-98b5-4ccd-90b8-96891512af20",
      "contractTradeId": 42,
      "status": "confirmed",
      "rate": 0.915,
      "from": {
        "currency": "USDC",
        "amount": "10"
      },
      "to": {
        "currency": "EURC",
        "amount": "9.15"
      },
      "createDate": "2023-01-01T12:04:05Z",
      "updateDate": "2023-01-01T12:04:05Z",
      "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
    }
  ],
  "pagination": {
    "next": "",
    "previous": ""
  }
}
```

## Part 2: Register your signature

Decide which trades to take from the maker side, and register your signature for
those trades.

### 2.1. Get the typed data for the trade

Using the `id` field from the response in the previous step, get the typed data
for the trade using the
[generate trade presign data](/api-reference/stablefx/all/generate-trade-signature-data)
endpoint. The following is an example request:

```shell theme={null}
curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/signatures/presign/c2558cd1-98b5-4ccd-90b8-96891512af20 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json theme={null}
{
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 5042002,
      "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
    },
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "TokenPermissions": [
        { "name": "token", "type": "address" },
        { "name": "amount", "type": "uint256" }
      ],
      "Consideration": [
        { "name": "quoteId", "type": "bytes32" },
        { "name": "base", "type": "address" },
        { "name": "quote", "type": "address" },
        { "name": "baseAmount", "type": "uint256" },
        { "name": "quoteAmount", "type": "uint256" },
        { "name": "maturity", "type": "uint256" }
      ],
      "TradeWitness": [
        { "name": "consideration", "type": "Consideration" },
        { "name": "fee", "type": "uint256" }
      ],
      "PermitWitnessTransferFrom": [
        { "name": "permitted", "type": "TokenPermissions" },
        { "name": "spender", "type": "address" },
        { "name": "nonce", "type": "uint256" },
        { "name": "deadline", "type": "uint256" },
        { "name": "witness", "type": "TradeWitness" }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0x3600000000000000000000000000000000000000",
        "amount": 429000000
      },
      "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
      "nonce": 309585810,
      "deadline": 1770302983,
      "witness": {
        "consideration": {
          "quoteId": "0x00000000000000000000000000000000c4d1da72111e4d52bdbf2e74a2d803d5",
          "base": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
          "quote": "0x3600000000000000000000000000000000000000",
          "baseAmount": "915000000",
          "quoteAmount": "1000000000",
          "maturity": 1752148800
        },
        "fee": 80000
      }
    }
  }
}
```

### 2.2. Sign the typed data

Using your wallet, sign the typed data returned from the previous step.

### 2.3. Submit the signed data

Submit the signed data to the
[submit a trade signature](/api-reference/stablefx/all/register-trade-signature)
endpoint. The following example submits the signed data from the previous step:

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/signatures \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tradeId": "c2558cd1-98b5-4ccd-90b8-96891512af20",
  "address": "0xYOUR_WALLET_ADDRESS",
  "details": {
    "permitted": {
      "token": "0x3600000000000000000000000000000000000000",
      "amount": 429000000
    },
    "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
    "nonce": 309585810,
    "deadline": 1770302983,
    "witness": {
      "consideration": {
        "quoteId": "0x00000000000000000000000000000000c4d1da72111e4d52bdbf2e74a2d803d5",
        "base": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
        "quote": "0x3600000000000000000000000000000000000000",
        "baseAmount": "915000000",
        "quoteAmount": "1000000000",
        "maturity": 1752148800
      },
      "fee": 80000
    }
  },
  "signature": "0xsignature"
}
'
```

## Part 3: Fund the trade

Use the following steps to fund the trade onchain.

### 3.1. Get trades that are ready for funding

Before you send funds onchain, you should confirm that the trade is ready for
funding. To do this, call the
[get all trades](/api-reference/stablefx/all/list-trades) endpoint. You should
filter the response by the `taker_funded` status.

### 3.2. Get the funding signature data

To use the StableFX API to deliver the funds onchain, you must first sign the
funding typed data with an EIP-712 signature. To get the data to sign, call the
[generate funding presign data](/api-reference/stablefx/all/generate-funding-presign-data)
endpoint. Your request must include the contract ID of the trade and the side of
the trade that you are taking (`"type": "maker"`). The following is an example
request:

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/signatures/funding/presign \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
  {
  "contractTradeIds": ["${stablefx_contract_trade_id}"],
  "type": "maker"
}
'
```

**Response**

```json theme={null}
{
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 11155111,
      "verifyingContract": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE"
    },
    "types": {
      "EIP712Domain": [
        {
          "name": "name",
          "type": "string"
        },

        {
          "name": "chainId",
          "type": "uint256"
        },

        {
          "name": "verifyingContract",
          "type": "address"
        }
      ],
      "TokenPermissions": [
        {
          "name": "token",
          "type": "address"
        },

        {
          "name": "amount",
          "type": "uint256"
        }
      ],
      "SingleTradeWitness": [
        {
          "name": "id",
          "type": "uint256"
        }
      ],
      "PermitWitnessTransferFrom": [
        {
          "name": "permitted",
          "type": "TokenPermissions"
        },

        {
          "name": "spender",
          "type": "address"
        },

        {
          "name": "nonce",
          "type": "uint256"
        },

        {
          "name": "deadline",
          "type": "uint256"
        },

        {
          "name": "witness",
          "type": "SingleTradeWitness"
        }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0xTOKEN",
        "amount": "1000"
      },
      "spender": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE",
      "nonce": "42",
      "deadline": "1735689600",
      "witness": {
        "id": "10"
      }
    }
  },
  "deliverables": [
    {
      "currency": "EURC",
      "amount": "915.00"
    }
  ],
  "receivables": [
    {
      "currency": "USDC",
      "amount": "1000.00"
    }
  ]
}
```

### 3.3. Fund the trade with the StableFX API

The StableFX API can handle the onchain transaction for you through the
[fund trades](/api-reference/stablefx/all/fund-trade) endpoint. You must submit
the maker-specific funding data along with your signature.

```shell theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/fund \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "maker",
  "signature": "0xsignature",
  "permit2": {
    "permitted": {
      "token": "0xTOKEN1",
      "amount": "9.15"
    },
    "spender": "0xTOKEN1",
    "nonce": "123456",
    "deadline": 1752149700,
    "witness": {
      "id": "123456"
    }
  }
}
'
```

If the signed data is accepted, the API returns a blank `200` response.

<Note>
  It's not required to submit the funding transaction through the StableFX API.
  You can submit the transaction onchain using your own web3 provider or wallet by
  calling the appropriate maker contract methods directly.
</Note>

## Testing trade batches

Note that the query for trades endpoint returns multiple trades. This can be
useful for testing a batch integration. If you are testing batching, you need to
get the `contractTradeId` for each trade that you'd like to fund. You should
complete [part 2](#part-2-register-your-signature) for each trade that you'd
like to fund.

Once you have the array of IDs, and your signature is submitted for each trade,
you can use the same [fund trades](/api-reference/stablefx/all/fund-trade)
endpoint to fund multiple trades by submitting the permit2 data for each trade
along with the appropriate signatures.


# Test your StableFX Integration as a Taker
Source: https://developers.circle.com/stablefx/tutorials/test-stablefx-integration-taker

Test your integration with the StableFX API and smart contracts on the taker side

This tutorial walks you through the steps to test your StableFX integration as a
taker. This tutorial contains general instructions on testing your integration
with successful trades. If you want to test specific failure scenarios, see
[Magic Numbers for Testing StableFX](/stablefx/references/testing-magic-numbers).

## Prerequisites

Before you begin, ensure that you have:

* Obtained an API key for StableFX from Circle
* Obtained testnet USDC in a supported wallet on Arc
* Installed cURL on your development machine

This guide provides API requests in cURL format, along with example responses.
In all examples, replace `${YOUR_API_KEY}` with your actual API key and any
other placeholder values with the appropriate data for your test.

<Note>
  StableFX uses a single endpoint for all API requests. The base URL is
  `https://api.circle.com/`. The StableFX API uses your API key for authentication
  and to determine which environment to use. The `TEST` environment executes
  against Arc testnet and returns mock data.

  When developing or testing your integration, you should use your `TEST` API key.
  When you are ready to move to production, just update your code to use your
  `LIVE` API key.
</Note>

## Step 1: Create a trade

To test your integration, you need to create at least one trade. Use the
following steps to request a tradable quote, sign the Permit2 typed data, and
create the trade.

### 1.1. Request a tradable quote

Request a tradable quote for a trade from USDC to EURC using the
[create a quote](/api-reference/stablefx/all/create-quote) endpoint. Provide a
value for the `amount` parameter in either the `from` or `to` fields, but not
both. Set `type` to `tradable` to receive an executable quote. Include a
`recipientAddress` for tradable quote requests. The `recipientAddress` is the
wallet address that receives the destination currency (EURC in this example)
after the trade settles:

```bash theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/quotes \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "currency": "USDC",
    "amount": "10"
  },
  "to": {
    "currency": "EURC"
  },
  "tenor": "instant",
  "type": "tradable",
  "recipientAddress": "0x1f531ce3c418bbd830d06138a9e5b5eacfdfb3d6"
}
'
```

**Response**

The response includes the standard quote fields and a `typedData` object
containing the Permit2 EIP-712 typed data you need to sign before creating the
trade.

```json theme={null}
{
  "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "rate": 0.915,
  "to": {
    "currency": "EURC",
    "amount": "9.15"
  },
  "from": {
    "currency": "USDC",
    "amount": "10"
  },
  "createdAt": "2025-01-01T12:04:05Z",
  "expiresAt": "2025-01-01T12:04:05Z",
  "fee": {
    "currency": "USDC",
    "amount": "0.01"
  },
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 11155111,
      "verifyingContract": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE"
    },
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "Consideration": [
        { "name": "quoteId", "type": "string" },
        { "name": "base", "type": "address" },
        { "name": "quote", "type": "address" },
        { "name": "baseAmount", "type": "uint256" },
        { "name": "quoteAmount", "type": "uint256" },
        { "name": "maturity", "type": "uint256" }
      ],
      "TakerDetails": [
        { "name": "consideration", "type": "Consideration" },
        { "name": "recipient", "type": "address" },
        { "name": "fee", "type": "uint256" }
      ],
      "TokenPermissions": [
        { "name": "token", "type": "address" },
        { "name": "amount", "type": "uint256" }
      ],
      "PermitWitnessTransferFrom": [
        { "name": "permitted", "type": "TokenPermissions" },
        { "name": "spender", "type": "address" },
        { "name": "nonce", "type": "uint256" },
        { "name": "deadline", "type": "uint256" },
        { "name": "witness", "type": "TakerDetails" }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0x3600000000000000000000000000000000000000",
        "amount": 429000000
      },
      "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
      "nonce": 309585810,
      "deadline": 1770302983,
      "witness": {
        "consideration": {
          "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
          "base": "0x3600000000000000000000000000000000000000",
          "quote": "0x4200000000000000000000000000000000000000",
          "baseAmount": "10",
          "quoteAmount": "9.15",
          "maturity": 1716153600
        },
        "recipient": "0x1f531ce3c418bbd830d06138a9e5b5eacfdfb3d6",
        "fee": 80000
      }
    }
  }
}
```

### 1.2. Sign the typed data

Using a `Permit2`-compliant EIP-712 compatible wallet or signing library, sign
the `typedData` object returned in the quote response. Use the `domain`,
`types`, `primaryType`, and `message` fields from the response to construct the
EIP-712 signature.

After signing, you have a hex-encoded signature string (for example,
`0x1234...`). You use this signature in the next step to create the trade.

### 1.3. Create the trade

Accept the quote and create a trade on StableFX using the
[create a trade](/api-reference/stablefx/all/create-trade) endpoint. You need to
provide the quote ID, your wallet address, the `message` from the quote
response's `typedData.message` field, the signature from the previous step, and
a randomly generated [idempotency key](/api-reference/idempotent-requests) in
UUIDv4 format (`${randomUUID}` in the following example). The following is an
example request:

```bash theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/trades \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "${randomUUID}",
  "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "address": "0x1f531ce3c418bbd830d06138a9e5b5eacfdfb3d6",
  "message": {
    "permitted": {
      "token": "0x3600000000000000000000000000000000000000",
      "amount": 429000000
    },
    "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
    "nonce": 309585810,
    "deadline": 1770302983,
    "witness": {
      "consideration": {
        "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
        "base": "0x3600000000000000000000000000000000000000",
        "quote": "0x4200000000000000000000000000000000000000",
        "baseAmount": "10",
        "quoteAmount": "9.15",
        "maturity": 1716153600
      },
      "recipient": "0x1f531ce3c418bbd830d06138a9e5b5eacfdfb3d6",
      "fee": 80000
    }
  },
  "signature": "0xsignature"
}
'
```

**Response**

```json theme={null}
{
  "id": "c2558cd1-98b5-4ccd-90b8-96891512af20",
  "contractTradeId": "24",
  "status": "pending_settlement",
  "rate": 0.915,
  "from": {
    "currency": "USDC",
    "amount": "10"
  },
  "to": {
    "currency": "EURC",
    "amount": "9.15"
  },
  "createDate": "2025-01-01T12:04:05Z",
  "updateDate": "2025-01-01T12:04:05Z",
  "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
}
```

Verify that the response contains `"status": "pending_settlement"`. This
confirms that the trade was created and is awaiting settlement. For a full list
of trade states, see [Trade States](/stablefx/references/trade-states).

## Step 2: Fund the trade

Use the following steps to fund the trade onchain.

### 2.1. Get trades that are ready for funding

Before you send funds onchain, confirm that the trade is ready for funding. To
do this, call the [get all trades](/api-reference/stablefx/all/list-trades)
endpoint. Filter the response by the `pending_settlement` status. Your trade ID
should be listed in the response.

```bash theme={null}
curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/trades?type=taker&status=pending_settlement \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
```

**Response**

```json theme={null}
{
  "id": "c2558cd1-98b5-4ccd-90b8-96891512af20",
  "contractTradeId": "24",
  "status": "pending_settlement",
  "rate": 0.915,
  "from": {
    "currency": "USDC",
    "amount": "10"
  },
  "to": {
    "currency": "EURC",
    "amount": "9.15"
  },
  "createDate": "2025-01-01T12:04:05Z",
  "updateDate": "2025-01-01T12:04:05Z",
  "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
}
```

### 2.2. Get the funding signature data

To use the StableFX API to deliver the funds onchain, you must first sign the
funding typed data with an EIP-712 signature. To get the data to sign, call the
[generate funding presign data](/api-reference/stablefx/all/generate-trade-signature-data)
endpoint. Your request must include the contract ID of the trade
(`${stablefx_contract_trade_id}` in the example, replaced with the
`contractTradeId` value from the step 1.3 response) and the side of the trade
that you are taking. The following is an example request:

```bash theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/signatures/funding/presign \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contractTradeIds": ["${stablefx_contract_trade_id}"],
  "type": "taker"
}
'
```

**Response**

```json theme={null}
{
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 11155111,
      "verifyingContract": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE"
    },
    "types": {
      "EIP712Domain": [
        {
          "name": "name",
          "type": "string"
        },

        {
          "name": "chainId",
          "type": "uint256"
        },

        {
          "name": "verifyingContract",
          "type": "address"
        }
      ],
      "TokenPermissions": [
        {
          "name": "token",
          "type": "address"
        },

        {
          "name": "amount",
          "type": "uint256"
        }
      ],
      "SingleTradeWitness": [
        {
          "name": "id",
          "type": "uint256"
        }
      ],
      "PermitWitnessTransferFrom": [
        {
          "name": "permitted",
          "type": "TokenPermissions"
        },

        {
          "name": "spender",
          "type": "address"
        },

        {
          "name": "nonce",
          "type": "uint256"
        },

        {
          "name": "deadline",
          "type": "uint256"
        },

        {
          "name": "witness",
          "type": "SingleTradeWitness"
        }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0xTOKEN",
        "amount": "1000"
      },
      "spender": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE",
      "nonce": 42,
      "deadline": 1735689600,
      "witness": {
        "id": "10"
      }
    }
  },
  "deliverables": [
    {
      "currency": "USDC",
      "amount": "1000.00"
    }
  ],
  "receivables": [
    {
      "currency": "EURC",
      "amount": "915.00"
    }
  ]
}
```

### 2.3. Sign the funding data

Using a `Permit2`-compliant EIP-712 compatible wallet or signing library, sign
the data from the `typedData` field returned in the previous step. Use the
`domain`, `types`, `primaryType`, and `message` fields to construct the EIP-712
signature. This signature authorizes the Permit2 contract to transfer your funds
to the escrow contract.

After signing, you have a hex-encoded signature string. You submit this
signature in the next step to fund the trade.

### 2.4. Fund the trade with the StableFX API

The StableFX API can handle the onchain transaction for you. You must submit a
permit2-compliant data object along with the signature to the
[fund trades](/api-reference/stablefx/all/fund-trade) endpoint. The endpoint
allows you to submit either a single object or a batch of objects along with the
required signatures.

The following is an example request for a single trade:

```bash theme={null}
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/fund \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "taker",
  "signature": "0xsignature",
  "permit2": {
    "permitted": {
      "token": "0xTOKEN1",
      "amount": "10"
    },
    "spender": "0xTOKEN1",
    "nonce": 123456,
    "deadline": 1752149700,
    "witness": {
      "id": "123456"
    }
  }
}
'
```

If the signed data is accepted, the API returns a blank `200` response. This
confirms the funding transaction was submitted successfully.

<Note>
  You don't need to submit the funding transaction through the StableFX API. You
  can also submit the transaction onchain using your own web3 provider or
  wallet.
</Note>

### 2.5. Confirm the trade is funded

To confirm the trade was funded, call the
[get a trade by ID](/api-reference/stablefx/all/get-trade-by-id) endpoint. The
trade is funded when the status is `taker_funded`.

```bash theme={null}
curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/trades/${trade_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'
```

Verify that the response contains `"status": "taker_funded"`. This confirms that
your funding transaction was processed successfully.

<Note>
  After a trade reaches the `taker_funded` status, the maker funds their side of
  the trade. The trade then transitions to `maker_funded`, and finally to
  `settled` once the onchain settlement completes and both parties receive their
  funds. If either side fails to fund in the required window, the trade
  transitions to `breaching`, then `breached` and any funded amounts are
  returned.
</Note>

## Testing trade batches

To test a batch integration where you fund multiple trades at once, repeat
[Part 1](#step-1-create-a-trade) to create multiple trades. Get the
`contractTradeId` for each trade that requires funding by calling the
[get all trades](/api-reference/stablefx/all/list-trades) endpoint filtered by
the `pending_settlement` status.

Once you have the array of IDs, you can use the same
[fund trades](/api-reference/stablefx/all/fund-trade) endpoint to fund multiple
trades by submitting the permit2 data for each trade along with the appropriate
signatures.


# USYC Overview
Source: https://developers.circle.com/tokenized/usyc/overview



<Note>
  USYC is available only to entities that are not U.S. Persons, as defined in
  Regulation S under the Securities Act of 1933. Eligibility restrictions apply.
  For details, see [Investor
  Onboarding](https://help.circle.com/s/article/Investor-Onboarding?language=en_US\&category=With_USYC)
  in the Circle Help Center or contact
  [customer-support@circle.com](mailto:customer-support@circle.com).
</Note>

USYC is the onchain representation of Hashnote International Short Duration
Yield Fund Ltd. ("SDYF"). SDYF invests primarily in reverse repurchase
agreements (reverse repo) backed by U.S. government securities.

USYC is issued by Circle International Bermuda Limited, regulated by the Bermuda
Monetary Authority (BMA), and represents an interest in a Cayman Islands mutual
fund licensed by the Cayman Islands Monetary Authority (CIMA).

Interacting with USYC onchain is seamless through an audited smart contract.
Subscriptions and redemptions are available 24/7/365 and settle atomically in
real time (T+0).

USYC includes the following features:

* **Onchain settlement**: USYC positions are entered or exited by exchanging
  USDC. No offchain steps or intermediaries are required.
* **Yield profile**: Assets earn the overnight federal funds rate through
  reverse repo agreements.
* **Transparency**: The token price and fund holdings are published through an
  onchain Oracle. The token contract is audited and verified on Etherscan.
* **Composability**: USYC integrates with the existing DeFi ecosystem as a
  standard ERC-20 token.

To learn how to integrate USYC, see
[Quickstart: Subscribe and Redeem USYC Using the Teller Smart Contract](/tokenized/usyc/subscribe-and-redeem).

For more information about USYC, see the
[Circle Help Center](https://help.circle.com/s/category?language=en_US\&name=Tokenized_Funds).


# USYC Contract Addresses
Source: https://developers.circle.com/tokenized/usyc/smart-contracts



You can use the following contract addresses to integrate with USYC.

For Binance (BSC), you can use the Cross Chain Teller to subscribe and redeem
native USYC from Ethereum.

## Mainnet

| Chain    | Contract                      | Address                                        |
| -------- | ----------------------------- | ---------------------------------------------- |
| BSC      | Cross Chain Teller (USDC)     | `0xf38979E05650be7926EA07BB59C48Fb9b1DB3D08`   |
| BSC      | Entitlements                  | `0x6B7d54003f73bE979cf92BF369432aC534853692`   |
| BSC      | USYC                          | `0x8D0fA28f221eB5735BC71d3a0Da67EE5bC821311`   |
| Ethereum | Cross Chain Teller (USDC)     | `0x5dbeCcECEbCdC2ce3258f6E638373d2923560c7d`   |
| Ethereum | Entitlements                  | `0x902D906b8d988092213bE799B18Bd2cbd64F808C`   |
| Ethereum | Oracle                        | `0x74f2199AEb743f68f05943e5715A33EaF2b61f53`   |
| Ethereum | Teller (USDC)                 | `0xeE35F963BFC71b51eC95147f26c030D674ea30e6`   |
| Ethereum | USYC                          | `0x136471a34f6ef19fE571EFFC1CA711fdb8E49f2b`   |
| Solana   | Teller (USDC) and Permissions | `EMfvuBR8rre2f7sNqdDyPzQW7kgBUsVtxg7nX93YwAdm` |
| Solana   | USYC                          | `7LWanZteUKtvFjv4MHYgKXXdAuCQYFPJysL9pxxdRQGn` |

## Testnet

| Chain            | Contract                      | Address                                        |
| ---------------- | ----------------------------- | ---------------------------------------------- |
| Arc Testnet      | Entitlements                  | `0xcc205224862c7641930c87679e98999d23c26113`   |
| Arc Testnet      | Oracle                        | `0x52b56c7642E71dc54714d879127d97cd0B3D4581`   |
| Arc Testnet      | Teller (USDC)                 | `0x9fdF14c5B14173D74C08Af27AebFf39240dC105A`   |
| Arc Testnet      | USYC                          | `0xe9185F0c5F296Ed1797AaE4238D26CCaBEadb86C`   |
| BSC Testnet      | Cross Chain Teller (USDC)     | `0xc8ad161a7B8577fbBD5529b43d8a06CD8890b879`   |
| BSC Testnet      | Entitlements                  | `0x7860a6A8281eD687DcbAb942735F2be89Bcd4aE0`   |
| BSC Testnet      | USYC                          | `0x109656Aba6F175c634c63C9874f29CeAAAB8E606`   |
| Ethereum Sepolia | Cross Chain Teller (USDC)     | `0x06eFF53Db53a760a8BAfAD0E0E229b90Fb8bAA11`   |
| Ethereum Sepolia | Entitlements                  | `0x7f44c5F5551ed651F7298367Ee51f1CBa608571b`   |
| Ethereum Sepolia | Oracle                        | `0x48c9E02E09d03E448673166d29691ECdEf56526F`   |
| Ethereum Sepolia | Teller (USDC)                 | `0x96424C885951ceb4B79fecb934eD857999e6f82B`   |
| Ethereum Sepolia | USYC                          | `0x38D3A3f8717F4DB1CcB4Ad7D8C755919440848A3`   |
| Solana Devnet    | Teller (USDC) and Permissions | `8FZQeFy39fNK47ebUd7aUWoK1rLgJ7fsteWev3FPP1Aw` |
| Solana Devnet    | USYC                          | `7WkaBNxz6jpJWGLPNFNsUbuVH8iQ2FxBooMak6itUMWb` |


# Quickstart: Subscribe and Redeem USYC Using the Teller Smart Contract
Source: https://developers.circle.com/tokenized/usyc/subscribe-and-redeem



The Teller contract is an audited smart contract that handles USYC subscriptions
and redemptions. It is implemented with Solidity and you can interact with it
using Solidity, TypeScript, or any other programming language that supports
Ethereum smart contracts.

<Note>
  This quickstart uses testnet addresses. For mainnet addresses, see [USYC
  Contract Addresses](/tokenized/usyc/smart-contracts).
</Note>

The following example shows you how to call the Teller contract to subscribe to
and redeem USYC:

<CodeGroup>
  ```solidity Solidity theme={null}
  import "../IERC20.sol";

  interface ITeller {
    function deposit(uint256 _assets, address _receiver) external returns (uint256);
    function redeem(uint256 _shares, address _receiver, address _account) external returns (uint256);
  }

  ITeller teller = ITeller(0x96424C885951ceb4B79fecb934eD857999e6f82B);

  // Subscribe to USYC
  IERC20 usdc = IERC20(0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238);
  uint256 usdcAmount = 100 * 1e6; // 100.000000 USDC
  address usycReceiver = address(this); // Address to receive USYC
  usdc.approve(address(teller), usdcAmount);
  uint256 usycPurchased = teller.deposit(usdcAmount, usycReceiver);

  // Redeem USYC
  IERC20 usyc = IERC20(0x38D3A3f8717F4DB1CcB4Ad7D8C755919440848A3);
  uint256 usycAmount = 100 * 1e6; // 100.000000 USYC
  address usdcReceiver = address(this); // Address to receive USDC
  address usycAccount = address(this); // Address that holds USYC
  uint256 usdcPayout = teller.redeem(usycAmount, usdcReceiver, usycAccount);
  ```

  ```typescript TypeScript theme={null}
  import { Address, erc20ABI, writeContract, getAccount } from "@wagmi/core";

  const USYC_TELLER_ABI = [
    {
      inputs: [
        { internalType: "uint256", name: "_assets", type: "uint256" },
        { internalType: "address", name: "_receiver", type: "address" },
      ],
      name: "deposit",
      outputs: [{ internalType: "uint256", name: "", type: "uint256" }],
      stateMutability: "nonpayable",
      type: "function",
    },
    {
      inputs: [
        { internalType: "uint256", name: "_amount", type: "uint256" },
        { internalType: "address", name: "_receiver", type: "address" },
        { internalType: "address", name: "_account", type: "address" },
      ],
      name: "redeem",
      outputs: [{ internalType: "uint256", name: "", type: "uint256" }],
      stateMutability: "nonpayable",
      type: "function",
    },
  ] as const;

  // Ethereum Sepolia Addresses
  const SEPOLIA_CHAIN_ID = 11155111;
  const USYC_TELLER_ADDRESS: Address =
    "0x96424C885951ceb4B79fecb934eD857999e6f82B";
  const USDC_ADDRESS: Address = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238";
  const USYC_ADDRESS: Address = "0x38D3A3f8717F4DB1CcB4Ad7D8C755919440848A3";

  const ONE_HUNDRED_USDC = BigInt(100_000000); // USDC uses 6 decimals
  const ONE_HUNDRED_USYC = BigInt(100_000000); // USYC uses 6 decimals

  // Subscribe to USYC
  export const approveUSYCTellerToSpendUSDC = () =>
    writeContract({
      chainId: SEPOLIA_CHAIN_ID,
      address: USDC_ADDRESS,
      abi: erc20ABI,
      functionName: "approve",
      args: [USYC_TELLER_ADDRESS, ONE_HUNDRED_USDC],
    });

  const usycReceiverAddress: Address = getAccount(); // Address to receive USYC

  export const depositUSYC = () =>
    writeContract({
      chainId: SEPOLIA_CHAIN_ID,
      address: USYC_TELLER_ADDRESS,
      abi: USYC_TELLER_ABI,
      functionName: "deposit",
      args: [ONE_HUNDRED_USDC, usycReceiverAddress],
    });

  // Redeem USYC
  const usdcReceiverAddress: Address = getAccount(); // Address to receive USDC
  const usycAccountAddress: Address = getAccount(); // Address that holds USYC

  export const redeemUSYC = () =>
    writeContract({
      chainId: SEPOLIA_CHAIN_ID,
      address: USYC_TELLER_ADDRESS,
      abi: USYC_TELLER_ABI,
      functionName: "redeem",
      args: [ONE_HUNDRED_USYC, usdcReceiverAddress, usycAccountAddress],
    });
  ```
</CodeGroup>


# Quickstart: Subscribe and Redeem USYC Using the USYC Portal
Source: https://developers.circle.com/tokenized/usyc/subscribe-and-redeem-portal



This quickstart shows you how to use the USYC Portal to subscribe to and redeem
USYC.

## Step 1. Connect to the USYC Portal

<Steps>
  <Step title="Go to the USYC Portal">
    Access the USYC Portal on mainnet or testnet:

    * Mainnet: [https://usyc.hashnote.com](https://usyc.hashnote.com)
    * Testnet: [https://usyc.dev.hashnote.com](https://usyc.dev.hashnote.com)
  </Step>

  <Step title="Connect your wallet">
    Connect your wallet and select the blockchain network where your funds are
    located.

    <div>
      <Frame>
        <img alt="Wallet connection step 1" />
      </Frame>

      <Frame>
        <img alt="Wallet connection step 2" />
      </Frame>

      <Frame>
        <img alt="Wallet connection step 334" />
      </Frame>
    </div>
  </Step>
</Steps>

## Step 2. Subscribe to USYC

<Steps>
  <Step title="Enter USDC amount">
    From the **Subscribe** tab and in the **Balance** section, enter the amount of USDC to invest.

    <Frame>
      <img alt="Subscribe step 1" />
    </Frame>
  </Step>

  <Step title="Specify the destination chain">
    In the **Destination Chain** section, select the blockchain where you want to receive USYC.

    <Frame>
      <img alt="Subscribe step 2" />
    </Frame>
  </Step>

  <Step title="Approve USDC">
    Select **Approve USDC** to authorize the Teller contract to spend USDC.

    <Frame>
      <img alt="Subscribe step 3" />
    </Frame>
  </Step>

  <Step title="Mint USYC">
    Select **Mint USYC** to exchange the entered USDC amount for USYC.

    <Frame>
      <img alt="Subscribe step 4" />
    </Frame>
  </Step>

  <Step title="Await transaction confirmation">
    <div>
      <Frame>
        <img alt="Subscribe Confirm Tx step 1" />
      </Frame>

      <Frame>
        <img alt="Subscribe Confirm Tx step 2" />
      </Frame>
    </div>
  </Step>

  <Step title="Confirm successful transaction">
    If successful, a message is displayed confirming the minting of USYC.

    <Frame>
      <img alt="Subscribe step 6" />
    </Frame>
  </Step>
</Steps>

## Step 3. Redeem USYC

<Steps>
  <Step title="Enter USYC amount">
    Select the **Redeem** tab and from the **Balance** section, enter the amount of USYC to redeem.

    <Frame>
      <img alt="Redeem step 1" />
    </Frame>
  </Step>

  <Step title="Specify the destination chain">
    In the **Destination Chain** section, select the blockchain where you want to receive USDC.

    <Frame>
      <img alt="Redeem step 2" />
    </Frame>
  </Step>

  <Step title="Redeem USYC">
    Select **Redeem USYC** to exchange USYC for USDC. Fees apply.

    <Frame>
      <img alt="Redeem step 3" />
    </Frame>
  </Step>

  <Step title="Await transaction confirmation">
    <div>
      <Frame>
        <img alt="Redeem Confirm Tx step 1" />
      </Frame>

      <Frame>
        <img alt="Redeem Confirm Tx step 2" />
      </Frame>
    </div>
  </Step>

  <Step title="Confirm successful transaction">
    If successful, a message is displayed confirming the redemption.

    <Frame>
      <img alt="Redeem step 5" />
    </Frame>
  </Step>
</Steps>


# Quickstart: Subscribe and Redeem USYC on Solana
Source: https://developers.circle.com/tokenized/usyc/subscribe-and-redeem-solana



This quickstart shows you how to use the following Yieldcoin Manager program
instructions:

* **Deposit**: Convert underlying assets (USDC) into USYC shares
* **Redeem**: Convert USYC shares back into underlying assets

The Yieldcoin Manager program is an audited smart contract that handles USYC
subscriptions and redemptions on Solana. It includes the teller for processing
deposits and redemptions, and a permissioning system for entitled addresses.

The TypeScript examples in this quickstart use the
[Solana Kit library](https://github.com/anza-xyz/kit).

<Note>
  The code snippets in this quickstart use Solana devnet addresses. For mainnet
  addresses, see [USYC Contract Addresses](/tokenized/usyc/smart-contracts).
</Note>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/)
* Obtained an entitled address to interact with the teller and hold USYC

## Step 1: Set up the project

This step shows you how to install dependencies and generate the client code you
need to interact with the Yieldcoin Manager program.

### 1.1. Install dependencies

Install the Solana Kit library and token program packages:

```bash Shell theme={null}
npm install @solana/kit @solana-program/token @solana-program/token-2022
```

### 1.2. Generate client code

Generate client code from the
[Yieldcoin Manager IDL](https://explorer.solana.com/address/8FZQeFy39fNK47ebUd7aUWoK1rLgJ7fsteWev3FPP1Aw/idl?cluster=devnet)
using your preferred code generator, such as Codama or other Solana IDL tools.

The generated code provides instruction builders similar to the following:

```typescript TypeScript theme={null}
// Example of generated getDepositInstruction function
export function getDepositInstruction<
  TAccountPayer extends string,
  TAccountAssetMint extends string,
  TAccountSenderAssetAccount extends string,
  TAccountTreasuryAssetAccount extends string,
  TAccountFeeRecipientAssetAccount extends string,
  TAccountTeller extends string,
  TAccountShareMint extends string,
  TAccountReceiverShareAccount extends string,
  TAccountReceiverPermissions extends string,
  TAccountAssetTokenProgram extends string,
  TAccountShareTokenProgram extends string,
  TAccountEventAuthority extends string,
  TAccountProgram extends string,
  TProgramAddress extends Address
>(
  input: DepositInput</* ... type parameters ... */>,
  config?: { programAddress?: TProgramAddress }
): DepositInstruction</* ... return type parameters ... */>;
```

## Step 2: Set up the script

This step shows you how to configure imports, constants, and helper functions
for interacting with the Yieldcoin Manager program.

### 2.1. Define imports and constants

Create a new TypeScript file and add the following imports and constants:

```typescript TypeScript theme={null}
import {
  address as toAddress,
  Address,
  appendTransactionMessageInstruction,
  createSolanaRpc,
  createTransactionMessage,
  getAddressEncoder,
  getProgramDerivedAddress,
  Instruction,
  pipe,
  sendAndConfirmTransaction,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  signTransactionMessageWithSigners,
  TransactionSigner,
} from "@solana/kit";
import {
  fetchMaybeTeller,
  getDepositInstruction,
  getRedeemInstruction,
} from "./generated-client"; // Your generated client code
import { TOKEN_PROGRAM_ADDRESS } from "@solana-program/token";
import { TOKEN_2022_PROGRAM_ADDRESS } from "@solana-program/token-2022";

// Program address (devnet)
const YIELDCOIN_MANAGER_PROGRAM_ADDRESS =
  "8FZQeFy39fNK47ebUd7aUWoK1rLgJ7fsteWev3FPP1Aw" as Address;

// Program seeds for PDA derivation
const PROGRAM_SEEDS = {
  USER_PERMISSIONS: "user_permissions",
  EVENT_AUTHORITY: "__event_authority",
  TELLER: "teller",
};

const ONE_HUNDRED_USDC = 100_000000n;
const ONE_HUNDRED_USYC = 100_000000n;
```

### 2.2. Define helper functions

Add the following helper functions to derive PDAs, fetch teller data, and send
transactions:

```typescript TypeScript theme={null}
// Get all public PDAs
export const getPublicPDAs = async () => {
  const programAddress = YIELDCOIN_MANAGER_PROGRAM_ADDRESS;

  const [tellerPda] = await getProgramDerivedAddress({
    programAddress,
    seeds: [PROGRAM_SEEDS.TELLER],
  });

  const [eventAuthorityPda] = await getProgramDerivedAddress({
    programAddress,
    seeds: [PROGRAM_SEEDS.EVENT_AUTHORITY],
  });

  return { tellerPda, eventAuthorityPda };
};

// Get user permissions PDA - derived from wallet address
export const getUserPermissionsPDA = async (
  walletAddress: Address,
): Promise<Address> => {
  const addressEncoder = getAddressEncoder();
  const [userPermissionsPda] = await getProgramDerivedAddress({
    programAddress: YIELDCOIN_MANAGER_PROGRAM_ADDRESS,
    seeds: [
      PROGRAM_SEEDS.USER_PERMISSIONS,
      addressEncoder.encode(walletAddress),
    ],
  });
  return userPermissionsPda;
};

// Fetch teller account data
export const fetchTellerData = async (rpcEndpoint: string) => {
  const rpc = createSolanaRpc(rpcEndpoint);
  const { tellerPda } = await getPublicPDAs();
  const tellerAccount = await fetchMaybeTeller(rpc, tellerPda);
  if (!tellerAccount.exists || !tellerAccount.data) {
    throw new Error("Teller account not found");
  }
  return tellerAccount.data;
};

// Send a transaction with a single instruction
export const sendTransaction = async (
  rpcEndpoint: string,
  instruction: Instruction,
  feePayerSigner: TransactionSigner,
) => {
  const rpc = createSolanaRpc(rpcEndpoint);

  const { value: latestBlockhash } = await rpc
    .getLatestBlockhash({ commitment: "confirmed" })
    .send();

  const transactionMessage = pipe(
    createTransactionMessage({ version: 0 }),
    (m) => setTransactionMessageFeePayerSigner(feePayerSigner, m),
    (m) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, m),
    (m) => appendTransactionMessageInstruction(instruction, m),
  );

  const signedTx = await signTransactionMessageWithSigners(transactionMessage);

  return await sendAndConfirmTransaction(rpc, signedTx, {
    commitment: "confirmed",
  });
};
```

## Step 3: Subscribe and redeem

This step shows you how to subscribe to USYC (deposit USDC) and redeem USYC
(withdraw USDC) using the generated contract functions.

### 3.1. Subscribe to USYC (deposit)

The deposit operation converts USDC into USYC shares. Add the following code to
create a deposit instruction and execute it:

```typescript TypeScript theme={null}
export const createUSYCSubscribeInstruction = async (
  walletAddress: Address,
  senderAssetAccount: Address,
  receiverShareAccount: Address,
  assetAmount: bigint,
  tellerData: any, // Fetched from teller account
) => {
  const { tellerPda, eventAuthorityPda } = await getPublicPDAs();
  // Permissions PDA is derived from the wallet address
  const receiverPermissions = await getUserPermissionsPDA(walletAddress);
  const programAddress = YIELDCOIN_MANAGER_PROGRAM_ADDRESS;

  const depositInstruction = getDepositInstruction(
    {
      payer: walletAddress,
      assetMint: tellerData.assetMint,
      senderAssetAccount,
      treasuryAssetAccount: tellerData.treasuryAssetAccount,
      feeRecipientAssetAccount: tellerData.feeRecipientAssetAccount,
      teller: tellerPda,
      shareMint: tellerData.shareMint,
      receiverShareAccount,
      receiverPermissions,
      assetTokenProgram: TOKEN_PROGRAM_ADDRESS,
      shareTokenProgram: TOKEN_2022_PROGRAM_ADDRESS,
      eventAuthority: eventAuthorityPda,
      program: programAddress,
      assets: assetAmount,
      receiver: walletAddress,
    },
    { programAddress },
  );

  return depositInstruction;
};

// Example usage
export const subscribeExample = async (signer: TransactionSigner) => {
  const walletAddress = "YourWalletAddressHere";
  const senderAssetAccount: Address = "YourUSDCTokenAccountHere";
  const receiverShareAccount: Address = "YourUSYCTokenAccountHere";

  // Fetch teller data first to get mints and treasury addresses
  const tellerData = await fetchTellerData("https://api.devnet.solana.com");

  const instruction = await createUSYCSubscribeInstruction(
    walletAddress,
    senderAssetAccount,
    receiverShareAccount,
    ONE_HUNDRED_USDC,
    tellerData,
  );

  return await sendTransaction(
    "https://api.devnet.solana.com",
    instruction,
    signer,
  );
};
```

### 3.2. Redeem USYC

The redeem operation converts USYC shares back into USDC. Add the following code
to create a redeem instruction and execute it:

```typescript TypeScript theme={null}
export const createUSYCRedeemInstruction = async (
  walletAddress: Address,
  senderShareAccount: Address,
  receiverAssetAccount: Address,
  shareAmount: bigint,
  tellerData: any, // Fetched from teller account
) => {
  const { tellerPda, eventAuthorityPda } = await getPublicPDAs();
  // Permissions PDA is derived from the wallet address
  const senderPermissions = await getUserPermissionsPDA(walletAddress);
  const programAddress = YIELDCOIN_MANAGER_PROGRAM_ADDRESS;

  const redeemInstruction = getRedeemInstruction(
    {
      payer: walletAddress,
      assetMint: tellerData.assetMint,
      receiverAssetAccount,
      treasuryAssetAccount: tellerData.treasuryAssetAccount,
      feeRecipientAssetAccount: tellerData.feeRecipientAssetAccount,
      teller: tellerPda,
      shareMint: tellerData.shareMint,
      senderShareAccount,
      senderPermissions,
      assetTokenProgram: TOKEN_PROGRAM_ADDRESS,
      shareTokenProgram: TOKEN_2022_PROGRAM_ADDRESS,
      eventAuthority: eventAuthorityPda,
      program: programAddress,
      shares: shareAmount,
      receiver: walletAddress,
    },
    { programAddress },
  );

  return redeemInstruction;
};

// Example usage
export const redeemExample = async (signer: TransactionSigner) => {
  const walletAddress = "YourWalletAddressHere";
  const senderShareAccount: Address = "YourUSYCTokenAccountHere";
  const receiverAssetAccount: Address = "YourUSDCTokenAccountHere";

  // Fetch teller data first to get mints and treasury addresses
  const tellerData = await fetchTellerData("https://api.devnet.solana.com");

  const instruction = await createUSYCRedeemInstruction(
    walletAddress,
    senderShareAccount,
    receiverAssetAccount,
    ONE_HUNDRED_USYC,
    tellerData,
  );

  return await sendTransaction(
    "https://api.devnet.solana.com",
    instruction,
    signer,
  );
};
```


# API Endpoints
Source: https://developers.circle.com/tokenized/usyc/web2-apis



You can use the following public HTTP endpoints as an alternative to smart
contract calls.

| Endpoint description                    | Network          | URL                                                                                       |
| --------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| Get the current USYC token price        | Ethereum Mainnet | `https://usyc.hashnote.com/api/price`                                                     |
| Get historical USYC price data          | Ethereum Mainnet | `https://usyc.hashnote.com/api/price-reports`                                             |
| Get the current USYC token price        | Ethereum Sepolia | `https://usyc.dev.hashnote.com/api/price`                                                 |
| Get historical USYC price data          | Ethereum Sepolia | `https://usyc.dev.hashnote.com/api/price-reports`                                         |
| Check if an address is entitled to USYC | Ethereum Mainnet | `https://api.hashnote.com/v1/entitlements/token_access?address={address}&symbol=USYC`     |
| Check if an address is entitled to USYC | Ethereum Sepolia | `https://api.dev.hashnote.com/v1/entitlements/token_access?address={address}&symbol=USYC` |


# Circle Wallets
Source: https://developers.circle.com/wallets

Add secure, embedded wallets to your application with Circle's APIs and SDKs. Manage keys, sign transactions, and support multiple blockchains.

Circle Wallets helps you add secure, embedded
<Tooltip>wallets</Tooltip>
to your application so your users can hold and use digital assets without the
usual complexity of keys, infrastructure, and chain-specific details. You
integrate using REST APIs or Web and Mobile SDKs (Android and iOS).

## Key features

Circle Wallets gives you the building blocks to ship embedded wallets without
running key infrastructure or blockchain nodes yourself.

<AccordionGroup>
  <Accordion title="Key storage and signing" icon="key">
    You don't manage raw private keys. Circle secures keys with MPC or passkeys
    depending on wallet product; you get APIs to create wallets, sign
    transactions, and authorize actions. Key backup, rotation, and recovery are
    built in so you can focus on your app logic.
  </Accordion>

  <Accordion title="Unified APIs and SDKs" icon="server">
    One integration surface for REST APIs and Web or Mobile SDKs (Android and
    iOS). Create wallets, send transfers, and run contract calls from your
    backend or client. Same patterns across developer-controlled,
    user-controlled, and modular wallets based on the supported feature set for
    each product.
  </Accordion>

  <Accordion title="Managed blockchain infrastructure" icon="layer-group">
    Circle handles broadcasting, indexing, and balance and event data for
    supported chains. You don't run or maintain nodes. For chains where full
    infrastructure is not offered, use Signing APIs with your own node.
  </Accordion>

  <Accordion title="Multi-chain and token support" icon="coins">
    Support for multiple chains and token types (including ERC-20, ERC-721,
    ERC-1155 on EVM and SPL on Solana). Unified addressing on EVM so one wallet
    can share the same address across chains. See [Supported
    blockchains](/wallets/supported-blockchains) and [Monitored
    tokens](/wallets/monitored-tokens) for details.
  </Accordion>
</AccordionGroup>

## Products

<CardGroup>
  <Card title="Developer-controlled wallets" icon="server" href="/wallets/dev-controlled">
    You create and operate wallets for your users. Best when you need to move
    funds or run actions on their behalf (for example, payouts or automation).
  </Card>

  <Card title="User-controlled wallets" icon="users" href="/wallets/user-controlled">
    Your users control their own wallets inside your app, with familiar sign-in
    (social, email, or PIN). Best when users should own and approve every
    transaction.
  </Card>

  <Card title="Modular wallets" icon="puzzle-piece" href="/wallets/modular">
    Your users control their wallets with passkeys and optional modules, like
    gasless. Best when you need passkey-based custody and flexible account
    configuration.
  </Card>

  <Card title="Gas Station" icon="gas-pump" href="/wallets/gas-station">
    Sponsor network fees so your users don't need to hold native tokens. Set
    policies and pay gas with your credit card.
  </Card>

  <Card title="Paymaster" icon="credit-card" href="/paymaster">
    Let users pay gas fees with USDC instead of native tokens using Circle's
    permissionless ERC-4337 paymaster contracts.
  </Card>

  <Card title="Compliance Engine" icon="shield-check" href="/wallets/compliance-engine">
    Automate transaction screening for AML and CTF compliance. Define rules,
    manage allowlists and blocklists, and review alerts.
  </Card>
</CardGroup>

## Get started

The right wallet product depends on who controls the wallet:

| Custody model                                       | Best for                                                   | Product                                                 |
| :-------------------------------------------------- | :--------------------------------------------------------- | :------------------------------------------------------ |
| You control the wallet                              | Payouts, automation, backend-initiated actions             | [Developer-controlled wallets](/wallets/dev-controlled) |
| Your users control the wallet with familiar sign-in | Consumer apps where users approve transactions             | [User-controlled wallets](/wallets/user-controlled)     |
| Your users control the wallet with passkeys         | Apps requiring phishing-resistant auth and account modules | [Modular wallets](/wallets/modular)                     |

Confirm blockchain support and account type compatibility before you start
building.

<CardGroup>
  <Card title="Choose your wallet and account types" icon="compass" href="/wallets/account-types">
    Compare wallet products and account types (EOA, SCA, MSCA) to find the right
    fit for your application.
  </Card>

  <Card title="Supported blockchains" icon="link" href="/wallets/supported-blockchains">
    Check which blockchains and tokens are available for each wallet product.
  </Card>
</CardGroup>

## Explore key topics

Explore the following topics as you build. They apply to all wallet products.

<CardGroup>
  <Card title="Signing and authorization" icon="pen" href="/wallets/signing-and-authorization-models">
    How transactions are initiated, authorized, and signed across wallet types.
  </Card>

  <Card title="Batch operations" icon="layer-group" href="/wallets/batch-operations">
    Run multiple operations in one request for supported wallet types and
    chains.
  </Card>

  <Card title="Key management" icon="key" href="/wallets/key-management">
    How keys are secured (MPC vs passkeys), who controls them, and node hosting
    options.
  </Card>

  <Card title="Wallet infrastructure" icon="server" href="/wallets/blockchain-infrastructure">
    Broadcasting, indexing, gas, and bundling; how Circle runs wallet
    infrastructure.
  </Card>
</CardGroup>


# Choose Your Wallet Product and Account Types
Source: https://developers.circle.com/wallets/account-types

Choose the right Circle Wallets product and account type for your use case.

Before you build, you need to choose a wallet product. Your wallet product
determines which account types are available to you. If you choose Modular
Wallets, your account type is always a
[Modular Smart Contract Account (MSCA)](#smart-contract-accounts-sca-and-msca).

If you choose developer-controlled or user-controlled wallets, you need to pick
between an [Externally Owned Account (EOA)](#externally-owned-accounts-eoa) and
a [Smart Contract Account (SCA)](#smart-contract-accounts-sca-and-msca). EOAs
are controlled by a private key and work across all supported blockchains. SCAs
are smart contracts that support gas sponsorship, batch operations, and flexible
ownership. See the [account type comparison](#account-type-comparison) for a
full breakdown.

## Wallet product comparison

The following table maps common use cases to the recommended wallet product and
account type:

| If you want                                                              | Wallet product       | Account type       |
| ------------------------------------------------------------------------ | -------------------- | ------------------ |
| Full backend control (for example, payouts, automation, custodial flows) | Developer-controlled | EOA or SCA         |
| Users to own and approve their transactions                              | User-controlled      | EOA or SCA         |
| Passkeys, modules, or a fully customized wallet experience               | Modular              | MSCA (only option) |

### Developer-controlled wallets

Your backend creates and manages wallets on behalf of users. You control when
wallets are created, how transactions are signed, and how funds move without
your users managing keys or interacting with the blockchain directly.

**Use when:** You need fine-grained control over wallets and transactions
without exposing blockchain complexity to your users.

**Example use cases**: Payouts, automation, deposit collection, AI agent wallets

[Account type](#account-type-comparison): EOA or SCA

### User-controlled wallets

Users own and control their wallets inside your app. They authenticate with
familiar methods
([social login](/wallets/user-controlled/create-user-wallets-with-social-login),
[email OTP](/wallets/user-controlled/create-user-wallets-with-email), or
[PIN](/wallets/user-controlled/create-user-wallets-with-pin)) and approve every
transaction. Your app handles the interface while Circle handles key management
and recovery.

**Use when:** You want your users to fully control their funds and approve every
transaction.

**Example use cases**: Consumer apps, fintech platforms, reward wallets

[Account type](#account-type-comparison): EOA or SCA

### Modular wallets

You design the wallet experience while Circle handles signing and
infrastructure. Modular wallets are smart contract wallets built on open
composable standards, extendable with pre-built audited modules, for example,
passkey authentication, batch transactions, and parallel execution.

**Use when:** You need a customized wallet experience that developer-controlled
or user-controlled wallets don't cover.

**Example use cases**: Passkey signing, multisig, subscriptions, custom
transaction logic

[Account type](#account-type-comparison): MSCA only

## Account type comparison

The following table compares EOA and smart contract account capabilities:

|                         | EOA                                                         | Smart contract account (SCA / MSCA)                                         |
| ----------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Wallet product**      | Developer-controlled, user-controlled                       | SCA: Developer-controlled, user-controlled <br /> MSCA: Modular only        |
| **Control**             | Private key                                                 | Smart contract (owner can be a single key, passkey, or multiple signers)    |
| **Blockchains**         | All [supported blockchains](/wallets/supported-blockchains) | EVM only                                                                    |
| **Creation fee**        | None                                                        | Gas charged on first outbound transaction                                   |
| **Gas per transaction** | Lower                                                       | Higher (contract validation overhead)                                       |
| **Gas sponsorship**     | Solana only, using [`feePayer`](/wallets/wallets-on-solana) | Yes, using [Gas Station](/wallets/gas-station) or a [paymaster](/paymaster) |
| **Batch operations**    | No                                                          | Yes                                                                         |
| **Modules**             | No                                                          | MSCA only                                                                   |

<Tip>
  For Ethereum mainnet, use EOA. SCA deployment gas on Ethereum mainnet can be
  high.
</Tip>

### Externally owned accounts (EOA)

An EOA is an account controlled by a private key. On EVM, EOAs require native
tokens for gas. EOAs work on all
[supported blockchains](/wallets/supported-blockchains) and are the only option
on Solana, Aptos, and NEAR.

**Use EOA when:**

* You are building on Solana, Aptos, or NEAR.
* You are building on Ethereum mainnet and want to avoid high SCA deployment
  costs.
* You need high transaction throughput. For example, airdrops or mass payouts.
* You do not need gas sponsorship, batching, or custom account logic.

### Smart contract accounts (SCA and MSCA)

SCAs are available with developer-controlled and user-controlled wallets. MSCAs
are available with Modular Wallets only.

A Smart Contract Account (SCA) and a Modular Smart Contract Account (MSCA) share
the same foundation: both follow [ERC-4337](https://www.erc4337.io/docs) and
[ERC-6900](https://www.erc6900.io/), both support gas abstraction and batch
operations, and both use lazy deployment. Deployment gas is charged on the first
outbound transaction, not at wallet creation. Both also carry higher
per-transaction gas than EOAs due to contract validation overhead.

SCA and MSCA wallets use versioned proxy contracts. For contract versions,
addresses, and upgrade instructions, see
[Upgrade your SCA wallet](/wallets/wallet-upgrades).

**Use SCA or MSCA when:**

* You want to sponsor gas for users (gasless transactions)
* You need to batch multiple operations into one transaction
* You are building on EVM L2s or other supported EVM networks

<Note>
  If you chose Modular Wallets, your smart contract account is an MSCA. The key
  difference from an SCA is that MSCAs support
  [modules](/wallets/modular/modules), pre-built audited smart contracts that
  extend account behavior with features like passkey authentication, multisig, or
  subscription logic. Everything else, gas abstraction, batching, and lazy
  deployment, works the same way. For a full explanation of how MSCAs work with
  the Modular Wallet SDK, see [Modular Wallets](/wallets/modular).
</Note>


# Wallets API Rate Limits
Source: https://developers.circle.com/wallets/api-rate-limits



Circle APIs handle a large number of API requests. There are limits on how many
requests you can make per second. This keeps the API working well for everyone.

The default rate limit for all Wallets API endpoints is 5 requests per second
(RPS). The table below lists all endpoints that have a different rate limit.

| Method | Endpoint                                                  | Maximum requests per second |
| ------ | --------------------------------------------------------- | --------------------------- |
| `POST` | `/v1/w3s/developer/wallets`                               | 10                          |
| `PUT`  | `/v1/w3s/developer/wallets/{id}/blockchains/{blockchain}` | 10                          |
| `POST` | `/v1/w3s/transactions/transfer/estimateFee`               | 10                          |
| `POST` | `/v1/w3s/transactions/contractExecution/estimateFee`      | 10                          |
| `POST` | `/v1/w3s/users/token`                                     | 10                          |
| `POST` | `/v1/w3s/user/sign/transaction`                           | 10                          |
| `POST` | `/v1/w3s/user/sign/message`                               | 10                          |
| `POST` | `/v1/w3s/user/sign/typedData`                             | 10                          |
| `POST` | `/v1/w3s/developer/sign/transaction`                      | 10                          |
| `POST` | `/v1/w3s/developer/sign/message`                          | 10                          |
| `POST` | `/v1/w3s/developer/sign/typedData`                        | 10                          |
| `POST` | `/v1/w3s/developer/sign/delegateAction`                   | 10                          |
| `GET`  | All endpoints                                             | 20                          |
| `POST` | All other endpoints                                       | 5                           |


# Transaction States and Errors
Source: https://developers.circle.com/wallets/asynchronous-states-and-statuses

Reference for transaction and challenge states, transaction error reasons, and ESTIMATION_ERROR details for Circle Wallets.

API entities, such as transactions and challenges, are processed asynchronously
after the initial POST request.

As the request is processed, the transaction's state, or the challenge's status,
will update accordingly. This update can be retrieved either by polling the
associated GET endpoint or by subscribing to
[webhook notifications](/wallets/webhook-notifications) (recommended).

<Note>
  **Learn more about managing transactions**: transaction queues, stuck
  transactions, and performance optimizations in
  [Transaction Rate Limits and Optimizations](/wallets/transaction-limits-and-optimizations).
</Note>

## Transaction states

Transactions go through various states after initiation to indicate if they've
begun processing, are identifiable on the blockchain, complete, failed, or
require further action, such as when a transaction becomes `STUCK`.

Specific actions, like canceling or accelerating a transaction, can only be
taken when a transaction is in a specific state.

Canceling a transaction can only occur when a transaction is in the `INITIATED`,
`QUEUED`, or `SENT` states.

Accelerating a transaction can only occur when a transaction is in the `SENT` or
`STUCK` state.

If a transaction cannot be successfully completed, it enters the `FAILED` state
and has accompanying `errorReason` and `errorDetails` fields that describe the
failure.

The following table describes the possible states of a transaction:

| **State**   | **Description**                                                                                                                                                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INITIATED` | The transaction has been initiated.                                                                                                                                                                                             |
| `QUEUED`    | The transaction is in the processing queue.                                                                                                                                                                                     |
| `CLEARED`   | The transaction has passed initial checks and risk screening and is ready for further processing.                                                                                                                               |
| `SENT`      | The transaction has been identified in the Mempool and assigned a transaction hash. The transaction may be accelerated at this stage.                                                                                           |
| `STUCK`     | The transaction has been sent to the blockchain but could not be included in a block. See how to [handle stuck transactions](/wallets/transaction-limits-and-optimizations#handling-stuck-transactions) to ensure confirmation. |
| `CONFIRMED` | The transaction has been identified on a mined block. The transaction can no longer be canceled.                                                                                                                                |
| `COMPLETE`  | **Terminal State.** The transaction has successfully completed.                                                                                                                                                                 |
| `CANCELLED` | **Terminal State.** The transaction has been canceled and must be re-initiated.                                                                                                                                                 |
| `FAILED`    | **Terminal State.** The transaction has failed. The transaction must be re-initiated.                                                                                                                                           |
| `DENIED`    | **Terminal State.** The platform denies the transaction. For additional information, refer to the `errorReason` and `errorDetails` fields.                                                                                      |

## Transaction errors

If a transaction cannot be completed and enters the FAILED state, the
transaction object has accompanying `errorReason` and `errorDetails` fields that
describe the failure.

| Error Reason                                     | Description                                                                                                                                                                                                                                                              |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ESTIMATION_ERROR`                               | The transaction estimation failed during node execution. See [ESTIMATION\_ERROR Details](#estimation_error-details) for common causes and remedies.                                                                                                                      |
| `INSUFFICIENT_NATIVE_TOKEN`                      | The wallet does not have a sufficient balance of the blockchain's native asset to cover the [gas fees](/wallets/gas-fees) needed for all pending transactions.                                                                                                           |
| `ABI_SIGNATURE_PARAMS_MISMATCH`                  | The signature and parameter of ABI are mismatched.                                                                                                                                                                                                                       |
| `FEE_EXCEEDS_MAX_ALLOWANCE`                      | The fee exceeds the max allowance. There is one native token fee limit to prevent any unintended transaction from being sent out.                                                                                                                                        |
| `QUERY_NFT_METADATA_ERROR`                       | The NFT metadata cannot be found.                                                                                                                                                                                                                                        |
| `GAS_LIMIT_TOO_LOW`                              | The provided fee tolerance (`gasLimit`) was too low to complete the requested transaction.                                                                                                                                                                               |
| `TRANSACTION_UNDER_PRICE`                        | The transaction's max fee or priority fee is lower than the current lowest max fee or priority fee in mempool when mempool is full.                                                                                                                                      |
| `FAILED_ON_CHAIN`                                | The transaction failed to be processed by the blockchain.                                                                                                                                                                                                                |
| `FAILED_REORG`                                   | The transaction was dropped because of blockchain re-org.                                                                                                                                                                                                                |
| `INTERNAL_ERROR`                                 | The transaction failed due to an internal error.                                                                                                                                                                                                                         |
| `PAYMASTER_POLICY_NOT_ACTIVATED`                 | The paymaster policy hasn't been set or activated.                                                                                                                                                                                                                       |
| `PAYMASTER_POLICY_EXCEED_MAX_DAILY_TRANSACTIONS` | The maximum number of daily transactions allowed by the paymaster policy has been reached. Try again tomorrow or update the policy limits.                                                                                                                               |
| `PAYMASTER_POLICY_EXCEED_MAX_SPEND_USD_PER_TX`   | The transaction exceeds the maximum allowable spend in USD as per the paymaster policy for a single transaction. Increase the limits in your policy for such transactions to go through.                                                                                 |
| `PAYMASTER_POLICY_EXCEED_MAX_SPEND_USD_DAILY`    | The maximum daily spending limit in USD set by the paymaster policy has been reached. Try again tomorrow or update the policy limits.                                                                                                                                    |
| `PAYMASTER_POLICY_EXCEED_MAX_NATIVE_TOKEN_DAILY` | The maximum daily spending limit for native tokens set by the paymaster policy has been reached. Try again tomorrow or update the policy limits.                                                                                                                         |
| `PAYMASTER_POLICY_SENDER_IN_BLOCKLIST`           | The sender wallet of the transaction is blocked by the paymaster policy. Update the policy blocklist to allow this user to go through.                                                                                                                                   |
| `PAYMASTER_ENTITY_RESTRICTION`                   | At this time, your account is restricted from using Gas Station. Go to the Developer Services [Console Paymaster](https://console.circle.com/gas-station/paymasters) page to learn more.                                                                                 |
| `SOLANA_ATA_NOT_FOUND`                           | The recipient's Associated Token Account (ATA) on Solana does not exist. See [Solana ATA sponsorship](/wallets/gas-station/solana-ata-sponsorship) to have Gas Station fund ATA creation, or [create and fund the ATA](/wallets/gas-station/create-solana-ata) yourself. |

## Challenge states

Challenges go through several statuses to indicate whether they have been
presented to the user, completed, and more.

If a challenge cannot be successfully completed, it enters the `FAILED` state
and has accompanying `errorCode` and `errorMessage` fields that describe the
failure.

| **Status**   | **Description**                                                         |
| ------------ | ----------------------------------------------------------------------- |
| PENDING      | The request has been created but has not yet been approved by the user. |
| IN\_PROGRESS | The user has approved the request, and it is being executed.            |
| COMPLETED    | The request is complete.                                                |
| FAILED       | The request has failed to execute. The request must be re-initiated.    |
| EXPIRED      | The request has expired. The request must be re-initiated.              |

## ESTIMATION\_ERROR details

When a transaction fails with `ESTIMATION_ERROR`, the `errorDetails` field
provides specific information about why the transaction estimation failed.

Below are the common `errorDetails` values grouped by category, along with their
causes and recommended remedies.

### Insufficient balance errors

These errors occur when the wallet or contract doesn't have enough tokens to
complete the transaction.

| `errorDetails`                               | Cause                                                                                                                             | Remedy                                                                                                                     |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `ERC20: transfer amount exceeds balance`     | The wallet doesn't have enough ERC-20 tokens to complete the transfer.                                                            | Verify the wallet has sufficient token balance before initiating the transaction. Top up the wallet if needed.             |
| `ERC1155: insufficient balance for transfer` | The wallet doesn't have enough ERC-1155 tokens (NFTs or semi-fungible tokens) to transfer.                                        | Check the wallet's ERC-1155 token balance for the specific token ID. Ensure the correct token ID and amount are specified. |
| `Insufficient Balance`                       | General insufficient balance error. The wallet either doesn't have enough gas or does not have enough tokens for the transaction. | Verify the contract has sufficient USDC. This may require the contract owner to top up the contract.                       |

### Blocklist and access control errors

These errors occur when an account is restricted from performing certain
actions.

| `errorDetails` | Cause | Remedy |
| -------------- | ----- | ------ |

&#x20;\| `Blacklistable: account is blacklisted` | The
recipient or sender address has been added to the token contract's denylist. See
details below. | Verify you're not sending to the token contract address itself.
\|  |
`AccessControl: account ... is missing role ...` | The wallet doesn't have the
required role/permission to execute this function on the contract. | Ensure the
wallet has been granted the necessary role by the contract administrator, or use
an authorized wallet. |

<Note>
  **Common cause: Sending USDC to the USDC contract address**

  The USDC contract address itself is intentionally on Circle's denylist to
  prevent developers from accidentally sending USDC tokens to the contract
  address. Tokens sent to a token contract address would be permanently locked and
  unrecoverable through normal means.
</Note>

### Allowance and approval errors

These errors occur when token spending approvals are missing or insufficient.

| `errorDetails`                             | Cause                                                                             | Remedy                                                                                                     |
| ------------------------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `ERC20: transfer amount exceeds allowance` | The contract hasn't been approved to spend enough tokens on behalf of the wallet. | Call the `approve()` function on the token contract to grant sufficient allowance to the spender contract. |
| `ERC20: insufficient allowance`            | Similar to the preceding error—the spender doesn't have enough allowance.         | Increase the token allowance by calling `approve()` or `increaseAllowance()`.                              |
| `Check allowance` / `Allowance`            | Generic allowance error.                                                          | Verify and increase token allowance.                                                                       |

### Signature and authentication errors

These errors occur when cryptographic signatures are invalid or expired.

| `errorDetails`                    | Cause                                                                       | Remedy                                                                       |
| --------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `EIP2612: invalid signature`      | The permit signature is invalid, malformed, or was signed by the wrong key. | Generate a new valid signature using the correct private key and parameters. |
| `Permit: invalid signature`       | Invalid permit signature.                                                   | Re-sign the permit with correct parameters.                                  |
| `Invalid signature: not attester` | The signature wasn't created by an authorized attester (common in CCTP).    | Use a signature from an authorized attester.                                 |
| `Nonce already used`              | The nonce in the signed message has already been consumed.                  | Use a fresh nonce value when creating the signature.                         |

### Smart account (ERC-4337) errors

These errors occur with smart contract wallets using account abstraction.

| `errorDetails`                    | Cause                                            | Remedy                                                                |
| --------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------- |
| `AA33 reverted: Pausable: paused` | The smart account or paymaster is paused.        | Wait for the contract to be `unpaused`, or contact the administrator. |
| `AA95 out of gas`                 | The transaction ran out of gas during execution. | Increase the gas limit for the transaction.                           |

### Invalid parameters

These errors occur when transaction parameters are incorrect.

| `errorDetails`                                                         | Cause                                                 | Remedy                                                                      |
| ---------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------- |
| `Transfer amount must be greater than zero` / `Amount must be nonzero` | The amount parameter cannot be zero.                  | Provide a positive amount value.                                            |
| `Amount below minimum` / `USDC amount too small`                       | The amount is below the minimum required threshold.   | Increase the amount to meet minimum requirements.                           |
| `ERC20: transfer to the zero address`                                  | Cannot transfer tokens to the zero address (0x0).     | Provide a valid non-zero recipient address.                                 |
| `ERC721: invalid token ID`                                             | The specified NFT token ID doesn't exist.             | Verify the token ID exists and is valid.                                    |
| `Max fee must be less than amount`                                     | The fee exceeds the transaction amount.               | Reduce the fee or increase the transaction amount.                          |
| `Slippage Limit Exceeded`                                              | The price slippage exceeds the allowed tolerance.     | Increase slippage tolerance or wait for better market conditions.           |
| `Too little received` / `insufficient amountReceived`                  | The output amount is less than the minimum specified. | Adjust minimum output amount or retry when market conditions are favorable. |

### Timeout and execution errors

These generic errors can occur during transaction execution.

| `errorDetails`                             | Cause                                                              | Remedy                                                                                                                        |
| ------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `Fails to perform transaction estimation.` | General estimation failure without specific details.               | Review contract state and transaction parameters. This often happens due to network fee fluctuation; retry later often helps. |
| `execution aborted (timeout = 10s)`        | The estimation took too long and timed out.                        | This could be due to an RPC node being temporarily unavailable. Retry later often helps.                                      |
| `execution reverted`                       | Generic revert without a specific reason provided by the RPC node. | Review contract state and transaction parameters. This often happens due to network fee fluctuation; retry later often helps. |

For guidance on diagnosing and resolving failed transactions, see
[Troubleshoot failed transactions](/wallets/troubleshoot-failed-transactions).


# Batch Operations
Source: https://developers.circle.com/wallets/batch-operations

Submit multiple user operations as a batch

Both developer-controlled wallets and modular smart contract accounts (MSCAs)
support batching user operations into a single atomic transaction. These batched
operations have several advantages:

* Users only need to wait for a single batched transaction to execute, instead
  of multiple individual transactions.
* Users pay less in gas fees, as batched transactions cost less than multiple
  individual transactions.
* Transactions are atomic: if any transaction in the batch reverts, the entire
  batch reverts.

You can batch transactions through the
[`contractExecution`](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-contract-execution)
endpoint.

## Example: Batch transfer

The following example demonstrates how to generate a call to the
`contractExecution` endpoint that batches two USDC transfer transactions. This
example uses an MSCA wallet, on the ETH-SEPOLIA testnet.

This code creates the encoding of the `transfer` function calls that make up the
`abiParameters` data for the call to the `contractExecution` endpoint:

```javascript JavaScript theme={null}
const { ethers } = require("ethers");

const abiEncode = async function () {
  // encode callData for transfers
  const abiTransfer = ["function transfer(address recipient, uint256 amount)"];
  const contractInterfaceTransfer = new ethers.utils.Interface(abiTransfer);
  let data = contractInterfaceTransfer.encodeFunctionData("transfer", [
    "0xa1404d9E7646b0112C49aE0296D6347C956D0867",
    100000000, // 100 usdc
  ]);
  console.log(data);
};

abiEncode()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });
```

Note that the preceding code sample encodes only a single call to the `transfer`
function, the call is then specified twice in the `abiParameters` field of the
call to the `contractExecution` endpoint.

```json JSON theme={null}
{
  "idempotencyKey": "{{$randomUUID}}",
  "walletId": "{{wallet-id}}",
  "feeLevel": "HIGH",
  "refId": "test batch transfer",

  "contractAddress": "0xcd3d4d703f1884313e8f3188a8c60cc6d389ebd1", // sca wallet address

  "abiFunctionSignature": "executeBatch((address, uint256, bytes)[])",
  "abiParameters": [
    [
      [
        "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238",
        "0",
        "0xa9059cbb000000000000000000000000a1404d9e7646b0112c49ae0296d6347c956d08670000000000000000000000000000000000000000000000000000000000000001"
      ],
      [
        "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238",
        "0",
        "0xa9059cbb000000000000000000000000a1404d9e7646b0112c49ae0296d6347c956d08670000000000000000000000000000000000000000000000000000000000000001"
      ]
    ]
  ],

  "entitySecretCiphertext": "{{entity-secret-ciphertext}}"
}
```

The function signature called is
`executeBatch((address address, uint256 amount, bytes func)[])`. The `address`
is the USDC contract address, `amount` is `0` (the amount of native token
transferred), and `func` is the encoded function call generated by the sample
code. The example provides the parameters twice, so the resulting batched
transactions result in 200 USDC transferred (100 for each transaction).

## Example: Batching CCTP approve and depositForBurn

The following example demonstrates how to generate a call to the
`contractExecution` endpoint that batches two related transactions: `approve`,
and `depositForBurn` in the CCTP contract. This example uses an MSCA wallet, on
the ETH-SEPOLIA testnet.

This code creates the encoding of the two calls that make up the `abiParameters`
data for the call to the `contractExecution` endpoint.

```javascript JavaScript theme={null}
const { ethers } = require("ethers");

const abiEncode = async function () {
  const abiDepositForBurn = [
    "function depositForBurn(uint256,uint32,bytes32,address)",
  ];
  const abiApprove = ["function approve(address,uint256)"];
  const contractInterfaceApprove = new ethers.utils.Interface(abiApprove);
  const contractInterfaceDepositForBurn = new ethers.utils.Interface(
    abiDepositForBurn,
  );

  // encode approve
  let dataApprove = contractInterfaceApprove.encodeFunctionData("approve", [
    "0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5",
    100000000, // 100 usdc
  ]);
  console.log(dataApprove);

  // encode sca wallet address
  const abi = ethers.utils.defaultAbiCoder;
  let encodedAddress = abi.encode(
    ["address"],
    ["0xc4b69f1f26c820e7fa18c925da8bf2b2a3357fe0"],
  );
  console.log(encodedAddress);

  // encode depositForBurn
  let dataDepositForBurn = contractInterfaceDepositForBurn.encodeFunctionData(
    "depositForBurn",
    [
      100000000,
      2, // AVAX
      encodedAddress, // encoded sca wallet address
      "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238", // usdc contract
    ],
  );
  console.log(dataDepositForBurn);
};

abiEncode()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });
```

The first transaction in the batch is a call to the function on the USDC
contract: `approve(address spender, uint256 value)`. Calling `approve` allows
the `spender` to spend `value` USDC on your behalf. This is necessary for the
subsequent `depositForBurn` transaction in the batch. In this example, `address`
is the `TokenMessenger` contract address and the `value` is `100000000` (100
USDC). Note that the example code encodes the parameters of the function call,
the subsequent call to the Circle API specifies the contract address to make the
call to.

The second transaction in the batch is a call to the function on the
`TokenMessenger` contract:
`depositForBurn(uint256 amount, uint32 destinationDomain, bytes32 mintRecipient, address burnToken)`.
Calling `depositForBurn` results in the `TokenMessenger` contract transferring
and burning the specified amount of USDC from the wallet on the origin chain.
The parameters to the `depositForBurn` call are:

* `amount`: the amount of USDC to burn. In this example, `100000000` (100 USDC)
* `destinationDomain`: a Circle-issued identifier for a network where Circle
  deploys CCTP contracts. In this example, `2` to specify Avalanche. For a full
  list, see the
  [CCTP domain list](/cctp/cctp-supported-blockchains#cctp-supported-domains).
* `mintRecipient`: the destination address, encoded as a Solidity address.
* `burnToken`: the contract address of the token to burn. In this example, the
  USDC contract on the source chain.

The preceding code results in a request to the `contractExecution` endpoint like
this:

```json JSON theme={null}
{
  "idempotencyKey": "{{$randomUUID}}",
  "walletId": "{{wallet-id}}",
  "feeLevel": "HIGH",
  "refId": "test batch CCTP",
  "contractAddress": "0xcd3d4d703f1884313e8f3188a8c60cc6d389ebd1", // sca wallet address
  "abiFunctionSignature": "executeBatch((address, uint256, bytes)[])",
  "abiParameters": [
    [
      [
        "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238",
        "0",
        "0x095ea7b30000000000000000000000009f3b8679c73c2fef8b59b4f3444d4e156fb70aa500000000000000000000000000000000000000000000000000000000000003e8"
      ],
      [
        "0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5",
        "0",
        "0x6fd3504e00000000000000000000000000000000000000000000000000000000000003e80000000000000000000000000000000000000000000000000000000000000002000000000000000000000000c4b69f1f26c820e7fa18c925da8bf2b2a3357fe00000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c7238"
      ]
    ]
  ],
  "entitySecretCiphertext": "{{entity-secret-ciphertext}}"
}
```

The function signature called is
`executeBatch((address address, uint256 amount, bytes func)[])`. The parameters
for each transaction are:

* `approve`
  * `address` is the USDC token contract address
  * `amount` is the amount of native tokens transferred
  * `func` is the encoded function call generated by the sample code

* `depositForBurn`
  * `address` is the `TokenMessenger` contract address
  * `amount` is the amount of native tokens transferred
  * `func` is the encoded function call generated by the sample code


# Blockchain Confirmations
Source: https://developers.circle.com/wallets/blockchain-confirmations

How Circle Wallets uses blockchain confirmations to determine transaction finality.

Blockchain confirmations secure transactions and ensure finality on a
blockchain. When you build with Circle Wallets, understanding confirmations
helps you balance speed with the risk of blockchain reorganizations (reorgs).

## How confirmations work

When you submit a transaction to a blockchain using Circle Wallets, it starts in
the `INITIATED` state. The network must include it in a block before it reaches
the `CONFIRMED` state. Each new block added after that makes the transaction
harder to reverse.

A **confirmation number** is the number of blocks that must follow a
transaction's block before it is final. Once the confirmation number is reached,
the transaction can't be reversed.

## Why confirmations matter

Without enough confirmations, transactions are at risk of reorgs. A reorg
happens when validators discard recent blocks and replace them with new ones,
rewriting part of the blockchain's history. This can reverse transactions that
appeared settled.

Each extra confirmation makes a reorg less likely. Because blockchains differ in
design, block times, and consensus, the number of confirmations needed varies by
blockchain.

## How Circle Wallets handles confirmations

Circle Wallets waits for each blockchain's standard confirmation threshold
before marking a transaction as `COMPLETE`. Confirmation times vary by
blockchain.

<Note>
  Even if a transaction is visible on a block explorer, it may not be `COMPLETE`
  in Circle Wallets if it hasn't reached the required number of confirmations for
  that blockchain.
</Note>


# Blockchain Infrastructure
Source: https://developers.circle.com/wallets/blockchain-infrastructure

The blockchain infrastructure Circle Wallets provides, including broadcasting, indexing, gas fees, and transaction bundling.

Circle Wallets provides built-in blockchain infrastructure on all blockchains
listed in [Supported blockchains](/wallets/supported-blockchains), except for
NEAR and the Other EVM blockchains category. This eliminates the need to
integrate third-party providers for the following:

* **Broadcasting**: Circle broadcasts signed transactions to the blockchain. To
  use your own node provider, use the [Signing APIs](/wallets/signing-apis) to
  sign transactions and broadcast them yourself.
* **Indexing**: Circle indexes transfer events and balances in real time,
  serving data through low-latency APIs and
  [webhook notifications](/api-reference/wallets/common/create-subscription).
* **[Gas Station](/wallets/gas-station)**: Circle manages gas fees so users
  don't need to hold native tokens.
* **Bundler**: Circle bundles user operations for smart contract account (SCA)
  and modular smart contract account (MSCA) wallets, so you can initiate
  transactions without constructing them manually.


# Compliance Engine
Source: https://developers.circle.com/wallets/compliance-engine



Compliance Engine helps developers enable compliance with evolving regulations
in the blockchain space. It provides a tool for automating transaction screening
that you can integrate into your blockchain workflows through new and updated
APIs.

<Note>
  Compliance Engine on both testnet and mainnet is only available for eligible
  customers. Contact Circle through the
  [Compliance Engine request form](https://www.circle.com/wallets/compliance-engine/#get-in-touch)
  to get access.
</Note>

## Introduction

The rapid evolution of digital assets has introduced new regulatory challenges
for enterprises working with blockchain technologies. Ensuring compliance with
Anti-Money Laundering (AML), Counter-Terrorist Financing (CTF), and other
jurisdictional requirements is now a fundamental need. Circle's Compliance
Engine is a response to these challenges, offering you a solution you can
integrate directly into your applications.

[Transaction Screening](/wallets/compliance-engine/tx-screening) automatically
flags high-risk transactions in real-time, preventing potentially non-compliant
activities before they occur.

This tool, available as part of Compliance Engine, provides a seamless solution
for managing compliance workflows, protecting businesses from financial crime
while reducing operational burden.

## Key features

* **One-stop shop:** Consolidate wallet management and transaction evaluations
  into a single platform to remove additional costs like internal training,
  vendor onboarding, or system integrations.
* **Tailored Compliance:** Define rules on how to handle transactions and alerts
  to ensure they align with your unique business use-case and regulatory
  requirements.
* **In-depth investigations:** Leverage console tooling to deep-dive and
  evaluate alerts and research specific wallet addresses to assist with
  transaction reviews or internal investigations.
* **Allowlists & blocklists:** Mitigate risk with quick and granular control
  over your business database of authorized or blocklisted entities.
* **Comprehensive Reporting:** Access and export detailed transaction logs and
  compliance data to facilitate internal investigations, or emphasize regulatory
  adherence.

<Note>
  For integration details, see the
  [Compliance Engine](/wallets/compliance-engine/tx-screening-quickstart) and
  explore the transaction screening option available in the
  [Circle Console](https://console.circle.com/).
</Note>


# Compliance Engine API Error Codes
Source: https://developers.circle.com/wallets/compliance-engine/error-codes

Descriptions of error codes returned by the Compliance Engine API

The Wallets and Contracts APIs return an
[HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) when
they encounter an error in an API request:

* `4xx` errors are client errors, which are informative and actionable. They
  communicate a mistake to the user and suggest fixes.
* `5xx` errors are unexpected server-side errors.

The tables in the following sections describe some of the common error messages
you might encounter using the Wallets and Contracts APIs. Where possible, a
suggested fix is provided in the `Description` column.

## General error format

HTTP status codes do not always provide sufficient information to determine the
cause of the error. Since the status code is part of the header of the response,
the body of response contains additional, Circle-specific, error information.
For example, if a request contains an invalid parameter, the response includes
the following:

**Header**

`HTTP/1.1 400 Bad RequestContent-Type: application/json`

**Body**

```json JSON theme={null}
{
  "code": 2,
  "message": "API parameter invalid"
}
```

## Extended error format

In some cases, the response includes extended information about the cause of the
error. For example, if a request doesn't include a value for a required
parameter, the response includes a detailed error message:

**Header**

`HTTP/1.1 400 Bad RequestContent-Type: application/json`

**Body**

```json JSON theme={null}
{
  "code": 2,
  "message": "API parameter invalid",
  "errors": [
    {
      "error": "required",
      "message": "fail to bind request to CreateWalletSetRequest: EOF",
      "location": "field1",
      "invalidValue": "null",
      "constraints": {}
    }
  ]
}
```

## General errors

This section describes some common extended error messages you might encounter
using Wallets and Contracts APIs.

The following errors are general errors that can be returned for any request.

| Error Code | HTTP code | Error Message          | Description                                                      |
| :--------- | :-------- | :--------------------- | :--------------------------------------------------------------- |
| `-1`       | `400`     | `Something went wrong` | An unknown error occurred while processing the API request.      |
| `3`        | `403`     | `Forbidden`            | The API key used does not have access to the requested endpoint. |

### Invalid requests

A `400` HTTP status code indicates that the request is invalid or malformed.
When the request is invalid, the Circle-specific error code is `2`. The
following table describes the common error messages that can be returned for
invalid requests.

| Error Code | HTTP code | Error Message                                                             | Description                                                                                                          |
| :--------- | :-------- | :------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------- |
| `2`        | `400`     | `Invalid Entity`                                                          | There is an error in the JSON format passed in the request.                                                          |
| `2`        | `400`     | `Fail to bind request to parameter: invalid UUID format`                  | The parameter must be in UUID format.                                                                                |
| `2`        | `400`     | `Error: Field validation`                                                 | One of the fields in the request is invalid.                                                                         |
| `2`        | `400`     | `Error: Field validation for blockchain failed on the blockchain tag`     | The blockchain does not exist. Try again with a [supported blockchain](/wallets/supported-blockchains).              |
| `2`        | `400`     | `Error: Field validation for gasLimit failed on the required_without tag` | If `feeLevel` is provided, `gasLimit` should be set to `NULL`. If `feeLevel` is `NULL`, `gasLimit` must be provided. |
| `2`        | `400`     | `Error: Field validation for parameter failed on the min tag`             | The parameter is not in the correct format.                                                                          |
| `2`        | `400`     | `Cannot unmarshal`                                                        | The JSON body of the request is not valid.                                                                           |
| `2`        | `400`     | `INVALID: parameter empty`                                                | The parameter is required for this request. Try the request again with this parameter.                               |

## Compliance Engine errors

This section includes the errors that can be returned from Compliance Engine API
requests.

### Standalone screening errors

| Error code | HTTP code | Error message                | Description                                                    |
| ---------- | --------- | ---------------------------- | -------------------------------------------------------------- |
| `280001`   | `400`     | `Unsupported blockchain`     | Provided blockchain either does not exist or is not supported. |
| `280002`   | `400`     | `Invalid blockchain address` | Provided blockchain address is not valid.                      |


# Transaction Screening
Source: https://developers.circle.com/wallets/compliance-engine/tx-screening



Transaction Screening is a real-time tool that automatically checks blockchain
transactions and associated addresses for risks related to sanctioned entities,
terrorist financing, or other suspicious behaviors. This is a core component of
the [Compliance Engine](/wallets/compliance-engine) and it allows you to
configure screening rules to meet the specific compliance requirements of your
jurisdiction or industry.

You can trigger screening evaluations using two methods:

* Embedded: screening occurs implicitly during regular programmable wallet
  transaction flow.
* Standalone: screening is triggered explicitly through the Compliance API.

<Note>
  Compliance Engine on both testnet and mainnet is only available for eligible
  customers. Contact Circle through the
  [Compliance Engine request form](https://www.circle.com/wallets/compliance-engine/#get-in-touch)
  to get access.
</Note>

## Features

* **Custom rules**: Tailor your own screening rules to match your specific use
  and regulatory requirements.
* **Blocklist/Allowlist**: You can specify blocklisted or allowlisted addresses,
  enhancing control over transactions and minimizing the chance of interacting
  with known bad actors.
* **Real-time alerts**: The system provides immediate notifications when a
  transaction violates pre-set screening rules. Alerts can trigger actions such
  as blocking a transaction, freezing a wallet, or sending it for further manual
  review.
* **Detailed logs and API integration**: You can access detailed logs and
  results of screened transactions, enabling easier auditing and review. The
  system also offers a robust API for integrating screening capabilities into
  existing workflows.

## Embedded screening

For Wallets using embedded screening, the existing
[Get a transaction](/api-reference/wallets/developer-controlled-wallets/get-transaction)
API endpoint includes a response field, `transactionScreeningEvaluation`, for
transaction screening result, detailing:

* **Rule** found during screening
* **Actions** taken for the decision
* **Reasons** for the decision, related risk signals found during the screening:
  source, risk score, risk category, etc.

## Standalone screening

If you are using Wallets with standalone screening, Compliance Engine exposes a
new
[Screen a blockchain address](/api-reference/wallets/compliance/screen-address)
API endpoint, enabling you to screen a specific blockchain address on a given
[supported blockchain](/wallets/supported-blockchains) independently of any
transaction flow. The endpoint response returns the following:

* **Screening result**: High level of the screening result, either `APPROVED` or
  `DENIED`.
* **Screening decision**: Same information as the
  `transactionScreeningEvaluation` field above.
* **Detailed vendor response**: Findings from vendors to provide a deeper
  understanding of the screening results and their source. Note: values will
  only be available on testnet for the test cases provided on the
  [Testing Guide](/wallets/compliance-engine/tx-screening-testing).

## Workflow

Compliance Engine is available for eligible users. Reach out to Circle through
the
[Compliance Engine request form](https://www.circle.com/wallets/compliance-engine/#get-in-touch)
to get access. Once approved, you can:

1. Customize your screening rules via the console to match your own risk and
   compliance requirements:\
   a. Check the
   [Compliance Engine whitepaper](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/PDFs/Whitepapers/ComplianceEngine_whitepaper.pdf)
   (Part 3) for some helpful questions to consider when establishing your
   requirements.\
   b. Check the
   [Rule Management](/wallets/compliance-engine/tx-screening-rule-management)
   guide for possible configurations.
2. Trigger a screening evaluation:\
   a. Through the
   [Screen a blockchain address](/api-reference/wallets/compliance/screen-address)
   API endpoint.\
   b. Through generating an onchain transaction via the
   [Transactions API](/api-reference/wallets/developer-controlled-wallets/list-transactions).

You can review detailed results for all rule matches and alerts on the
[Circle Console](https://console.circle.com/).


# Alert Management
Source: https://developers.circle.com/wallets/compliance-engine/tx-screening-alert-management



The [Alerts](https://console.circle.com/compliance/alerts/screening) page on the
console gives you access to all historical alerts generated. From there you can
view summary data on each alert and access other key alert management features.

<Note>
  Compliance Engine on both testnet and mainnet is only available for eligible
  customers. Contact Circle through the
  [Compliance Engine request form](https://www.circle.com/wallets/compliance-engine/#get-in-touch)
  to get access.
</Note>

## Managing alerts

Use the following steps to manage alerts:

1. **Access the Alerts page.** Using your credentials log into the Circle
   [Console](https://console.circle.com/). Navigate to the *Alerts* page under
   the *Compliance Engine*.
2. **Browse historical alerts.** Can browse for historical alerts via the
   tabular view.
3. **Select alert to review.** Selecting any alert will let you view the alert
   page. This page provides detailed alert-level information for review. You can
   also navigate to a number of other pages that will provide further
   information on entities related to the alert.\
   a. **Wallet Page**. Provides detailed risk information on the associated
   blockchain wallet that triggered the alert. You can reach this by selecting
   the hyperlinked *Wallet Address* under the *Entities* section.\
   b. **Transaction Page**. Provides detailed data points on the transaction
   associated with the alert. You can reach this by selecting the hyperlinked
   *Transaction ID* under the *Transaction* section.
4. **Action Alert.** There are a number of actions available for you to take
   directly from the Alert page.\
   a. **Freeze Wallet.** You can freeze the wallet associated with the
   transaction in question via the `Freeze Wallet` button in the **Entities >
   Action** column.\
   b. **Add to blocklist.** You can add external addresses directly to your
   *blocklist* instead of navigating to the *Watchlists* page via the
   `Add to blocklist` button in the **Entities > Action** column\
   c. **Alert Status.** You can close out any alert by adjusting its *Status*
   via the dropdown to the right of the *Alert ID* in the table header.

<Accordion title="Video Tutorial: Using Alerts in the Console">
  <iframe title="Video Tutorial: Using Alerts in the Console" />
</Accordion>


# Quickstart: Assess the Risk of Wallet Addresses
Source: https://developers.circle.com/wallets/compliance-engine/tx-screening-quickstart



Transaction Screening allows you to programmatically assess the risk of wallet
addresses when sending digital assets using Circle Wallets. This guide walks you
through setup, integration, and testing using Circle's Compliance Engine.

This guide applies specifically to the
[standalone screening](/wallets/compliance-engine/tx-screening#standalone-screening)
mode, where blockchain addresses are screened independently of transaction
flows.

<Note>
  Compliance Engine on both testnet and mainnet is only available for eligible
  customers. Contact Circle through the
  [Compliance Engine request form](https://www.circle.com/wallets/compliance-engine/#get-in-touch)
  to get access.
</Note>

## Prerequisites

Before you begin, make sure you have the following:

* A Circle Developer Account
* An API key with appropriate access to
  [Compliance Engine](https://console.circle.com/compliance)
* [Node.js](https://nodejs.org/en/download) installed, or an API tool like
  Postman or cURL
* [Axios](https://axios-http.com/) installed, if using Node.js

## Steps

Follow the steps below to screen an address:

### 1. Generate a test address

To simulate a real screening scenario, visit
[vanity-eth.tk](https://vanity-eth.tk) to generate a test Ethereum wallet
address ending in `9999`:

For example, `0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999`.

The `9999` suffix triggers Circle's sanctions blocklist in the screening API.

### 2. Screen the wallet address explicitly using Circle's API

Submit a `POST` request to the screening API using Node.js:

```javascript JavaScript theme={null}
import axios from "axios";

const options = {
  method: "POST",
  url: "https://api.circle.com/v1/w3s/compliance/screening/addresses",
  headers: {
    Authorization: "Bearer <API_KEY>",
    "Content-Type": "application/json",
  },
  data: {
    idempotencyKey: "44bd2d89-9461-4502-84ba-550c9e278db7", // unique-idempotency-key
    address: "0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999",
    chain: "ETH-SEPOLIA",
  },
};

axios
  .request(options)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });
```

<Note>
  **Note:** You must replace the `<API_KEY>` above with your actual Circle API
  key.
</Note>

### 3. Review the screening response

If the address is flagged, the response returns a `DENIED` result with some
actionable compliance recommendations:

```json JSON theme={null}
{
  "result": "DENIED",
  "decision": {
    "ruleName": "Circle's Sanctions Blocklist",
    "actions": ["FREEZE_WALLET", "DENY", "REVIEW"],
    "reasons": [
      {
        "source": "ADDRESS",
        "sourceValue": "0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999",
        "riskScore": "BLOCKLIST",
        "riskCategories": ["SANCTIONS"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "2025-03-29T01:59:02Z"
  },
  "address": "0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999",
  "chain": "ETH-SEPOLIA"
}
```

### 4. Evaluate screening recommendations

If the screening result is `DENIED`, you can take the following actions based on
the recommendations provided:

* **Block** the wallet from transaction activity (based on the `DENY`
  recommendation)
* **Flag** the wallet for manual review (based on the `REVIEW` recommendation)
* **Freeze** the wallet (based on the `FREEZE_WALLET` recommendation)

<Note>
  You can **block** or **freeze** the wallet from the [Compliance Engine >
  Alerts](https://console.circle.com/compliance/alerts/screening) page in the
  Developer Console. For more details, see the [Alerts
  Management](/wallets/compliance-engine/tx-screening-alert-management)
  documentation.
</Note>

## Automate rules based on screening outcomes

You can integrate
[actions and alerts](/wallets/compliance-engine/tx-screening-rule-management)
into the transaction logic of your application:

```javascript JavaScript theme={null}
if (response.data.result === "DENIED") {
  const ruleName = response.data.decision.ruleName;
  const actions = response.data.decision.actions;

  console.log("Screening result: DENIED by Rule: " + ruleName);

  if (actions.includes("DENY")) {
    console.log("Recommended action: DENY — block transactions on wallet");
  }

  if (actions.includes("REVIEW")) {
    console.log("Recommended action: REVIEW — flag wallet for manual review");
  }

  if (actions.includes("FREEZE_WALLET")) {
    console.log("Recommended action: FREEZE_WALLET — freeze wallet activity");
  }
}
```

You can also query additional fields such as `riskCategories`, `ruleName`, and
`type` to make compliance decisions tailored to your business needs. For more
information about these fields, refer to their descriptions in the response
object of the
[Screen a blockchain address](/api-reference/wallets/compliance/screen-address)
API endpoint.

## Testing with simulated risk categories

You can use specific suffixes in test addresses to simulate different risk
scenarios:

| Suffix | Simulated Rule Triggered           |
| ------ | ---------------------------------- |
| `9999` | Circle's Sanctions Blocklist       |
| `8888` | Frozen User Wallet                 |
| `7777` | Custom Blocklist Rule              |
| `8999` | Severe Sanctions Risk (Owner)      |
| `8899` | Severe Terrorist Financing (Owner) |
| `8889` | Severe CSAM Risk (Owner)           |
| `7779` | Severe Illicit Behavior (Owner)    |
| `7666` | High Illicit Behavior Risk (Owner) |
| `7766` | High Gambling Risk (Owner)         |

<Note>
  **Test suffixes** are useful in pre-production environments for validation of
  custom rule enforcement and behavior.
</Note>


# Rule Management
Source: https://developers.circle.com/wallets/compliance-engine/tx-screening-rule-management



Your transaction screening rules are the rules against which your screening
events (embedded or address) will be evaluated. They will contain the rule
criteria that will trigger the rule and the applicable or suggested actions for
each rule if triggered. For testnet, there are a number of default rules in
place which you can use to test against (see
[Testing Guide](/wallets/compliance-engine/tx-screening-testing)).

<Note>
  Compliance Engine on both testnet and mainnet is only available for eligible
  customers. Contact Circle through the
  [Compliance Engine request form](https://www.circle.com/wallets/compliance-engine/#get-in-touch)
  to get access.
</Note>

## Default rules

On mainnet, there are also default rules in place as a starting point. However,
they may not be sufficient to address your company's compliance obligations or
risk appetite. You should consult legal counsel when evaluating
[compliance requirements](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/PDFs/Whitepapers/ComplianceEngine_whitepaper.pdf)
as they relate to your unique business model and the jurisdictions in which you
operate. Once you have done so, you can set up appropriate configurable rules to
address your risks.

## Rule configurations

There are two types of rules for
[Transaction Screening](/wallets/compliance-engine/tx-screening) which can be
configured: *Restrictive Rules* and *Alert-only Rules*.

A rule consists of the following:

1. **Name:** This is auto generated based on the rule criteria and actions.
2. **Description:** This is an optional text field to provide a summary of what
   the rule is designed to accomplish.
3. **Actions**: What actions should be applied or suggested when a rule is
   matched. There are two distinct rule types, *Restrictive* and *Alert-only*,
   for which the following actions are associated:\
   a. **Transaction Decision**: this action allows you to prevent outgoing
   transactions from being broadcast. It is available as a *restrictive* rule
   only.\
   b. **Wallet Freeze**: this action allows you to freeze the funds in the
   associated Circle Wallet. It is available as a *restrictive* rule only.\
   c. **Generate an Alert**: this action will trigger the generation of an alert
   in your Alerts Table in the [Console](https://console.circle.com/). This is
   optional on *restrictive* rules but mandatory on *alert-only* rules.
4. **Rule Criteria**: What combination of risk signals should a rule alert on.
   There are three unique criteria to be set with each rule:\
   a. **Risk Category**: general categorization of the risk that has been
   flagged for the entity in question.\
   b. **Risk Score**: representative value for the level of risk associated with
   the entity.\
   c. **Risk Type**: level of exposure for the risk involved. Is the address
   directly or indirectly associated with the risk?

## Mandatory rules

There are a number of rules in place by default that have minimal configuration
options, e.g. the ability to toggle the alert action. These rules are as
follows:

* **Circle's Sanctions Blocklist.** This rule is in line with the mandatory
  [Compliance Requirements](/wallets/compliance-requirements#ofac-sanctions-compliance-in-terms-of-service)
  you must adhere to when using Circle Wallets. Wallets and transactions will be
  restricted if they are detected sending or receiving from any OFAC-sanctioned
  address.
* **Your blocklist.** This rule relates to the
  [Watchlists](/wallets/compliance-engine/tx-screening-rule-management#watchlists)
  functionality.
* **Frozen.** This rule is used to enforce the wallet freeze, which is applied
  to wallets by other transaction screening rules, or via the developer console.
* **Your allowlist.** This rule relates to the
  [Watchlists](/wallets/compliance-engine/tx-screening-rule-management#watchlists)
  functionality.

## Configurable rule criteria combinations

The table below outlines all possible criteria combinations that can be used to
create/configure rules.

| Symbol | Meaning                                                                                      |
| ------ | -------------------------------------------------------------------------------------------- |
| ✅      | Default Combination in place on Mainnet. Configurable.                                       |
| 🟡     | Possible Combination that can be utilized in a configurable rule.                            |
| ❌      | Unsupported combination, a screening cannot result in this possible combination of criteria. |

<br />

| Risk Category       | Risk Type    | Risk Score |          |            |         |
| ------------------- | ------------ | ---------- | -------- | ---------- | ------- |
|                     |              | **Severe** | **High** | **Medium** | **Low** |
| Sanctions           | Ownership    | ✅          | ❌        | ❌          | ❌       |
| Sanctions           | Counterparty | 🟡         | ❌        | ❌          | ❌       |
| Sanctions           | Indirect     | ❌          | 🟡       | ❌          | ❌       |
| Terrorist Financing | Ownership    | ✅          | 🟡       | ❌          | ❌       |
| Terrorist Financing | Counterparty | 🟡         | 🟡       | ❌          | ❌       |
| Terrorist Financing | Indirect     | ❌          | 🟡       | 🟡         | ❌       |
| CSAM                | Ownership    | ✅          | ❌        | ❌          | ❌       |
| CSAM                | Counterparty | 🟡         | ❌        | ❌          | ❌       |
| CSAM                | Indirect     | ❌          | 🟡       | ❌          | ❌       |
| PEP                 | Ownership    | ❌          | ❌        | 🟡         | ❌       |
| PEP                 | Counterparty | ❌          | ❌        | 🟡         | ❌       |
| PEP                 | Indirect     | ❌          | ❌        | ❌          | 🟡      |
| Gambling            | Ownership    | ❌          | ❌        | ❌          | ❌       |
| Gambling            | Counterparty | ❌          | ❌        | 🟡         | ❌       |
| Gambling            | Indirect     | ❌          | ❌        | ❌          | 🟡      |
| Illicit Behavior    | Ownership    | 🟡         | 🟡       | 🟡         | ❌       |
| Illicit Behavior    | Counterparty | 🟡         | 🟡       | 🟡         | ❌       |
| Illicit Behavior    | Indirect     | ❌          | 🟡       | 🟡         | 🟡      |
| High Risk Industry  | Ownership    | ❌          | ❌        | 🟡         | 🟡      |
| High Risk Industry  | Counterparty | ❌          | ❌        | 🟡         | 🟡      |
| High Risk Industry  | Indirect     | ❌          | ❌        | ❌          | 🟡      |
| Other               | Ownership    | ❌          | 🟡       | ❌          | 🟡      |
| Other               | Counterparty | ❌          | 🟡       | 🟡         | 🟡      |
| Other               | Indirect     | ❌          | ❌        | 🟡         | 🟡      |

## Rule setup

To create or edit a rule, follow these steps:

1. **Access Settings page**: Using your credentials, log in to the Circle
   [Console](https://console.circle.com/). From there, navigate to the
   **Compliance Engine > Settings** section, which allows you to manage your
   screening rules conveniently.
2. **Choose to create or edit a rule**: Select the appropriate rule type
   *Configurable **restrictive** rules* or *Configurable **alert-only** rules*.
   To edit an existing rule, select the rule in question and click the `Edit`
   button. To add a new rule, select `Add Rule`.
3. **Configure the rule**: Set the desired rule (*description*, *actions*, and
   *criteria*) based on your requirements. Refer to the above
   [possible configurations](/wallets/compliance-engine/tx-screening-rule-management#configurable-rule-criteria-combinations)
   for clarity on the available options.
4. **Update or create the rule**: After applying the necessary configurations,
   select either:
   * `Save` to modify an existing rule; or
   * `Create Rule` button (top-right of page) to create a new rule.

<Accordion title="Video Tutorial: Creating a Rule in the Console">
  <iframe title="Video Tutorial: Creating a Rule in the Console" />
</Accordion>

## Deactivating a rule

New rules will be created in an *active* state by default. If you need to
temporarily deactivate a rule, you can do so as follows:

1. **Select the rule.** Using your credentials, log in to the Circle
   [Console](https://console.circle.com/). From there, navigate to the
   **Compliance Engine > Settings** section, select the rule you wish to change,
   and select the `Edit` button.
2. **Toggle the Rule Status.** Rule status is located at the bottom of the page.
   Just toggle the Rule Status from `Active` to `Inactive`.
3. **Save change.**

<Accordion title="Video Tutorial: Deactivating a Rule in the Console">
  <iframe title="Video Tutorial: Deactivating a Rule in the Console" />
</Accordion>

## Deleting a rule

If you need to permanently delete a rule, you can do so as follows:

1. **Select the rule.** Using your credentials, log in to the Circle
   [Console](https://console.circle.com/). From there, navigate to the
   **Compliance Engine > Settings** section, select the rule you wish to change.
2. **Delete the rule.** Select the `Delete` button twice.

<Accordion title="Video Tutorial: Deleting a Rule in the Console">
  <iframe title="Video Tutorial: Deleting a Rule in the Console" />
</Accordion>

## Watchlists

Another method for influencing your rule configuration is via the *Watchlists*
feature. You can influence the screening evaluations by adding blockchain
addresses to either the *Blocklist* or the *Allowlist*.

These lists act as the inputs for two of your default rules:

* *Your blocklist* will deny any transaction where the associated address has
  been added to your blocklist.
* *Your allowlist* will allow any transaction where the associated address has
  been added to your allowlist.

To add an address to either your allowlist or your blocklist:

1. **Access the Watchlists page.** Using your credentials log into the Circle
   [Console](https://console.circle.com/). Navigate to the *Watchlists* page
   under the *Compliance Engine*.
2. **Choose the appropriate list.** Select the appropriate tab between
   *Blocklist* and *Allowlist* for your desired outcome.
3. **Add entry.** Select the `Add Entry` button on the top right. Enter the
   blockchain address, choose the reason, and leave an optional note explaining
   the addition.

<Accordion title="Video Tutorial: Using Watchlists in the Console">
  <iframe title="Video Tutorial: Using Watchlists in the Console" />
</Accordion>


# Testing Guide
Source: https://developers.circle.com/wallets/compliance-engine/tx-screening-testing



This guide walks you through testing Circle's Transaction Screening service
using the [Developer Services API](/api-reference/wallets/common/ping) on
testnet. The service is a real time tool that checks blockchain transactions and
addresses against predefined rules outlined in your Console.

For testnet, nine (9) default rules are already in place. Therefore, you will
not need to set up rules using this guide. Note that if you remove rules in
testnet, the testing flows below will no longer work.

This guide allows you to trigger hits against each of these rules.

<Note>
  Compliance Engine on both testnet and mainnet is only available for eligible
  customers. Contact Circle through the
  [Compliance Engine request form](https://www.circle.com/wallets/compliance-engine/#get-in-touch)
  to get access.
</Note>

## Setting Up Your Testing Environment with Magic Values

1. **Use Magic Values for Testing**:
   * You can test different rules by sending transactions between Programmable
     Wallets and blockchain addresses ending with specific suffixes (referred to
     as "Magic Values").
   * For example, sending funds to an address ending in `9999` triggers the
     *Sanctioned Address* rule.
2. **Address Generation**:
   * Use a vanity address generator like [vanity-eth.tk](https://vanity-eth.tk/)
     to create an Ethereum address with the required suffix.
   * Import the generated address into your ETH wallet (e.g. MetaMask) using the
     private key.
3. **Funding the Address**:
   * Add testnet tokens to your generated address using the
     [Circle Faucet](https://faucet.circle.com/).

## Summary of Test Cases

You can test the rules using both existing flows to trigger a screening
evaluation against the magic value address generated in the previous steps:

1. By initiating transactions as usual using the Wallets APIs
2. By invoking the address screening endpoint via the Compliance Engine API

You can trigger specific responses and actions using addresses with certain
suffixes:

* **Circle's Sanctions Blocklist**: `9999`
* **Frozen User Wallet**: `8888`
* **Your blocklist**: `7777`
* **Severe Sanctions Risk (Owner)**: `8999`
* **Severe Terrorist Financing (Owner)**: `8899`
* **Severe CSAM Risk (Owner)**: `8889`
* **Severe Illicit Behavior (Owner)**: `7779`
* **High Illicit Behavior Risk (Owner)**: `7666`
* **High Gambling Risk (Owner)**: `7766`

These addresses will return the appropriate test responses, allowing you to
verify the functionality of the screening system.

<Note>
  **Note**

  This guide helps you test Circle's transaction screening service thoroughly and
  ensures your applications comply with Circle's rules for real-time transaction
  risk screening.
</Note>

## Test Cases Example Responses

## 1. Circle's Sanctions Blocklist

* Magic Value: Address ending in `9999`.
* Result:

<CodeGroup>
  ```json INBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Circle's Sanctions Blocklist",
      "actions": ["REVIEW", "FREEZE_WALLET"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "addressValue",
          "riskScore": "blocklist",
          "riskCategories": ["Sanctions"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Circle's Sanctions Blocklist",
      "actions": ["DENY", "REVIEW", "FREEZE_WALLET"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "addressValue",
          "riskScore": "blocklist",
          "riskCategories": ["Sanctions"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json ADDRESS SCREENING theme={null}
  {
    "data": {
      "result": "DENIED",
      "decision": {
        "ruleName": "Circle's Sanctions Blocklist",
        "actions": ["REVIEW", "FREEZE_WALLET", "DENY"],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0xed594180baa31cd9cb95c2e55b33b93e983d9999",
            "riskScore": "blocklist",
            "riskCategories": ["Sanctions"],
            "type": "OWNERSHIP",
            "signalSource": null
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "address": "0xed594180baa31cd9cb95c2e55b33b93e983d9999",
      "chain": "MATIC",
      "details": []
    }
  }
  ```
</CodeGroup>

## 2. Frozen User Wallet

* Magic Value: Address ending in `8888`.
* Result:

<CodeGroup>
  ```json INBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Frozen User Wallet",
      "actions": ["REVIEW"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "addressValue",
          "riskScore": "blocklist",
          "riskCategories": ["FROZEN"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Frozen User Wallet",
      "actions": ["DENY", "REVIEW"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "addressValue",
          "riskScore": "blocklist",
          "riskCategories": ["FROZEN"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json ADDRESS SCREENING theme={null}
  {
    "data": {
      "result": "DENIED",
      "decision": {
        "ruleName": "Frozen User Wallet",
        "actions": ["REVIEW", "DENY"],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0x111F4247ada509383Ce9f241Ff64Fac6f9E28888",
            "riskScore": "blocklist",
            "riskCategories": ["FROZEN"],
            "type": "OWNERSHIP",
            "signalSource": null
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "id": "9199c1b2-8499-4cdd-83aa-6d73e696e09f",
      "address": "0x111F4247ada509383Ce9f241Ff64Fac6f9E28888",
      "chain": "MATIC",
      "details": [],
      "alertId": "6f394f8b-9696-4dbb-a882-6bada11e22ac"
    }
  }
  ```
</CodeGroup>

## 3. Your blocklist

* Magic Value: Address ending in `7777`.
* Result:

<CodeGroup>
  ```json INBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Your blocklist",
      "actions": ["REVIEW"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0xd89e56cba08ee44a9ca9f6c5f2f0e608227b7777",
          "riskScore": "blocklist",
          "riskCategories": ["UNSUPPORTED"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Your blocklist",
      "actions": ["REVIEW", "DENY"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0xd89e56cba08ee44a9ca9f6c5f2f0e608227b7777",
          "riskScore": "blocklist",
          "riskCategories": ["UNSUPPORTED"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json ADDRESS SCREENING theme={null}
  {
    "data": {
      "result": "DENIED",
      "decision": {
        "ruleName": "Your blocklist",
        "actions": ["DENY", "REVIEW"],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0x860ba02b2884296Aeab83e216d1e375A831A7777",
            "riskScore": "blocklist",
            "riskCategories": ["UNSUPPORTED"],
            "type": "OWNERSHIP",
            "signalSource": null
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "id": "21387f8a-809a-401d-8b28-60cbf872a36e",
      "address": "0x860ba02b2884296Aeab83e216d1e375A831A7777",
      "chain": "MATIC",
      "details": [],
      "alertId": "c062db2a-ea95-47c5-b0c8-a7a967782b0e"
    }
  }
  ```
</CodeGroup>

## 4. Severe Sanctions Risk (Owner)

* Magic Value: Address ending in `8999`.
* Result:

<CodeGroup>
  ```json INBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Severe Sanctions Risk (Owner)",
      "actions": ["REVIEW", "FREEZE_WALLET"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0x21e936783ed3ced968ab083010eb14f359018999",
          "riskScore": "severe",
          "riskCategories": ["SANCTIONS"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Severe Sanctions Risk (Owner)",
      "actions": ["DENY", "REVIEW", "FREEZE_WALLET"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0x21e936783ed3ced968ab083010eb14f359018999",
          "riskScore": "severe",
          "riskCategories": ["SANCTIONS"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json ADDRESS SCREENING theme={null}
  {
    "data": {
      "result": "DENIED",
      "decision": {
        "ruleName": "Severe Sanctions Risk (Owner)",
        "actions": ["FREEZE_WALLET", "DENY", "REVIEW"],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0xbEcf2Fc0d5F639c513b8ac99846C7507b5f08999",
            "riskScore": "severe",
            "riskCategories": ["SANCTIONS"],
            "type": "OWNERSHIP",
            "signalSource": {
              "rowId": "3c5309dd-623c-4206-ac23-dceef7471351",
              "pointer": "/addressRiskIndicator/0"
            }
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "id": "3aa5b955-a1b3-474d-8605-c9f5bfffbe91",
      "address": "0xbEcf2Fc0d5F639c513b8ac99846C7507b5f08999",
      "chain": "MATIC",
      "details": [
        {
          "id": "3c5309dd-623c-4206-ac23-dceef7471351",
          "vendor": "<vendorName>",
          "response": {
            "chain": "polygon",
            "address": "0xbEcf2Fc0d5F639c513b8ac99846C7507b5f08999",
            "entities": [
              {
                "entity": "DGqLQmvLoM",
                "category": "Screening",
                "riskScoreLevel": 80,
                "riskScoreLevelLabel": "Severe"
              }
            ],
            "addressSubmitted": "0xbEcf2Fc0d5F639c513b8ac99846C7507b5f08999",
            "addressRiskIndicators": [
              {
                "category": "Sanctions",
                "riskType": "OWNERSHIP",
                "totalVolumeUsd": "2715.0367502807676",
                "incomingVolumeUsd": "2052.45711257512",
                "outgoingVolumeUsd": "662.5796377056477",
                "categoryRiskScoreLevelLabel": "Severe"
              }
            ],
            "addressTotalVolumeUsd": "2715.0367502807676",
            "addressIncomingVolumeUsd": "2052.45711257512",
            "addressOutgoingVolumeUsd": "662.5796377056477"
          },
          "createDate": "<timestamp>"
        }
      ],
      "alertId": "c933b018-ccdd-430e-982e-164b097b227c"
    }
  }
  ```
</CodeGroup>

## 5. Severe Terrorist Financing Risk (Owner)

* Magic Values: Address ending in `8899`.
* Result:

<CodeGroup>
  ```json INBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Severe Terrorist Financing Risk (Owner)",
      "actions": ["REVIEW", "FREEZE_WALLET"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0x01f43824a066cebe734f3d949e48392851cf8899",
          "riskScore": "severe",
          "riskCategories": ["TERRORIST_FINANCING"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Severe Terrorist Financing Risk (Owner)",
      "actions": ["DENY", "REVIEW", "FREEZE_WALLET"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0x01f43824a066cebe734f3d949e48392851cf8899",
          "riskScore": "severe",
          "riskCategories": ["TERRORIST_FINANCING"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json ADDRESS SCREENING theme={null}
  {
    "data": {
      "result": "DENIED",
      "decision": {
        "ruleName": "Severe Terrorist Financing Risk (Owner)",
        "actions": ["FREEZE_WALLET", "REVIEW", "DENY"],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0x8fF9C8a2bEdba9f4553f5e47A1830b85dE168899",
            "riskScore": "severe",
            "riskCategories": ["TERRORIST_FINANCING"],
            "type": "OWNERSHIP",
            "signalSource": {
              "rowId": "d1c036ca-6cfd-423e-8e9f-c2e6ac5a51dd",
              "pointer": "/addressRiskIndicator/0"
            }
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "id": "ec1b1e47-31e2-4f61-9e0b-c5f786d36681",
      "address": "0x8fF9C8a2bEdba9f4553f5e47A1830b85dE168899",
      "chain": "MATIC",
      "details": [
        {
          "id": "d1c036ca-6cfd-423e-8e9f-c2e6ac5a51dd",
          "vendor": "<vendorName>",
          "response": {
            "chain": "polygon",
            "address": "0x8fF9C8a2bEdba9f4553f5e47A1830b85dE168899",
            "entities": [
              {
                "entity": "PFpd82Qj4Y",
                "category": "Terrorist Financing",
                "riskScoreLevel": 80,
                "riskScoreLevelLabel": "Severe"
              }
            ],
            "addressSubmitted": "0x8fF9C8a2bEdba9f4553f5e47A1830b85dE168899",
            "addressRiskIndicators": [
              {
                "category": "Terrorist Financing",
                "riskType": "OWNERSHIP",
                "totalVolumeUsd": "2614.71272693432",
                "incomingVolumeUsd": "2078.1795850416493",
                "outgoingVolumeUsd": "536.5331418926708",
                "categoryRiskScoreLevelLabel": "Severe"
              }
            ],
            "addressTotalVolumeUsd": "2614.71272693432",
            "addressIncomingVolumeUsd": "2078.1795850416493",
            "addressOutgoingVolumeUsd": "536.5331418926708"
          },
          "createDate": "<timestamp>"
        }
      ],
      "alertId": "a39b400c-d11c-4287-94c2-c31979a592a0"
    }
  }
  ```
</CodeGroup>

## 6. Severe CSAM Risk (Owner)

* Magic Value: Address ending in `8889`.
* Result:

<CodeGroup>
  ```json INBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Severe CSAM Risk (Owner)",
      "actions": [
        "REVIEW",
        "FREEZE_WALLET"
      ],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0x068f626eacfbf669a0f4995b4de79f46cb9e8889",
          "riskScore": "severe",
          "riskCategories": [
            "CSAM"
          ],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": “<timestamp>”
    }
  }
  ```

  ```json OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Severe CSAM Risk (Owner)",
      "actions": [
        "DENY",
        "REVIEW",
        "FREEZE_WALLET"
      ],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0x068f626eacfbf669a0f4995b4de79f46cb9e8889",
          "riskScore": "severe",
          "riskCategories": [
            "CSAM"
          ],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  {
    "data": {
      "result": "DENIED",
      "decision": {
        "ruleName": "Severe CSAM Risk (Owner)",
        "actions": [
          "FREEZE_WALLET",
          "DENY",
          "REVIEW"
        ],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0x1c3Af0f2c682f3625B4D8C60b23c5aF0d9E98889",
            "riskScore": "severe",
            "riskCategories": [
              "CSAM"
            ],
            "type": "OWNERSHIP",
            "signalSource": {
              "rowId": "a04389af-4830-4d35-a641-16c8b5af33c5",
              "pointer": "/addressRiskIndicator/0"
            }
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "id": "b3d95694-c9e0-4d88-a27f-87bf241c4d37",
      "address": "0x1c3Af0f2c682f3625B4D8C60b23c5aF0d9E98889",
      "chain": "MATIC",
      "details": [
        {
          "id": "a04389af-4830-4d35-a641-16c8b5af33c5",
          "vendor": "<vendorName>",
          "response": {
            "chain": "polygon",
            "address": "0x1c3Af0f2c682f3625B4D8C60b23c5aF0d9E98889",
            "entities": [
              {
                "entity": "2wRepYwHMB",
                "category": "Child Sexual Abuse Material (CSAM) Consumer",
                "riskScoreLevel": 80,
                "riskScoreLevelLabel": "Severe"
              }
            ],
            "addressSubmitted": "0x1c3Af0f2c682f3625B4D8C60b23c5aF0d9E98889",
            "addressRiskIndicators": [
              {
                "category": "Child Sexual Abuse Material (CSAM)",
                "riskType": "OWNERSHIP",
                "totalVolumeUsd": "2156.8026917979587",
                "incomingVolumeUsd": "2336.8225842450083",
                "outgoingVolumeUsd": "-180.01989244704964",
                "categoryRiskScoreLevelLabel": "Severe"
              }
            ],
            "addressTotalVolumeUsd": "2156.8026917979587",
            "addressIncomingVolumeUsd": "2336.8225842450083",
            "addressOutgoingVolumeUsd": "-180.01989244704964"
          },
          "createDate": "<timestamp>"
        }
      ],
      "alertId": "cd278c66-fa44-40f6-8dde-c4fa81210f4c"
    }
  }
  ```
</CodeGroup>

## 7. Severe Illicit Behavior Risk (Owner)

* Magic Value: Address ending in `7779`.
* Result:

<CodeGroup>
  ```json INBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Severe Illicit Behavior Risk (Owner)",
      "actions": ["REVIEW", "FREEZE_WALLET"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0xd5d268603413c563a9739a4ca69214cc4ed77779",
          "riskScore": "severe",
          "riskCategories": ["ILLICIT_BEHAVIOR"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "Severe Illicit Behavior Risk (Owner)",
      "actions": ["DENY", "REVIEW", "FREEZE_WALLET"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0xd5d268603413c563a9739a4ca69214cc4ed77779",
          "riskScore": "severe",
          "riskCategories": ["ILLICIT_BEHAVIOR"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json ADDRESS SCREENING theme={null}
  {
    "data": {
      "result": "DENIED",
      "decision": {
        "ruleName": "Severe Illicit Behavior Risk (Owner)",
        "actions": ["REVIEW", "DENY", "FREEZE_WALLET"],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0xD5DFfE73DAc5B4eeF3cBe9EEDBD964fbF5CC7779",
            "riskScore": "severe",
            "riskCategories": ["ILLICIT_BEHAVIOR"],
            "type": "OWNERSHIP",
            "signalSource": {
              "rowId": "76c7738b-7168-4a3c-b79c-dafddd34443d",
              "pointer": "/addressRiskIndicator/0"
            }
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "id": "eae928b5-22a8-4800-8aee-9d4ccad0486c",
      "address": "0xD5DFfE73DAc5B4eeF3cBe9EEDBD964fbF5CC7779",
      "chain": "MATIC",
      "details": [
        {
          "id": "76c7738b-7168-4a3c-b79c-dafddd34443d",
          "vendor": "<vendorName>",
          "response": {
            "chain": "polygon",
            "address": "0xD5DFfE73DAc5B4eeF3cBe9EEDBD964fbF5CC7779",
            "entities": [
              {
                "entity": "d0LZgYvcxZ",
                "category": "High Yield Investment Scheme",
                "riskScoreLevel": 80,
                "riskScoreLevelLabel": "Severe"
              }
            ],
            "addressSubmitted": "0xD5DFfE73DAc5B4eeF3cBe9EEDBD964fbF5CC7779",
            "addressRiskIndicators": [
              {
                "category": "High Yield Investment Scheme",
                "riskType": "OWNERSHIP",
                "totalVolumeUsd": "2694.1238387788844",
                "incomingVolumeUsd": "1515.9560043460124",
                "outgoingVolumeUsd": "1178.167834432872",
                "categoryRiskScoreLevelLabel": "Severe"
              }
            ],
            "addressTotalVolumeUsd": "2694.1238387788844",
            "addressIncomingVolumeUsd": "1515.9560043460124",
            "addressOutgoingVolumeUsd": "1178.167834432872"
          },
          "createDate": "<timestamp>"
        }
      ],
      "alertId": "22fa6e1a-0721-4967-8320-26fd93b334e4"
    }
  }
  ```
</CodeGroup>

## 8. High Illicit Behavior Risk (Owner)

* Magic Value: Send funds to an address ending in `7666`.
* Result:

<CodeGroup>
  ```json INBOUND / OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "High Illicit Behavior Risk (Owner)",
      "actions": ["REVIEW"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "address",
          "riskScore": "high",
          "riskCategories": ["ILLICIT_BEHAVIOR"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json ADDRESS SCREENING theme={null}
  {
    "data": {
      "result": "APPROVED",
      "decision": {
        "ruleName": "High Illicit Behavior Risk (Owner)",
        "actions": ["REVIEW"],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0x5f7E820b57bA360562209f789D7110919a017666",
            "riskScore": "high",
            "riskCategories": ["ILLICIT_BEHAVIOR"],
            "type": "OWNERSHIP",
            "signalSource": {
              "rowId": "e6a16937-34d5-4ea7-a69d-daf5e7a49818",
              "pointer": "/addressRiskIndicator/0"
            }
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "id": "867306ac-c75e-45ac-8f9f-d4bd8caccb11",
      "address": "0x5f7E820b57bA360562209f789D7110919a017666",
      "chain": "MATIC",
      "details": [
        {
          "id": "e6a16937-34d5-4ea7-a69d-daf5e7a49818",
          "vendor": "<vendorName>",
          "response": {
            "chain": "polygon",
            "address": "0x5f7E820b57bA360562209f789D7110919a017666",
            "entities": [
              {
                "entity": "AuND7zgiJv",
                "category": "Mixer",
                "riskScoreLevel": 40,
                "riskScoreLevelLabel": "High"
              }
            ],
            "addressSubmitted": "0x5f7E820b57bA360562209f789D7110919a017666",
            "addressRiskIndicators": [
              {
                "category": "Malware",
                "riskType": "OWNERSHIP",
                "totalVolumeUsd": "2822.1827321490728",
                "incomingVolumeUsd": "1619.6413453166992",
                "outgoingVolumeUsd": "1202.5413868323735",
                "categoryRiskScoreLevelLabel": "High"
              }
            ],
            "addressTotalVolumeUsd": "2822.1827321490728",
            "addressIncomingVolumeUsd": "1619.6413453166992",
            "addressOutgoingVolumeUsd": "1202.5413868323735"
          },
          "createDate": "<timestamp>"
        }
      ],
      "alertId": "267fb4c3-8fb2-49f1-8cc8-39c1e62cfed4"
    }
  }
  ```
</CodeGroup>

## 9. High Gambling Risk (Owner)

* Magic Value: Address ending in `7766`.
* Result:

<CodeGroup>
  ```json INBOUND / OUTBOUND TXN theme={null}
  {
    "transactionScreeningEvaluation": {
      "ruleName": "High Gambling Risk (Owner)",
      "actions": ["REVIEW"],
      "reasons": [
        {
          "source": "address",
          "sourceValue": "0x2d6d4a938e7b69f9b67d815cd0c2737ebf897766",
          "riskScore": "high",
          "riskCategories": ["GAMBLING"],
          "type": "OWNERSHIP"
        }
      ],
      "screeningDate": "<timestamp>"
    }
  }
  ```

  ```json ADDRESS SCREENING theme={null}
  {
    "data": {
      "result": "APPROVED",
      "decision": {
        "ruleName": "High Gambling Risk (Owner)",
        "actions": ["REVIEW"],
        "reasons": [
          {
            "source": "address",
            "sourceValue": "0x5408E93c5B314D71bd000f903596638e83b97766",
            "riskScore": "high",
            "riskCategories": ["GAMBLING"],
            "type": "OWNERSHIP",
            "signalSource": {
              "rowId": "4e8f5a71-6250-4ac3-a9b5-b6e1e7415b50",
              "pointer": "/addressRiskIndicator/0"
            }
          }
        ],
        "screeningDate": "<timestamp>"
      },
      "id": "7ed18366-8e6c-467e-84e0-9f20cc4fb45a",
      "address": "0x5408E93c5B314D71bd000f903596638e83b97766",
      "chain": "MATIC",
      "details": [
        {
          "id": "4e8f5a71-6250-4ac3-a9b5-b6e1e7415b50",
          "vendor": "TRM",
          "response": {
            "chain": "polygon",
            "address": "0x5408E93c5B314D71bd000f903596638e83b97766",
            "entities": [
              {
                "entity": "6I0BB6c42L",
                "category": "Gambling Service",
                "riskScoreLevel": 40,
                "riskScoreLevelLabel": "High"
              }
            ],
            "addressSubmitted": "0x5408E93c5B314D71bd000f903596638e83b97766",
            "addressRiskIndicators": [
              {
                "category": "Gambling Service",
                "riskType": "OWNERSHIP",
                "totalVolumeUsd": "2179.558889753797",
                "incomingVolumeUsd": "1993.5326719259065",
                "outgoingVolumeUsd": "186.02621782789038",
                "categoryRiskScoreLevelLabel": "High"
              }
            ],
            "addressTotalVolumeUsd": "2179.558889753797",
            "addressIncomingVolumeUsd": "1993.5326719259065",
            "addressOutgoingVolumeUsd": "186.02621782789038"
          },
          "createDate": "<timestamp>"
        }
      ],
      "alertId": "4891023d-d19c-4e77-bcd0-c5d3fc24449a"
    }
  }
  ```
</CodeGroup>


# Compliance Requirements
Source: https://developers.circle.com/wallets/compliance-requirements

Understand the OFAC sanctions compliance requirements that apply when managing wallets on the Circle platform.

When you manage wallets on Circle's platform, you must comply with applicable
sanctions laws, including regulations enforced by the Office of Foreign Assets
Control (OFAC). The following sections explain what OFAC compliance requires,
how Circle's terms of service address it, and what actions Circle takes when it
detects non-compliant transactions.

## Addressing OFAC sanctions in wallet management

You must adhere to Circle's terms of service regarding
[OFAC sanctions](https://ofac.treasury.gov/) when managing wallets. You are
responsible for maintaining compliance with these regulations and understanding
the consequences of violating them.

## OFAC sanctions compliance in terms of service

* You must ensure that the wallets you create do not transact with
  OFAC-sanctioned addresses.
* Violations may result in reporting to OFAC or banning your developer account.

## Actions taken for detected non-compliant transactions

Circle takes the following actions when a wallet sends or receives a transaction
involving an OFAC-sanctioned address:

* Circle temporarily restricts the wallet from making outbound transactions
  pending a review.
* You should contact Circle Customer Support to move the affected funds to a
  quarantine wallet.

For more information, refer to the following:

* U.S. Treasury's Office of Foreign Assets Control
  [SDN List](https://www.treasury.gov/ofac/downloads/sdnlist.pdf)
* Circle [Legal & Privacy](https://www.circle.com/en/legal)


# Dev-Controlled Wallets
Source: https://developers.circle.com/wallets/dev-controlled

Understand how dev-controlled wallets work, when to use them, and how Circle enables programmatic wallet infrastructure.

Dev-controlled wallets are blockchain wallets you manage programmatically from
your application. You control wallet creation, transaction execution, and
signing through Circle APIs and SDKs. For a comparison of all wallet products,
see [Choose your wallet product and account types](/wallets/account-types).

## Key features

<CardGroup>
  <Card title="API-driven" icon="server">
    Create wallets and send transactions with Circle APIs and SDKs. No node
    setup or low-level signing required for supported chains. For unsupported chains, bring your own node with [Signing APIs](/wallets/signing-apis).
  </Card>

  <Card title="You retain custody" icon="key">
    Your
    <Tooltip>entity secret</Tooltip>
    stays with you: built-in encryption, registration, rotation, and recovery
    keep compliance and custody clear.
  </Card>

  <Card title="Web3 for users" icon="users">
    Run transfers, smart contract interactions, and other onchain actions on
    behalf of your users so they can hold and use digital assets without
    managing keys or understanding blockchain details.
  </Card>

  <Card title="Scalability" icon="layer-group">
    Scale to many wallets across chains from a single entity secret. Support for
    unified EVM addresses and high throughput.
  </Card>
</CardGroup>

Dev-controlled wallets are designed for server-side, automated, or custodial use
cases. You define policies, execute transactions, and manage wallet operations.
Unlike user-controlled wallets, end users don't control the private keys
directly.

## What you can build

Use dev-controlled wallets when you need funds you control, automation, or many
wallets from a single API. Here are some common use cases:

<AccordionGroup>
  <Accordion title="Custodial wallets" icon="wallet">
    You hold and manage assets on behalf of users; they don't control keys
    directly. You create and fund wallets per user or account, execute
    withdrawals and transfers when users request them, and enforce your own
    policies (limits, KYC, fraud checks) before any onchain action.
  </Accordion>

  <Accordion title="Treasury and liquidity management" icon="building-columns">
    Manage platform reserves, liquidity pools, and rebalancing from programmatic
    wallets. You hold and move funds between pools or protocols, execute
    rebalancing or yield strategies, and keep operational and reserve wallets
    under one entity secret and API surface.
  </Accordion>

  <Accordion title="Automated payouts" icon="paper-plane">
    Run scheduled or event-driven disbursements to many recipients. You trigger
    payouts (payroll, rebates, refunds, incentives) to a list of addresses or to
    wallets you create per recipient, with full control over timing, amounts,
    and auditability.
  </Accordion>

  <Accordion title="Exchange or marketplace infrastructure" icon="chart-network">
    Use programmatic wallets for deposits, withdrawals, and settlement. Incoming
    funds land in wallets you control; you move assets between hot/cold or
    operational wallets, process withdrawals to user addresses, and settle
    marketplace or P2P trades without handing keys to end users.
  </Accordion>

  <Accordion title="Gaming or rewards systems" icon="coins">
    Power in-game or loyalty balances and automated distribution. You create and
    fund wallets for players or reward recipients. You credit and debit balances
    using your logic, then run batch payouts or airdrops without each user
    managing their own keys.
  </Accordion>
</AccordionGroup>

## Account types

On EVM chains, a developer-controlled wallet is created as either an externally
owned account (EOA) or a smart contract account (SCA). Pick one based on your
needs. For non-EVM chains such as Aptos or Solana, see
[Choose your wallet product and account types](/wallets/account-types) for a
full breakdown by blockchain.

<CardGroup>
  <Card title="EOA (Externally Owned Account)" icon="wallet">
    Select when the source wallet can hold native token for gas, you want simple
    key-controlled accounts, and you don't need multiple operations in one
    transaction (batch execution).
  </Card>

  <Card title="SCA (Smart Contract Account)" icon="cube">
    Select when you need gas paid by a relayer or platform (gas sponsorship),
    batch execution, or other programmable behavior. For details on gas
    sponsorship, see [Gas Station](/wallets/gas-station).
  </Card>
</CardGroup>

## Get started

Create your first dev-controlled wallet or jump straight to a fee-paying
transfer after the quickstart:

<CardGroup>
  <Card title="Create a dev-controlled wallet" icon="wallet" href="/wallets/dev-controlled/create-your-first-wallet">
    Create a wallet set and EOA wallet on Arc Testnet, then use it in the
    transfer and signing guides.
  </Card>

  <Card title="Send a transaction with fee" icon="arrow-right-arrow-left" href="/wallets/dev-controlled/transfer-tokens-across-wallets">
    Send USDC from one dev-controlled wallet to another and verify the recipient
    balance.
  </Card>
</CardGroup>


# How-to: Batch-Create Wallets for Existing Users
Source: https://developers.circle.com/wallets/dev-controlled/batch-create-wallets

Create up to 200 dev-controlled wallets in a single API call and link each wallet to an existing user in your system using metadata.

Use the
[`POST /developer/wallets`](/api-reference/wallets/developer-controlled-wallets/create-wallet)
endpoint to batch-create dev-controlled wallets and link each one to an existing
user in your system. Pass a `metadata` array with `name` and `refId` fields to
associate each wallet with a user. You can create up to 200 wallets per request.

## Prerequisites

Before you begin, ensure that you've:

* Created a
  [Circle Developer Account and an API key](/w3s/circle-developer-account).
* [Registered your entity secret](/wallets/dev-controlled/register-entity-secret).
* Created a wallet set. If you haven't, complete the
  [Create a Dev-Controlled Wallet](/wallets/dev-controlled/create-your-first-wallet)
  quickstart.
* Installed [Node.js 22+](https://nodejs.org/) or
  [Python 3.11+](https://www.python.org/).
* Installed the applicable server-side SDK for your language:

  <Tabs>
    <Tab title="Node.js">
      Use the following commands to install the SDK. You can
      [view the package information on the npm site](https://www.npmjs.com/package/@circle-fin/developer-controlled-wallets).

      <CodeGroup>
        ```shell npm theme={null}
        npm install @circle-fin/developer-controlled-wallets --save
        ```

        ```shell yarn theme={null}
        yarn add @circle-fin/developer-controlled-wallets
        ```
      </CodeGroup>

      For more information, visit the
      [Node.js SDK](/sdks/developer-controlled-wallets-nodejs-sdk).
    </Tab>

    <Tab title="Python">
      Use the following command to install the SDK with
      [pip](https://pypi.org/project/pip/):

      ```shell theme={null}
      pip install circle-developer-controlled-wallets
      ```

      For more information, visit the
      [Python SDK](/sdks/developer-controlled-wallets-python-sdk).
    </Tab>
  </Tabs>

## Step 1. Prepare the metadata array

Build a `metadata` array where each element corresponds to one wallet you want
to create. Each element accepts two fields:

* `name`: A human-readable label for the wallet.
* `refId`: Your internal user identifier (for example, a UUID from your
  database). Use this field to map the wallet back to the user in your system.

The length of the `metadata` array must exactly match the `count` value you pass
in the request. If they differ, the API returns error `155503`.

For example, to create wallets for two users:

```ts theme={null}
const metadata = [
  { name: "Alice Wallet", refId: "user-uuid-1001" },
  { name: "Bob Wallet", refId: "user-uuid-1002" },
];
```

## Step 2. Create the wallets

Call `createWallets` with your `walletSetId`, target blockchain, `count`,
`accountType`, and the `metadata` array from Step 1.

<CodeGroup>
  ```ts Node.js SDK theme={null}
  import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

  const client = initiateDeveloperControlledWalletsClient({
    apiKey: process.env.CIRCLE_API_KEY!,
    entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
  });

  const response = await client.createWallets({
    walletSetId: "your-wallet-set-id",
    blockchains: ["ARC-TESTNET"],
    count: 2,
    accountType: "SCA",
    metadata: [
      { name: "Alice Wallet", refId: "user-uuid-1001" },
      { name: "Bob Wallet", refId: "user-uuid-1002" },
    ],
  });
  ```

  ```python Python SDK theme={null}
  import os
  from circle.web3 import developer_controlled_wallets

  client = developer_controlled_wallets.DeveloperControlledWalletsClient(
      api_key=os.getenv("CIRCLE_API_KEY"),
      entity_secret=os.getenv("CIRCLE_ENTITY_SECRET"),
  )

  response = client.create_wallets(
      wallet_set_id="your-wallet-set-id",
      blockchains=["ARC-TESTNET"],
      count=2,
      account_type="SCA",
      metadata=[
          {"name": "Alice Wallet", "refId": "user-uuid-1001"},
          {"name": "Bob Wallet", "refId": "user-uuid-1002"},
      ],
  )
  ```
</CodeGroup>

<Note>
  You can create up to 200 wallets per request. If you need more, make
  additional requests until you reach the required total.
</Note>

## Step 3. Map wallet IDs to your users

Inspect `data.wallets` in the response. Each wallet object includes the `refId`
and `name` you provided, along with the assigned wallet `id` and `address`.

```json Response theme={null}
{
  "data": {
    "wallets": [
      {
        "id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "refId": "user-uuid-1001",
        "name": "Alice Wallet",
        "address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
        "blockchain": "ARC-TESTNET",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      },
      {
        "id": "cda61d8d-7d46-5a39-a8a6-6b4a3d6fdac3",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "refId": "user-uuid-1002",
        "name": "Bob Wallet",
        "address": "0x29b27e792b8b854e48e85ab4f456cf5a9f1579fb",
        "blockchain": "ARC-TESTNET",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      }
    ]
  }
}
```

Persist the wallet `id` against each user record in your database. Use the
`refId` field to match each wallet in the response to the corresponding user in
your system.


# Quickstart: Create a Dev-Controlled Wallet
Source: https://developers.circle.com/wallets/dev-controlled/create-your-first-wallet

Get started with developer-controlled wallets by creating a wallet set and a wallet within it.

A wallet set is a container that groups your developer-controlled wallets under
a single [entity secret](/wallets/dev-controlled/entity-secret-management). All
wallets in a set share the same entity secret, and EVM wallets in the same set
share the [same address](/wallets/unified-wallet-addressing-evm). After
completing this tutorial, you'll have a wallet set and a developer-controlled
wallet. The examples use an
[externally owned account (EOA)](/wallets/account-types#externally-owned-accounts-eoa)
on Arc Testnet, but you can create a
[smart contract account (SCA)](/wallets/account-types#smart-contract-accounts-sca-and-msca)
or use any [supported blockchain](/wallets/supported-blockchains).

## Prerequisites

Before you begin, ensure you have:

* Obtained an [API key](/api-reference/keys) from the
  [Circle Console](https://console.circle.com/).
* Generated and registered an
  [entity secret](/wallets/dev-controlled/register-entity-secret).
* Installed [Node.js 22+](https://nodejs.org/) or
  [Python 3.11+](https://www.python.org/).

## Step 1. Set up your project

### 1.1. Create the project and install dependencies

Create a new directory and install the SDK for the path you want to use.

<CodeGroup>
  ```shell Node.js theme={null}
  # Create the project directory and initialize Node.js
  mkdir dev-controlled-projects
  cd dev-controlled-projects
  npm init -y

  # Set up module type and a start command
  npm pkg set type=module
  npm pkg set scripts.create-wallet="tsx --env-file=.env create-wallet.ts"

  # Install runtime dependencies
  npm install @circle-fin/developer-controlled-wallets

  # Install dev dependencies
  npm install --save-dev tsx typescript @types/node
  ```

  ```shell Python theme={null}
  # Create the project directory and initialize Python
  mkdir dev-controlled-projects
  cd dev-controlled-projects
  python3 -m venv .venv
  source .venv/bin/activate

  # Install runtime dependencies
  pip install circle-developer-controlled-wallets python-dotenv
  ```
</CodeGroup>

### 1.2. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.3. Set environment variables

Create a `.env` file in the project directory:

```text .env theme={null}
CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
```

* `CIRCLE_API_KEY` is your Circle Developer API key.
* `CIRCLE_ENTITY_SECRET` is your registered entity secret.

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

## Step 2. Create your wallet

Write a script creates a wallet set and a developer-controlled wallet, then
prints the wallet set ID, wallet ID, and wallet address.

### 2.1. Create the script

Create a `create-wallet.ts` (or `create_wallet.py`) file and add the following
code. This code creates a wallet set first, and then creates a wallet within it:

<CodeGroup>
  ```ts create-wallet.ts theme={null}
  import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

  const client = initiateDeveloperControlledWalletsClient({
    apiKey: process.env.CIRCLE_API_KEY!,
    entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
  });

  async function main() {
    const walletSetResponse = await client.createWalletSet({
      name: "My First Dev-Controlled Wallet Set",
    });

    const walletSet = walletSetResponse.data?.walletSet;
    if (!walletSet?.id) {
      throw new Error("Wallet set creation failed: no ID returned");
    }

    const walletResponse = await client.createWallets({
      walletSetId: walletSet.id,
      blockchains: ["ARC-TESTNET"], // Can be any supported blockchain
      count: 1,
      accountType: "EOA", // Can be EOA or SCA
    });

    console.log("Wallet set response:", walletSetResponse.data);
    console.log("Wallet response:", walletResponse.data);
  }

  main().catch((err) => {
    console.error("Error:", err.message || err);
    process.exit(1);
  });
  ```

  ```python create_wallet.py theme={null}
  from circle.web3 import utils, developer_controlled_wallets
  from dotenv import load_dotenv
  import os
  import json

  load_dotenv()

  client = utils.init_developer_controlled_wallets_client(
      api_key=os.getenv("CIRCLE_API_KEY"),
      entity_secret=os.getenv("CIRCLE_ENTITY_SECRET")
  )

  wallet_sets_api = developer_controlled_wallets.WalletSetsApi(client)
  wallets_api = developer_controlled_wallets.WalletsApi(client)

  try:
      wallet_set = wallet_sets_api.create_wallet_set(
          developer_controlled_wallets.CreateWalletSetRequest.from_dict({
              "name": "My First Dev-Controlled Wallet Set"
          })
      )

      wallet = wallets_api.create_wallet(
          developer_controlled_wallets.CreateWalletRequest.from_dict({
              "walletSetId": wallet_set.data.wallet_set.actual_instance.id,
              "blockchains": ["ARC-TESTNET"],
              "count": 1,
              "accountType": "EOA"
          })
      )

      print(json.dumps(json.loads(wallet_set.model_dump_json()), indent=2))
      print(json.dumps(json.loads(wallet.model_dump_json()), indent=2))
  except developer_controlled_wallets.ApiException as e:
      print("Exception when calling the Circle Wallets API: %s\n" % e)
  ```
</CodeGroup>

<Note>
  If you are calling the API directly instead of using the SDK, you need two
  requests: one to [create the wallet
  set](/api-reference/wallets/developer-controlled-wallets/create-wallet-set)
  and one to [create the
  wallet](/api-reference/wallets/developer-controlled-wallets/create-wallet).
  Replace the entity secret ciphertext and idempotency key in your request. The
  SDKs handle this automatically.
</Note>

### 2.2. Run the script

Run the script from your project directory:

<CodeGroup>
  ```shell Node.js theme={null}
  npm run create-wallet
  ```

  ```shell Python theme={null}
  python create_wallet.py
  ```
</CodeGroup>

The output looks similar to:

<CodeGroup>
  ```text Node.js theme={null}
  Wallet set response: {
    walletSet: {
      id: "9d4f..."
    }
  }
  Wallet response: {
    wallets: [
      {
        id: "1f29...",
        address: "0x1234...",
        blockchain: "ARC-TESTNET"
      }
    ]
  }
  ```

  ```text Python theme={null}
  {
    "data": {
      "wallet_set": {
        "id": "9d4f..."
      }
    }
  }
  {
    "data": {
      "wallets": [
        {
          "id": "1f29...",
          "address": "0x1234...",
          "blockchain": "ARC-TESTNET"
        }
      ]
    }
  }
  ```
</CodeGroup>

Save the wallet ID and address for future wallet operations such as transferring
tokens or checking balances.

## Next steps

Now that you have a developer-controlled wallet, you can:

* **Fund the wallet**: Get testnet USDC from the
  [Circle Faucet](https://faucet.circle.com/).
* **[Send tokens across wallets](/wallets/dev-controlled/transfer-tokens-across-wallets)**:
  Transfer USDC from one developer-controlled wallet to another.
* **Build payment workflows with [Arc App Kit](https://docs.arc.io/app-kit)**:
  Use the
  [Circle Wallets adapter](https://docs.arc.io/app-kit/tutorials/adapter-setups#circle-wallets)
  to add token transfers, swaps, bridging, and chain-agnostic unified balances
  to your app without building each integration yourself.


# How the Entity Secret Works
Source: https://developers.circle.com/wallets/dev-controlled/entity-secret-management

Learn how the entity secret secures developer-controlled wallets and how it is used in API requests.

Developer-controlled wallets depend on a single developer-held cryptographic
key: the entity secret. Because Circle never stores it, you retain exclusive
control over your wallets and bear sole responsibility for its security.

## The entity secret and ciphertext

These two terms are distinct but inseparable: the entity secret is the key
itself, and the ciphertext is the encrypted form you send in API requests.

### Entity secret

The entity secret is a randomly generated 32-byte private key that authorizes
sensitive wallet operations under your Circle account.

**What to know:**

* Scoped to your Circle account, not to individual API keys. API keys
  authenticate requests; the entity secret authorizes the wallet operations
  those requests perform.
* Circle never stores a copy. Only you can authorize operations on your
  developer-controlled wallets.
* Losing it without a recovery file means permanent loss of access to your
  wallets and funds.

### Entity secret ciphertext

The entity secret ciphertext is the encrypted form of the entity secret, passed
as `entitySecretCiphertext` in API request bodies.

**What to know:**

* Produced by encrypting the entity secret with Circle's public RSA key before
  each request. Circle decrypts it server-side to verify authenticity and
  authorize the operation. For the encryption implementation, see the
  [entity secret sample code](https://github.com/circlefin/w3s-entity-secret-sample-code)
  on GitHub.
* Each ciphertext is single-use. Reusing one causes the request to be rejected,
  which prevents replay attacks.
* When you use the
  [Circle Node.js SDK](/sdks/developer-controlled-wallets-nodejs-sdk) or
  [Python SDK](/sdks/developer-controlled-wallets-python-sdk), re-encryption
  happens automatically before every call. If you make direct API calls without
  an SDK, you are responsible for re-encrypting for each request.

## The recovery file

When you register your entity secret, Circle generates a recovery file tied to
that secret. The recovery file is the only mechanism for resetting your entity
secret through [Circle Console](https://console.circle.com/) if it is ever lost.

**What to know:**

* Without the recovery file, there is no path to recover access to your
  developer-controlled wallets or the funds they hold.
* The recovery file is invalidated each time you rotate your entity secret. Each
  rotation produces a new one. Storing an old recovery file after rotation
  provides no protection.

## Best practices

* **Store the entity secret securely.** Use a secrets manager, hardware security
  module (HSM), or encrypted password manager. Never commit the entity secret to
  version control, include it in application configuration files, or allow it to
  appear in logs.

* **Save the recovery file immediately after registration.** The recovery file
  can only be downloaded once, during the registration flow. If you skip this
  step, you must rotate your entity secret to generate a new one. Store it in a
  separate, secure location from the entity secret itself.

* **Rotate periodically.** Rotating the entity secret limits exposure if it is
  ever silently compromised. Rotate on a regular schedule, such as every 180
  days. Rotation takes effect immediately. Any in-flight API requests using the
  old entity secret will fail. Plan rotations during low-traffic periods and
  reinitialize pending requests afterward. Rotate in
  [Circle Console](https://console.circle.com/).

* **Reset if compromised or lost.** If your entity secret is lost or you suspect
  it has been compromised, use your recovery file to reset it in
  [Circle Console](https://console.circle.com/). After a reset, the old entity
  secret is invalidated immediately and a new recovery file is generated.

<Warning>
  If both the entity secret and the recovery file are lost, you cannot create
  new developer-controlled wallets or initiate transactions from existing
  wallets. There is no recovery path. Store both in separate, secure locations.
</Warning>


# How-to: Pre-Create Wallets and Assign on Demand
Source: https://developers.circle.com/wallets/dev-controlled/pre-create-wallets

Create a pool of unassigned wallets in advance and assign them to new users on demand as they sign up.

Create a pool of developer-controlled wallets before users arrive so wallets are
ready to assign instantly. When a new user signs up, assign an available wallet
by updating its `name` and `refId` fields. This approach reduces sign-up latency
because wallet creation happens ahead of time rather than during registration.

<Warning>
  **Cost consideration for Externally Owned Account (EOA) wallets**

  Creating EOA wallets on mainnet incurs a minor expense per wallet. To optimize
  costs, forecast user demand and batch-create wallets accordingly. For example,
  prepare enough wallets to cover the expected demand for the next 30 days to
  avoid unnecessary expenses.
</Warning>

## Prerequisites

Before you begin, ensure that you've:

* Created a
  [Circle Developer Account and an API key](/w3s/circle-developer-account).
* [Registered your entity secret](/wallets/dev-controlled/register-entity-secret).
* Created a wallet set. If you haven't, complete the
  [Create a Dev-Controlled Wallet](/wallets/dev-controlled/create-your-first-wallet)
  quickstart first.
* Installed [Node.js 22+](https://nodejs.org/) or
  [Python 3.11+](https://www.python.org/).
* Installed the applicable server-side SDK for your language:

  <Tabs>
    <Tab title="Node.js">
      Use the following commands to install the SDK. You can
      [view the package information on the npm site](https://www.npmjs.com/package/@circle-fin/developer-controlled-wallets).

      <CodeGroup>
        ```shell npm theme={null}
        npm install @circle-fin/developer-controlled-wallets --save
        ```

        ```shell yarn theme={null}
        yarn add @circle-fin/developer-controlled-wallets
        ```
      </CodeGroup>

      For more information, visit the
      [Node.js SDK](/sdks/developer-controlled-wallets-nodejs-sdk).
    </Tab>

    <Tab title="Python">
      Use the following command to install the SDK with
      [pip](https://pypi.org/project/pip/):

      ```shell theme={null}
      pip install circle-developer-controlled-wallets
      ```

      For more information, visit the
      [Python SDK](/sdks/developer-controlled-wallets-python-sdk).
    </Tab>
  </Tabs>

## Step 1. Create a pool of unassigned wallets

Call the create wallets endpoint with a `count` value but without `metadata`.
Omitting `metadata` creates wallets that have no `name` or `refId`, leaving them
available for assignment later.

<Note>
  You can create up to 200 wallets per request. If you need more, make additional
  requests until you reach the required total.
</Note>

<CodeGroup>
  ```ts Node.js SDK theme={null}
  import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

  const client = initiateDeveloperControlledWalletsClient({
    apiKey: process.env.CIRCLE_API_KEY!,
    entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
  });

  const response = await client.createWallets({
    walletSetId: "your-wallet-set-id",
    blockchains: ["ARC-TESTNET"],
    count: 50,
    accountType: "SCA",
  });

  console.log(response.data?.wallets);
  ```

  ```python Python SDK theme={null}
  import os
  from circle.web3 import developer_controlled_wallets

  client = developer_controlled_wallets.DeveloperControlledWalletsClient(
      api_key=os.getenv("CIRCLE_API_KEY"),
      entity_secret=os.getenv("CIRCLE_ENTITY_SECRET"),
  )

  response = client.create_wallets(
      wallet_set_id="your-wallet-set-id",
      blockchains=["ARC-TESTNET"],
      count=50,
      account_type="SCA",
  )

  print(response.data.wallets)
  ```
</CodeGroup>

The response contains the newly created wallets. The `name` and `refId` fields
are omitted because no `metadata` was provided:

```json Response theme={null}
{
  "data": {
    "wallets": [
      {
        "id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
        "blockchain": "ARC-TESTNET",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      },
      {
        "id": "cda61d8d-7d46-5a39-a8a6-6b4a3d6fdac3",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "address": "0x29b27e792b8b854e48e85ab4f456cf5a9f1579fb",
        "blockchain": "ARC-TESTNET",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      }
    ]
  }
}
```

## Step 2. Store wallet IDs

Persist the returned wallet IDs in your system and mark each one as
**unassigned**. The storage mechanism is application-specific—you might use a
database table, a key-value store, or any other persistence layer your
application already uses.

Track each wallet's assignment status so that when a new user signs up, your
application can quickly select an unassigned wallet and avoid double-assigning
the same wallet to multiple users. A simple boolean flag or status column (for
example, `assigned: false`) works for most implementations.

## Step 3. Assign a wallet to a new user

When a user registers, select an unassigned wallet from the pool and call the
update wallet endpoint to set its `name` and `refId`. The `refId` field is
designed for linking wallets to entities in your own system, such as a user ID.

This endpoint does not require `entitySecretCiphertext`, so no entity secret
encryption is needed for this call.

<CodeGroup>
  ```ts Node.js SDK theme={null}
  const walletId: string = "66b67097-307e-5b46-a1d5-0b1577d67fd4";
  const userId: string = "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a";

  const updated = await client.updateWallet({
    id: walletId,
    name: "User Wallet",
    refId: userId,
  });

  console.log(updated.data?.wallet);
  ```

  ```python Python SDK theme={null}
  wallet_id = "66b67097-307e-5b46-a1d5-0b1577d67fd4"
  user_id = "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a"

  updated = client.update_wallet(
      id=wallet_id,
      name="User Wallet",
      ref_id=user_id,
  )

  print(updated.data.wallet)
  ```
</CodeGroup>

The response confirms the wallet now has the assigned `name` and `refId`:

```json Response theme={null}
{
  "data": {
    "wallet": {
      "id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
      "state": "LIVE",
      "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
      "custodyType": "DEVELOPER",
      "refId": "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a",
      "name": "User Wallet",
      "address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
      "blockchain": "ARC-TESTNET",
      "accountType": "SCA",
      "updateDate": "2024-01-22T23:15:42Z",
      "createDate": "2024-01-22T22:57:20Z"
    }
  }
}
```

After the update succeeds, mark the wallet as **assigned** in your own system so
it is no longer available in the unassigned pool.

## Step 4. Verify the assignment

Call the list wallets endpoint filtered by `refId` to confirm the wallet is
correctly assigned to the user.

<CodeGroup>
  ```ts Node.js SDK theme={null}
  const userId: string = "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a";

  const wallets = await client.listWallets({
    refId: userId,
  });

  console.log(wallets.data?.wallets);
  ```

  ```python Python SDK theme={null}
  user_id = "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a"

  wallets = client.list_wallets(
      ref_id=user_id,
  )

  print(wallets.data.wallets)
  ```
</CodeGroup>

The response returns only wallets matching the specified `refId`:

```json Response theme={null}
{
  "data": {
    "wallets": [
      {
        "id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "refId": "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a",
        "name": "User Wallet",
        "address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
        "blockchain": "ARC-TESTNET",
        "accountType": "SCA",
        "updateDate": "2024-01-22T23:15:42Z",
        "createDate": "2024-01-22T22:57:20Z"
      }
    ]
  }
}
```


# How-to: Generate and Register Your Entity Secret
Source: https://developers.circle.com/wallets/dev-controlled/register-entity-secret

Generate an entity secret and register it with Circle.

Registering your entity secret with Circle enables developer-controlled wallet
operations. After completing these steps, your entity secret is active and your
recovery file is saved.

## Prerequisites

Before you begin, ensure you've:

* Created an API key in the [Circle Console](https://console.circle.com/).
* Installed [Node.js 22+](https://nodejs.org/) or
  [Python 3.11+](https://www.python.org/).
* Installed the developer-controlled wallets SDK:

<CodeGroup>
  ```shell Node.js theme={null}
  npm install @circle-fin/developer-controlled-wallets
  ```

  ```shell Python theme={null}
  pip install circle-developer-controlled-wallets
  ```
</CodeGroup>

<Note>
  If you are not using the Circle SDK, you can generate and register your entity
  secret [manually](https://github.com/circlefin/w3s-entity-secret-sample-code)
  using standard libraries or command-line tools.
</Note>

## Generate and register an entity secret

<Steps>
  <Step title="Generate an entity secret">
    Use the `generateEntitySecret` function from the Node.js SDK or the
    `generate_entity_secret` function from the Python SDK:

    <CodeGroup>
      ```typescript Node.js theme={null}
      import { generateEntitySecret } from "@circle-fin/developer-controlled-wallets";

      generateEntitySecret();
      ```

      ```python Python theme={null}
      from circle.web3 import utils

      entity_secret = utils.generate_entity_secret()
      print(entity_secret)
      ```
    </CodeGroup>

    Copy the printed value and store it securely as `CIRCLE_ENTITY_SECRET`. You need
    it in the next step and for all future API calls.
  </Step>

  <Step title="Register the entity secret">
    Pass your API key, entity secret, and a local directory path to the registration
    function. The SDK encrypts the entity secret, registers it with Circle, and
    saves the recovery file to the path you provide:

    <CodeGroup>
      ```typescript Node.js theme={null}
      import { registerEntitySecretCiphertext } from "@circle-fin/developer-controlled-wallets";

      const response = await registerEntitySecretCiphertext({
        apiKey: process.env.CIRCLE_API_KEY ?? "",
        entitySecret: process.env.CIRCLE_ENTITY_SECRET ?? "",
        recoveryFileDownloadPath: "./recovery",
      });

      console.log(response.data?.recoveryFile);
      ```

      ```python Python theme={null}
      import os
      from circle.web3 import utils

      result = utils.register_entity_secret_ciphertext(
        api_key=os.environ.get("CIRCLE_API_KEY", ""),
        entity_secret=os.environ.get("CIRCLE_ENTITY_SECRET", ""),
        recoveryFileDownloadPath="./recovery",
      )

      print(result)
      ```
    </CodeGroup>
  </Step>
</Steps>

<Warning>
  **Secure your entity secret and recovery file.**

  Store your entity secret in a secrets manager or encrypted password manager.
  Save the recovery file to a separate, secure location. It is the only way to
  reset your entity secret if it is lost. Circle does not store your entity secret
  and cannot recover it for you. For more on storage and rotation best practices,
  see
  [How the Entity Secret Works](/wallets/dev-controlled/entity-secret-management).
</Warning>


# Send Tokens Across Wallets
Source: https://developers.circle.com/wallets/dev-controlled/transfer-tokens-across-wallets

Send USDC from one dev-controlled wallet to another, then verify the transaction status and recipient balance.

Developer-controlled wallets can send tokens to any address on the same
blockchain. After completing this tutorial, you'll have sent USDC from one
developer-controlled wallet to\
another. The examples use Arc Testnet, but you can send tokens on any
[supported blockchain](/wallets/supported-blockchains).

<Tip>
  Circle offers [Gas Station](/wallets/gas-station) if you want to sponsor gas
  instead of funding the sender wallet directly. See [Send a Gasless
  Transaction](/wallets/gas-station/send-a-gasless-transaction).
</Tip>

## Prerequisites

Before you begin, ensure you have:

* Obtained an [API key](/api-reference/keys) from the
  [Circle Console](https://console.circle.com/).
* Registered an [entity secret](/wallets/dev-controlled/register-entity-secret).
* Completed the
  [Create a Dev-Controlled Wallet](/wallets/dev-controlled/create-your-first-wallet)
  quickstart and created two wallets (a source wallet and a destination wallet).
* Funded the source wallet with testnet USDC from the
  [Circle Faucet](https://faucet.circle.com/).
* Installed [Node.js 22+](https://nodejs.org/) or
  [Python 3.11+](https://www.python.org/).

## Step 1. Set up your project

Reuse the `dev-controlled-projects` folder you created in the
[Create a Dev-Controlled Wallet](/wallets/dev-controlled/create-your-first-wallet)
quickstart.

### 1.1. Prepare your project

Add the transfer run command:

<CodeGroup>
  ```shell Node.js theme={null}
  # Add a script for the transfer quickstart
  npm pkg set scripts.send-tokens="tsx --env-file=.env send-tokens.ts"
  ```

  ```shell Python theme={null}
  # Create or reactivate the virtual environment
  python3 -m venv .venv
  source .venv/bin/activate

  # Install runtime dependencies
  pip install circle-developer-controlled-wallets python-dotenv
  ```
</CodeGroup>

### 1.2. Set environment variables

Add your API key and entity secret to `.env`:

```text .env theme={null}
CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
```

* `CIRCLE_API_KEY` is your Circle Developer API key.
* `CIRCLE_ENTITY_SECRET` is your registered entity secret.

<Tip>
  Open `.env` in your editor rather than writing values with shell commands, and
  add `.env` to your `.gitignore`. This prevents credentials from leaking into
  your shell history or version control.
</Tip>

## Step 2. Send USDC between wallets

Write a script that sends USDC from the source wallet, polls for completion,
then checks the recipient balance.

### 2.1. Create the script

Create a `send-tokens.ts` (or `send_tokens.py`) file and add the following code.
The script calls `createTransaction()` to initiate the transfer, then polls
`getTransaction()` until the transaction reaches a terminal state: `COMPLETE`,
`FAILED`, `CANCELLED`, or `DENIED`.

<CodeGroup>
  ```ts send-tokens.ts theme={null}
  import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

  // Replace the source and destination constants with your own wallet values
  const SOURCE_WALLET_ADDRESS: string = "0x..."; // Used with blockchain to identify the source wallet
  const SOURCE_WALLET_BLOCKCHAIN = "0x..."; // Used with blockchain to identify the source wallet
  const DESTINATION_WALLET_ADDRESS: string = "0x..."; // Recipient wallet address
  const DESTINATION_WALLET_ID: string = "..."; // Used for post-transfer balance check only
  const ARC_TESTNET_USDC: string = "0x3600000000000000000000000000000000000000";
  const TRANSFER_AMOUNT_USDC: string = "5"; // Token quantity as a string

  // Initialize the wallets client
  const client = initiateDeveloperControlledWalletsClient({
    apiKey: process.env.CIRCLE_API_KEY!,
    entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
  });

  async function main() {
    // Validate the wallet inputs
    if (
      SOURCE_WALLET_ADDRESS === "YOUR_SOURCE_WALLET_ADDRESS" ||
      DESTINATION_WALLET_ID === "YOUR_DESTINATION_WALLET_ID" ||
      DESTINATION_WALLET_ADDRESS === "YOUR_DESTINATION_WALLET_ADDRESS"
    ) {
      throw new Error(
        "Replace the wallet constants at the top of send-tokens.ts before running the script.",
      );
    }

    // Create the transfer transaction
    const transferResponse = await client.createTransaction({
      blockchain: SOURCE_WALLET_BLOCKCHAIN,
      walletAddress: SOURCE_WALLET_ADDRESS,
      tokenAddress: ARC_TESTNET_USDC, // USDC contract address on Arc Testnet; replace for other chains
      destinationAddress: DESTINATION_WALLET_ADDRESS,
      amount: [TRANSFER_AMOUNT_USDC],
      fee: {
        type: "level",
        config: { feeLevel: "MEDIUM" }, // Gas fee strategy: LOW, MEDIUM, or HIGH
      },
    });

    const transactionId = transferResponse.data?.id;
    let currentState = transferResponse.data?.state ?? "";

    if (!transactionId) {
      throw new Error("Transaction creation failed: no ID returned");
    }

    console.log("Transfer response:", transferResponse.data);

    // Wait for the transfer to finish
    const terminalStates = new Set(["COMPLETE", "FAILED", "CANCELLED", "DENIED"]);

    while (!terminalStates.has(currentState)) {
      await new Promise((resolve) => setTimeout(resolve, 3000));
      const pollResponse = await client.getTransaction({ id: transactionId });
      const tx = pollResponse.data?.transaction;
      currentState = tx?.state ?? "";
      console.log("Transaction response:", pollResponse.data);

      if (currentState === "COMPLETE") break;
    }

    if (currentState !== "COMPLETE") {
      throw new Error(`Transaction ended in state: ${currentState}`);
    }

    // Check the recipient balance
    const destinationBalanceResponse = await client.getWalletTokenBalance({
      id: DESTINATION_WALLET_ID,
    });

    console.log("Wallet balance response:", destinationBalanceResponse.data);
  }

  main().catch((err) => {
    console.error("Error:", err.message || err);
    process.exit(1);
  });
  ```

  ```python send_tokens.py theme={null}
  from circle.web3 import utils, developer_controlled_wallets
  from dotenv import load_dotenv
  import os
  import time
  import json

  load_dotenv()

  # Set transfer inputs
  SOURCE_WALLET_ADDRESS = "YOUR_SOURCE_WALLET_ADDRESS"
  SOURCE_WALLET_BLOCKCHAIN = "ARC-TESTNET"
  DESTINATION_WALLET_ID = "YOUR_DESTINATION_WALLET_ID"
  DESTINATION_WALLET_ADDRESS = "YOUR_DESTINATION_WALLET_ADDRESS"
  ARC_TESTNET_USDC = "0x3600000000000000000000000000000000000000"
  TRANSFER_AMOUNT_USDC = "5"

  # Initialize the wallets client
  client = utils.init_developer_controlled_wallets_client(
      api_key=os.getenv("CIRCLE_API_KEY"),
      entity_secret=os.getenv("CIRCLE_ENTITY_SECRET")
  )

  transactions_api = developer_controlled_wallets.TransactionsApi(client)
  wallets_api = developer_controlled_wallets.WalletsApi(client)

  # Validate the wallet inputs
  if (
      SOURCE_WALLET_ADDRESS == "YOUR_SOURCE_WALLET_ADDRESS"
      or DESTINATION_WALLET_ID == "YOUR_DESTINATION_WALLET_ID"
      or DESTINATION_WALLET_ADDRESS == "YOUR_DESTINATION_WALLET_ADDRESS"
  ):
      raise ValueError(
          "Replace the wallet constants at the top of send_tokens.py before running the script."
      )

  try:
      # Create the transfer transaction
      request = developer_controlled_wallets.CreateTransferTransactionForDeveloperRequest.from_dict({
          "walletAddress": SOURCE_WALLET_ADDRESS,
          "blockchain": SOURCE_WALLET_BLOCKCHAIN,
          "destinationAddress": DESTINATION_WALLET_ADDRESS,
          "tokenAddress": ARC_TESTNET_USDC,
          "amounts": [TRANSFER_AMOUNT_USDC],
          "feeLevel": "MEDIUM"
      })

      transfer_response = transactions_api.create_developer_transaction_transfer(request)
      transfer_data = transfer_response.data.to_dict()
      transaction_id = transfer_data["id"]
      current_state = transfer_data["state"]

      print(json.dumps(json.loads(transfer_response.model_dump_json()), indent=2))

      # Wait for the transfer to finish
      terminal_states = {"COMPLETE", "FAILED", "CANCELLED", "DENIED"}

      while current_state not in terminal_states:
          time.sleep(3)
          poll_response = transactions_api.get_transaction(id=transaction_id)
          transaction = poll_response.data.to_dict()["transaction"]
          current_state = transaction["state"]
          print(json.dumps(json.loads(poll_response.model_dump_json()), indent=2))

      if current_state != "COMPLETE":
          raise RuntimeError(f"Transaction ended in state: {current_state}")

      # Check the recipient balance
      destination_balance_response = wallets_api.list_wallet_balance(id=DESTINATION_WALLET_ID)
      print(json.dumps(json.loads(destination_balance_response.model_dump_json()), indent=2))
  except developer_controlled_wallets.ApiException as e:
      print("Exception when calling the Circle Wallets API: %s\n" % e)
  ```
</CodeGroup>

<Note>
  If you're calling the API directly instead of using the SDK, use
  [Create Transfer Transaction](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-transfer),
  [Get Transaction](/api-reference/wallets/developer-controlled-wallets/get-transaction),
  and
  [List Wallet Balance](/api-reference/wallets/developer-controlled-wallets/list-wallet-balance).
  Be sure to replace the entity secret ciphertext and idempotency key in your
  request. If you're using the SDKs, this is handled automatically for you.
</Note>

### 2.2. Run the script

Run the script from your project directory:

<CodeGroup>
  ```shell Node.js theme={null}
  npm run send-tokens
  ```

  ```shell Python theme={null}
  python send_tokens.py
  ```
</CodeGroup>

The output looks similar to:

<CodeGroup>
  ```text Node.js theme={null}
  Transfer response: {
    id: "6f10...",
    state: "INITIATED"
  }
  Transaction response: {
    transaction: {
      id: "6f10...",
      state: "COMPLETE",
      blockchain: "ARC-TESTNET",
      txHash: "0x..."
    }
  }
  Wallet balance response: {
    tokenBalances: [
      {
        token: [Object],
        amount: "5"
      }
    ]
  }
  ```

  ```text Python theme={null}
  {
    "data": {
      "id": "6f10...",
      "state": "INITIATED"
    }
  }
  {
    "data": {
      "transaction": {
        "id": "6f10...",
        "state": "COMPLETE",
        "blockchain": "ARC-TESTNET",
        "tx_hash": "0x..."
      }
    }
  }
  {
    "data": {
      "token_balances": [
        {
          "amount": "5",
          "token": {
            "symbol": "USDC"
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

<Note>
  You can also monitor the transfer through [webhook
  notifications](/wallets/webhook-notifications) or by polling [Get
  Transaction](/api-reference/wallets/developer-controlled-wallets/get-transaction).
</Note>

## Next steps

* **Build payment workflows with [Arc App Kit](https://docs.arc.io/app-kit)**:
  Use the
  [Circle Wallets adapter](https://docs.arc.io/app-kit/tutorials/adapter-setups#circle-wallets)
  to add token transfers, swaps, bridging, and chain-agnostic unified balances
  to your app without building each integration yourself.


# Programmable Wallets API Error Codes
Source: https://developers.circle.com/wallets/error-codes

Descriptions of error codes returned by the Wallets API

The Wallets and Contracts APIs return an
[HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) when
they encounter an error in an API request:

* `4xx` errors are client errors, which are informative and actionable. They
  communicate a mistake to the user and suggest fixes.
* `5xx` errors are unexpected server-side errors.

The tables in the following sections describe some of the common error messages
you might encounter using the Wallets and Contracts APIs. Where possible, a
suggested fix is provided in the `Description` column.

## General error format

HTTP status codes do not always provide sufficient information to determine the
cause of the error. Since the status code is part of the header of the response,
the body of response contains additional, Circle-specific, error information.
For example, if a request contains an invalid parameter, the response includes
the following:

**Header**

`HTTP/1.1 400 Bad RequestContent-Type: application/json`

**Body**

```json JSON theme={null}
{
  "code": 2,
  "message": "API parameter invalid"
}
```

## Extended error format

In some cases, the response includes extended information about the cause of the
error. For example, if a request doesn't include a value for a required
parameter, the response includes a detailed error message:

**Header**

`HTTP/1.1 400 Bad RequestContent-Type: application/json`

**Body**

```json JSON theme={null}
{
  "code": 2,
  "message": "API parameter invalid",
  "errors": [
    {
      "error": "required",
      "message": "fail to bind request to CreateWalletSetRequest: EOF",
      "location": "field1",
      "invalidValue": "null",
      "constraints": {}
    }
  ]
}
```

## General errors

This section describes some common extended error messages you might encounter
using Wallets and Contracts APIs.

The following errors are general errors that can be returned for any request.

| Error Code | HTTP code | Error Message          | Description                                                      |
| :--------- | :-------- | :--------------------- | :--------------------------------------------------------------- |
| `-1`       | `400`     | `Something went wrong` | An unknown error occurred while processing the API request.      |
| `3`        | `403`     | `Forbidden`            | The API key used does not have access to the requested endpoint. |

### Invalid requests

A `400` HTTP status code indicates that the request is invalid or malformed.
When the request is invalid, the Circle-specific error code is `2`. The
following table describes the common error messages that can be returned for
invalid requests.

| Error Code | HTTP code | Error Message                                                             | Description                                                                                                          |
| :--------- | :-------- | :------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------- |
| `2`        | `400`     | `Invalid Entity`                                                          | There is an error in the JSON format passed in the request.                                                          |
| `2`        | `400`     | `Fail to bind request to parameter: invalid UUID format`                  | The parameter must be in UUID format.                                                                                |
| `2`        | `400`     | `Error: Field validation`                                                 | One of the fields in the request is invalid.                                                                         |
| `2`        | `400`     | `Error: Field validation for blockchain failed on the blockchain tag`     | The blockchain does not exist. Try again with a [supported blockchain](/wallets/supported-blockchains).              |
| `2`        | `400`     | `Error: Field validation for gasLimit failed on the required_without tag` | If `feeLevel` is provided, `gasLimit` should be set to `NULL`. If `feeLevel` is `NULL`, `gasLimit` must be provided. |
| `2`        | `400`     | `Error: Field validation for parameter failed on the min tag`             | The parameter is not in the correct format.                                                                          |
| `2`        | `400`     | `Cannot unmarshal`                                                        | The JSON body of the request is not valid.                                                                           |
| `2`        | `400`     | `INVALID: parameter empty`                                                | The parameter is required for this request. Try the request again with this parameter.                               |

## Wallets errors

This section describes the errors that can be returned for Programmable Wallet
API requests.

### User errors

| Error code | HTTP code | Error message                                                                                                               | Description                                                                                                                                                                                                  |
| ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `155101`   | `409`     | `Existing user already created with the provided userId.`                                                                   | The user ID already exists. Try the request again with a different user ID.                                                                                                                                  |
| `155102`   | `404`     | `Cannot find the user id in the system.`                                                                                    | The user is not found. Try the request again with a different user ID.                                                                                                                                       |
| `155103`   | `401`     | `Cannot find the user token in the system.`                                                                                 | The user token is not found. Try the request again with a different user token.                                                                                                                              |
| `155104`   | `403`     | `The userToken had expired.`                                                                                                | The user token has expired. Generate a new user token and try the request again.                                                                                                                             |
| `155105`   | `403`     | `The userToken is invalid.`                                                                                                 | The user token is invalid. Generate a new user token and try the request again.                                                                                                                              |
| `155106`   | `409`     | `The user had already been initialized.`                                                                                    | The user has already been initialized. Query the user status first to check if the user has already set a pin and created a wallet.                                                                          |
| `155107`   | `409`     | `User has previously set a PIN. Use PUT /user/pin to reset the PIN.`                                                        | The PIN has already been set successfully. Query the user status to check if the user has already set a PIN.                                                                                                 |
| `155108`   | `409`     | `User has previously set up their security questions, and they can't be reset.`                                             | The user has already set the security questions successfully. The questions can only be set once.                                                                                                            |
| `155109`   | `409`     | `The specified user has been disabled.`                                                                                     | The specified user has been disabled.                                                                                                                                                                        |
| `155110`   | `400`     | `User has not set up a PIN yet.`                                                                                            | The action cannot be performed before the user sets their pin. To set a pin, call initialize or set a pin first.                                                                                             |
| `155111`   | `400`     | `User hasn't set the security questions for PIN backup yet.`                                                                | The action cannot be performed before the user sets their security questions. To set security questions, call initialize or set security questions first.                                                    |
| `155112`   | `400`     | `The user has inputted the incorrect pin.`                                                                                  | The user's PIN is not correct. Try the request again with a different PIN.                                                                                                                                   |
| `155113`   | `400`     | `Provided device ID is not found in the system.`                                                                            | The device ID is not correct. Try the request again with a different device ID.                                                                                                                              |
| `155114`   | `400`     | `Provided app ID is not recognized in the system.`                                                                          | The app ID is not found. Check the app ID in the SDK API. If you do not have the app ID or it is incorrect, you can acquire it from the Developer Console or by making an API request to GET /config/entity. |
| `155115`   | `400`     | `The user has inputted the incorrect security answers`                                                                      | The provided security answers are not correct. Try the request again with different answers.                                                                                                                 |
| `155116`   | `404`     | `The challenge ID doesn't exist in the system.`                                                                             | The challenge ID is invalid. Check the challenge ID in the SDK API.                                                                                                                                          |
| `155117`   | `400`     | `The content provided for approval is not correct.`                                                                         | The provided approval content is unknown. Integrate with the latest SDK.                                                                                                                                     |
| `155118`   | `400`     | `Encryption key does not match with the user's token. Call POST /users/token to get the correct token encryption key pair.` | The encryption key does not match the user's token. Call POST /users/token to get the correct token encryption key pair.                                                                                     |
| `155119`   | `400`     | `The user's PIN input is locked. It will be unlocked after the cooldown period.`                                            | The user's PIN input is locked. Wait for the cooldown period to unlock, and try again.                                                                                                                       |
| `155120`   | `400`     | `The user's security questions input is locked. It will be unlocked after the cooldown period.`                             | The user's security questions input is locked. Wait for the locked period to expire to unlock, and try again.                                                                                                |
| `155121`   | `403`     | `The provided challengeId has expired.`                                                                                     | The challenge has expired. Try the request again to create a new challenge.                                                                                                                                  |
| `155122`   | `403`     | `The provided challengeId is invalid`                                                                                       | The challenge is invalid. Try the request again to create a new challenge.                                                                                                                                   |
| `155123`   | `403`     | `No extra information provided when adding PIN-related requests.`                                                           | When SDK approves the challenge, the challenge format is wrong. Try the request again to create a new challenge.                                                                                             |
| `155124`   | `403`     | `The extra information provided for PIN-related requests is invalid.`                                                       | When SDK approves the challenge, the challenge format is wrong. Try the request again to create a new challenge.                                                                                             |
| `155130`   | `400`     | `User OTP token is expired.`                                                                                                | User OTP token is expired. Request an OTP email again.                                                                                                                                                       |
| `155131`   | `400`     | `User OTP token is invalid.`                                                                                                | User OTP token is invalid. Check the input parameters.                                                                                                                                                       |
| `155132`   | `404`     | `User OTP value is not found.`                                                                                              | User OTP value is not found. Request an OTP email first.                                                                                                                                                     |
| `155133`   | `400`     | `User OTP value is invalid.`                                                                                                | User OTP value is invalid. Check the input parameters.                                                                                                                                                       |
| `155134`   | `400`     | `User OTP value is not matched.`                                                                                            | User OTP value is not matched. Check if the OTP value and OTP token match.                                                                                                                                   |
| `155135`   | `400`     | `User's email is invalid.`                                                                                                  | User's email is invalid. Check the email format in the request.                                                                                                                                              |
| `155136`   | `400`     | `User's email is not matched.`                                                                                              | User's email is not matched. Check if the email is the same.                                                                                                                                                 |
| `155137`   | `400`     | `User's device ID is invalid.`                                                                                              | User's device ID is invalid. Check the input parameters.                                                                                                                                                     |
| `155138`   | `400`     | `Failed to send the email.`                                                                                                 | Failed to send the email. Check the SMTP configuration in the developer console.                                                                                                                             |
| `155139`   | `400`     | `The idToken / accessToken of SSO is expired.`                                                                              | The `idToken` / `accessToken` of SSO is expired. Get it from the SSO provider again.                                                                                                                         |
| `155140`   | `400`     | `Failed to validate the idToken/ accessToken.`                                                                              | Failed to validate the `idToken` / `accessToken`. Ensure the ID input on the SSO provider configuration is correct.                                                                                          |
| `155141`   | `400`     | `The user has exceeded the max limit (5) of entering OTP at the moment.`                                                    | The user has exceeded the max limit (5) of entering OTP at the moment. Wait for a cool-down period of 60 minutes before attempting again.                                                                    |
| `155142`   | `400`     | `The max limit (5) of sending OTP has been exceeded at the moment.`                                                         | The max limit (5) of sending OTP has been exceeded at the moment. Wait for a cool-down period of 60 minutes before attempting again.                                                                         |
| `155143`   | `400`     | `The device token is expired.`                                                                                              | The device token is expired. Request a new device token, and note that the expiry time is 10 minutes.                                                                                                        |
| `155144`   | `400`     | `The device token is invalid.`                                                                                              | The device token is invalid. Request a new device token, and ensure it is the correct token. Note that only one active token is allowed per `deviceId`.                                                      |
| `155145`   | `404`     | `The device token is not found.`                                                                                            | The device token is not found. Request a new device token to proceed.                                                                                                                                        |
| `155146`   | `400`     | `The OTP token is invalid as the user has entered it incorrectly three times.`                                              | The OTP token is invalid as the user has entered it incorrectly three times. Request a new OTP email.                                                                                                        |

### Entity errors

| Error code | HTTP code | Error message                                  | Description                                                                                           |
| ---------- | --------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `155150`   | `404`     | `The SMTP server configuration is not found.`  | The SMTP server configuration is not found. Complete the SMTP setting in the developer console first. |
| `155151`   | `400`     | `The SMTP server configuration is invalid.`    | The SMTP server configuration is invalid. Check the SMTP setting in the developer console.            |
| `155152`   | `404`     | `The SSO provider configuration is not found.` | The SSO provider configuration is not found. Add the SSO provider in the developer console.           |
| `155154`   | `400`     | `The OTP email template is invalid.`           | The OTP email template is invalid. Check the OTP email template configuration.                        |
| `155155`   | `404`     | `The OTP email template is not found.`         | The OTP email template is not found. Add the OTP email template in the developer console first.       |
| `155156`   | `400`     | `Failed to update the email template.`         | Failed to update the email template. Check the content of the OTP email template.                     |
| `155157`   | `400`     | `Failed to update the SMTP server`             | Failed to update the SMTP server configuration. Check the SMTP setting in the developer console.      |

### Transaction errors

| Error code | HTTP code | Error message                                                                                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `155201`   | `400`     | `Not enough funds to fulfill the withdraw request.`                                                                                                                        | There is insufficient native token balance in the wallet to cover all pending transactions on the network. Add funds to the wallet, and try again.                                                                                                                                                                                                                                                           |
| `155202`   | `400`     | `Transaction nonce is inconsistent with sender's latest nonce.`                                                                                                            | Transaction nonce mismatches occur when a sender has created one or more transactions onchain where the initial transaction has not yet reached finality. Try the transaction again.                                                                                                                                                                                                                         |
| `155203`   | `400`     | `User op nonce can not be larger than 0 when smart contract wallet hasn't been deployed.`                                                                                  | User op nonce can not be larger than 0 when the smart contract wallet hasn't been deployed.                                                                                                                                                                                                                                                                                                                  |
| `155204`   | `400`     | `The total cost of executing transaction is higher than the balance of the user's account when estimating fee.`                                                            | There is insufficient native token balance in the wallet to cover the total cost of executing the transaction. Add funds to the wallet, and try again.                                                                                                                                                                                                                                                       |
| `155205`   | `400`     | `Failed to execute this request on EVM due to insufficient token when estimating fee.`                                                                                     | There is insufficient non-native token balance in the wallet to cover the request execution. Add funds to the wallet, and try again.                                                                                                                                                                                                                                                                         |
| `155206`   | `400`     | `The sender address is not token owner or approved when estimating token transfer.`                                                                                        | The owner of the tokens may not call approve ABI to allow the caller to access the tokens.                                                                                                                                                                                                                                                                                                                   |
| `155207`   | `400`     | `Gas required exceeds allowance when estimating fee.`                                                                                                                      | Gas required exceeds allowance when estimating fee.                                                                                                                                                                                                                                                                                                                                                          |
| `155208`   | `400`     | `Estimate fee execution reverted.`                                                                                                                                         | Estimate fee execution reverted on EVM.                                                                                                                                                                                                                                                                                                                                                                      |
| `155209`   | `400`     | `ABI function signature can't pack ABI parameter.`                                                                                                                         | The ABI parameters were invalid. Correct the ABI parameters and try again.                                                                                                                                                                                                                                                                                                                                   |
| `155210`   | `400`     | `Fails to perform transaction estimation.`                                                                                                                                 | Estimate fee execution failed on EVM.                                                                                                                                                                                                                                                                                                                                                                        |
| `155211`   | `400`     | `MaxFee * GasLimit exceed configurable max transaction fee (default is 1 native token).`                                                                                   | Reduce maxFee or gasLimit, and try again. Note Circle has system-wide limits for maxFee for each blockchain network and native token pair. Ethereum = 1 ETH, Polygon = 10 MATIC, Avalanche = 1 AVAX.                                                                                                                                                                                                         |
| `155215`   | `400`     | `Unsupported operation for transaction.`                                                                                                                                   | The requested operation for the transaction is not eligible to be executed anymore. Check the status of the transaction.                                                                                                                                                                                                                                                                                     |
| `155218`   | `400`     | `Invalid number of nft in transaction request.`                                                                                                                            | Invalid number of NFT in the transaction request. Only ERC-1155 supports batch NFT token transfer.                                                                                                                                                                                                                                                                                                           |
| `155219`   | `400`     | `Invalid destination address.`                                                                                                                                             | Correct the destination address, and try again.                                                                                                                                                                                                                                                                                                                                                              |
| `155220`   | `400`     | `Wallet and token's blockchain mismatch.`                                                                                                                                  | The wallet and token's blockchain must be the same.                                                                                                                                                                                                                                                                                                                                                          |
| `155221`   | `400`     | `Invalid amounts in transfer request.`                                                                                                                                     | Other than ERC-1155, all other types of token transfer amount length should be 1.                                                                                                                                                                                                                                                                                                                            |
| `155222`   | `404`     | `NFT metadata can not be found.`                                                                                                                                           | NFT metadata can not be found.                                                                                                                                                                                                                                                                                                                                                                               |
| `155223`   | `400`     | `Unsupported userId for get transactions.`                                                                                                                                 | UserId is not supported as a query parameter for GET transaction requests.                                                                                                                                                                                                                                                                                                                                   |
| `155224`   | `400`     | `Failed to parse the provided amounts in request to decimals.`                                                                                                             | Failed to parse the provided amounts in request to decimals.                                                                                                                                                                                                                                                                                                                                                 |
| `155225`   | `400`     | `Wallet and request's blockchain mismatch.`                                                                                                                                | The wallet and blockchain in the request should be the same.                                                                                                                                                                                                                                                                                                                                                 |
| `155226`   | `400`     | `Invalid source address.`                                                                                                                                                  | Correct the source address, and try again.                                                                                                                                                                                                                                                                                                                                                                   |
| `155227`   | `400`     | `Invalid transaction type.`                                                                                                                                                | Transaction validation failed because the transaction type is not outbound.                                                                                                                                                                                                                                                                                                                                  |
| `155228`   | `400`     | `Missing token ID.`                                                                                                                                                        | The token ID is missing from the request. Add the correct token ID, and try again.                                                                                                                                                                                                                                                                                                                           |
| `155229`   | `400`     | `Transaction is not eligible for operation.`                                                                                                                               | The transaction is not eligible for operation.                                                                                                                                                                                                                                                                                                                                                               |
| `155230`   | `400`     | `No call data or abi signature provided.`                                                                                                                                  | Provide an ABI signature, and try again.                                                                                                                                                                                                                                                                                                                                                                     |
| `155231`   | `400`     | `Transaction needs feeLevel or gasLimit provided.`                                                                                                                         | Provide feeLevel or gasLimit, and try again.                                                                                                                                                                                                                                                                                                                                                                 |
| `155232`   | `400`     | `SCA transaction needs feeLevel provided.`                                                                                                                                 | SCA transaction needs feeLevel provided. Specify the feeLevel, and try again.                                                                                                                                                                                                                                                                                                                                |
| `155233`   | `400`     | `Provided gasLimit is too low to complete the requested transaction.`                                                                                                      | Provided gasLimit smaller than network estimation. Provide a higher gasLimit, and try again.                                                                                                                                                                                                                                                                                                                 |
| `155234`   | `400`     | `Transaction can't have both feeLevel and fee parameters provided.`                                                                                                        | Specify either feeLevel, or provide the detailed fee parameters for a transaction.                                                                                                                                                                                                                                                                                                                           |
| `155235`   | `400`     | `EIP1559 chains need maxFee/priorityFee provided.`                                                                                                                         | EIP1559 chains need maxFee/priorityFee provided.                                                                                                                                                                                                                                                                                                                                                             |
| `155236`   | `400`     | `Failed to parse the provided fee in request to decimals.`                                                                                                                 | Failed to parse the provided fee in request to decimals.                                                                                                                                                                                                                                                                                                                                                     |
| `155237`   | `400`     | `PriorityFee cannot be larger than maxFee in creating transaction request.`                                                                                                | PriorityFee cannot be larger than maxFee in creating transaction requests.                                                                                                                                                                                                                                                                                                                                   |
| `155238`   | `400`     | `Non-EIP1559 chains need gasPrice provided.`                                                                                                                               | Non-EIP1559 chains need `gasPrice` provided.                                                                                                                                                                                                                                                                                                                                                                 |
| `155239`   | `400`     | `Invalid token address for transfer.`                                                                                                                                      | Correct the token address, and try again.                                                                                                                                                                                                                                                                                                                                                                    |
| `155240`   | `400`     | `Invalid token standard for transfer.`                                                                                                                                     | Correct the token standard, and try again.                                                                                                                                                                                                                                                                                                                                                                   |
| `155241`   | `400`     | `Invalid token decimal for transfer.`                                                                                                                                      | Correct the token decimal, and try again.                                                                                                                                                                                                                                                                                                                                                                    |
| `155242`   | `400`     | `The lengths of amounts and nft tokens don't match.`                                                                                                                       | The lengths of amounts and NFT tokens don't match.                                                                                                                                                                                                                                                                                                                                                           |
| `155243`   | `400`     | `Missing bytecode for contract deployment.`                                                                                                                                | Provide bytecode for contract deployment, and try again.                                                                                                                                                                                                                                                                                                                                                     |
| `155244`   | `400`     | `Cannot provide both WalletID and SourceAddress/Blockchain.`                                                                                                               | Specify WalletID or provide the SourceAddress/Blockchain, and try the request again.                                                                                                                                                                                                                                                                                                                         |
| `155245`   | `400`     | `Invalid amount in contract execution request.`                                                                                                                            | Invalid amount in contract execution request. Error raised when parsing amount in the request.                                                                                                                                                                                                                                                                                                               |
| `155247`   | `400`     | `Cannot provide both CallData and AbiFunctionSignature/AbiParameters.`                                                                                                     | Specify CallData or provide AbiFunctionSignature/AbiParameters, and try the request again.                                                                                                                                                                                                                                                                                                                   |
| `155264`   | `400`     | `Wait for pending transactions to be included on the blockchain before submitting new requests. EVM chains restrict the number of queued transactions per sender address.` | Wait, as you have reached the maximum number of pending transactions per sender address for the corresponding chain. You can check the status of your transactions using the GET /transactions endpoint. To expedite processing, consider using multiple wallets to distribute your transactions. (see [Transaction Limits and Optimizations](/wallets/transaction-limits-and-optimizations) for more tips.) |

### Wallet errors

| Error code | HTTP code | Error message                                                                                                        | Description                                                                                                                                                                                                         |
| ---------- | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `155501`   | `409`     | `Frozen wallets can not be updated or interact with, only query.`                                                    | Frozen wallets cannot be updated or interacted with. You can only query this wallet.                                                                                                                                |
| `155502`   | `403`     | `Max amount of wallets (tentative 1M) reached under 1 wallet set.`                                                   | 1M maximum amount of wallets has been reached under 1 wallet set.                                                                                                                                                   |
| `155503`   | `400`     | `Metadata array length needs to match wallet count in create developer wallets request.`                             | The metadata array length must match the wallet count in the POST /developer/wallets request.                                                                                                                       |
| `155504`   | `400`     | `Metadata array length needs to match number of blockchains in create user wallets request.`                         | The metadata array length must match the number of blockchains in the create user wallet request.                                                                                                                   |
| `155505`   | `400`     | `SCA wallet needs to wait for first-time transaction to be queued before processing more transactions.`              | SCA wallet needs to wait for first-time transactions to be queued before processing more transactions.                                                                                                              |
| `155506`   | `400`     | `SCA wallet config is invalid.`                                                                                      | SCA wallet config is invalid.                                                                                                                                                                                       |
| `155507`   | `400`     | `SCA account is not supported on the given blockchain.`                                                              | The SCA account type is not supported on the given chain. See [supported blockchains](/wallets/supported-blockchains) for more details.                                                                             |
| `155509`   | `400`     | `Entity needs to setup paymaster policy on Mainnet before SCA account creation. Please check paymaster policy setup` | The paymaster policies for your account need to be properly configured. Go to the web3 console and ensure you have a policy configured for the blockchain and do not have multiple policies for a given blockchain. |
| `155510`   | `400`     | `The operation is not supported on the blockchain you specify.`                                                      | The provided wallet is associated with a blockchain that does not support the requested API operation. Ensure you are using a compatible wallet and refer to the documentation for a list of supported operations.  |
| `155511`   | `400`     | `Blockchain is not supported for wallet creation.`                                                                   | The specified blockchain is not supported for wallet creation. See the list of [supported blockchains](/wallets/supported-blockchains).                                                                             |
| `155512`   | `404`     | `The owner of the SCA wallet can not be found.`                                                                      | The SCA wallet owner cannot be found. Check if ownership was transferred or if the account is set up correctly.                                                                                                     |
| `155515`   | `400`     | `The provided wallet account type is not supported by this API.`                                                     | The specified wallet account type is not supported by this API. See [account types](/wallets/account-types) for a list of supported types.                                                                          |

### Wallet set errors

| Error code | HTTP code | Error message                                         | Description                                                                                   |
| ---------- | --------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `155601`   | `400`     | `Failed to retrieve wallet set which already exists.` | Cannot create a new wallet set because it already exists. Try again with a unique wallet set. |

### SDK UI errors

| Error code | HTTP code | Error message                                                                                                                                                                            | Description                                                                                                                                                                               |
| ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `155701`   | `N/A`     | `User canceled`                                                                                                                                                                          | The user canceled or exited the execute UI.                                                                                                                                               |
| `155702`   | `N/A`     | `<Launch UI failed reason>`                                                                                                                                                              | Check the error message to see the exact UI launch failure reason.                                                                                                                        |
| `155703`   | `N/A`     | `The code you entered is not the same as the first one`                                                                                                                                  | The code you entered is not the same as the first one.                                                                                                                                    |
| `155704`   | `N/A`     | `Your PIN can't have repeating or consecutive numbers`                                                                                                                                   | Your PIN can't have repeating or consecutive numbers. Try again with a valid PIN.                                                                                                         |
| `155705`   | `N/A`     | `Your hint can't be the same as the answer`                                                                                                                                              | Your hint can't be the same as the answer. Try again with a valid hint.                                                                                                                   |
| `155706`   | `N/A`     | `Network error`                                                                                                                                                                          | Network error. Try again.                                                                                                                                                                 |
| `155707`   | `N/A`     | `Failed to encrypt data`                                                                                                                                                                 | Failed to encrypt data. Try again.                                                                                                                                                        |
| `155708`   | `N/A`     | `"Biometrics instead of PIN" is disabled`                                                                                                                                                | Enable the "Biometrics instead of PIN" SDK API.                                                                                                                                           |
| `155709`   | `N/A`     | `The device system doesn't support biometrics`                                                                                                                                           | Cannot enable biometrics in this device. The user must use the PIN code.                                                                                                                  |
| `155710`   | `N/A`     | `Failed to decrypt biometrics key`                                                                                                                                                       | Ask the user to reset the biometrics settings.                                                                                                                                            |
| `155711`   | `N/A`     | `The user has not enabled biometrics yet`                                                                                                                                                | The user skipped the biometrics setting.                                                                                                                                                  |
| `155712`   | `N/A`     | `The user refused to enable biometrics`                                                                                                                                                  | Must call the SetBiometricsPin SDK API so the user can enable biometrics.                                                                                                                 |
| `155713`   | `N/A`     | `Too many requests. Try again later`                                                                                                                                                     | Wait for 30 minutes, and try again.                                                                                                                                                       |
| `155714`   | `N/A`     | `Too many requests. The biometrics sensor on the device is locked`                                                                                                                       | Go to the device system settings to unlock.                                                                                                                                               |
| `155715`   | `N/A`     | `The user didn't enable biometrics`                                                                                                                                                      | The user can be prompted to go to the App Settings to re-allow the app to use biometrics. (Warning) This operation will cause the app to be relaunched.                                   |
| `155716`   | `N/A`     | `Unexpected error for biometrics`                                                                                                                                                        | Unexpected error. Try again.                                                                                                                                                              |
| `155717`   | `N/A`     | `User secret is missing. Check the input parameters.`                                                                                                                                    | The user secret is missing from the request. Ensure the input parameters are correct and retry the operation.                                                                             |
| `155718`   | `N/A`     | `User token format is invalid`                                                                                                                                                           | User token format is invalid. Ensure the format of the user token is correct, then perform login and execute the challenge again.                                                         |
| `155719`   | `N/A`     | `User token and SDK API execute function do not match. Please ensure that executeWithUserSecret is for users with SSO/Email auth method, and execute is for users with PIN auth method.` | User token and SDK API execute function do not match. Ensure that `executeWithUserSecret` is for users with SSO/email auth method, and <br />`execute` is for users with PIN auth method. |
| `155720`   | `N/A`     | `Social login failed`                                                                                                                                                                    | Social login failed. The social provider returns failed during the execution of social login flow. Refer to the error message for more details.                                           |
| `155721`   | `N/A`     | `Login info is missing`                                                                                                                                                                  | Login info is missing. Perform login and execute the challenge again.                                                                                                                     |

### Sign transaction errors

| Error code | HTTP code | Error message                                    | Description                                                             |
| ---------- | --------- | ------------------------------------------------ | ----------------------------------------------------------------------- |
| `155801`   | `400`     | `Transaction or rawTransaction is invalid.`      | Invalid transaction or `rawTransaction` in request.                     |
| `155802`   | `400`     | `Account not found.`                             | Cannot find account in the transaction header.                          |
| `155803`   | `400`     | `Not signer account.`                            | Account is not the signer of this transaction.                          |
| `155804`   | `400`     | `Transaction is already signed.`                 | Transaction is already signed.                                          |
| `155805`   | `400`     | `Transaction failed to deserialize.`             | Transaction failed to de-serialize.                                     |
| `155806`   | `400`     | `The transaction size exceeds blockchain limit.` | The transaction size exceeds blockchain limit.                          |
| `155807`   | `400`     | `The chain ID is not supported for signing.`     | The typed data or transaction chain ID is not supported for EVM signing |
| `155808`   | `400`     | `The chain ID is missing in sign request.`       | The chain ID is missing from typed data or transaction for EVM signing. |

### Common errors

| Error code | HTTP code | Error message                                                                                                                        | Description                                                                                                                                                                                          |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `156001`   | `404`     | `Cannot find target wallet in the system. Either the specified wallet doesn't exist or it's not accessible to the caller.`           | The specified wallet does not exist, or is not visible to the caller. Try the request again with a valid wallet ID.                                                                                  |
| `156002`   | `404`     | `Cannot find target token in the system. Either the specified token doesn't exist or it's not accessible to the caller.`             | The specified token does not exist, or is not visible to the caller. Try the request again with a valid token ID.                                                                                    |
| `156003`   | `404`     | `Cannot find target transaction in the system. Either the specified transaction doesn't exist or it's not accessible to the caller.` | The specified transaction does not exist, or is not visible to the caller. Try the request again with a valid transaction ID.                                                                        |
| `156004`   | `400`     | `Reusing an entity secret ciphertext is not allowed. Please re-encrypt the entity secret to generate new ciphertext.`                | Reusing an entity secret ciphertext is not allowed. Re-encrypt the entity secret to generate a new ciphertext and try again.                                                                         |
| `156005`   | `404`     | `Cannot find target wallet set in the system. Either no such wallet set, or it's not accessible to the caller.`                      | The specified wallet set does not exist, or is not visible to the caller. Try the request again with a valid wallet set.                                                                             |
| `156006`   | `400`     | `TEST_API key cannot be used with blockchain mainnets, or LIVE_API key cannot be used with blockchain testnets.`                     | A TEST\_API key cannot be used with blockchain Mainnets, and a LIVE\_API key cannot be used with blockchain Testnets. Try again with a valid API key.                                                |
| `156007`   | `401`     | `TEST_API key or LIVE_API key is not found for the request.`                                                                         | A TEST\_API key or LIVE\_API key is not found for the request. Try again with a valid API key.                                                                                                       |
| `156008`   | `400`     | `Cannot find target entity config in the system. Either no such entity config, or it's not accessible to the caller.`                | The specified entity config does not exist, or is not visible to the caller. Try the request again with a valid entity config.                                                                       |
| `156009`   | `400`     | `Fail to parse id as UUID in url.`                                                                                                   | The specified id is invalid (must be in UUID format). Try again with a valid id.                                                                                                                     |
| `156010`   | `404`     | `Cannot find the corresponding entity in the system.`                                                                                | The specified entity does not exist, or is not configured. Try again with a valid entity.                                                                                                            |
| `156011`   | `404`     | `Cannot find target nftTokenId in the system.`                                                                                       | The nftTokenId does not exist. Try again with a valid nftTokenId.                                                                                                                                    |
| `156012`   | `404`     | `Cannot find corresponding pagination cursor in the system.`                                                                         | The pagination parameters are invalid. Correct your pagination parameters, and try again.                                                                                                            |
| `156013`   | `400`     | `The provided entity secret is invalid.`                                                                                             | The specified entity secret is not valid. Create or re-encrypt your entity secret, and try again.                                                                                                    |
| `156014`   | `400`     | `Pagination params are invalid. Only UUID format is supported for pageBefore and pageAfter.`                                         | Pagination parameters are invalid. Only UUID format is supported for `pageBefore` and `pageAfter`.                                                                                                   |
| `156015`   | `409`     | `The secret for this entity has already been set.`                                                                                   | The secret for this entity has already been set.                                                                                                                                                     |
| `156016`   | `403`     | `The entity secret has not been set yet. Please provide encrypted ciphertext in the console.`                                        | The entity secret has not been set yet. Provide encrypted ciphertext in the Developer console.                                                                                                       |
| `156017`   | `400`     | `The specified blockchain parameters are incorrect.`                                                                                 | The blockchain parameters are invalid. Correct the blockchain parameters, and try again.                                                                                                             |
| `156018`   | `403`     | `The uploaded recovery file is invalid.`                                                                                             | The uploaded recovery file is invalid. Try again with a valid recovery file.                                                                                                                         |
| `156019`   | `403`     | `Current entity secret is invalid. Please rotate the entity secret first.`                                                           | The current entity secret is invalid. Rotate the entity secret first in the Developer console, and try again.                                                                                        |
| `156020`   | `403`     | `Please use a new idempotency key.`                                                                                                  | Use a new idempotency key, and try again.                                                                                                                                                            |
| `156021`   | `409`     | `A new wallet set ID is required.`                                                                                                   | Use a new wallet set ID, and try again.                                                                                                                                                              |
| `156023`   | `409`     | `EncodedByHex is true in sign request, but the message is not hex encoded.`                                                          | The `encodedByHex` parameter is set to `true`, but the provided message is not in the correct hex-encoded format. Ensure the message is hex-encoded and try again, or set `encodedByHex` to `false`. |
| `156024`   | `400`     | `Data is not a valid JSON string in sign request.`                                                                                   | Data is not a valid JSON string in the Sign request. Provide a valid JSON format typed data string.                                                                                                  |
| `156025`   | `400`     | `Invalid message in request.`                                                                                                        | Sign message is invalid. Try the request again with a valid EIP-191 message.                                                                                                                         |
| `156026`   | `400`     | `Invalid typed data in request.`                                                                                                     | Typed data is invalid. Try the request again with a valid EIP-712 typed data.                                                                                                                        |
| `156027`   | `400`     | `The specified blockchain is either not supported or deprecated.`                                                                    | Try again with a supported blockchain. See the guide [Supported blockchains](/wallets/supported-blockchains#supported-blockchains) for the complete list of supported blockchains.                   |
| `156030`   | `400`     | `Invalid unsigned delegate action in request.`                                                                                       | Invalid unsigned delegate action in request.                                                                                                                                                         |


# Gas Fees
Source: https://developers.circle.com/wallets/gas-fees



Gas fees are the costs associated with initiating a transaction on a given
blockchain, allowing network validators to perform the requested function.

Gas fees can fluctuate due to network congestion, the type of transaction you
request, and the priority placed on your request. You can accelerate a
transaction by paying additional gas fees.

Each blockchain has its own native asset required to pay these fees. When
interacting with the blockchain, you'll need to account for the amount of this
native asset required for the requested transaction.

You can estimate transaction fees and contract execution with Circle's Wallets
API.

<Accordion title="Video Tutorial: Estimating Gas Fees for Transactions">
  Watch this video to learn about gas fees, also known as transaction fees. In
  the video, you will learn the importance of gas fees, understand how to
  estimate fees for a transfer transaction using an API and send USDC to other
  wallets using the estimates.

  <iframe title="Video Tutorial: Estimating Gas Fees for Transactions" />
</Accordion>

## Wallets gas fee configurations

When initiating a request via the Wallets APIs that requires gas fees, you have
two options for configuring your fee tolerance: **fee levels** and **gas
limits**.

**Fee levels** provide a simple way to configure your gas tolerance. Depending
on your choice, the speed in which your transaction completes compared to the
expected [blockchain confirmation](/wallets/blockchain-confirmations) timing may
vary.

You can choose between three tolerance levels:

1. `low` - a low-priority transaction, expected to take longer than the average
   amount of time to complete, with lower fees
2. `medium` - a medium-priority transaction, expected to take the average amount
   of time to complete, with average fees
3. `high` - a high-priority transaction, expected to take less than the average
   amount of time to complete, with higher fees

**Gas limits** allow for a more advanced configuration of your gas tolerance.
Setting gas limit requires the following parameters, which are all designated in
wei:

1. `gasLimit` - the base amount of gas required to process the requested
   transaction
2. `priorityFee` - an additional “tip” that can be added to the validator to
   accelerate the requested transaction
3. `maxFee` - maximum fee that can be used for the requested transaction, if the
   fee is greater, the transaction will be failed. Note that Solana has no
   concept of a max fee.

## Differences in gas fee specification

While EVM chains and Solana support fee levels, you can also assign your own gas
fee. The process differs based on the blockchain and protocols supported.

## EVM chains

When
[creating a transfer transaction](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-transfer),
you must specify `gasLimit`, `maxFee`, and `priorityFee`. Your actual fee will
be *(base fee + priority fee) \* gas used* . Note that you do not need to
specify the base fee in your transaction because it is automatically determined
and adjusted by the network based on its current congestion level.

<Note>`priorityFee` is not applicable to Arbitrum and can be left blank.</Note>

* **Base fee**: Fee set by the network based on congestion levels. It is burned
  with a transaction, which means it is removed from circulation.
* **Priority fee**: Additional fee paid to miners that expedites your
  transaction.
* **Max fee**: Maximum price you're willing to pay per unit of gas for the
  transaction. This protects against paying excessive prices when the base fee
  rises unexpectedly.

## Solana

The gas fee mechanism is similar to EIP-1559, where you can specify the
`priority fee` to incentivize miners to include your transaction in a block.
However, there's no max fee concept in Solana, and the `gasLimit` is optional as
Solana defaults to a gas limit of 200,000 micro-lamport (10<sup>-15</sup> SOL).

## Native token price for gas fee estimates

The following table shows the estimated gas fees on various blockchains, using a
trailing six-month average, and includes the date when the data was last
updated.

| Blockchain  | Price of Native Token (USD) | As of Date |
| ----------- | --------------------------- | ---------- |
| Aptos       | \$4.35                      | Sep 2024   |
| Arbitrum    | \$3,046                     | Sep 2024   |
| Avalanche   | \$28                        | Jul 2025   |
| Base        | \$3,046                     | Sep 2024   |
| Ethereum    | \$3,046                     | Sep 2024   |
| Optimism    | \$3,046                     | Sep 2024   |
| Polygon PoS | \$0.54                      | Sep 2024   |
| Solana      | \$151                       | Sep 2024   |
| Unichain    | \$3,046                     | Sep 2024   |

### Smart Contract Account (SCA) wallets

SCA wallet creation is unique to EVMs and has a gas cost in deploying the smart
contract account. Circle uses lazy deployment at the time of the first outbound
transaction, so there is no gas cost in creation and deposits.

The following table shows the estimated total gas fees in native tokens and USD
for wallet deployment and fungible token transfers on various blockchains for
SCA wallets.

| Blockchain  | Deploy Fee (native)  | Deploy Fee (USD) | Transfer Fee (native) | Transfer Fee (USD) |
| ----------- | -------------------- | ---------------- | --------------------- | ------------------ |
| Arbitrum    | 0.0000034            | \$0.010          | 0.0000021             | \$0.006            |
| Arc Testnet | 0.003381             | \$0.003381       | 0.00771808            | \$0.00771808       |
| Avalanche   | 0.00324355           | \$0.0518968      | 0.00191335            | \$0.0306136        |
| Base        | 0.000000040589440509 | \$0.00012363543  | 0.000000014010345339  | \$0.00004267551    |
| Ethereum    | 0.0020745            | \$6.319          | 0.0012237             | \$3.727            |
| Monad       | 0.134501994          | -                | 0.0597872715          | -                  |
| Optimism    | 0.000000040624052029 | \$0.00012374086  | 0.000000012263512376  | \$0.00003735465    |
| Polygon PoS | 0.0372023            | \$0.020          | 0.0219454             | \$0.012            |
| Unichain    | 0.0000001            | \$0.0004         | 0.00000003            | \$0.00009          |

### Externally Owned Account (EOA) wallets

Creating an EOA wallet is free. However, both Solana and Aptos charge a one-time
fee when receiving a non-native token for the first time. On Solana, the fee is
used to create an associated token account (ATA) and can be recovered by closing
the account. On Aptos, the fee is used to store the token on the recipient's
account and is not recoverable.

The following table shows the estimated total gas fees in native tokens and USD
for account creation and fungible token transfers on various blockchains that
support EOA wallets.

| Blockchain | Wallet Deployment Fee (native tokens) | Wallet Deployment Fee (USD) | Token Transfer Total Fee (native tokens) | Token Transfer Total Fee (USD) |
| ---------- | ------------------------------------- | --------------------------- | ---------------------------------------- | ------------------------------ |
| Aptos      | 0.0004916                             | \$0.00213846                | 0.0005324\*                              | \$0.00231594\*                 |
| Arbitrum   | 0.0000034                             | \$0.010                     | 0.0000021                                | \$0.006                        |
| Avalanche  | 0.0122877                             | \$0.344                     | 0.0072485                                | \$0.203                        |
| Base       | 0.000000040589440509                  | \$0.00012363543             | 0.000000014010345339                     | \$0.00004267551                |
| Ethereum   | 0.0020745                             | \$6.319                     | 0.0012237                                | \$3.727                        |
| Monad      | 0.0842586                             | -                           | 0.00482246                               | -                              |
| Optimism   | 0.000000040624052029                  | \$0.00012374086             | 0.000000012263512376                     | \$0.00003735465                |
| Polygon    | 0.0372023                             | \$0.020                     | 0.0219454                                | \$0.012                        |
| Solana     | 0.0020910                             | \$0.316                     | 0.0000388                                | \$0.0059                       |
| Unichain   | 0.0000001                             | \$0.0004                    | 0.00000003                               | \$0.00009                      |

<Note>
  **Aptos** charges an additional storage creation fee when transferring a
  fungible token to an address for the first time. The approximate total gas fees
  are:

  * First transfer to a new address: **0.0005324 APT** (\~\$0.00232 USD)
  * Subsequent transfers to the same address: **0.0000002 APT** (\~\$0.00000087
    USD)
</Note>


# Gas Station
Source: https://developers.circle.com/wallets/gas-station



Gas Station enables developers to build experiences that abstract gas - both for
end-users and developers. Developers can sponsor network fees for the end-user,
removing the need for end-users to hold native tokens in their wallets. The
sponsored gas fees are charged to the developer's credit card; hence, not having
them to hold native tokens across chains. This abstracts gas fees: one of the
biggest problems of building blockchain apps.

## Problem with gas fees

Blockchains require gas transaction fees to incentivize validators and protect
networks against denial of service attacks. The mechanics for these fees have
traditionally been built into the blockchain itself, often requiring gas fees to
be paid in native tokens and sourced by the address that initiated the
transaction.

The experience of sourcing native tokens by the originating wallet makes it hard
for users to interact onchain and limits the usability of blockchain
applications. Depending on the blockchain, there can be different ways to
abstract gas. For example:

1. On EVM chains: With the introduction of
   [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) (account abstraction),
   there is a way to pay network fees in non-native tokens via smart contracts
   called paymasters
2. On Solana: By using the concept of fee-payers, third party wallets can pay
   for gas on behalf of a user.

## Circle's Gas Station solution

Circle's Gas Station utilizes paymasters (on EVM) and fee-payers (on Solana) to
create a solution that completely abstracts gas. Circle has deployed paymaster
smart contracts and fee-payer wallets that developers can use with Circle
Wallets.

The solution has the following components:

1. **Gas Sponsor:** A third party smart contract or wallet that pays on-chain
   gas fees according to the sponsorship conditions.
   1. Paymaster (EVM): Smart contract (ERC-4337 standard)
   2. Fee-Payer (Solana): Wallets that pay gas fees
2. **Policy:** Let developers set up custom rules and limits on the blockchains
   they want to sponsor.
3. **Billing:** Let developers pay all the gas fees using their preferred
   payment modes (cards).

On EVM chains, the Programmable Wallet must be an ERC-4337-compliant smart
contract account. Developers can create these wallets by passing
`"accountType": "SCA"` in the create wallet API for Wallets.

To learn more on creating a SCA wallet follow one of the two guides:

1. [Create your first developer-controlled wallets](/wallets/dev-controlled/create-your-first-wallet).
2. [Create your first user-controlled wallet](/wallets/user-controlled/react-native-sdk-ui-customization-api).

On Solana, Gas Station can
[sponsor](/wallets/gas-station/solana-ata-sponsorship) the rent deposit for
ATAs, or you can
[create and fund an ATA yourself](/wallets/gas-station/create-solana-ata).

## Supported blockchains

Circle Gas Stations support the following blockchains:

| Blockchain Network       | PW User-Controlled | PW Developer Controlled |
| :----------------------- | :----------------- | :---------------------- |
| Aptos Mainnet            | ✅                  | ✅                       |
| Aptos Testnet            | ✅                  | ✅                       |
| Arbitrum Mainnet         | ✅                  | ✅                       |
| Arbitrum Sepolia Testnet | ✅                  | ✅                       |
| Arc Testnet              | ✅                  | ✅                       |
| Avalanche Mainnet        | ✅                  | ✅                       |
| Avalanche Fuji Testnet   | ✅                  | ✅                       |
| Base Mainnet             | ✅                  | ✅                       |
| Base Sepolia Testnet     | ✅                  | ✅                       |
| Ethereum Mainnet         | ✅                  | ✅                       |
| Ethereum Sepolia Testnet | ✅                  | ✅                       |
| Monad Mainnet            | ✅                  | ✅                       |
| Monad Testnet            | ✅                  | ✅                       |
| Optimism Mainnet         | ✅                  | ✅                       |
| Optimism Sepolia Testnet | ✅                  | ✅                       |
| Polygon Mainnet          | ✅                  | ✅                       |
| Polygon Amoy Testnet     | ✅                  | ✅                       |
| Solana Mainnet           | ✅                  | ✅                       |
| Solana Devnet            | ✅                  | ✅                       |
| Unichain Mainnet         | ✅                  | ✅                       |
| Unichain Sepolia Testnet | ✅                  | ✅                       |

## Related products

Gas Station allows you to sponsor network fees for your users. If you want to
allow users to pay their network fees with USDC themselves, see the
[Circle Paymaster](/paymaster).

### Comparison with Circle Paymaster

| Category               | Circle Paymaster                                                                                    | Gas Station                                                                      |
| ---------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Description**        | A permissionless smart contract that allows users to pay gas fees in USDC instead of native tokens. | A feature of Wallets that allows developers to sponsor gas fees for their users. |
| **Circle account**     | Not required                                                                                        | Required                                                                         |
| **Compatible wallets** | Any ERC-4337-compliant wallet                                                                       | Circle Wallets                                                                   |
| **Gas fees paid in**   | USDC                                                                                                | Fiat currency via credit card                                                    |
| **Pricing model**      | 10% of the gas fee                                                                                  | 5% of the gas fee                                                                |
| **Paid by**            | End user                                                                                            | Developer                                                                        |


# Billing for Sponsored Gas Fees
Source: https://developers.circle.com/wallets/gas-station/billing



To ensure a smooth and transparent billing reimbursement process, please note
the following details regarding bill payments for gas fee sponsorships made
through Gas Station:

1. **Reimbursement and Invoicing:** As the policyholder, you are responsible for
   reimbursing Circle for all the gas fee sponsorships made on your behalf.
   Invoices will be generated and sent to you, including applicable local taxes
   and a 5% processing fee.
2. **Period and Frequency:** Bills are charged at the earliest occurrence of two
   events:\
   The 1st of each calendar month: On this date, the gas fee sponsorships are
   made on your behalf will be consolidated into a bill for that specific
   billing period.
3. **Accumulation of \$100 worth of gas fees:** If the cumulative value of your
   gas fee sponsorships reaches or exceeds \$100 before the 1st of the month, a
   bill will be generated at that point.
4. **Payment Terms:** Invoices must be settled within seven days of being issued
   or up to \$20 in additional Gas Station charges. It is essential to adhere to
   these payment terms to ensure uninterrupted gas fee sponsorship and the
   continued functionality of Gas Station.
5. **Consequences of Unpaid Bills:** Failure to pay a bill within seven days
   after it is invoiced or upon accumulating an additional \$20 in Gas Station
   charges will result in the pausing of all gas station policies. When the
   policy is paused, Gas Station will cease to sponsor any Mainnet transactions.
   Therefore, it is crucial to keep a valid credit card on file and promptly
   settle any outstanding bills to avoid service disruptions.

<Note>
  If these limits do not meet your needs, please contact our sales team or
  Account Executive you are working with.
</Note>

<Warning>
  Please be vigilant in managing your bill payments and maintaining a valid
  credit card account to avoid any interruptions in gas fee sponsorship and the
  smooth operation of your Gas Station policy.
</Warning>


# Gas Station Contract Addresses
Source: https://developers.circle.com/wallets/gas-station/contract-addresses



## EVM chains

Built with ERC-4337 compatible smart contracts, Gas Station for Circle Wallets
allows developers to sponsor network fees for SCA wallet users. If a transaction
meets the policies you set, Gas Station calls these contracts to cover the
network fee.

The following are the smart contract addresses that power Gas Station on EVM
blockchains:

| Blockchain | Network         | Blockchain Address                                                                                                                         |
| :--------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum   | Mainnet         | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://arbiscan.io/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)                     |
| Arbitrum   | Sepolia Testnet | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://sepolia.arbiscan.io/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)             |
| Arc        | Testnet         | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://testnet.arcscan.app/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)             |
| Avalanche  | Mainnet         | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://snowtrace.io/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)                    |
| Avalanche  | Fuji Testnet    | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://testnet.snowtrace.io/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)            |
| Base       | Mainnet         | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://basescan.org/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)                    |
| Base       | Sepolia Testnet | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://base-sepolia.blockscout.com/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)     |
| Ethereum   | Mainnet         | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://etherscan.io/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)                    |
| Ethereum   | Sepolia Testnet | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://sepolia.etherscan.io/address/0x7cea357b5ac0639f89f9e378a1f03aa5005c0a25)            |
| Monad      | Monad Mainnet   | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://monadvision.com/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)                 |
| Monad      | Monad Testnet   | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://testnet.monadexplorer.com/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)       |
| Optimism   | Mainnet         | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://optimistic.etherscan.io/address/0x7cea357b5ac0639f89f9e378a1f03aa5005c0a25)         |
| Optimism   | Sepolia Testnet | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://sepolia-optimism.etherscan.io/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)   |
| Polygon    | Mainnet         | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://polygonscan.com/address/0x7cea357b5ac0639f89f9e378a1f03aa5005c0a25)                 |
| Polygon    | Amoy Testnet    | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://amoy.polygonscan.com/address/0x7cea357b5ac0639f89f9e378a1f03aa5005c0a25)            |
| Unichain   | Mainnet         | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://uniscan.xyz/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25)                     |
| Unichain   | Sepolia Testnet | [`0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25`](https://unichain-sepolia.blockscout.com/address/0x7ceA357B5AC0639F89F9e378a1f03Aa5005C0a25) |

## Non-EVM chains

| Blockchain | Network | Blockchain Address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Solana     | Mainnet | • [`9kHTT3RgH51FhMzKjxk8XXHoNnVjEjK5JnwTVSP8rXTy`](https://solscan.io/account/9kHTT3RgH51FhMzKjxk8XXHoNnVjEjK5JnwTVSP8rXTy?cluster=mainnet) <br /> • [`HcSvhXR7yNdNmnz8QjWbo9EnWm9zB4nfX6MoJAXfEdBa`](https://solscan.io/account/HcSvhXR7yNdNmnz8QjWbo9EnWm9zB4nfX6MoJAXfEdBa?cluster=mainnet) <br /> • [`6nvUkyJG5j6rH3Hfm15mJNgPMJ1cxHQapfm5K3k647iv`](https://solscan.io/account/6nvUkyJG5j6rH3Hfm15mJNgPMJ1cxHQapfm5K3k647iv?cluster=mainnet) <br /> • [`FU8KibWzoNfnsytAfc3fRG8AZMMB4hS7Pfx9NyNSXt1D`](https://solscan.io/account/FU8KibWzoNfnsytAfc3fRG8AZMMB4hS7Pfx9NyNSXt1D?cluster=mainnet) <br /> • [`HCcQZ3UPYR1XQSzMvLUH8yVuZKaxi5J5n7mHkccMW7D9`](https://solscan.io/account/HCcQZ3UPYR1XQSzMvLUH8yVuZKaxi5J5n7mHkccMW7D9?cluster=mainnet)                                                                                                                                                                                                                                                                                         |
| Solana     | Devnet  | • [`99TfgApJDd6WSpVq5wBhbwqieoFYs4buzv8p9Uv5monw`](https://solscan.io/account/99TfgApJDd6WSpVq5wBhbwqieoFYs4buzv8p9Uv5monw?cluster=devnet) <br /> • [`8XejFT3EpdFfxgPimne75us4wdnctSznu9Jvx3wLhJkd`](https://solscan.io/account/8XejFT3EpdFfxgPimne75us4wdnctSznu9Jvx3wLhJkd?cluster=devnet) <br /> • [`BS5QyQcsFbrep8mNrCh5DtnTaihB2C2HUZEW8UJbY2xM`](https://solscan.io/account/BS5QyQcsFbrep8mNrCh5DtnTaihB2C2HUZEW8UJbY2xM?cluster=devnet) <br /> • [`2AMHVbmq5oz8zUibEw3KSPR8btJKqB1jbp1azepprt7E`](https://solscan.io/account/2AMHVbmq5oz8zUibEw3KSPR8btJKqB1jbp1azepprt7E?cluster=devnet) <br /> • [`PKWh66GhWw5HQW2dDo9LvbuNd6b4EbJ49NmCi1Dsu3A`](https://solscan.io/account/PKWh66GhWw5HQW2dDo9LvbuNd6b4EbJ49NmCi1Dsu3A?cluster=devnet)                                                                                                                                                                                                                                                                                                |
| Aptos      | Mainnet | • [`0xea9434b70c638db3a8175dd9b4db66e1b6ad03b9e4de01a67488b4a2e93b23cd`](https://explorer.aptoslabs.com/account/0xea9434b70c638db3a8175dd9b4db66e1b6ad03b9e4de01a67488b4a2e93b23cd?network=mainnet) <br /> • [`0x1e3c8ad3abedab489849b3c294ec3ab1755279d2c6ec7ae3c1955dc1e07769d6`](https://explorer.aptoslabs.com/account/0x1e3c8ad3abedab489849b3c294ec3ab1755279d2c6ec7ae3c1955dc1e07769d6?network=mainnet) <br /> • [`0x1e0b80ef6e26a3440a87f26aec0975ae7aec27c65dd6c8622bda7c9f2dc74c6e`](https://explorer.aptoslabs.com/account/0x1e0b80ef6e26a3440a87f26aec0975ae7aec27c65dd6c8622bda7c9f2dc74c6e?network=mainnet) <br /> • [`0x4548236f98f7ceb227b452dee8e5ff1f6db2ac48d54b22ce7ae2eafa88ec26a1`](https://explorer.aptoslabs.com/account/0x4548236f98f7ceb227b452dee8e5ff1f6db2ac48d54b22ce7ae2eafa88ec26a1?network=mainnet) <br /> • [`0x0b18439154c6a7007343b0198eca7aef1874f537589ad47d16b74ee3a27fe882`](https://explorer.aptoslabs.com/account/0x0b18439154c6a7007343b0198eca7aef1874f537589ad47d16b74ee3a27fe882?network=mainnet) |
| Aptos      | Testnet | • [`0xc00c6f9cd50104a09190209ad4edd371453fe6f6294d0af306c94eae74ed7fe5`](https://explorer.aptoslabs.com/account/0xc00c6f9cd50104a09190209ad4edd371453fe6f6294d0af306c94eae74ed7fe5?network=testnet) <br /> • [`0x8bed386d4a4a950ad486e277c43cbd273b5304b3dfa12b0b00f6dad555578d18`](https://explorer.aptoslabs.com/account/0x8bed386d4a4a950ad486e277c43cbd273b5304b3dfa12b0b00f6dad555578d18?network=testnet) <br /> • [`0xbb97626c7968b94a6a53c972891f1ee342364e1dcc32118c14c60b0d74629d5a`](https://explorer.aptoslabs.com/account/0xbb97626c7968b94a6a53c972891f1ee342364e1dcc32118c14c60b0d74629d5a?network=testnet) <br /> • [`0x7fc660c2b729b1f4c7464a865f3819f01e4ad1cfa4f1fe774598f6dc2fc97e69`](https://explorer.aptoslabs.com/account/0x7fc660c2b729b1f4c7464a865f3819f01e4ad1cfa4f1fe774598f6dc2fc97e69?network=testnet) <br /> • [`0x5e3517733659e3a8a544aa81605a5c687df879b6fb5f0b34594b3635f59edbf3`](https://explorer.aptoslabs.com/account/0x5e3517733659e3a8a544aa81605a5c687df879b6fb5f0b34594b3635f59edbf3?network=testnet) |

<Note>
  **Solana**

  Gas Station on Solana is powered by fee-payers: programs that cover network fees
  for users on your behalf. If a transaction meets the policies you set, Gas
  Station calls the fee payer to sponsor the network fee of the transaction. Gas
  Station is available on both mainnet and devnet.
</Note>


# Quickstart: Create and Fund a Solana Associated Token Account (ATA)
Source: https://developers.circle.com/wallets/gas-station/create-solana-ata

Create a Solana ATA for an owner wallet and pay the creation rent from a payer wallet

On Solana, SPL token transfers require the recipient to have an Associated Token
Account (ATA) for that token. Gas Station does not pay for ATA creation unless
you use [Solana ATA sponsorship](/wallets/gas-station/solana-ata-sponsorship).
Without sponsorship, you must create the ATA and pay its rent before a transfer
can succeed.

This quickstart walks you through a server-side script that creates a USDC ATA.
A payer wallet pays the one-time SOL rent, and an owner wallet owns the ATA and
receives USDC.

<Note>
  All transactions in this guide take place on Solana Devnet. No real funds are
  required beyond testnet SOL for rent and fees. You can adapt the code for
  mainnet by setting `CLUSTER` to `'mainnet-beta'` and using mainnet USDC mint
  addresses.
</Note>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v18+](https://nodejs.org/).
* Created a payer wallet and obtained its keypair (private key).
* Funded the payer wallet with at least \~0.00204 SOL on Solana Devnet to cover
  ATA rent-exempt minimum and transaction fees:
  * Use the [Solana faucet](https://faucet.solana.com/) to obtain testnet SOL.
* Obtained the owner wallet's public key (base58 address). The owner can be a
  wallet you create or any recipient's address.

## Step 1: Set up the project

This step sets up your project environment and installs the required
dependencies.

### 1.1. Create a new project

Create a new directory and initialize a new Node.js project with default
settings:

```shell Shell theme={null}
mkdir create-usdc-ata-solana
cd create-usdc-ata-solana
npm init -y
npm pkg set type=module
```

### 1.2. Install dependencies

Install the required dependencies for Solana and SPL token interactions, and set
the start script to run the TypeScript file with `tsx`:

```shell Shell theme={null}
npm install @solana/web3.js @solana/spl-token tsx
npm pkg set scripts.start="npx tsx --env-file=.env index.ts"
npm install --save-dev typescript @types/node
```

### 1.3. Configure TypeScript (optional)

<Tip>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Tip>

Create a `tsconfig.json` file:

```shell theme={null}
npx tsc --init
```

Then, update the `tsconfig.json` file:

```shell theme={null}
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF
```

### 1.4. Configure environment variables

Create a `.env` file with `PAYER_PRIVATE_KEY` (payer keypair as a JSON array)
and `OWNER_PUBLIC_KEY` (base58 address of the wallet that will own the ATA):

```shell Shell theme={null}
echo "PAYER_PRIVATE_KEY=[1,2,3,...]" > .env
echo "OWNER_PUBLIC_KEY=YourOwnerBase58Address" >> .env
```

<Warning>
  This example uses one or more private keys for local testing. In production,
  use a secure key management solution and never expose or share private keys.
</Warning>

The `PAYER_PRIVATE_KEY` should be a JSON array of bytes representing your
private key. You can export this from most Solana wallets.

<Accordion title="Converting Base58 private key to JSON array">
  Some wallets export Solana private keys as Base58 encoded strings. If you have a
  Base58 encoded private key, install `bs58`, save the following code as
  `convert-key.ts`, and run it with `tsx` to convert it to a JSON array:

  ```shell Shell theme={null}
  npm install bs58
  npx tsx convert-key.ts
  ```

  ```typescript TypeScript theme={null}
  import bs58 from "bs58";

  const privateKeyBase58: string = "YOUR_BASE58_PRIVATE_KEY";

  try {
    // Decode the Base58 string to a Uint8Array
    const privateKeyBytes: Uint8Array = bs58.decode(privateKeyBase58);

    // Convert the Uint8Array to a JSON array string
    const privateKeyJsonString: string = JSON.stringify(
      Array.from(privateKeyBytes),
    );

    console.log("JSON Array:", privateKeyJsonString);
  } catch (error) {
    console.error(
      "Error converting key. Check if the Base58 key is valid.",
      error,
    );
  }
  ```
</Accordion>

## Step 2: Create the script

This step creates the complete script. It adds imports and configuration,
implements ATA creation, and runs the script.

### 2.1. Import dependencies

Create an `index.ts` file:

```shell Shell theme={null}
touch index.ts
```

Then, add the imports and configuration constants:

```typescript index.ts theme={null}
import {
  Connection,
  Keypair,
  PublicKey,
  Transaction,
  sendAndConfirmTransaction,
  clusterApiUrl,
} from "@solana/web3.js";
import {
  createAssociatedTokenAccountIdempotentInstruction,
  getAssociatedTokenAddressSync,
} from "@solana/spl-token";

const CLUSTER: "mainnet-beta" | "devnet" = "devnet";

const USDC_MINT = {
  "mainnet-beta": new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),
  devnet: new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"),
} as const;
```

### 2.2. Add the ATA creation logic

Add the following code to `index.ts`. This code defines the `createUSDCata`
function and the main function.

<Accordion icon="circle-info" title="How this script works">
  The `createUSDCata` function:

  * Derives the ATA address.
  * Builds the idempotent ATA instruction.
  * Sends the transaction.

  The `main` function:

  * Loads the payer keypair and owner address from `.env`.
  * Initializes the Solana connection.
  * Calls `createUSDCata`.
  * Prints the final ATA address.

  The payer covers the ATA rent-exempt amount and transaction fees.
</Accordion>

```typescript index.ts theme={null}
async function createUSDCata(
  connection: Connection,
  payer: Keypair,
  owner: PublicKey,
): Promise<string> {
  // Select the correct USDC mint for the configured cluster.
  const mint = USDC_MINT[CLUSTER];

  // Derive the owner's Associated Token Account (ATA) for USDC.
  const ata = getAssociatedTokenAddressSync(mint, owner);

  // Create an idempotent ATA instruction.
  // If the ATA already exists, this instruction is a no-op.
  const ix = createAssociatedTokenAccountIdempotentInstruction(
    payer.publicKey,
    ata,
    owner,
    mint,
  );

  // Build and send the transaction. The payer signs and pays ATA rent plus fees.
  const tx = new Transaction().add(ix);
  await sendAndConfirmTransaction(connection, tx, [payer], {
    commitment: "confirmed",
  });

  // Print the ATA and a Solana Explorer link for verification.
  console.log("ATA created:", ata.toBase58());
  const explorerCluster =
    CLUSTER === "mainnet-beta" ? "" : `?cluster=${CLUSTER}`;
  console.log(
    `Explorer: https://explorer.solana.com/address/${ata.toBase58()}${explorerCluster}`,
  );

  return ata.toBase58();
}

async function main(): Promise<void> {
  const payerRaw = process.env.PAYER_PRIVATE_KEY;
  const ownerRaw = process.env.OWNER_PUBLIC_KEY;

  // Validate required environment variables.
  if (!payerRaw || !ownerRaw) {
    throw new Error(
      "Set PAYER_PRIVATE_KEY and OWNER_PUBLIC_KEY in .env (see Step 1.4)",
    );
  }

  // Parse keys and create an RPC connection.
  const payer = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(payerRaw)));
  const owner = new PublicKey(ownerRaw);
  const connection = new Connection(clusterApiUrl(CLUSTER), "confirmed");

  // Create the ATA and print the final address.
  const ataAddress = await createUSDCata(connection, payer, owner);
  console.log("Ready to receive USDC at:", ataAddress);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});
```

### 2.3. Run the script

Run the script with the following command:

```shell Shell theme={null}
npm start
```

You should see output similar to:

```text theme={null}
ATA created: DC85yuMEnGDTLpubqUC53BgmMeMjVvoqQyqopekUXffz
Explorer: https://explorer.solana.com/address/DC85yuMEnGDTLpubqUC53BgmMeMjVvoqQyqopekUXffz?cluster=devnet
Ready to receive USDC at: DC85yuMEnGDTLpubqUC53BgmMeMjVvoqQyqopekUXffz
```

Open the Solana Explorer link to verify the ATA onchain. Run the script again to
confirm idempotent behavior: the transaction still succeeds and the ATA address
is unchanged.


# Policy Management
Source: https://developers.circle.com/wallets/gas-station/policy-management



A policy is your configuration on a blockchain network for using Circle's Gas
Station. You must set up a policy to use the Gas Station on mainnet. Here, you
configure what you are willing to sponsor on behalf of your users. Circle's Gas
Station pays the fees if a transaction meets your configuration.

## Policy Setup for Gas Station on mainnets

To activate a mainnet policy, follow these steps:

1. **Access the Sponsorship Policy page:** Using your credentials, log in to the
   developer console. Toggle to mainnet \[top left corner]. From there, navigate
   to the Gas Station section, which allows you to manage your gas fee
   sponsorship policies efficiently.
2. **Choose to create or select a policy:** If you don't have a mainnet policy
   yet, select the option to create a new policy. Alternatively, choose the
   desired policy from the available list if you already have an existing one.
3. **Configure policy settings:** Set the desired configurations for your policy
   based on your specific needs. Refer to the list of configurations provided
   below for clarity on available options.

<Note>
  > **Tip:**: Make sure your limits are set high enough to cover your expected >
  > user transactions. Otherwise, transactions that exceed your policy are not >
  > sponsored and may fail.
</Note>

4. **Update or create the policy:** After applying the necessary configurations,
   choose either the **Update** or **Create** button at the bottom of the page.
   Select **Update** to modify an existing policy, and select **Create\*** to
   create a new policy.
5. **Activate the policy:** After confirming your chosen policy configurations,
   click the **Activate** button. This final step enables the selected policy
   and initiates gas fee sponsorship according to the specified settings.

<Check>
  **Gas Station auto-sponsors after Policy is set**

  When you create a policy on a chain, Circle sponsors gas fees for all accounts
  that meet your configuration. You don't need to pass the policy ID in each
  transaction request.
</Check>

## Policy configurations

A policy consists of the following configurations:

1. **Policy Name:** Provide a descriptive name for the policy to identify it in
   the policy list. The policy name displays only in the console.
2. **Network:** Refers to the specific blockchain network where the Gas Station
   covers gas fees. Each policy supports only one blockchain network, ensuring
   clarity and ease of management.
3. **Default Policy:** The policy sponsors gas fees for any transaction on a
   specific network, including wallet creation and contract execution. You can
   set only one default policy per network. Circle recommends designating this
   as the first policy for the specified network.

<Note>
  > **Note**: Transactions use only default policies. If you want to use a >
  > non-default policy, update it to default and activate it.
</Note>

4. **Maximum spend per day\* (optional):** Specify the maximum allowance for gas
   fees in USD that you are willing to sponsor within a 24-hour period. This
   restriction provides control over the allocated budget for gas fee
   sponsorship.
5. **Maximum spend per transaction\* (optional):** The maximum allowance for gas
   fees in USD that you are willing to sponsor for a single transaction.

<Note>
  **Note**: Maximum spend per transaction limit does not apply to the first
  transaction made from any Smart Contract Account (SCA) wallet. This includes
  SCA-type wallets as well as Console Wallets.
</Note>

<Note>
  This first transaction limit check does not lock the nonce of the wallet, so
  in some cases it is possible that multiple calls with high network fees bypass
  the check.
</Note>

6. **Maximum operations per day\* (optional):** The maximum number of supported
   operations (such as transactions) per day.
7. **Blocked addresses (optional):** A configurable list of blockchain addresses
   that should not receive sponsored gas fees. This feature allows you to
   exclude specific addresses from benefiting from gas fee coverage.

*\*Daily limits reset once every 24 hours at 0:00 UTC.*

By leveraging these configurations within a policy, you can fine-tune the gas
fee sponsorship parameters to your specific requirements and financial
considerations. Note that any limits left blank are not applied.

<Warning>
  **Transactions Outside Your Policy**

  If a transaction exceeds your configured policy limits, such as maximum spend
  per transaction, maximum spend per day, or maximum operations per day, **the
  transaction is not sponsored** by Circle's Gas Station. In this case, the
  transaction fails unless the sender provides their own gas.

  If your policy settings are missing, misconfigured, or too restrictive, user
  transactions may fail. Review your policy carefully and monitor transaction
  activity to avoid unexpected failures.
</Warning>

## Deactivating a Gas Station policy on mainnets

If you need to deactivate the mainnet policy at any given time, it can be done
conveniently from the developer console. To deactivate the mainnet policy,
follow these simple steps:

1. **Select the mainnet policy:** Access the console and locate the intended
   mainnet policy that you wish to deactivate. This can be found in the policy
   management section.
2. **Click the deactivate option:** Once you have identified the mainnet policy,
   click the **Deactivate** button in the console interface's top right corner.
   This action triggers the deactivation process.
3. **Confirm the deactivation:** A pop-up modal appears after clicking the
   deactivate option. Select the deactivate button within the modal to confirm
   deactivation of the policy.

<Warning>
  **Warning:** Deactivating a policy stops all mainnet transaction sponsorships
  and end-users wallet transactions are rejected for sponsorship.
</Warning>

Following these steps, you can easily deactivate the mainnet policy, granting
you control and flexibility over the gas fee sponsorship within your
application.

## Policy Setup for Gas Station on testnets

When it comes to using Gas Station on testnets, the setup process is
hassle-free. Circle takes care of the initial configuration by automatically
generating a default policy upon signing up for an account. This default policy
is designed for developers leveraging Wallets during the testing phase. With
this default policy in place, you can seamlessly sponsor testnet tokens while
building your applications.

It's important to note the gas fee sponsorship limits applicable for different
testnets:

| Testnet          | Sponsored Token | Daily Limit |
| ---------------- | --------------- | ----------- |
| Aptos Testnet    | `APT`           | 10          |
| Arbitrum Sepolia | `ETH`           | 50          |
| Arc Testnet      | `USDC`          | 50          |
| Avalanche Fuji   | `AVAX`          | 50          |
| Base Sepolia     | `ETH`           | 50          |
| Ethereum Sepolia | `ETH`           | 50          |
| Monad Testnet    | `MON`           | 50          |
| Optimism Sepolia | `ETH`           | 50          |
| Polygon Amoy     | `MATIC`         | 50          |
| Solana Devnet    | `SOL`           | 2           |
| Unichain Sepolia | `ETH`           | 50          |

## View gas sponsored transactions

Circle provides a dashboard to monitor and analyze these gas sponsorship
transactions.

### Using the Developer Dashboard

To view gas-sponsored transactions in testnet or mainnet:

1. **Access the Gas Station policy page:** log in to the developer console using
   your credentials. From there, navigate to the Gas Station Policy section,
   which allows you to manage your gas fee sponsorship policies efficiently.
2. **Select a policy:** Choose the specific policy you want to review from the
   available list on the policy page.

**View sponsored transactions table:** There is a table on the policy page that
lists transactions that have been sponsored. You can apply filters to refine the
view, enabling you to focus on specific transactions.


# Send a Gasless Transaction
Source: https://developers.circle.com/wallets/gas-station/send-a-gasless-transaction



This step-by-step guide lays out the process for sending gasless transactions
from your wallet on <Tooltip>Testnet</Tooltip>. Gasless transactions are no
different than any other Programmable Wallet transaction. As long as a
<Tooltip>Gas Station policy</Tooltip> is configured, and you use a supported
wallet, <Tooltip>gas fees</Tooltip> will be sponsored automatically.

<Note>
  For **Testnet**, a preconfigured policy is already in place. Therefore, you
  are not required to create a Gas Station policy for this quickstart guide.
</Note>

Before you begin, it's important to understand which blockchains support gasless
transactions and the wallet types supported on each.

* The following **EVM chains** support smart contract accounts (SCAs) for
  gasless transactions:
  * **Arbitrum**: Mainnet, Sepolia testnet
  * **Arc**: Testnet
  * **Avalanche**: Mainnet, Fuji testnet
  * **Base**: Mainnet, Sepolia testnet
  * **Ethereum**: Mainnet, Sepolia testnet
  * **Monad**: Mainnet, Testnet
  * **Optimism**: Mainnet, Sepolia testnet
  * **Polygon**: Mainnet, Amoy testnet
  * **Unichain**: Mainnet, Sepolia testnet

* **Aptos** supports externally owned accounts (EOAs)

* **Solana** supports externally owned accounts (EOAs)

To learn more, see [Gas Station overview](/wallets/gas-station).

## 1. Create a Wallet

To create a wallet, follow our comprehensive quickstart guide on
[creating your first developer-controlled wallet](/wallets/dev-controlled/create-your-first-wallet).
Remember, you must create an SCA wallet for EVM chains to perform gasless
transactions while you must create an EOA wallet on Solana. Once the wallet is
successfully created, note down the wallet's address from step 3.

Alternatively, if you prefer to use user-controlled wallets, follow the
[Create Your First Wallet](/wallets/user-controlled/react-native-sdk-ui-customization-api)
guide.

## 2. Fund the Wallet

Next, you will fund your wallet with a token to provide an asset for conducting
transactions. In this guide, we will transfer USDC into the wallet using the
[USDC faucet](https://faucet.circle.com/). While on the
<Tooltip>faucet</Tooltip>, provide your wallet's address to complete the
process.

Alternatively, if you prefer to deposit a native token, you can visit the
[ETH](https://www.alchemy.com/faucets/ethereum-sepolia) or
[MATIC](https://faucet.polygon.technology/) faucets.

## 3. Send a Transfer

Follow the instructions in the quick start guide
[Transfer Tokens from Wallet to Wallet](/wallets/dev-controlled/transfer-tokens-across-wallets).
This guide will walk you through sending a transaction without requiring gas.
Once completed, you can head to the
[developer dashboard policies page](https://console.circle.com/gas-station/policies)
and view the sponsored transaction within the respective policy.

For those using user-controlled wallets, follow the
[Send an Outbound Transfer](/wallets/user-controlled/send-outbound-transfer)
instead.

***

Congratulations on successfully sending a gasless transaction! With Circle
taking care of the complexities, you can fully concentrate on providing a
delightful user experience without the hassle of intricate setup.

To expand your knowledge and explore further, please visit the following
resources:

1. [**Gas Station Overview:**](/wallets/gas-station) Get familiar with Gas
   Station, its functions, and how it can be used in your app.
2. [**Policy Management:**](/wallets/gas-station/policy-management) Understand
   how to manage Gas Station policies effectively and view gas-sponsored
   transactions.
3. [**Billing for Sponsored Gas Fees:**](/wallets/gas-station/billing)
   Understand how you will be billed for sponsored gas fees.
4. [**Paymaster & Fee-Payer:**](/wallets/gas-station/contract-addresses) Dive
   deeper into the concept of Paymaster and its role in gasless transactions.

By leveraging these resources, you can enhance your understanding and maximize
the potential of gasless transactions. Stay tuned for exciting updates and
features as we strive to streamline the gasless transaction experience.


# Solana ATA Sponsorship
Source: https://developers.circle.com/wallets/gas-station/solana-ata-sponsorship



<Note>
  Solana ATA sponsorship is a permissioned feature. Contact your [Circle
  representative](mailto:customer-support@circle.com) to request access.
</Note>

Solana transfers require an
[Associated Token Account (ATA)](https://solana.com/docs/tokens#associated-token-account)
for every token a wallet holds. Gas Station pays the rent deposit required to
create those ATAs so you don't have to fund the creation fees. Without
sponsorship, you must
[create and fund an ATA yourself](/wallets/gas-station/create-solana-ata).

## Protect against abuse

<Danger>
  If Circle detects ATA abuse, Circle will suspend your account and charge you for
  the sponsored spend tied to that abuse.
</Danger>

You are responsible for detecting abuse scenarios such as users repeatedly
closing ATAs to reclaim rent deposits. You should monitor sponsored transactions
and set [policies](/wallets/gas-station/policy-management) that match your risk
tolerance.


# Key Management
Source: https://developers.circle.com/wallets/key-management

How Circle Wallets secures keys with MPC and passkeys across developer-controlled, user-controlled, and modular wallets.

Circle Wallets secures keys differently depending on the
[wallet product you choose](/wallets/account-types). Developer-controlled and
user-controlled wallets use
[multi-party computation (MPC)](#multi-party-computation-mpc). Modular wallets
use [passkeys](#passkeys).

The following table summarizes how keys are secured for each wallet type.

| Wallet type              | Key type | Who controls                                | Where keys live                                 |
| ------------------------ | -------- | ------------------------------------------- | ----------------------------------------------- |
| **Developer-controlled** | MPC      | You, using the entity secret                | Circle-hosted MPC nodes, or self-hosted         |
| **User-controlled**      | MPC      | Your user, using their key shard credential | Circle-hosted MPC nodes                         |
| **Modular**              | Passkey  | Your user                                   | Your user's device (with optional cloud backup) |

## Multi-party computation (MPC)

MPC splits the private key into shards held by separate parties, so no single
party ever holds the complete key. This means a compromised server or stolen
credential alone cannot leak the full key.

### Developer-controlled wallets

Developer-controlled wallets use 2-of-2 MPC. You can let Circle host both nodes,
share hosting with Circle, or host both nodes yourself.

<Tip>
  Circle offers a key backup and recovery tool.
  [Contact Circle](https://help.circle.com/s/submit-ticket?language=en_US) to
  learn more about this tool, or to set up shared or self-hosted node hosting.
</Tip>

* **Circle hosts both nodes (default):** Signing is protected by an
  [entity secret](/wallets/dev-controlled/entity-secret-management#entity-secret-ciphertext)
  that you create and store on your server. The entity secret is required to
  create wallets and sign transactions. This option is ideal for getting started
  with minimum setup effort.

* **Shared node hosting:** You and Circle each host one MPC node. Circle
  provides a keyguard service that you host on your servers to authorize signing
  before every transaction. This splits private key management across two
  parties on different servers.

* **You host both nodes:** You host both MPC nodes with the keyguard service
  authorizing signing for every transaction. This setup may be required in
  certain regulatory jurisdictions.

The following diagram shows how signing is split across two servers in shared
node hosting.

```mermaid theme={null}
flowchart TB
  subgraph circle["Circle"]
    direction TB
    cw["Circle Wallets"]
    kms["Key management service (KMS)"]
    node1["Circle MPC node"]
    cw --> kms
    kms -->|"Circle's key share"| node1
  end

  subgraph you["You"]
    direction TB
    server["Your server"]
    verify["Your verification logic"]
    kg["Circle keyguard service"]
    node2["Your MPC node"]
    server -.->|"Transaction details"| verify
    kg -.->|"Transaction details"| verify
    verify -->|"Approval"| kg
    kg -->|"Your key share"| node2
  end

  server -->|"API request to create a transaction"| cw
  node1 <-->|"Message queue"| node2
```

### User-controlled wallets

Circle uses 2-of-2 MPC for user-controlled wallets and hosts both nodes. Only
your users can sign after they
[authenticate](/wallets/user-controlled/authentication-methods) with social
login, email + OTP, or PIN.

**Backup and recovery:** If your users forget their PIN, they can recover
account access by answering security questions. See
[Recover an account](/wallets/user-controlled/recover-account).

## Passkeys

Modular wallets use passkeys as signers. Passkeys live in the secure enclave (a
dedicated security chip on the user's device), so only your users can sign
transactions.

**Backup and recovery:** Your users can back up their passkeys using the FIDO2
backup standard supported by iCloud, Google Drive, and password managers like
1Password.


# Modular Wallets
Source: https://developers.circle.com/wallets/modular

Understand how modular wallets work, when to use them, and how Circle enables passkey-based smart accounts with gasless transactions, batch execution, and optional modules.

Modular wallets are user-controlled smart accounts built on
[Modular Smart Contract Accounts (MSCA)](/wallets/account-types#modular-smart-contract-accounts-msca).
Users sign with
<Tooltip>passkeys</Tooltip>
, and you integrate via Circle SDKs for web, iOS, and Android. You can sponsor
gas, run batch or parallel transactions, and extend behavior with modules. For a
comparison of all wallet products, see
[Choose your wallet product and account types](/wallets/account-types).

## Key features

<CardGroup>
  <Card title="User retains custody" icon="key">
    Users control their keys via passkeys (WebAuthn). Keys stay on the user's
    device; your app never holds them. Optional
    [recovery](/wallets/modular/recover-passkey) lets users restore access with
    a recovery key.
  </Card>

  <Card title="Gasless transactions" icon="gas-pump">
    Use [Gas Station](/wallets/gas-station) to sponsor network fees so users
    don't need native tokens. Set paymaster policies in the Circle Console and
    pass `paymaster: true` when sending user operations.
  </Card>

  <Card title="Batch and parallel execution" icon="layer-group">
    Send multiple operations in one user op for better UX and efficiency. Use 2D
    nonces to run independent transactions in parallel. See [Modular Wallet
    Operations](/wallets/modular/key-features) for details.
  </Card>

  <Card title="Modules and SDKs" icon="cube">
    Extend accounts with [modules](/wallets/modular/modules) (for example
    allowlists, automation). Build with the [Web](/wallets/modular/web-sdk),
    [iOS](/wallets/modular/ios-sdk), or [Android](/wallets/modular/android-sdk)
    SDK.
  </Card>
</CardGroup>

## What you can build

Use modular wallets when you want user-owned keys with a simple onboarding flow.
Common use cases:

<AccordionGroup>
  <Accordion title="Consumer apps with passkeys" icon="fingerprint">
    Onboard users with biometrics or device unlock, with no seed phrases or
    passwords. Users sign transactions from your app; you orchestrate flows with
    the modular wallets SDK and never hold keys.
  </Accordion>

  <Accordion title="Gasless and batch flows" icon="arrow-right-arrow-left">
    Sponsor gas so users don't need native tokens. Combine multiple actions (for
    example approve and transfer) in one user operation, or run independent
    operations in parallel with 2D nonces.
  </Accordion>

  <Accordion title="Programmability through modules" icon="puzzle-piece">
    Add [modules](/wallets/modular/modules) to smart accounts for allowlisted
    transfers or custom logic.
  </Accordion>

  <Accordion title="Third-party wallet connection" icon="link">
    Expose modular wallets as an EIP-1193 provider so other Web3 SDKs (for
    example Web3.js) can connect to Circle Smart Accounts. See [Modular Wallet
    Operations](/wallets/modular/key-features#use-the-eip-1193-provider) for the
    pattern.
  </Accordion>
</AccordionGroup>

## Get started

<CardGroup>
  <Card title="Passkey and Smart Account" icon="circle-info" href="/wallets/modular/passkey-and-smart-account">
    Understand passkey as signer and the Circle Smart Account flow before you
    run the quickstart.
  </Card>

  <Card title="Create a Modular Wallet" icon="wallet" href="/wallets/modular/create-a-wallet-and-send-gasless-txn">
    Set up the SDK, register with a passkey, create a smart account, and send a
    gasless user operation.
  </Card>
</CardGroup>


# Modular Wallets Android SDK
Source: https://developers.circle.com/wallets/modular/android-sdk



Welcome to Circle's modular wallets Android SDK documentation. The SDK enables
developers to integrate modular wallets to build secure, scalable Web3
applications by leveraging tools for key management, smart account interactions,
gasless transactions, and blockchain communication.

## Installation

Follow the steps provided in the
[GitHub repository](https://github.com/circlefin/modularwallets-android-sdk#installation)
to install and set up the modular wallets Android SDK.

<Note>
  **Java Developers:**

  If you're building with **Java**, review the integration notes provided in the
  [Calling Kotlin suspending functions from Java](#calling-kotlin-suspending-functions-from-java)
  section before proceeding.
</Note>

## API Documentation

The following sections detail the SDK's transport mechanisms, client
interactions, account management, utility functions, and supported blockchain
networks.

### Transports

#### Interface: HttpTransport

* Description: Interface representing a transport mechanism for making RPC
  requests.

##### Methods

###### request

* Description: Sends an RPC request and returns the response.
* Parameters:
  * req: RpcRequest - The RPC request to be sent.
  * Returns: Response\<RpcResponse>

#### Class: HttpRpcClientOptions

* Description: Data class representing HTTP RPC client options.
* Properties:
  * headers: Map\<String, String>? - Optional headers to include in the HTTP
    requests.

#### Function: toModularTransport

* Description: Creates a modular HTTP transport instance.
* Parameters:
  * context: Context - The application context.
  * clientKey: String - The client key for authorization.
  * url: String - The URL for the HTTP transport.
* Returns: HttpTransport - The configured HTTP transport instance.

#### Function: toPasskeyTransport

* Description: Creates an HTTP transport instance.
* Parameters:
  * context: Context - The application context.
  * clientKey: String - The client key for authorization.
  * url: String - The URL for the HTTP transport.
* Returns: HttpTransport - The configured HTTP transport instance.

#### Function: http

* Description: Creates an HTTP transport instance.
* Parameters:
  * context: Context - The application context.
  * url: String - The URL for the HTTP transport.
  * config: HttpRpcClientOptions - The configuration options for the HTTP
    transport (default is an empty configuration).
* Returns: HttpTransport - The configured HTTP transport instance.

### Clients

#### Class: Client

* Description: Represents a client that interacts with a blockchain, with the
  following derived classes:
  * BundlerClient
  * PaymasterClient
* Properties:
  * chain: Chain - The blockchain that the client interacts with.
  * transport: Transport - The transport mechanism used for making RPC requests.

#### Class: BundlerClient

* Description: Client for interacting with the Bundler API. A Bundler Client is
  an interface to interact with ERC-4337 Bundlers and provides the ability to
  send and retrieve User Operations through Bundler Actions.
* Inheritance: Inherits from Client

##### Methods

###### estimateUserOperationGas

* Description: Estimates the gas values for a User Operation to be executed
  successfully.
* Parameters:
  * account: SmartAccount - The Account to use for User Operation execution.
  * calls: Array\<EncodeCallDataArg> - The calls to execute in the User
    Operation.
  * paymaster: Paymaster? - Sets Paymaster configuration for the User Operation.
  * estimateFeesPerGas: (suspend (SmartAccount, BundlerClient, UserOperationV07)
    -> EstimateFeesPerGasResult)? - Prepares fee properties for the User
    Operation request. Not available in Java.
* Returns: EstimateUserOperationGasResult

###### getChainId

* Description: Returns the chain ID associated with the current network
* Returns: Long - The current chain ID.

###### getSupportedEntryPoints

* Description: Returns the EntryPoints that the bundler supports.
* Returns: ArrayList\<String> - The EntryPoints that the bundler supports.

###### getUserOperation

* Description: Retrieves information about a User Operation given a hash.
* Parameters:
  * userOpHash: String - User Operation hash.
* Returns: GetUserOperationResult - User Operation information.

###### getUserOperationReceipt

* Description: Returns the User Operation Receipt given a User Operation hash.
* Parameters:
  * userOpHash: String - User Operation hash.
* Returns: UserOperationReceipt - The User Operation receipt.

###### sendUserOperation

* Description: Broadcasts a User Operation to the Bundler.
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack
  * account: SmartAccount - The Account to use for User Operation execution.
  * calls: Array\<EncodeCallDataArg>? - The calls to execute in the User
    Operation
  * partialUserOp: UserOperationV07- (default: UserOperationV07()) The partial
    User Operation to be completed .
  * paymaster: Paymaster? - Sets Paymaster configuration for the User Operation.
  * estimateFeesPerGas: (suspend (SmartAccount, BundlerClient, UserOperationV07)
    -> EstimateFeesPerGasResult)? - Prepares fee properties for the User
    Operation request. Not available in Java.
* Returns: String - The hash of the sent User Operation.

###### prepareUserOperation

* Description: Prepares a User Operation for execution and fills in missing
  properties.
* Parameters:
  * account: SmartAccount - The Account to use for User Operation execution.
  * calls: Array\<EncodeCallDataArg>? - The calls to execute in the User
    Operation
  * partialUserOp: UserOperationV07 - The partial User Operation to be completed
  * paymaster: Paymaster? - Sets Paymaster configuration for the User Operation.
  * estimateFeesPerGas: (suspend (SmartAccount, BundlerClient, UserOperationV07)
    -> EstimateFeesPerGasResult)? - Prepares fee properties for the User
    Operation request. Not available in Java.
* Returns: UserOperationV07- The prepared User Operation.

###### waitForUserOperationReceipt

* Description: Waits for the User Operation to be included on a Block (one
  confirmation), and then returns the User Operation receipt.
* Parameters:
  * userOpHash: String - A User Operation hash.
  * pollingInterval: Long (default: 4000) - Polling frequency (in ms).
  * retryCount: Int (default: 6) - The number of times to retry.
  * timeout: Long? - Optional timeout (in ms) to wait before stopping polling.
* Returns: UserOperationReceipt - The User Operation receipt.

###### getBalance

* Description: Retrieves the balance of the specified address at a given block
  tag or block number.
* Overloaded Methods:
  * Parameters:
    * address: String - The address to query the balance for. Only wallet
      addresses that registered with the using client key can be retrieved
    * blockNumber: BigInteger - The balance of the account at a block number.
  * Returns: BigInteger - The balance of the address in wei.
  * Parameters:
    * address: String - The address to query the balance for. Only wallet
      addresses that registered with the using client key can be retrieved
    * blockTag: String (default: "latest") - The balance of the account at a
      block tag.
  * Returns: BigInteger - The balance of the address in wei.

###### getBlockNumber

* Description: Returns the number of the most recent block seen.
* Returns: BigInteger - The number of the block.

###### getGasPrice

* Description: Returns the current price of gas (in wei).
* Returns: BigInteger - The gas price (in wei).

###### call

* Description: Executes a new message call immediately without submitting a
  transaction to the network.
* Parameters:
  * from: String? - The Account to call from.
  * to: String - The contract address or recipient.
  * data: String - A contract hashed method call with encoded args.
* Returns: String - The call data.

###### getCode

* Description: Retrieves the bytecode at an address.
* Overloaded Methods:
  * Parameters:
    * address: String - The contract address.
    * blockNumber: BigInteger - The block number to perform the bytecode read
      against.
  * Returns: String - The contract's bytecode.
  * Parameters:
    * address: String - The contract address.
    * blockTag: String (default: "latest") - The block tag to perform the
      bytecode read against.
  * Returns: String - The contract's bytecode.

###### estimateMaxPriorityFeePerGas

* Description: Returns an estimate for the max priority fee per gas (in wei) for
  a transaction to be likely included in the next block. The Action will either
  call eth\_maxPriorityFeePerGas (if supported) or manually calculate the max
  priority fee per gas based on the current block base fee per gas + gas price.
* Returns: BigInteger - An estimate (in wei) for the max priority fee per gas.

###### getBlock

* Description: Returns information about a block at a block number, hash or tag.
* Overloaded Methods:
  * Parameters:
    * includeTransactions: Boolean (default: false) - Whether or not to include
      transactions (as a structured array of Transaction objects).
    * blockNumber: BigInteger - Information at a given block number.
  * Returns: Block - Information about the block.
  * Parameters:
    * includeTransactions: Boolean (default: false) - Whether or not to include
      transactions (as a structured array of Transaction objects).
    * blockTag: String (default: "latest") - Information at a given block tag.
  * Returns: Block - Information about the block.

#### Class: PaymasterClient

* Description: Client for interacting with the Paymaster API. A Paymaster Client
  is an interface to interact with
  [ERC-7677 compliant Paymasters](https://eips.ethereum.org/EIPS/eip-7677) and
  provides the ability to sponsor User Operation gas fees.
* Inheritance: Inherits from Client

##### Methods

###### getPaymasterData

* Description: Retrieves paymaster-related User Operation properties to be used
  for sending the User Operation.
* Parameters:
  * userOp: T - The User Operation to retrieve Paymaster data for. Type T must
    be the subclass of UserOperation.
  * entryPoint: EntryPoint - EntryPoint address to target.
  * context: Map\<String, Any>? - Paymaster specific fields.
* Returns: GetPaymasterDataResult - Paymaster-related User Operation properties.

###### getPaymasterStubData

* Description: Retrieves paymaster-related User Operation properties to be used
  for User Operation gas estimation.
* Parameters:
  * userOp: T - The User Operation to retrieve Paymaster stub data for. Type T
    must be the subclass of UserOperation.
  * entryPoint: EntryPoint - EntryPoint address to target.
  * context: Map\<String, Any>? - Paymaster specific fields.
* Returns: GetPaymasterStubDataResult - Paymaster-related User Operation
  properties.

### Accounts

#### Functions: toCircleSmartAccount

* Description: Create a Circle smart account.
* Parameters:
  * client: Client - The client used to interact with the blockchain.
  * owner: Account\<SignResult> - The owner account associated with the Circle
    smart account.
  * version: String (default: "circle\_passkey\_account\_v1") - The version of the
    Circle smart account.
  * name: String (default: `passkey-{timestamp}`, for example,
    `2025-01-01T00:00:00.000Z`) - The wallet name assigned to the newly
    registered account.
* Returns: CircleSmartAccount

#### Functions: toWebAuthnAccount

* Description: Creates a WebAuthn account.
* Parameters:
  * credential: WebAuthnCredential - The WebAuthn credential associated with the
    account.
* Returns: WebAuthnAccount - The created WebAuthn account.

#### Functions: toWebAuthnCredential

* Description: Logs in or registers a user and returns a WebAuthnCredential.
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack
  * transport: Transport - The transport used to communicate with the RP API.
  * userName: String? (required for WebAuthnMode.Register) - The username of the
    user.
  * mode: WebAuthnMode - The mode of the WebAuthn credential.
* Returns: WebAuthnCredential

#### Class: WebAuthnCredential

* Description: Represents a P-256 WebAuthn Credential.
* Properties:
  * id: String - The unique identifier for the credential.
  * publicKey: String - The public key associated with the credential.
  * raw: PublicKeyCredential - The public key associated with the credential.
  * rpId: String - The relying party identifier.

#### Abstract Class: Account\<T>

* Description: Abstract class representing an account.
* Type Parameter: T - The type of the signed data.

##### Methods

###### getAddress

* Description: Retrieves the address of the account.
* Returns: The address of the account.

###### sign

* Description: Signs the given hash.
* Parameters:
  * context: Context - The context in which the signing operation is performed.
  * messageHash: String - The hash to sign.
* Returns: The signed data of type T.

###### signMessage

* Description: Signs the given message.
* Parameters:
  * context: Context - The context in which the signing operation is performed.
  * message: String - The message to sign.
* Returns: The signed message of type T.

###### signTypedData

* Description: Signs the given typed data.
* Parameters:
  * context: Context - The context in which the signing operation is performed.
  * typedData: String - The typed data to sign.
* Returns: The signed typed data of type T.

#### Class: WebAuthnAccount

* Description: Represents a WebAuthn account for handling authentication
  credentials and signing. WebAuthn Accounts are commonly used as
  [Smart Account](https://viem.sh/account-abstraction/accounts/smart) Owners to
  sign User Operations and messages on behalf of the Smart Account.
* Inheritance: Inherits from Account.

##### Methods

###### getAddress

* Description: Retrieves the public key address associated with the WebAuthn
  credential.
* Returns: String - The public key associated with the WebAuthn credential.

###### sign

* Description: Signs the given hash.
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack
  * messageHash: String - The hash to sign.
* Returns: SignResult - The result of the signing operation.

###### signMessage

* Description: Signs the given message.
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack
  * message: String - The message to sign.
* Returns: SignResult - The result of the signing operation.

###### signTypedData

* Description: Signs the typed data.
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack
  * typedData: String - The typed data to sign.
* Returns: SignResult - The result of the signing operation.

#### Abstract Class: SmartAccount

* Description: A Smart Account is an account whose implementation resides in a
  Smart Contract, and implements the
  [ERC-4337 interface](https://eips.ethereum.org/EIPS/eip-4337#account-contract-interface).
* Properties:
  * client: Client - The client used to interact with the blockchain.
  * entryPoint: EntryPoint - The entry point for the smart account.
  * userOperation: UserOperationConfiguration? - Configuration for the user
    operation.

##### Methods

###### getAddress

* Description: Returns the address of the account.
* Returns: String - The address of the smart account.

###### encodeCalls

* Description: Encodes the given call data arguments.
* Parameters:
  * args: Array\<EncodeCallDataArg> - The call data arguments to encode.
* Returns: String - The encoded call data.

###### getFactoryArgs

* Description: Returns the factory arguments for the smart account.
* Returns: Pair\<String, String>? - A pair containing the factory address and
  factory data.

###### getNonce

* Description: Returns the nonce for the smart account.
* Parameters:
  * key: BigInteger? - Optional key to retrieve the nonce for.
* Returns: BigInteger - The nonce of the smart account.

###### getStubSignature

* Description: Returns the stub signature for the given user operation.
* Parameters:
  * userOp: T - The user operation to retrieve the stub signature for. Type T
    must be the subclass of UserOperation.
* Returns: String - The stub signature.

###### sign

* Description: Signs the given hash via the Smart Account's owner.
* Parameters:
  * context: Context - The context instance.
  * messageHash: String - The hash to sign.
* Returns: String - The signed string.

###### signMessage

* Description: Signs the given message.
* Parameters:
  * context: Context - The context in which the signing operation is performed.
  * message: String - The message to sign.
* Returns: String - The signed message.

###### signTypedData

* Description: Signs the given typed data.
* Parameters:
  * context: Context - The context in which the signing operation is performed.
  * typedData: String - The typed data to sign.
* Returns: String - The signed typed data.

###### signUserOperation

* Description: Signs the given user operation.
* Parameters:
  * context: Context - The context in which the signing operation is performed.
  * chainId: Long - The chain ID for the user operation. Default is the chain ID
    of the client.
  * userOp: UserOperationV07 - The user operation to sign.
* Returns: String - The signed user operation.

#### Class: CircleSmartAccount

* Description: Represents a Circle smart account.
* Properties:
  * client: Client - The client used to interact with the blockchain.
  * owner: Account\<SignResult> - The owner account associated with the Circle
    smart account.
  * entryPoint: EntryPoint - The entry point for the smart account.
  * userOperation: UserOperationConfiguration? - Configuration for the user
    operation.
* Inheritance: Inherits from SmartAccount.

##### Methods

###### getAddress

* Description: Returns the address of the Circle smart account.
* Returns: String - The address of the Circle smart account.

###### encodeCalls

* Description: Encodes the given call data arguments.
* Parameters:
  * args: Array\<EncodeCallDataArg> - The call data arguments to encode.
* Returns: String - The encoded call data.

###### getFactoryArgs

* Description: Returns the factory arguments if the account is not deployed.
* Returns: Pair\<String, String>? - The factory arguments or null if already
  deployed.

###### isDeployed

* Description: Checks if the account is deployed.
* Returns: Boolean - True if the account is deployed, false otherwise.

###### getNonce

* Description: Returns the nonce for the Circle smart account.
* Parameters:
  * key: BigInteger? - Optional key to retrieve the nonce for.
* Returns: BigInteger -The nonce of the Circle smart account.

###### getStubSignature

* Description: Returns the stub signature for the given user operation.
* Parameters:
  * userOp: T -The user operation to retrieve the stub signature for. Type T
    must be the subclass of UserOperation.
* Returns: String - The stub signature.

###### sign

* Description: Signs the given hash via the Smart Account's owner.
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack.
  * messageHash: String - The hash to sign.
* Returns: String - The signed string.

###### signMessage

* Description: Signs the given message using the
  [EIP-191 signed data standard](https://eips.ethereum.org/EIPS/eip-191).
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack.
  * message: String - The message to sign.
* Returns: String - The signed message.

###### signTypedData

* Description: Signs the given typed data.
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack.
  * typedData: String - The typed data to sign.
* Returns: String - The signed typed data.

###### signUserOperation

* Description: Signs the given user operation.
* Parameters:
  * context: Context - The context used to launch framework UI flows; use an
    activity context to make sure the UI is launched within the same task stack.
  * chainId: Long - The chain ID for the user operation. Default is the chain ID
    of the client.
  * userOp: UserOperationV07 - The user operation to sign.
* Returns: String - The signed user operation.

###### getInitCode

* Description: Returns the initialization code.
* Returns: String? - The initialization code.

### Utilities

#### Function: encodeTransfer

* Description: Encodes an ERC20 token transfer into calldata for executing a
  User Operation.
* Parameters:
  * to: String - The recipient address.
  * token: String - The token contract address or the name of Token enum.
    Supported tokens and their information are listed below.
  * amount: BigInteger - The amount to transfer.
* Returns: EncodeTransferResult - The encoded transfer ABI and contract address.
* Supported Tokens:

##### Mainnet USDC

| Blockchain Network | Enum            | Contract Address                                                                                                                    |
| ------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum           | Arbitrum\_USDC  | [`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`](https://arbiscan.io/token/0xaf88d065e77c8cc2239327c5edb3a432268e5831)                |
| Avalanche          | Avalanche\_USDC | [`0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`](https://snowtrace.io/token/0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E?chainid=43114) |
| Base               | Base\_USDC      | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913)               |
| Monad              | Monad\_USDC     | [`0x754704Bc059F8C67012fEd69BC8A327a5aafb603`](https://monadvision.com/token/0x754704Bc059F8C67012fEd69BC8A327a5aafb603)            |
| Optimism           | Optimism\_USDC  | [`0x0b2c639c533813f4aa9d7837caf62653d097ff85`](https://optimism.blockscout.com/address/0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85)  |
| Polygon            | Polygon\_USDC   | [`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`](https://polygonscan.com/token/0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359)            |
| Unichain           | Unichain\_USDC  | [`0x078D782b760474a361dDA0AF3839290b0EF57AD6`](https://unichain.blockscout.com/address/0x078D782b760474a361dDA0AF3839290b0EF57AD6)  |

##### Mainnet Native Tokens

| Blockchain Network | Token Name (Symbol) | Enum          | Contract Address                                                                                                                 |
| ------------------ | ------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum           | Arbitrum (ARB)      | Arbitrum\_ARB | [`0x912CE59144191C1204E64559FE8253a0e49E6548`](https://arbiscan.io/token/0x912ce59144191c1204e64559fe8253a0e49e6548)             |
| Optimism           | Optimism (OP)       | Optimism\_OP  | [`0x4200000000000000000000000000000000000042`](https://optimistic.etherscan.io/token/0x4200000000000000000000000000000000000042) |

##### Testnet USDC

| Blockchain Network | Enum                  | Contract Address                                                                                                                            |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum Sepolia   | ArbitrumSepolia\_USDC | [`0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d`](https://sepolia.arbiscan.io/token/0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d)                |
| Arc Testnet        | ArcTestnet\_USDC      | [`0x3600000000000000000000000000000000000000`](https://testnet.arcscan.app/address/0x3600000000000000000000000000000000000000)              |
| Avalanche Fuji     | AvalancheFuji\_USDC   | [`0x5425890298aed601595a70AB815c96711a31Bc65`](https://testnet.snowtrace.io/token/0x5425890298aed601595a70AB815c96711a31Bc65?chainid=43113) |
| Base Sepolia       | BaseSepolia\_USDC     | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://sepolia.basescan.org/token/0x036CbD53842c5426634e7929541eC2318f3dCF7e)               |
| Monad Testnet      | MonadTestnet\_USDC    | [`0x534b2f3A21130d7a60830c2Df862319e593943A3`](https://testnet.monadexplorer.com/token/0x534b2f3A21130d7a60830c2Df862319e593943A3)          |
| Optimism Sepolia   | OptimismSepolia\_USDC | [`0x5fd84259d66Cd46123540766Be93DFE6D43130D7`](https://optimism-sepolia.blockscout.com/address/0x5fd84259d66Cd46123540766Be93DFE6D43130D7)  |
| Polygon Amoy       | PolygonAmoy\_USDC     | [`0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582`](https://amoy.polygonscan.com/token/0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582)               |
| Unichain Sepolia   | UnichainSepolia\_USDC | [`0x31d0220469e10c4E71834a79b1f276d740d3768F`](https://unichain-sepolia.blockscout.com/address/0x31d0220469e10c4E71834a79b1f276d740d3768F)  |

#### Function: encodeFunctionData

* Description: Encodes the function name and parameters into an ABI encoded
  value (4 byte selector & arguments).
* Parameters:
  * functionName: String - The function to encode from the ABI.
  * abiJson: String - The ABI definition in JSON format.
  * args: Array\<Any> - The arguments for the function call.
* Returns: String - The encoded function call data.

#### Function: encodeContractExecution

* Description: Encodes a contract execution into calldata for executing a User
  Operation.
* Parameters:
  * to: String - The recipient address.
  * abiSignature: String - The ABI signature.
  * args: Array\<Any> - The arguments for the function call.
  * value: BigInteger - The value to send with the transaction.
* Returns: String - The encoded call data.

#### Function: parseEther

* Description: Converts a string representation of gwei to numerical wei.
* Properties:
  * value: String - The string representation of gwei.
  * unit: String - The unit of the value (default is "wei").
* Returns: BigInteger - The numerical value in wei.

#### Function: parseGwei

* Description: Converts a string representation of ether to numerical wei.
* Properties:
  * value: String - The string representation of ether.
  * unit: String - The unit of the value (default is "wei").
* Returns: BigInteger - The numerical value in wei.

#### Function: getMinimumVerificationGasLimit

* Description: Gets the minimum verification gas limit for a given chain.
* Properties:
  * deployed: Boolean - Whether the smart account is deployed.
  * chainId: Long - The chain ID.
* Returns: BigInteger - The chain-specific minimum verification gas limit or the
  default value if the chain is not supported.

### Models

#### Class: SignResult

* Description: Data class representing the result of a signing operation.
* Parameters:
  * signature: String - The signature generated by the signing operation.
  * webAuthn: WebAuthnData - The WebAuthn data associated with the signing
    operation.
  * raw: AuthenticationCredential - The raw authentication credential used in
    the signing operation.

#### Class: WebAuthnData

* Description: Data class representing WebAuthn data.
* Parameters:
  * authenticatorData: String - The authenticator data in hexadecimal format.
  * challengeIndex: Int - The index of the challenge in the client data JSON.
  * clientDataJSON: String - The client data JSON.
  * typeIndex: Int - The index of the type in the client data JSON.
  * userVerificationRequired: Boolean - Indicates whether user verification is
    required.

#### Class: EncodeCallDataArg

* Description: Data class representing arguments required for encoding call
  data.
* Properties:
  * to: String - The recipient address.
  * value: BigInteger? - The value to be sent with the transaction.
  * data: String? - The call data in hexadecimal format.
  * abiJson: String? - The ABI definition in JSON format.
  * args: Array\<Any>? - The arguments for the function call.
  * functionName: String? - The function name.

#### Class: EstimateUserOperationGasResult

* Description: Response model for estimating gas usage for user operations.
* Properties:
  * preVerificationGas: BigInteger? - Pre-verification gas limit.
  * verificationGasLimit: BigInteger? - Verification gas limit.
  * callGasLimit: BigInteger? - Call gas limit.
  * paymasterVerificationGasLimit: BigInteger? - Paymaster verification gas
    limit.
  * paymasterPostOpGasLimit: BigInteger? - Paymaster post-operation gas limit.

#### Class: EstimateFeesPerGasResult

* Description: Response model for estimating fees per gas.
* Properties:
  * maxFeePerGas: BigInteger? - Maximum fee per gas (EIP-1559).
  * maxPriorityFeePerGas: BigInteger? - Maximum priority fee per gas (EIP-1559).
  * gasPrice: BigInteger? - Legacy gas price.

#### Class: GetUserOperationResult

* Description: Response model for getting user operation details.
* Properties:
  * blockHash: String? - Block hash.
  * blockNumber: BigInteger? - Block number.
  * transactionHash: String? - Transaction hash.
  * entryPoint: String? - Entry point address.
  * userOperation: UserOperationRpc? - User operation details.

#### Class: UserOperationReceipt

* Description: Data class representing the receipt of a user operation.
* Properties:
  * actualGasCost: BigInteger? - Actual gas cost.
  * actualGasUsed: BigInteger? - Actual gas used.
  * entryPoint: String? - Entry point address.
  * logs: List\<Log>? - List of logs.
  * nonce: BigInteger? - Nonce.
  * paymaster: String? - Paymaster address.
  * reason: String? - Reason for failure (if any).
  * receipt: TransactionReceipt - Transaction receipt.
  * sender: String? - Sender address.
  * success: Boolean? - Success status.
  * userOpHash: String? - User operation hash.

#### Class: Log

* Description: Data class representing a log entry.
* Properties:
  * address: String? - Log address.
  * blockHash: String? - Block hash for the log.
  * blockNumber: BigInteger? - Block number for the log.
  * data: String? - Log data.
  * logIndex: BigInteger? - Log index.
  * transactionHash: String? - Transaction hash for the log.
  * transactionIndex: BigInteger? - Transaction index.
  * removed: Boolean? - Removed status.
  * topics: List\<String>? - List of topics.

#### Class: TransactionReceipt

* Description: Data class representing the receipt of a transaction.
* Properties:
  * blobGasPrice: BigInteger? - Blob gas price.
  * blobGasUsed: BigInteger? - Blob gas used.
  * blockHash: String? - Block hash.
  * blockNumber: BigInteger? - Block number.
  * contractAddress: String? - Contract address.
  * cumulativeGasUsed: BigInteger? - Cumulative gas used.
  * effectiveGasPrice: BigInteger? - Effective gas price.
  * from: String? - Sender address.
  * gasUsed: BigInteger? - Gas used.
  * logs: List\<Log>? - List of logs.
  * logsBloom: String? - Logs bloom.
  * root: String? - Root.
  * status: String? - Transaction status.
  * to: String? - Receiver address.
  * transactionHash: String? - Transaction hash.
  * transactionIndex: BigInteger? - Transaction index.
  * type: String? - Transaction type.

#### Class: GetPaymasterDataResult

* Description: Data class representing the result of getting paymaster data.
* Properties:
  * paymasterAndData: String? - Combined paymaster and data.
  * paymasterData: String? - Paymaster data.
  * paymaster: String? - Paymaster address.
  * paymasterPostOpGasLimit: BigInteger? - Gas limit for post-operation of
    paymaster.
  * paymasterVerificationGasLimit: BigInteger? - Gas limit for verification of
    paymaster.

#### Class: GetPaymasterStubDataResult

* Description: Data class representing the result of getting paymaster stub
  data.
* Properties:
  * paymasterAndData: String? - Combined paymaster and data.
  * paymaster: String? - Paymaster address.
  * paymasterData: String? - Paymaster data.
  * paymasterPostOpGasLimit: BigInteger? - Gas limit for post-operation of
    paymaster.
  * paymasterVerificationGasLimit: BigInteger? - Gas limit for verification of
    paymaster.
  * isFinal: Boolean? - Indicates if the data is final.
  * sponsor: Sponsor? - Sponsor information.

#### Class: Block

* Description: Data class representing a block.
* Properties:
  * baseFeePerGas: BigInteger? - Base fee per gas.
  * blobGasUsed: BigInteger? - Total used blob gas by all transactions in this
    block.
  * difficulty: BigInteger? - Difficulty for this block.
  * excessBlobGas: BigInteger? - Excess blob gas.
  * extraData: String? - "Extra data" field of this block.
  * gasLimit: BigInteger? - Maximum gas allowed in this block.
  * gasUsed: BigInteger? - Total used gas by all transactions in this block.
  * hash: String? - Block hash or null if pending.
  * logsBloom: String? - Logs bloom filter or null if pending.
  * miner: String? - Address that received this block's mining rewards.
  * mixHash: String? - Unique identifier for the block.
  * nonce: String? - Proof-of-work hash or null if pending.
  * number: BigInteger? - Block number or null if pending.
  * parentBeaconBlockRoot: String? - Root of the parent beacon chain block.
  * parentHash: String? - Parent block hash.
  * receiptsRoot: String? - Root of this block's receipts trie.
  * sealFields: List\<String>? - List of seal fields.
  * sha3Uncles: String? - SHA3 of the uncles data in this block.
  * size: BigInteger? - Size of this block in bytes.
  * stateRoot: String? - Root of this block's final state trie.
  * timestamp: BigInteger? - Unix timestamp of when this block was collated.
  * totalDifficulty: BigInteger? - Total difficulty of the chain until this
    block.
  * transactions: Array\<String>? - List of transaction objects or hashes.
  * transactionsRoot: String? - Root of this block's transaction trie.
  * uncles: Array\<String>? - List of uncle hashes.
  * withdrawals: Array\<Withdrawal>? - List of withdrawal objects.
  * withdrawalsRoot: String? - Root of this block's withdrawals trie.

#### Class: EncodeTransferResult

* Description: The return type for encodeTransfer.
* Properties:
  * data: String - The encoded data.
  * to: String - The token address.

#### Enum Class: EntryPoint

* Description: Enum class representing entry points with their respective
  addresses.
* Properties:
  * address: String - The address of the entry point.
* Entries
  * V07 - Represents the entry point version 0.7 with its respective address.

#### Sealed Class: Paymaster

* Description: Sealed class for setting User Operation Paymaster configuration.
  * If paymaster is PaymasterClient, it will use the provided Paymaster Client
    for sponsorship.
  * If paymaster is true, it will be assumed that the Bundler Client also
    supports Paymaster RPC methods (e.g. getPaymasterData), and uses them for
    sponsorship.
* Subclasses
  * True
    * Description: Represents a Paymaster configuration where the Bundler Client
      supports Paymaster RPC methods.
    * Properties:
      * paymasterContext: Map\<String, Any>? - Optional context for the
        paymaster.
  * Client
    * Description: Represents a Paymaster configuration using a provided
      Paymaster Client for sponsorship.
    * Properties:
      * client: PaymasterClient - The Paymaster Client used for sponsorship.
      * paymasterContext: Map\<String, Any>? - Optional context for the
        paymaster.

#### Abstract Class: PublicKeyCredential

* Description: Abstract class representing a public key credential, with the
  following derived classes:
  * RegistrationCredential
  * AuthenticationCredential
* Properties:
  * id: String - The unique identifier for the credential.
  * type: String - The type of the credential.
  * authenticatorAttachment: String - The attachment type of the authenticator.
  * response: AuthenticatorResponse - The response from the authenticator.
  * clientExtensionResults: AuthenticationExtensionsClientOutputs? - Optional
    client extension results.

#### Class: RegistrationCredential

* Description: Data class representing a block.
* Properties:
  * rawId: String - The raw identifier for the credential.
  * authenticatorAttachment: String - The attachment type of the authenticator.
  * type: String - The type of the credential.
  * id: String - The unique identifier for the credential.
  * response: AuthenticatorAttestationResponse - The attestation response from
    the authenticator.
  * clientExtensionResults: AuthenticationExtensionsClientOutputs? - Optional
    client extension results.
* Inheritance: Inherits from PublicKeyCredential.

#### Class: AuthenticationCredential

* Description: Data class representing a registration credential.
* Properties:
  * rawId: String - The raw identifier for the credential.
  * authenticatorAttachment: String - The attachment type of the authenticator.
  * type: String - The type of the credential.
  * id: String - The unique identifier for the credential.
  * response: AuthenticatorAssertionResponse - The assertion response from the
    authenticator.
  * clientExtensionResults: AuthenticationExtensionsClientOutputs? - Optional
    client extension results.
* Inheritance: Inherits from PublicKeyCredential.

#### Abstract Class: UserOperation

* Description: Abstract class representing a user operation, with the following
  derived classes:
  * UserOperationV07
* Properties:
  * sender: String? - The address of the sender.
  * nonce: BigInteger? - The nonce of the operation.
  * callData: String? - The data to be sent in the call.
  * callGasLimit: BigInteger? - The gas limit for the call.
  * verificationGasLimit: BigInteger? - The gas limit for verification.
  * preVerificationGas: BigInteger? - The gas used before verification.
  * maxPriorityFeePerGas: BigInteger? - The maximum priority fee per gas.
  * maxFeePerGas: BigInteger? - The maximum fee per gas.
  * signature: String? - The signature of the operation.

#### Class UserOperationV07

* Description: Data class representing a user operation for version 0.7.
* Properties:
  * sender: String? - The address of the sender.
  * nonce: BigInteger? - The nonce of the operation.
  * callData: String? - The data to be sent in the call.
  * callGasLimit: BigInteger? - The gas limit for the call.
  * verificationGasLimit: BigInteger? - The gas limit for verification.
  * preVerificationGas: BigInteger? - The gas used before verification.
  * maxPriorityFeePerGas: BigInteger? - The maximum priority fee per gas.
  * maxFeePerGas: BigInteger? - The maximum fee per gas.
  * signature: String? - The signature of the operation.
  * factory: String? - The factory address.
  * factoryData: String? - The data for the factory.
  * paymaster: String? - The paymaster address.
  * paymasterVerificationGasLimit: BigInteger? - The gas limit for paymaster
    verification.
  * paymasterPostOpGasLimit: BigInteger? - The gas limit for paymaster
    post-operation.
  * paymasterData: String? - The data for the paymaster.
* Inheritance: Inherits from UserOperation.

#### Class: UserOperationRpc

* Description: Data class representing a user operation in RPC format.
* Properties:
  * sender: String? - The address of the sender.
  * nonce: String? - The nonce of the operation.
  * callData: String? - The data to be sent in the call.
  * callGasLimit: String? - The gas limit for the call.
  * verificationGasLimit: String? - The gas limit for verification.
  * preVerificationGas: String? - The gas used before verification.
  * maxPriorityFeePerGas: String? - The maximum priority fee per gas.
  * maxFeePerGas: String? - The maximum fee per gas.
  * signature: String? - The signature of the operation.
  * factory: String? - The factory address.
  * factoryData: String? - The data for the factory.
  * paymaster: String? - The paymaster address.
  * paymasterVerificationGasLimit: String? - The gas limit for paymaster
    verification.
  * paymasterPostOpGasLimit: String? - The gas limit for paymaster
    post-operation.
  * paymasterData: String? - The data for the paymaster.
  * initCode: String? - The initialization code.
  * paymasterAndData: String? - The paymaster and data.

#### Function: UserOperationV07.toRpcUserOperation

* Description: Converts a UserOperationV07 instance to a UserOperationRpc
  instance.
* Returns: A UserOperationRpc instance with the corresponding properties from
  the UserOperationV07 instance.

#### Function: UserOperation.toRpcUserOperation

* Description: Converts a UserOperation instance to a UserOperationRpc instance.
* Returns: A UserOperationRpc instance with the corresponding properties from
  the UserOperation instance.

#### Function: UserOperationRpc.toUserOperationV07

* Description: Converts a UserOperationRpc instance to a UserOperationV07
  instance.
* Returns: A UserOperationV07 instance with the corresponding properties from
  the UserOperationRpc instance.

#### Enum Class: WebAuthnMode

* Description: Enum class representing the WebAuthn modes.
* Entries
  * Register - Mode for registering a new credential.
  * Login - Mode for logging in with an existing credential.

#### Enum Class: Token

* Description: Enum representing various tokens supported by encodeTransfer. The
  format is `{chain}_{symbol}`.
* Entries
  * Arbitrum\_ARB
  * Arbitrum\_USDC
  * ArbitrumSepolia\_USDC
  * ArcTestnet\_USDC
  * Avalanche\_USDC
  * AvalancheFuji\_USDC
  * Base\_USDC
  * BaseSepolia\_USDC
  * Monad\_USDC
  * MonadTestnet\_USDC
  * Optimism\_USDC
  * OptimismSepolia\_USDC
  * Polygon\_USDC
  * PolygonAmoy\_USDC
  * Unichain\_USDC
  * UnichainSepolia\_USDC

### Chains

#### Abstract Class: Chain

* Description: Abstract class representing the necessary definition of a
  blockchain for the SDK, with the following derived object classes as
  predefined chains:
  * Arbitrum
  * ArbitrumSepolia
  * ArcTestnet
  * Avalanche
  * AvalancheFuji
  * Base
  * BaseSepolia
  * Monad
  * MonadTestnet
  * Optimism
  * OptimismSepolia
  * Polygon
  * PolygonAmoy
  * Unichain
  * UnichainSepolia
* Properties:
  * chainId: Long - The unique identifier for the blockchain.

## Calling Kotlin Suspending Functions from Java

The **modular wallets Android SDK** uses suspending functions for asynchronous
operations. However, calling Kotlin's suspend functions from Java requires a
different approach due to Java's lack of built-in coroutine support. This
section explains how to invoke suspend functions from Java and demonstrates the
use of a custom continuation for managing coroutine execution.

### Creating a Custom Continuation

When calling a suspend function from Java, you must handle the coroutine's
**Continuation** parameter manually. A custom **Continuation** class can
implement Kotlin's **Continuation** interface to manage coroutine resumption,
handling both successful results and exceptions.

Below is the suggested approach for creating and using a custom continuation in
Java:

```java Example: Custom Continuation theme={null}
public class CustomContinuation<T> implements Continuation<T> {

    private final CompletableFuture<T> future;

    public CustomContinuation(CompletableFuture<T> future) {
        this.future = future;
    }

    @Override
    public void resumeWith(@NotNull Object o) {
        if (o instanceof Result.Failure)
            future.completeExceptionally((((Result.Failure) o).exception));
        else
            future.complete((T) o);
    }

    @NotNull
    @Override
    public CoroutineContext getContext() {
        return EmptyCoroutineContext.INSTANCE;
    }
}
```

### Using the Custom Continuation

Below is an example of how to use `CustomContinuation` to call the
`getChainId()` suspend function, which returns a `Long` value representing the
blockchain's chain ID.

```java Example: Suspend Function theme={null}
try {
    // Create a CompletableFuture to hold the result of the asynchronous operation
    CompletableFuture<Long> suspendResult = new CompletableFuture<>();
    // Call getChainId, passing in a CustomContinuation that will handle the result
    bundlerClient.getChainId(new CustomContinuation<>(suspendResult));
    // Wait for the CompletableFuture to complete and retrieve the result
    Long chainId = suspendResult.join();
} catch(Exception e) {
    e.printStackTrace;
}
```

### Key Points

* Suspend functions in Kotlin require a Continuation for resumption, which Java
  lacks natively.
* A custom continuation class in Java allows you to handle suspend function
  results and exceptions effectively.
* This approach ensures compatibility between Java and Kotlin while leveraging
  the asynchronous capabilities of the modular wallets Android SDK.

This approach can be used in your Java code for invoking Kotlin suspending
functions.


# Modular Wallets Console Setup
Source: https://developers.circle.com/wallets/modular/console-setup



This guide demonstrates how to create a client key and configure passkey
settings on the Circle Console.. This is needed to enable the basic
functionality provided by modular wallets. Once these steps are completed,
proceed to the
[Modular Wallets Quickstart](/wallets/modular/create-a-wallet-and-send-gasless-txn).

<Note>
  If you're building a web application, you need to ensure on the Circle Console
  that the Client Key's **Allowed Domain** input value matches exactly the
  Passkey's **Domain Name** configuration at the time of your product launch.
  These two settings must be consistent for your application to function
  correctly.
</Note>

## Create Client Key

Perform the steps below to create your client key.

1. Login to the [Circle Console](https://console.circle.com/), navigate to the
   **API & Client Keys** section, and click on `Create a key`.

<Frame>
  <img />
</Frame>

2. Select the **Client Key** option and type your client **Key Name**.

Each client key is bound to your application for identification and
authorization. Therefore, depending on your application setup, you may be able
to customize the following fields:

* Web **Allowed Domain**; for example, `your.website.com`, `localhost`, or
  `chrome-extension://<extension-id>`
* iOS **Bundle ID**; for example, `com.yourcompany.yourapp`
* Android
  * Package Name; for example, `com.yourcompany.yourapp`
  * Signature (SHA256); for example, `XX:XX:…:XX` (where `X`: `[0-9A-F]`)

<Note>
  **Platform Settings**

  1. If you run your web application locally, you can use `localhost` for the
     **Allowed Domain**. If you host your web application under a domain server,
     say `your.website.com`, you can use that domain server URL. For Chrome
     extensions, use the extension's URL in the format
     `chrome-extension://<extension-id>` as the **Allowed Domain**. You can find
     the extension ID on the Chrome Extensions page (`chrome://extensions`).

  2. If your application runs on multiple platforms, you can either configure the
     settings for each platform under such **Client Key**, or create a new
     **Client Key** for enhanced security; the latter approach is recommended.
</Note>

<Frame>
  <img />
</Frame>

3. Verify that the **Client Key** was created.

Once the information provided in the previous steps is validated, the system
generates a client key. Please store it in a safe place, as it won't be
displayed on the Console again.

<Note>
  Circle provides a built-in indexing service, allowing you to access
  transaction data per wallet faster and easier. You can check the transaction
  and `userOps` details through the Circle Console, or if you'd like to retrieve
  data from Circle's Indexing Service directly, you'll need to create an API Key
  to authenticate the RESTful API requests from your backend. Check the Modular
  Wallets API reference [here](/api-reference/wallets/buidl/list-transfers).
</Note>

<Frame>
  <img />
</Frame>

## Configure Passkey Domain

Perform the steps below to configure the **Domain Name** for your Passkey.

Enter the domain name of your application where users will be onboarded. Each
passkey created will be associated with this domain.

<Note>
  **Passkey for Mobile Apps**

  To enable passkey support for your iOS or Android application, you'll have to
  configure a web domain to associate your app with a website that your app owns,
  as passkeys on mobile-native apps are also domain-bound, similar to web
  applications.
</Note>

Configuration is required to enable Passkeys on mobile-native applications:

* **iOS**: A JSON file is required at the domain root:\
  `/.well-known /apple-app-site-association`. Refer to
  [this resource](https://developer.apple.com/documentation/xcode/configuring-an-associated-domain)
  for more details.
* **Android**: A JSON file is required at the domain root:\
  `/.well-known/assetlinks.json`. Refer to
  [this resource](https://developer.android.com/identity/sign-in/credential-manager#add-support-dal)
  for more details.

<Frame>
  <img />
</Frame>

## Retrieve Client URL

Visit the Configurator page to retrieve the **Client URL**, or copy from here:
`https://modular-sdk.circle.com/v1/rpc/w3s/buidl`. This URL is required for the
following **modular wallets SDK** methods:

* `toPasskeyTransport()`
* `toModularTransport()`: When using this method, you must specify the
  blockchain network. For more details, refer to the
  [Modular Wallets Quickstart](/wallets/modular/create-a-wallet-and-send-gasless-txn).

<Frame>
  <img />
</Frame>


# Quickstart: Create a Modular Wallet
Source: https://developers.circle.com/wallets/modular/create-a-wallet-and-send-gasless-txn



This Quickstart guides you through creating your first modular wallet smart
account and sending a gasless transaction using the modular wallets SDKs for
**Web**, **iOS**, or **Android**. For a complete web app implementation, refer
to the
[Circle Smart Account example](https://github.com/circlefin/modularwallets-web-sdk/tree/master/examples/circle-smart-account)
in the modular wallets web SDK.

## Prerequisites

Before you begin, ensure you have completed the following steps:

* Familiarize yourself with [API Keys and Client Keys](/api-reference/keys)
  authentication.
* Visit the [Modular Wallet Console Setup](/wallets/modular/console-setup) page
  to:
  * Create a **Client Key** for the modular wallets SDK
  * Configure the **Domain Name** for your Passkey.
  * Retrieve the **Client URL** for authentication.

<Note>
  **Note:**

  Circle provides a robust built-in indexing service optimized for subscribed
  transactions per wallet. You can set up
  [webhook subscriptions](https://console.circle.com/webhooks) on the Circle
  Console to receive notifications for transfer activities or user operations. To
  retrieve data from our Indexing Service through your backend, use an API Key to
  authenticate RESTful API requests.
</Note>

## Installation and Setup

Follow the applicable setup steps for the SDK you are installing:

<Tabs>
  <Tab title="Web SDK">
    1. Run the following command in your shell, depending on your package manager:

    <CodeGroup>
      ```shell npm theme={null}
      npm install @circle-fin/modular-wallets-core
      ```

      ```shell yarn theme={null}
      yarn add @circle-fin/modular-wallets-core
      ```
    </CodeGroup>

    2. Create an `.env` file in your local directory and add the **Client Key** and
       **Client URL** obtained from the
       [Modular Wallet Console Setup](/wallets/modular/console-setup) page:

    ```text theme={null}
    VITE_CLIENT_KEY=YOUR-CLIENT-KEY
    VITE_CLIENT_URL=YOUR-CLIENT-URL
    ```

    3. Follow the **React development workflow** to build your sample web app using
       the provided sample code.

    * The root dependencies should already be installed from the installation step
      above.
    * Install additional web app dependencies from the provided `package.json` file
      below.

    ```json package.json theme={null}
    {
      "name": "quickstart-circle-smart-account",
      "version": "0.0.0",
      "private": true,
      "type": "module",
      "scripts": {
        "dev": "vite"
      },
      "dependencies": {
        "react": "^18.2.0",
        "react-dom": "^18.2.0",
        "viem": "^2.21.27",
        "@circle-fin/modular-wallets-core": "^1.x.x"
      },
      "devDependencies": {
        "@types/react": "^18.0.27",
        "@types/react-dom": "^18.0.10",
        "@vitejs/plugin-react": "^4.3.2",
        "typescript": "^5.0.3",
        "vite": "^5.4.14"
      }
    }
    ```

    * Implement the quickstart steps below within a blank `index.tsx` file.
    * After completing all quickstart steps, you can test your app by launching a
      local web server.

    For more details, see the
    [Circle Smart Account Example](https://github.com/circlefin/modularwallets-web-sdk/tree/master/examples/circle-smart-account).
  </Tab>

  <Tab title="iOS SDK">
    ### Swift Package Manager

    The [Swift Package Manager](https://swift.org/package-manager/) is a tool for
    automating the distribution of Swift code and is integrated into the `swift`
    compiler.

    Once you have your Swift package set up, adding CircleModularWalletsCore as a
    dependency is as easy as adding it to the `dependencies` value of your
    `Package.swift` or the Package list in Xcode.

    ```swift Swift theme={null}
    dependencies: [
        .package(url: "https://github.com/circlefin/modularwallets-ios-sdk.git", .upToNextMajor(from: "1.0.0"))
    ]
    ```

    Normally you'll want to depend on the `CircleModularWalletsCore` target:

    ```swift Swift theme={null}
    .product(name: "CircleModularWalletsCore", package: "CircleModularWalletsCore")
    ```
  </Tab>

  <Tab title="Android SDK">
    Add the maven repository to your gradle file. It's suggested that load settings
    from `local.properties`:

    ```gradle Gradle theme={null}
    repositories {
        ...
        maven {
                Properties properties = new Properties()
                // Load local.properties.
                properties.load(new File(rootDir.absolutePath + "/local.properties").newDataInputStream())

            url properties.getProperty('mwsdk.maven.url')
            credentials {
                    username properties.getProperty('mwsdk.maven.username')
                    password properties.getProperty('mwsdk.maven.password')
            }
        }
    }
    ```

    Add the maven setting values in `local.properties` file:

    ```properties Properties theme={null}
    mwsdk.maven.url=https://maven.pkg.github.com/circlefin/modularwallets-android-sdk
    mwsdk.maven.username=<GITHUB_USERNAME>
    # Fine-grained personal access tokens or classic with package write permission.
    mwsdk.maven.password=<GITHUB_PAT>
    ```

    Add the dependency:

    ```gradle Gradle theme={null}
    dependencies {
        implementation 'circle.modularwallets:core:version'
    }
    ```
  </Tab>
</Tabs>

## Quickstart Steps

You can get started with the sample code below which showcases basic Modular
Wallets capabilities, including Circle Smart Account, passkey, paymaster, and
bundler services to send a gasless transaction with passkey signing.

### 1. Create or Use an Existing Passkey

Create a new Passkey or use an existing one from your
[client key, passkey domain, and client URL](/wallets/modular/console-setup)
values.

<CodeGroup>
  ```javascript WebSDK theme={null}
  import {
      toPasskeyTransport,
      toWebAuthnCredential,
  } from '@circle-fin/modular-wallets-core'

  // 0. retrieve client key and client url from environment vars
  const clientKey = import.meta.env.VITE_CLIENT_KEY as string
  const clientUrl = import.meta.env.VITE_CLIENT_URL as string

  // 1. register or login with a passkey and
  //    Create a Passkey Transport from client key
  const passkeyTransport = toPasskeyTransport(clientUrl, clientKey)
  const credential = await toWebAuthnCredential({
      transport: passkeyTransport,
      mode: WebAuthnMode.Register, //or WebAuthnMode.Login if login
      username: 'your-username'  //replace with actual username
  })
  ```

  ```swift iOS SDK theme={null}
  import CircleModularWalletsCore

  let CLIENT_KEY = "xxxxxxx:xxxxx"

  Task {
      do {
          // 1. Register or login with a passkey and
          //    Create a Passkey Transport from client key
          let transport = toPasskeyTransport(clientKey: CLIENT_KEY)

          let credential =
              try await toWebAuthnCredential(
                  transport: transport,
                  userName: "MyExampleName", // userName
                  mode: WebAuthnMode.register // or WebAuthnMode.login
              )

          // 2. Create a WebAuthn owner account from the credential
          let webAuthnAccount = toWebAuthnAccount(
              credential
          )
  ```

  ```java Android SDK theme={null}
  val CLIENT_KEY = "xxxxxxx:xxxxx"

  CoroutineScope(Dispatchers.IO).launch {
      try {
          // 1. Register or login with a passkey and
          //    Create a Passkey Transport from client key
          val transport = toPasskeyTransport(context, CLIENT_KEY, clientUrlWithoutChain)

          val credential = toWebAuthnCredential(
              context,
              transport,
              "MyExampleName", // userName
              WebAuthnMode.Register // or WebAuthnMode.Login
          )

          // 2. Create a WebAuthn owner account from the credential
          val webAuthnAccount = toWebAuthnAccount(
              credential,
          )
  ```

  ```java Android SDK (Java) theme={null}
  final String CLIENT_KEY = "xxxxxxx:xxxxx";
  try {
      // 1. Register or login with a passkey and
      //    Create a Passkey Transport from client key
      HttpTransport transport = toPasskeyTransport(
          context,
          CLIENT_KEY,
          clientUrlWithoutChain
      );
      CompletableFuture<WebAuthnCredential> suspendResult = new CompletableFuture<>();
      toWebAuthnCredential(
          context,
          transport,
          "MyExampleName",
          WebAuthnMode.Register, // or WebAuthnMode.Login
          new CustomContinuation<>(suspendResult) // see CustomContinuation in "Creating a Custom Continuation" from Android SDK
      );
      WebAuthnCredential credential = suspendResult.join();
      // 2. Create a WebAuthn owner account from the credential
      WebAuthnAccount webAuthnAccount = toWebAuthnAccount(credential);
  ```
</CodeGroup>

### 2. Create and Set Up a Client

Create a client to access the desired blockchain network. The sample below
demonstrates using the `polygonAmoy` chain.

<CodeGroup>
  ```javascript WebSDK theme={null}
  import { toModularTransport } from "@circle-fin/modular-wallets-core";
  import { createPublicClient } from "viem";
  import { polygonAmoy } from "viem/chains";

  // 2. Create modular transport for given chain from client url and client key
  const modularTransport = toModularTransport(
    clientUrl + "/polygonAmoy",
    clientKey,
  );

  // 3. Create client to connect to specified blockchain const client =
  createPublicClient({ chain: polygonAmoy, transport: modularTransport });
  ```

  ```swift iOS SDK theme={null}
          // 3. Create modular transport for given chain from client key and client url
          let modularTransport = toModularTransport(
              clientKey: CLIENT_KEY,
              url: clientUrl
          )
  ```

  ```java Android SDK theme={null}
          // 3. Create modular transport for given chain from client url and client key
          val modularTransport = toModularTransport(
              context,
              CLIENT_KEY,
              clientUrl
          )
  ```

  ```java Android SDK (Java) theme={null}
          // 3. Create modular transport from chain and client key
          Transport modularTransport = toModularTransport(
              context,
              CLIENT_KEY,
              clientUrl
          );
  ```
</CodeGroup>

<Note>
  **Note:**

  When invoking `toModularTransport()`, you must specify the **blockchain
  network**. Supported networks include:

  | Mainnets    | Testnets          |
  | ----------- | ----------------- |
  | `arbitrum`  | `arbitrumSepolia` |
  | `-`         | `arcTestnet`      |
  | `avalanche` | `avalancheFuji`   |
  | `base`      | `baseSepolia`     |
  | `monad`     | `monadTestnet`    |
  | `optimism`  | `optimismSepolia` |
  | `polygon`   | `polygonAmoy`     |
  | `unichain`  | `unichainSepolia` |
</Note>

### 3. Create a Circle Smart Account with Passkey

Create a Circle Smart Account using the transport client and the owner's
credentials. Then, create a bundler client to send user operations for the
specified blockchain. The example below uses the `polygonAmoy` chain.

<CodeGroup>
  ```javascript Web SDK theme={null}
  import { toCircleSmartAccount } from "@circle-fin/modular-wallets-core";
  import {
    createBundlerClient,
    toWebAuthnAccount,
  } from "viem/account-abstraction";

  // 4. create a circle smart account
  const smartAccount = await toCircleSmartAccount({
    client,
    owner: toWebAuthnAccount({ credential }),
  });

  // 5. create a bundler client
  const bundlerClient = createBundlerClient({
    smartAccount,
    chain: polygonAmoy,
    transport: modularTransport,
  });
  ```

  ```swift iOS SDK theme={null}
          // 4. Create a bundler client
          let bundlerClient = BundlerClient(
              chain: PolygonAmoy,
              transport: modularTransport
          )

          // 5. Create smart account (CircleSmartAccount)
          //    and set the WebAuthn account as the owner
          let smartAccount =
              try await toCircleSmartAccount(
                  client: bundlerClient,
                  owner: webAuthnAccount
              )
  ```

  ```javascript Android SDK theme={null}
          // 4. Create a bundler client
          val bundlerClient = BundlerClient(
              PolygonAmoy,
              modularTransport,
          )

          // 5. Create smart account (CircleSmartAccount)
          //    and set the WebAuthn account as the owner
          val smartAccount = toCircleSmartAccount(
              bundlerClient,
              webAuthnAccount,
          )
  ```

  ```java Android SDK (Java) theme={null}
          // 4. Create a bundler client
          BundlerClient bundlerClient = new BundlerClient(PolygonAmoy.INSTANCE, modularTransport);

          // 5. Create smart account (CircleSmartAccount) and set the WebAuthn account as the owner
          CompletableFuture<CircleSmartAccount> suspendAccount = new CompletableFuture<>();
          toCircleSmartAccount(bundlerClient, webAuthnAccount, new CustomContinuation<>(suspendAccount));
          CircleSmartAccount smartAccount = suspendSmartAccount.join();
  ```
</CodeGroup>

### 4. Send a Gasless Transaction

Encapsulate the transaction within a user operation (userOp) and send it to the
bundler. The bundler then initiates the transaction on behalf of the sender and
forwards the transaction receipt back upon request.

<Note>
  **Note:**

  On mobile platforms, **iOS** and **Android** offer at least a second option to
  send a transaction using the `encodeTransfer()` method. In the code below,
  ensure you select either **Option 1** or **Option 2** based on your
  requirements.
</Note>

<CodeGroup>
  ```javascript Web SDK theme={null}
  import { encodeTransfer } from "@circle-fin/modular-wallets-core";

  // 6. Send a user operation to the bundler.
  // // Here we send 1 USDC to a random address
  const USDC_CONTRACT_ADDRESS = "0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582"; //Polygon Amoy testnet const
  USDC_DECIMALS = 6;
  const userOpHash = await bundlerClient.sendUserOperation({
    calls: [encodeTransfer(to, USDC_CONTRACT_ADDRESS, 100000n)],
    paymaster: true,
  });

  // 7. wait for transaction receipt
  const { receipt } = await bundlerClient.waitForUserOperationReceipt({
    hash: userOpHash,
  });
  ```

  ```swift iOS SDK theme={null}
          // (Option 1)
          // 6. Send a user operation directly to the bundler.
          //    Here we send 1 USDC to a random address.
          let USDC_CONTRACT_ADDRESS = "0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582"  //Polygon Amoy testnet
          let USDC_DECIMALS: Float = pow(10, 6)
          let userOpHash = try await bundlerClient.sendUserOperation(
              account: smartAccount,
              calls: [
                  EncodeCallDataArg(
                      to: USDC_CONTRACT_ADDRESS,
                      value: BigInt(0),
                      abiJson: ERC20_ABI,
                      functionName: "transfer",
                      args: [
                          "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",  //recipient address
                          BigInt(1 * USDC_DECIMALS)  //transfer amount
                      ]
                  )
              ],
              paymaster: Paymaster.True()
          )

          // 7. Wait for transaction receipt
          let receipt = try await bundlerClient.waitForUserOperationReceipt(
              userOpHash: userOpHash
          )
      }
      catch {
          print(error)
      }
  }

          // (Option 2)
          // 6. Use encodeTransfer to send a user operation to the bundler.
          //    Here we send 1 USDC to a random address.
          let result = Utils.encodeTransfer(
              to: "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",  //receiver address,
              token: PolygonAmoyToken.USDC.name,
              amount: BigInt(1 * USDC_DECIMALS)  //transfer amount
          )
          let userOpHash = try await bundlerClient.sendUserOperation(
              account: smartAccount,
              calls: [
                  EncodeCallDataArg(
                      to: result.to,
                      value: BigInt(0),
                      data: result.data
                  )
              ],
              paymaster: Paymaster.True()
          )

          // 7. Wait for transaction receipt
          let receipt = try await bundlerClient.waitForUserOperationReceipt(
              userOpHash: userOpHash
          )
      }
      catch {
          print(error)
      }
  }
  ```

  ```java Android SDK theme={null}
          // (Option 1)
          // 6. Send a user operation to the bundler.
          //    Here we send 1 USDC to a random address.
          val USDC_CONTRACT_ADDRESS = "0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582"  //Polygon Amoy testnet
          val USDC_DECIMALS = 6
          val userOpHash = bundlerClient.sendUserOperation(
              context,
              smartAccount,
              arrayOf(
                  EncodeCallDataArg(
                      to = USDC_CONTRACT_ADDRESS,
                      value = BigInteger("0"),
                      functionName = "transfer",
                      abiJson = ABI_ERC20,
                      args = arrayOf(
                          "0x0000000071727De22E5E9d8BAf0edAc6f37da032",  //recipient address
                          parseUnits("1", USDC_DECIMALS)  //transfer amount
                      )
                  ),
                  paymaster = Paymaster.True()
              )
          )

          // 7. wait for transaction receipt
          val receipt = bundlerClient.waitForUserOperationReceipt(userOpHash)
      }
      catch (e: Exception) {
          e.printStackTrace()
      }
  }

          // (Option 2)
          // 6. Use encodeTransfer to send a user operation to the bundler.
          //    Here we send 1 USDC to a random address.
          val result = encodeTransfer(
              "0x0000000071727De22E5E9d8BAf0edAc6f37da032",  //receiver address
              Token.PolygonAmoy_USDC.name,
              parseUnits("1", USDC_DECIMALS)  //transfer amount
          )
          val userOpHash = bundlerClient.sendUserOperation(
              context,
              smartAccount,
              calls = arrayOf(
                  EncodeCallDataArg(
                      to = result.to,
                      value = BigInteger.ZERO,
                      data = result.data
                  )
              ),
              paymaster = Paymaster.True()
          )

          // 7. wait for transaction receipt
          val receipt = bundlerClient.waitForUserOperationReceipt(userOpHash)
      }
      catch (e: Exception) {
          e.printStackTrace()
      }
  }
  ```

  ```java Android SDK (Java) theme={null}
          // (Option 1)
          // 6. Send a user operation to the bundler.
          //    Here we send 1 USDC to a random address.
          String USDC_CONTRACT_ADDRESS = "0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582";
          EncodeCallDataArg usdcTransfer = new EncodeCallDataArg(
              USDC_CONTRACT_ADDRESS, // to
              BigInteger.valueOf(0), // value
              null, // data
              AbiConstantsKt.getABI_ERC20(), // abiJson
              new Object[]{
                  "0x0000000071727De22E5E9d8BAf0edAc6f37da032", // receiver addres
                  parseUnits("1", 6) // transfer amount
              },
              "transfer" // functionName
          );
          UserOperationV07 partialUserOp = new UserOperationV07();
          CompletableFuture<String> suspendUserOpHash = new CompletableFuture<>();
          bundlerClient.sendUserOperation(
              context,
              smartAccount,
              new EncodeCallDataArg[] {
                  usdcTransfer
              },
              partialUserOp,
              new Paymaster.True(),
              new CustomContinuation<>(suspendUserOpHash)
          );
          String userOpHash = suspendUserOpHash.join();
          // 7. wait for transaction receipt
          CompletableFuture<UserOperationReceipt> suspendReceipt = new CompletableFuture<>();
          bundlerClient.waitForUserOperationReceipt(userOpHash, new CustomContinuation<>(suspendReceipt));
          UserOperationReceipt receipt = suspendReceipt.join();
      }
      catch (Exception e) {
          e.printStackTrace()
      }
  }

          // (Option 2)
          // 6. Use encodeTransfer to send a user operation to the bundler.
          //    Here we send 1 USDC to a random address.
          EncodeTransferResult result = encodeTransfer(
              "0x0000000071727De22E5E9d8BAf0edAc6f37da032", //receiver address
              Token.PolygonAmoy_USDC.name(),
              parseUnits("1", 6) //transfer amount
          );
          CompletableFuture<String> suspendUserOpHash = new CompletableFuture<>();
          bundlerClient.sendUserOperation(
              context,
              smartAccount,
              new EncodeCallDataArg[]{
                  new EncodeCallDataArg(result.getTo(), BigInteger.ZERO, result.getData())
              },  // calls
              new UserOperationV07(),
              new Paymaster.True(),
              new CustomContinuation<>(suspendUserOpHash)
          );
          String userOpHash = suspendUserOpHash.join();
          // 7. wait for transaction receipt
          CompletableFuture<UserOperationReceipt> suspendReceipt = new CompletableFuture<>();
          bundlerClient.waitForUserOperationReceipt(userOpHash, new CustomContinuation<>(suspendReceipt));
          UserOperationReceipt receipt = suspendReceipt.join();
      }
      catch (Exception e) {
          e.printStackTrace()
      }
  }
  ```
</CodeGroup>

## Summary

In this Quickstart, you were able to:

* Set up the Modular Wallet SDK.
* Create a Circle Smart Account with Passkey.
* Send a gasless transaction using the bundler.

You can use these foundational steps to integrate modular wallets into your
application and explore its full suite of capabilities.


# Dynamic Integration Tutorial
Source: https://developers.circle.com/wallets/modular/dynamic-integration



This tutorial shows you how to integrate [Dynamic](https://www.dynamic.xyz/) as
an Externally Owned Account (EOA) signer for Circle Smart Accounts using the
modular wallets SDK. You'll learn how to connect Dynamic's authentication system
with Circle's Smart Accounts. You'll also send USDC as a user operation using
the `viem` account abstraction utilities, enabled by the modular wallets SDK.

## Prerequisites

Before you begin, make sure you have:

* A [Circle Developer Console](https://console.circle.com) account.
* A [Dynamic Dashboard](https://app.dynamic.xyz/) account.
* [Node.js](https://nodejs.org/) installed for local testing. Circle recommends
  Node 16 or higher.
* Testnet funds in your wallet:
  * **Testnet USDC**: Use the [Circle Faucet](https://faucet.circle.com) to mint
    USDC on supported testnets (for example, USDC on Polygon Amoy).
  * **Native testnet tokens**: Use a
    [Public Faucet](https://www.alchemy.com/dapps/best/crypto-faucets) to get
    native testnet tokens (for example, MATIC for Polygon Amoy). You'll need
    these to pay for transaction fees when gas sponsorship isn't available.

### Configure your Circle and Dynamic credentials

1. In the [Circle Developer Console](https://console.circle.com), complete the
   setup below by following the steps in the
   [Modular Wallets Console Setup](/wallets/modular/console-setup) section:
   * Create a **Client Key** for the modular wallets SDK.
   * Retrieve the **Client URL**.

2. In the [Dynamic Dashboard](https://app.dynamic.xyz/), do the following:

   * Obtain your **Environment ID** and store it in the project's `.env` file
     along with other credentials, to be accessed later using `import.meta.env`.
   * Set the default network to one of Circle's supported networks. In this
     example, we use **Polygon Amoy**.
   * Alternatively, configure a custom list of supported networks using
     [Dynamic's network overrides](https://docs.dynamic.xyz/chains/evmNetwork#example).

   <Frame>
     <img />
   </Frame>

   Here's how to override the default EVM networks in Dynamic:

   ```tsx Web theme={null}
   const evmNetworks = [
     {
       chainId: polygonAmoy.id,
       networkId: polygonAmoy.id,
       name: polygonAmoy.name,
       nativeCurrency: polygonAmoy.nativeCurrency,
       rpcUrls: [...polygonAmoy.rpcUrls.default.http],
       iconUrls: [],
       blockExplorerUrls: [polygonAmoy.blockExplorers.default.url],
     },
   ];

   function App() {
     return (
       <DynamicContextProvider
         settings={{
           environmentId,
           walletConnectors: [EthereumWalletConnectors],
           overrides: { evmNetworks },
         }}
       >
         <DynamicWidget variant="modal" />
         <Example />
       </DynamicContextProvider>
     );
   }
   ```

## Tutorial Steps

Follow the steps below to integrate Dynamic as an EOA signer for Circle Smart
Accounts. You'll start by installing the necessary dependencies, then configure
your application to wrap Dynamic's context, create a Circle Smart Account, and
send a user operation.

### Step 1: Install dependencies

Install the required Dynamic SDK packages, depending on your package manager:

<CodeGroup>
  ```shell npm theme={null}
  npm install @dynamic-labs/ethereum @dynamic-labs/sdk-react-core
  ```

  ```shell yarn theme={null}
  yarn add @dynamic-labs/ethereum @dynamic-labs/sdk-react-core
  ```
</CodeGroup>

### Step 2: Wrap your app in the Dynamic context provider

Wrap your app with `DynamicContextProvider` from the Dynamic SDK to enable
wallet authentication and connection.

```tsx Web theme={null}
import * as React from "react";
import * as ReactDOM from "react-dom/client";

import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import {
  DynamicContextProvider,
  DynamicWidget,
} from "@dynamic-labs/sdk-react-core";

import { Example } from ".";

const environmentId = import.meta.env.VITE_DYNAMIC_ENV_ID as string;

function App() {
  return (
    <DynamicContextProvider
      settings={{
        environmentId,
        walletConnectors: [EthereumWalletConnectors],
      }}
    >
      <DynamicWidget variant="modal" />
      <Example />
    </DynamicContextProvider>
  );
}

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <App />,
);
```

### Step 3: Create a Circle Smart Account using Dynamic provider

Use the Dynamic context and Circle's modular wallets SDK to create a Smart
Account. Here's the full working example:

```tsx Web theme={null}
import React, { useEffect } from "react";
import { createPublicClient, Hex, parseUnits } from "viem";

import { isEthereumWallet } from "@dynamic-labs/ethereum";
import { useDynamicContext } from "@dynamic-labs/sdk-react-core";

import {
  toCircleSmartAccount,
  toModularTransport,
  walletClientToLocalAccount,
  encodeTransfer,
} from "@circle-fin/modular-wallets-core";

import { createBundlerClient, SmartAccount } from "viem/account-abstraction";

import { polygonAmoy } from "viem/chains";

const clientKey = import.meta.env.VITE_CLIENT_KEY as string;
const clientUrl = import.meta.env.VITE_CLIENT_URL as string;

// Create Circle transports
const modularTransport = toModularTransport(
  `${clientUrl}/polygonAmoy`,
  clientKey,
);

// Create a public client
const client = createPublicClient({
  chain: polygonAmoy,
  transport: modularTransport,
});

// Create a bundler client
const bundlerClient = createBundlerClient({
  chain: polygonAmoy,
  transport: modularTransport,
});

export const Example = () => {
  const { primaryWallet } = useDynamicContext(); // Get the wallet information from the Dynamic context provider
  const [account, setAccount] = React.useState<SmartAccount>();
  const [hash, setHash] = React.useState<Hex>();
  const [userOpHash, setUserOpHash] = React.useState<Hex>();

  useEffect(() => {
    async function setSigner() {
      if (!primaryWallet) {
        setAccount(undefined); // Reset the account if the wallet is not connected
        return;
      }

      if (!isEthereumWallet(primaryWallet)) {
        throw new Error("Wallet is not EVM-compatible.");
      }

      const walletClient = await primaryWallet.getWalletClient(); // Dynamic provider

      const smartAccount = await toCircleSmartAccount({
        client,
        owner: walletClientToLocalAccount(walletClient), // Transform the wallet client to a local account
      });

      setAccount(smartAccount);
    }

    setSigner();
  }, [primaryWallet]);

  const sendUserOperation = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    if (!account) return;

    const formData = new FormData(event.currentTarget);
    const to = formData.get("to") as `0x${string}`;
    const value = formData.get("value") as string;

    const USDC_CONTRACT_ADDRESS = "0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582"; // Polygon Amoy testnet
    const USDC_DECIMALS = 6; // Used for parseUnits
    const callData = encodeTransfer(
      to,
      USDC_CONTRACT_ADDRESS,
      parseUnits(value, USDC_DECIMALS),
    );

    const opHash = await bundlerClient.sendUserOperation({
      account,
      calls: [callData],
      paymaster: true, // Enable gas sponsorship if supported
    });

    setUserOpHash(opHash);

    const { receipt } = await bundlerClient.waitForUserOperationReceipt({
      hash: opHash,
    });
    setHash(receipt.transactionHash);
  };

  if (!primaryWallet) return null;

  return (
    <div>
      {!account ? (
        <p>Loading...</p>
      ) : (
        <>
          <p>
            <strong>Address:</strong> {account.address}
          </p>
          <h2>Send User Operation</h2>
          <form onSubmit={sendUserOperation}>
            <input name="to" placeholder="Address" required />
            <input name="value" placeholder="Amount (USDC)" required />
            <button type="submit">Send</button>
          </form>
          {userOpHash && (
            <p>
              <strong>User Operation Hash:</strong> {userOpHash}
            </p>
          )}
          {hash && (
            <p>
              <strong>Transaction Hash:</strong> {hash}
            </p>
          )}
        </>
      )}
    </div>
  );
};
```

<Note>
  To access the current wallet, use the `useDynamicContext()` hook provided by
  `DynamicContextProvider` and get the `primaryWallet`. You can then convert it
  to a local account and use it to generate a Circle Smart Account.
</Note>

```tsx Web theme={null}
const { primaryWallet } = useDynamicContext();

if (primaryWallet && isEthereumWallet(primaryWallet)) {
  const walletClient = await primaryWallet.getWalletClient();
  const smartAccount = await toCircleSmartAccount({
    client,
    owner: walletClientToLocalAccount(walletClient),
  });
}
```

In the above code, if the `primaryWallet` is not null or undefined, you can
transform it into a wallet client, convert it to a local account, and then pass
it to `toCircleSmartAccount()` to create a Circle Smart Account. This account
can then be used to send user operations.

## Step 4: Run the app

Start your app, click **Login** or **Sign Up** using Dynamic, and you'll be
connected to the blockchain through Circle's modular wallets SDK.

Once logged in, you'll see the UI for sending a user operation:

<Frame>
  <img />
</Frame>

## Summary

In this tutorial, you integrated Dynamic as an EOA signer for Circle Smart
Accounts using the modular wallets SDK. You:

* Set up credentials in both Circle and Dynamic.
* Installed required dependencies.
* Wrapped your app with `DynamicContextProvider`.
* Created a smart account using `toCircleSmartAccount()`.
* Sent a user operation using `viem` bundler client.

This integration enables a seamless, passwordless Web3 onboarding experience and
allows you to build advanced features like gas sponsorship and session keys
using Circle's modular wallets framework.


# Modular Wallets iOS SDK
Source: https://developers.circle.com/wallets/modular/ios-sdk



Welcome to Circle's modular wallets iOS SDK documentation. The SDK enables
developers to integrate modular wallets to build secure, scalable Web3
applications by leveraging tools for key management, smart account interactions,
gasless transactions, and blockchain communication.

## Installation

Follow the steps provided in the
[GitHub repository](https://github.com/circlefin/modularwallets-ios-sdk#installation)
to install and set up the modular wallets iOS SDK.

## API Documentation

The following sections detail the SDK's transport mechanisms, client
interactions, account management, utility functions, model structures, and
supported blockchain networks.

***

### Transports

#### Protocol: `Transport`

* **Description**: Interface representing a transport mechanism for making RPC
  requests.

##### Methods

###### `request`

* **Description**: Sends an RPC request and returns the response.
* **Parameters**:
  * `rpcRequest`: `RpcRequest` - The RPC request to be sent.
* **Returns**: `RpcResponse`

#### Class: `HttpTransport`

* **Description**: The `HttpTransport` confirms the protocol `Transport` and
  implements the required methods.

#### Class: `ModularTransport`

* **Description**: The `ModularTransport` inherits `HttpTransport` and confirms
  the protocol `ModularRpcApi`.

#### Structure: `HttpRpcClientOptions`

* **Description**: Data class representing HTTP RPC client options.
* **Properties**:
  * `headers`: `[String: String]` - Headers to include in the HTTP requests.

#### Function: `toModularTransport`

* **Description**: Creates an instance of `ModularTransport` with the provided
  client key and URL.
* **Parameters**:
  * `clientKey`: `String` - The client key for authorization.
  * `url`: `String` - The URL for the HTTP transport.
* **Returns**: `HttpTransport` - The configured HTTP transport instance.

#### Function: `toPasskeyTransport`

* **Description**: Creates an instance of `HttpTransport` with the provided
  client key and URL, setting the authorization header.
* **Parameters**:
  * `clientKey`: `String` - The client key for authorization.
  * `url`: `String` - The URL of the transport endpoint. Defaults to
    `CIRCLE_BASE_URL`.
* **Returns**: `HttpTransport` - The configured HTTP transport instance.

#### Function: `http`

* **Description**: Creates an HTTP transport instance.
* **Parameters**:
  * `url`: `String` - The URL for the HTTP transport.
  * `options`: `HttpRpcClientOptions?` - Optional configuration options for the
    HTTP transport.
* **Returns**: `HttpTransport` - The configured HTTP transport instance.

***

### Clients

#### Class: `Client`

* **Description**: Represents a client that interacts with a blockchain, with
  the following derived classes:
  * `BundlerClient`
  * `PaymasterClient`
* **Properties**:
  * `chain`: `Chain` - The blockchain that the client interacts with.
  * `transport`: `Transport` - The transport mechanism used for making RPC
    requests.

#### Class: `BundlerClient`

* **Description**: Client for interacting with the Bundler API. A
  `BundlerClient` is an interface to interact with ERC-4337 Bundlers and
  provides the ability to send and retrieve User Operations through Bundler
  Actions.
* **Inheritance**: Inherits from `Client`.

##### Methods

###### `estimateUserOperationGas`

* **Description**: Estimates the gas values for a User Operation to be executed
  successfully.
* **Parameters**:
  * `account`: `SmartAccount` - The smart account to use for User Operation
    execution.
  * `calls`: `[EncodeCallDataArg]` - The calls to execute in the User Operation.
  * `paymaster`: `Paymaster?` - Optional, sets Paymaster configuration for the
    User Operation.
  * `estimateFeesPerGas`:
    `((SmartAccount, BundlerClient, UserOperationV07) async -> EstimateFeesPerGasResult)?` -
    Optional, prepares fee properties for the User Operation request.
* **Returns**: `EstimateUserOperationGasResult` - The result of the gas
  estimation.

###### `getChainId`

* **Description**: Returns the chain ID associated with the current network.
* **Returns**: `Int` - The current chain ID.

###### `getSupportedEntryPoints`

* **Description**: Retrieves the EntryPoints that the bundler supports.
* **Returns**: `[String]` - A list of supported EntryPoints.

###### `getUserOperation`

* **Description**: Retrieves information about a User Operation given a hash.
* **Parameters**:
  * `userOpHash`: `String` - The hash of the User Operation.
* **Returns**: `GetUserOperationResult` - User Operation information.

###### `getUserOperationReceipt`

* **Description**: Returns the User Operation Receipt given a User Operation
  hash.
* **Parameters**:
  * `userOpHash`: `String` - The hash of the User Operation.
* **Returns**: `GetUserOperationReceiptResult` - The User Operation receipt.

###### `prepareUserOperation`

* **Description**: Prepares a User Operation for execution and fills in missing
  properties.
* **Parameters**:
  * `account`: `SmartAccount` - The smart account to use for User Operation
    execution.
  * `calls`: `[EncodeCallDataArg]?` - The calls to execute in the User
    Operation.
  * `partialUserOp`: `UserOperationV07` - The partial User Operation to be
    completed.
  * `paymaster`: `Paymaster?` - Optional, sets Paymaster configuration for the
    User Operation.
  * `estimateFeesPerGas`:
    `((SmartAccount, BundlerClient, UserOperationV07) async -> EstimateFeesPerGasResult)?` -
    Optional, prepares fee properties for the User Operation request.
* **Returns**: `UserOperationV07` - The prepared User Operation.

###### `sendUserOperation`

* **Description**: Sends a User Operation to the Bundler.
* **Parameters**:
  * `account`: `SmartAccount` - The smart account to use for User Operation
    execution.
  * `calls`: `[EncodeCallDataArg]?` - The calls to execute in the User
    Operation.
  * `partialUserOp`: `UserOperationV07` - The partial User Operation to be
    completed.
  * `paymaster`: `Paymaster?` - Optional, sets Paymaster configuration for the
    User Operation.
  * `estimateFeesPerGas`:
    `((SmartAccount, BundlerClient, UserOperationV07) async -> EstimateFeesPerGasResult)?` -
    Optional, prepares fee properties for the User Operation request.
* **Returns**: `String?` - Optional, the hash of the sent User Operation, or
  `null` otherwise.

###### `waitForUserOperationReceipt`

* **Description**: Waits for the User Operation to be included in a block (one
  confirmation) and then returns the User Operation receipt.
* **Parameters**:
  * `userOpHash`: `String` - The User Operation hash.
  * `pollingInterval`: `Int` (default: `4000`) - The polling interval in
    milliseconds.
  * `retryCount`: `Int` (default: `6`) - The number of retries.
  * `timeout`: `Int?` - Optional timeout in milliseconds to wait before stopping
    polling.
* **Returns**: `GetUserOperationReceiptResult` - The result of the User
  Operation receipt retrieval.

###### `getBalance`

* **Description**: Retrieves the balance of the specified address at a given
  block tag or block number.
* **Parameters**:
  * `address`: `String` - The address to query the balance for. Only wallet
    addresses registered with the client key can be retrieved.
  * `blockNumber`: `BlockNumber` - The block number (default: `.latest`).
* **Returns**: `BigInt` - The balance of the address.

###### `getBlockNumber`

* **Description**: Returns the number of the most recent block seen.
* **Returns**: `BigInt` - The current block number.

###### `getGasPrice`

* **Description**: Retrieves the current gas price (in wei).
* **Returns**: `BigInt` - The current gas price (in wei).

###### `call`

* **Description**: Executes a new message call immediately without submitting a
  transaction to the network.
* **Parameters**:
  * `from`: `String?` - Optional, the address to send the call from.
  * `to`: `String` - The contract address or recipient.
  * `data`: `Data` - A contract hashed method call with encoded arguments.
* **Returns**: `String` - The call data.

###### `getCode`

* **Description**: Retrieves the bytecode at an address.
* **Parameters**:
  * `address`: `String` - The contract address.
  * `blockNumber`: `BlockNumber` - The block number (default: `.latest`).
* **Returns**: `String` - The contract's bytecode.

###### `estimateMaxPriorityFeePerGas`

* **Description**: Returns an estimate for the max priority fee per gas (in wei)
  for a transaction to likely be included in the next block. The Action will
  either call `eth_maxPriorityFeePerGas` (if supported) or manually calculate
  the max priority fee per gas based on the current block base fee per gas + gas
  price.
* **Returns**: `BigInt` - An estimate (in wei) for the max priority fee per gas.

###### `getBlock`

* **Description**: Returns information about a block at a specific block number.
* **Parameters**:
  * `includeTransactions`: `Boolean` (default: `false`) - Whether or not to
    include transactions (as a structured array of `Transaction` objects).
  * `blockNumber`: `BlockNumber` - The block number (default: `.latest`).
* **Returns**: `Block` - The block information.

###### `getUserOperationGasPrice`

Available only for modular wallets.

* **Description**: Retrieves gas price options for a user operation. You may
  include the SDK version parameter.
* **Returns**: `GetUserOperationGasPriceResult` - The gas price options in each
  tier (low, medium, high) and `verificationGasLimit` (optional).

#### Class: `PaymasterClient`

* **Description**: Client for interacting with the Paymaster API. A
  `PaymasterClient` is an interface to interact with
  [ERC-7677 compliant Paymasters](https://eips.ethereum.org/EIPS/eip-7677) and
  provides the ability to sponsor User Operation gas fees.
* **Inheritance**: Inherits from `Client`.

##### Methods

###### `getPaymasterData`

* **Description**: Retrieves paymaster-related User Operation properties to be
  used for sending the User Operation.
* **Parameters**:
  * `userOp`: `T` - The User Operation to retrieve Paymaster data for. Type `T`
    must be a subclass of `UserOperation`.
  * `entryPoint`: `EntryPoint` - The EntryPoint address to target.
  * `context`: `[String: AnyEncodable]?` - Optional, paymaster-specific fields.
* **Returns**: `GetPaymasterDataResult` - Paymaster-related User Operation
  properties.

###### `getPaymasterStubData`

* **Description**: Retrieves paymaster-related User Operation properties to be
  used for gas estimation.
* **Parameters**:
  * `userOp`: `T` - The User Operation to retrieve Paymaster data for. Type `T`
    must be a subclass of `UserOperation`.
  * `entryPoint`: `EntryPoint` - The EntryPoint address to target.
  * `context`: `[String: AnyEncodable]?` - Optional, paymaster-specific fields.
* **Returns**: `GetPaymasterStubDataResult` - Paymaster-related User Operation
  properties.

***

### Accounts

#### Function: `toCircleSmartAccount`

* **Description**: Creates a Circle passkey account.
* **Parameters**:
  * `client`: `Client` - The client used to interact with the blockchain.
  * `owner`: `Account<SignResult>` - The owner account associated with the
    Circle Passkey account.
  * `version`: `String` (default: `"circle_passkey_account_v1"`) - The version
    of the Circle Passkey account.
  * `name`: `String?` (optional, defaults to the format
    `passkey-yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`) - The wallet name assigned to the
    newly registered account.
* **Returns**: `CircleSmartAccount`

#### Function: `toWebAuthnAccount`

* **Description**: Creates a WebAuthn account.
* **Parameters**:
  * `credential`: `WebAuthnCredential` - The WebAuthn credential associated with
    the account.
* **Returns**: `WebAuthnAccount` - The created WebAuthn account.

#### Function: `toWebAuthnCredential`

* **Description**: Logs in or registers a user and returns a
  `WebAuthnCredential`.
* **Parameters**:
  * `transport`: `Transport` - The transport used to communicate with the RP
    API.
  * `userName`: `String?` (optional, required for `WebAuthnMode.Register`) - The
    username of the user.
  * `mode`: `WebAuthnMode` - The mode of the WebAuthn credential.
* **Returns**: `WebAuthnCredential`
* **Throws**: `BaseError` if `userName` is `null` for `WebAuthnMode.Register`.

#### Structure: `WebAuthnCredential`

* **Description**: Represents a P-256 WebAuthn credential used for registration
  and login.
* **Properties**:
  * `id`: `String` - The unique identifier for the credential.
  * `publicKey`: `String` (serialized hex) - The public key associated with the
    credential.
  * `raw`: `PublicKeyCredential` - The raw public key credential.
  * `rpId`: `String` - The relying party identifier.

#### Protocol: `Account`

* **Description**: A protocol defining the required methods for an account.
* **Type Parameter**: `T` - The type of the signed data.

##### Methods

###### `getAddress`

* **Description**: Retrieves the address of the account.
* **Returns**: `String` - The account's address.

###### `sign`

* **Description**: Signs the given hex data.
* **Parameters**:
  * `hex`: `String` - The hex data to sign.
* **Returns**: `T` - The signed data.

###### `signMessage`

* **Description**: Signs the given message.
* **Parameters**:
  * `message`: `String` - The message to sign.
* **Returns**: `T` - The signed message.

###### `signTypedData`

* **Description**: Signs the given typed data.
* **Parameters**:
  * `typedData`: `String` - The typed data to sign.
* **Returns**: `T` - The signed typed data.

#### Structure: `WebAuthnAccount`

* **Description**: Represents a WebAuthn account for handling authentication
  credentials and signing. Commonly used as a
  [Smart Account](https://viem.sh/account-abstraction/accounts/smart) owner to
  sign User Operations and messages on behalf of the Smart Account.
* **Conforms To**: `Account`

##### Methods

###### `getAddress`

* **Description**: Retrieves the public key address associated with the WebAuthn
  credential.
* **Returns**: `String` - The associated public key.

###### `sign`

* **Description**: Signs the given hex data.
* **Parameters**:
  * `hex`: `String` - The hex string to sign.
* **Returns**: `SignResult` - The result of the signing operation.

###### `signMessage`

* **Description**: Signs a message.
* **Parameters**:
  * `message`: `String` - The message to sign.
* **Returns**: `SignResult` - The result of the signing operation.

###### `signTypedData`

* **Description**: Signs typed data.
* **Parameters**:
  * `jsonData`: `String` - The JSON data to sign.
* **Returns**: `SignResult` - The result of the signing operation.

#### Protocol: `SmartAccount`

* **Description**: A Smart Account is an account whose implementation resides in
  a smart contract and implements the
  [ERC-4337 interface](https://eips.ethereum.org/EIPS/eip-4337#account-contract-interface).
* **Properties**:
  * `client`: `Client` - The client used to interact with the blockchain.
  * `entryPoint`: `EntryPoint` - The entry point for the smart account.
  * `userOperation`: `UserOperationConfiguration?` - Configuration for the User
    Operation.

##### Methods

###### `getAddress`

* **Description**: Returns the address of the account.
* **Returns**: `String` - The account address.

###### `encodeCalls`

* **Description**: Encodes the given call data arguments.
* **Parameters**:
  * `args`: `[EncodeCallDataArg]` - The call data arguments to encode.
* **Returns**: `String` - The encoded call data.

###### `getFactoryArgs`

* **Description**: Retrieves the factory arguments for the smart account.
* **Returns**: `(String, String)?` - A pair containing the factory address and
  factory data.

###### `getNonce`

* **Description**: Retrieves the nonce for the smart account.
* **Parameters**:
  * `key`: `BigInt?` - Optional key to retrieve the nonce for.
* **Returns**: `BigInt` - The nonce value.

###### `getStubSignature`

* **Description**: Retrieves the stub signature for a User Operation.
* **Parameters**:
  * `userOp`: `T` - The User Operation.
* **Returns**: `String` - The stub signature.

###### `sign`

* **Description**: Signs the given hex string.
* **Parameters**:
  * `hex`: `String` - The hex string to sign.
* **Returns**: `String` - The signed string.

###### `signMessage`

* **Description**: Signs the given message.
* **Parameters**:
  * `message`: `String` - The message to sign.
* **Returns**: `String` - The signed message.

###### `signTypedData`

* **Description**: Signs the given typed data.
* **Parameters**:
  * `typedData`: `String` - The typed data to sign.
* **Returns**: `String` - The signed typed data.

###### `signUserOperation`

* **Description**: Signs the given user operation.
* **Parameters**:
  * `chainId`: `Long` - The chain ID for the user operation. Defaults to the
    chain ID of the client.
  * `userOp`: `UserOperationV07` - The user operation to sign.
* **Returns**: `String` - The signed user operation.

#### Class: `CircleSmartAccount`

* **Description**: Represents a Circle passkey account. A Smart Account
  implemented via a smart contract that adheres to the ERC-4337 interface.
* **Properties**:
  * `client`: `Client` - The blockchain client.
  * `owner`: `Account<SignResult>` - The associated owner account.
  * `entryPoint`: `EntryPoint` - The entry point for the account.
  * `wallet`: Wallet information.
  * `userOperation`: `UserOperationConfiguration?` - Configuration for the User
    Operation.
* **Conforms To**: `SmartAccount`

##### Methods

###### `getAddress`

* **Description**: Retrieves the account address.
* **Returns**: `String` - The account address.

###### `encodeCalls`

* **Description**: Encodes call data arguments.
* **Parameters**:
  * `args`: `[EncodeCallDataArg]` - The call data arguments.
* **Returns**: `String?` - The encoded call data.

###### `getFactoryArgs`

* **Description**: Retrieves factory arguments.
* **Returns**: `(String, String)?` - The factory arguments.
* **Throws**: `BaseError` if there is no initialization code.

###### `getNonce`

* **Description**: Retrieves the account's nonce.
* **Parameters**:
  * `key`: `BigInt?` - Optional key.
* **Returns**: `BigInt` - The nonce value.

###### `getStubSignature`

* **Description**: Retrieves a stub signature for a User Operation.
* **Parameters**:
  * `userOp`: `T` - The User Operation.
* **Returns**: `String` - The stub signature.

###### `sign`

* **Description**: Signs a hex string.
* **Parameters**:
  * `hex`: `String` - The hex string to sign.
* **Returns**: `String` - The signature.
* **Throws**: `BaseError` if signing fails.

###### `signMessage`

* **Description**: Signs a message.
* **Parameters**:
  * `message`: `String` - The message to sign.
* **Returns**: `String` - The signature.
* **Throws**: `BaseError` if signing fails.

###### `signTypedData`

* **Description**: Signs typed data.
* **Parameters**:
  * `jsonData`: `String` - The JSON data to sign.
* **Returns**: `String` - The signature.
* **Throws**: `BaseError` if signing fails.

###### `signUserOperation`

* **Description**: Signs a user operation.
* **Parameters**:
  * `chainId`: `Int` - The chain ID.
  * `userOp`: `UserOperationV07` - The user operation.
* **Returns**: `String` - The signature.
* **Throws**: `BaseError` if signing fails.

###### `getInitCode`

* **Description**: Retrieves the initialization code.
* **Returns**: `String?` - The initialization code.

***

### Utilities

#### Function: `encodeTransfer`

* **Description**: Encodes a transfer function call.
* **Parameters**:
  * `to`: `String` - The recipient address.
  * `token`: `String` - The token contract address or the name of Token enum.
    Supported tokens and their information are listed below.
  * `amount`: `BigInt` - The amount to transfer.
* **Returns**: `EncodeTransferResult` - The encoded transfer ABI and contract
  address.
* Supported Tokens:

##### Mainnet USDC

| Blockchain Network | Enum                | Contract Address                                                                                                                    |
| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum           | ArbitrumToken.USDC  | [`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`](https://arbiscan.io/token/0xaf88d065e77c8cc2239327c5edb3a432268e5831)                |
| Avalanche          | AvalancheToken.USDC | [`0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`](https://snowtrace.io/token/0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E?chainid=43114) |
| Base               | BaseToken.USDC      | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913)               |
| Monad              | MonadToken.USDC     | [`0x754704Bc059F8C67012fEd69BC8A327a5aafb603`](https://monadvision.com/token/0x754704Bc059F8C67012fEd69BC8A327a5aafb603)            |
| Optimism           | OptimismToken.USDC  | [`0x0b2c639c533813f4aa9d7837caf62653d097ff85`](https://optimistic.etherscan.io/token/0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85)    |
| Polygon            | PolygonToken.USDC   | [`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`](https://polygonscan.com/token/0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359)            |
| Unichain           | UnichainToken.USDC  | [`0x078D782b760474a361dDA0AF3839290b0EF57AD6`](https://uniscan.xyz/address/0x078D782b760474a361dDA0AF3839290b0EF57AD6)              |

##### Mainnet Native Tokens

| Blockchain Network | Token Name (Symbol) | Enum              | Contract Address                                                                                                                 |
| ------------------ | ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum           | Arbitrum (ARB)      | ArbitrumToken.ARB | [`0x912CE59144191C1204E64559FE8253a0e49E6548`](https://arbiscan.io/token/0x912ce59144191c1204e64559fe8253a0e49e6548)             |
| Optimism           | Optimism (OP)       | OptimismToken.OP  | [`0x4200000000000000000000000000000000000042`](https://optimistic.etherscan.io/token/0x4200000000000000000000000000000000000042) |

##### Testnet USDC

| Blockchain Network | Enum                      | Contract Address                                                                                                                            |
| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum Sepolia   | ArbitrumSepoliaToken.USDC | [`0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d`](https://sepolia.arbiscan.io/token/0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d)                |
| Arc Testnet        | ArcTestnetToken.USDC      | [`0x3600000000000000000000000000000000000000`](https://testnet.arcscan.app/address/0x3600000000000000000000000000000000000000)              |
| Avalanche Fuji     | AvalancheFujiToken.USDC   | [`0x5425890298aed601595a70AB815c96711a31Bc65`](https://testnet.snowtrace.io/token/0x5425890298aed601595a70AB815c96711a31Bc65?chainid=43113) |
| Base Sepolia       | BaseSepoliaToken.USDC     | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://base-sepolia.blockscout.com/address/0x036CbD53842c5426634e7929541eC2318f3dCF7e)      |
| Monad Testnet      | MonadTestnetToken.USDC    | [`0x534b2f3A21130d7a60830c2Df862319e593943A3`](https://testnet.monadexplorer.com/token/0x534b2f3A21130d7a60830c2Df862319e593943A3)          |
| Optimism Sepolia   | OptimismSepoliaToken.USDC | [`0x5fd84259d66Cd46123540766Be93DFE6D43130D7`](https://sepolia-optimism.etherscan.io/address/0x5fd84259d66Cd46123540766Be93DFE6D43130D7)    |
| Polygon Amoy       | PolygonAmoyToken.USDC     | [`0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582`](https://amoy.polygonscan.com/token/0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582)               |
| Unichain Sepolia   | UnichainSepoliaToken.USDC | [`0x31d0220469e10c4E71834a79b1f276d740d3768F`](https://unichain-sepolia.blockscout.com/address/0x31d0220469e10c4E71834a79b1f276d740d3768F)  |

#### Function: `encodeFunctionData`

* **Description**: Encodes the function name and parameters into an ABI-encoded
  value (4-byte selector and arguments).
* **Parameters**:
  * `functionName`: `String` - The name of the ABI function.
  * `abiJson`: `String` - The ABI JSON.
  * `args`: `[Any]` - The input arguments for the ABI function.
* **Returns**: `String?` - Optional encoded ABI function data.

#### Function: `encodeContractExecution`

* **Description**: Encodes a contract execution into calldata for executing a
  User Operation.
* **Parameters**:
  * `to`: `String` - The target address.
  * `abiSignature`: `String` - The ABI signature of the function.
  * `args`: `[Any]` - The arguments for the function.
  * `value`: `BigInt` - The value to send.
* **Returns**: `String` - The encoded contract execution function data.

#### Function: `parseGweiToWei`

* **Description**: Parses a positive Gwei value to Wei.
* **Parameters**:
  * `value`: `String` - The Gwei value as a string.
* **Returns**: `BigInt` - The Wei value.

#### Function: `parseEtherToWei`

* **Description**: Parses a positive Ether value to Wei.
* **Parameters**:
  * `value`: `String` - The Ether value as a string.
* **Returns**: `BigInt` - The Wei value.

***

### Models

#### Structure: `SignResult`

* **Description**: Represents the result of a signing operation.
* **Properties**:
  * `signature`: `String` - The signature generated by the signing operation.
  * `webAuthn`: `WebAuthnData` - The WebAuthn data associated with the signing
    operation.
  * `raw`: `AuthenticationCredential` - The raw authentication credential used
    in the signing operation.

#### Structure: `WebAuthnData`

* **Description**: Represents WebAuthn data.
* **Properties**:
  * `authenticatorData`: `String` - The authenticator data in hexadecimal
    format.
  * `challengeIndex`: `Int` - The index of the challenge in the client data
    JSON.
  * `clientDataJSON`: `String` - The client data JSON.
  * `typeIndex`: `Int` - The index of the type in the client data JSON.
  * `userVerificationRequired`: `Boolean` - Indicates whether user verification
    is required.

#### Structure: `EncodeCallDataArg`

* **Description**: A struct used to encode call data for smart contracts.
* **Conforms to**: Encodable
* **Properties**:
  * `to`: `String` - The target address for the call (required).
  * `value`: `BigInt?` - The amount of value to send with the call (optional,
    defaults to 0).
  * `data`: `String?` - The call data to be sent (optional, defaults to `"0x"`
    if not provided).
  * `abiJson`: `String?` - The ABI JSON of the smart contract function
    (optional).
  * `args`: `[AnyEncodable]?` - The arguments for the ABI function (optional).
  * `functionName`: `String?` - The name of the function to be called
    (optional).

#### Structure: `EstimateUserOperationGasResult`

* **Description**: Represents the result of estimating gas for a User Operation.
* **Conforms to**: `Codable`
* **Properties**:
  * `preVerificationGas`: `BigInt?` - The gas used for pre-verification.
  * `verificationGasLimit`: `BigInt?` - The gas limit for verification.
  * `callGasLimit`: `BigInt?` - The gas limit for the call.
  * `paymasterVerificationGasLimit`: `BigInt?` - The gas limit for paymaster
    verification.
  * `paymasterPostOpGasLimit`: `BigInt?` - The gas limit for paymaster
    post-operation.

#### Structure: `EstimateFeesPerGasResult`

* **Description**: Represents the result of estimating fees per gas.
* **Properties**:
  * `maxFeePerGas`: `BigInt?` - Maximum fee per gas (EIP-1559).
  * `maxPriorityFeePerGas`: `BigInt?` - Maximum priority fee per gas (EIP-1559).
  * `gasPrice`: `BigInt?` - Legacy gas price.

#### Structure: `GetUserOperationReceiptResult`

* **Description**: Response model for getting a User Operation receipt.
* **Properties**:
  * `userOpHash`: `String?` - The hash of the User Operation.
  * `sender`: `String?` - The sender address.
  * `nonce`: `String?` - The nonce value.
  * `actualGasCost`: `String?` - The actual gas cost in hexadecimal format.
  * `actualGasUsed`: `String?` - The actual gas used in hexadecimal format.
  * `success`: `Boolean?` - Indicates whether the operation was successful.
  * `paymaster`: `String?` - The paymaster address.
  * `logs`: `[Log]?` - The list of logs.
  * `receipt`: `UserOperationReceipt` - The User Operation receipt details.

#### Structure: `GetUserOperationResult`

* **Description**: Represents the result of retrieving a User Operation.
* **Conforms to**: `Codable`
* **Properties**:
  * `blockHash`: `String?` - The hash of the block containing the operation.
  * `blockNumber`: `BigInt?` - The number of the block containing the operation.
  * `transactionHash`: `String?` - The hash of the transaction for the
    operation.
  * `entryPoint`: `String?` - The entry point of the operation.
  * `userOperation`: `UserOperationType?` - The User Operation.

#### Structure: `UserOperationReceipt`

* **Description**: Represents the receipt of a User Operation.
* **Conforms to**: `Codable`
* **Properties**:
  * `transactionHash`: `String?` - The transaction hash.
  * `transactionIndex`: `String?` - The transaction index.
  * `blockHash`: `String?` - The block hash.
  * `blockNumber`: `String?` - The block number.
  * `from`: `String?` - The sender's address.
  * `to`: `String?` - The recipient's address.
  * `cumulativeGasUsed`: `String?` - The cumulative gas used.
  * `gasUsed`: `String?` - The gas used.
  * `logs`: `[Log]?` - The list of logs.
  * `logsBloom`: `String?` - The bloom filter for logs.
  * `status`: `String?` - The status of the operation.
  * `effectiveGasPrice`: `String?` - The effective gas price.

#### Structure: `Log`

* **Description**: Represents a log entry.
* **Conforms to**: `Codable`
* **Properties**:
  * `removed`: `Boolean?` - Indicates whether the log was removed.
  * `logIndex`: `String?` - The index of the log.
  * `transactionIndex`: `String?` - The index of the transaction.
  * `transactionHash`: `String?` - The transaction hash.
  * `blockHash`: `String?` - The block hash.
  * `blockNumber`: `String?` - The block number.
  * `address`: `String?` - The address of the contract generating the log.
  * `data`: `String?` - The log data.
  * `topics`: `[String]?` - The list of topics.

#### Structure: `GetPaymasterDataResult`

* **Description**: Represents the result of retrieving Paymaster data.
* **Conforms to**: `Codable`
* **Properties**:
  * `paymaster`: `String?` - The Paymaster address for entry point version 0.7.
  * `paymasterData`: `String?` - The Paymaster data for entry point version 0.7.
  * `paymasterPostOpGasLimit`: `BigInt?` - The gas limit for the Paymaster
    post-operation for entry point version 0.7.
  * `paymasterVerificationGasLimit`: `BigInt?` - The gas limit for the Paymaster
    verification for entry point version 0.7.
  * `paymasterAndData`: `String?` - The Paymaster and associated data for entry
    point version 0.6.

#### Structure: `GetPaymasterStubDataResult`

* **Description**: Represents the result of retrieving Paymaster stub data.
* **Conforms to**: `Codable`
* **Properties**:
  * `paymaster`: `String?` - The Paymaster address for entry point version 0.7.
  * `paymasterData`: `String?` - The Paymaster data for entry point version 0.7.
  * `paymasterPostOpGasLimit`: `BigInt?` - The gas limit for the Paymaster
    post-operation for entry point version 0.7.
  * `paymasterVerificationGasLimit`: `BigInt?` - The gas limit for the Paymaster
    verification for entry point version 0.7.
  * `paymasterAndData`: `String?` - The Paymaster and associated data for entry
    point version 0.6.
  * `isFinal`: `Boolean?` - Indicates whether the caller does not need to call
    `getPaymasterData`.
  * `sponsor`: `SponsorInfo?` - Sponsor information associated with the
    Paymaster.

#### Structure: `Block`

* **Description**: Represents a block in the Ethereum blockchain.
* **Conforms to**: `Codable`
* **Properties**:
  * `number`: `BigUInt` - The block number.
  * `hash`: `Data` - The block hash.
  * `parentHash`: `Data` - The parent block hash.
  * `nonce`: `Data?` - The block nonce (optional).
  * `sha3Uncles`: `Data` - The SHA3 hash of the uncles.
  * `logsBloom`: `EthereumBloomFilter?` - The bloom filter for the logs
    (optional).
  * `transactionsRoot`: `Data` - The root of the transactions trie.
  * `stateRoot`: `Data` - The root of the state trie.
  * `receiptsRoot`: `Data` - The root of the receipts trie.
  * `miner`: `EthereumAddress?` - The address of the miner.
  * `difficulty`: `BigUInt` - The difficulty of the block.
  * `totalDifficulty`: `BigUInt?` - The total difficulty of the chain up to this
    block.
  * `extraData`: `Data` - Extra data included in the block.
  * `size`: `BigUInt` - The size of the block.
  * `gasLimit`: `BigUInt` - The gas limit of the block.
  * `gasUsed`: `BigUInt` - The gas used in the block.
  * `baseFeePerGas`: `BigUInt?` - The base fee per gas (optional, present in
    EIP-1559 blocks).
  * `timestamp`: `Date` - The timestamp of the block.
  * `transactions`: `[TransactionInBlock]` - The list of transactions in the
    block.
  * `uncles`: `[Data]` - The list of uncle blocks.

#### Structure: `GetUserOperationGasPriceResult`

* **Description**: Represents the result of the `getUserOperationGasPrice`
  method.
* **Conforms to**: `Decodable`
* **Properties**:
  * `low`: `GasPriceOption` - The low-priority gas price option.
  * `medium`: `GasPriceOption` - The medium-priority gas price option.
  * `high`: `GasPriceOption` - The high-priority gas price option.
  * `deployed`: `BigInt?` - The verification gas for a deployed smart account
    (optional).
  * `notDeployed`: `BigInt?` - The verification gas for a non-deployed smart
    account (optional).

#### Structure: `GasPriceOption`

* **Description**: Represents a gas price option.
* **Conforms to**: `Decodable`
* **Properties**:
  * `maxFeePerGas`: `BigInt` - The maximum fee per gas.

#### Structure: `EncodeTransferResult`

* **Description**: The return type for `encodeTransfer`.
* **Properties**:
  * `data`: `String` - The encoded data.
  * `to`: `String` - The token address.

#### Enum: `EntryPoint`

* **Description**: Represents entry points with their respective addresses.
* **Properties**:
  * `address`: `String` - The address of the entry point.
* **Entries**:
  * `v07` - Represents the entry point version 0.7 with its respective address.

#### Class: `Paymaster`

* **Description**: A sealed class for setting User Operation Paymaster
  configuration.
  * If the Paymaster is a `PaymasterClient`, it uses the provided Paymaster
    Client for sponsorship.
  * If the Paymaster is `true`, it assumes that the Bundler Client supports
    Paymaster RPC methods (e.g. `getPaymasterData`) and uses them for
    sponsorship.

##### Subclasses

###### `True`

* **Description**: Represents a Paymaster configuration where the Bundler Client
  supports Paymaster RPC methods.
* **Properties**:
  * `paymasterContext`: `[String: AnyEncodable]?` - Optional context for the
    Paymaster.

###### `Client`

* **Description**: Represents a Paymaster configuration using a provided
  Paymaster Client for sponsorship.
* **Properties**:
  * `client`: `PaymasterClient` - The Paymaster Client used for sponsorship.
  * `paymasterContext`: `[String: AnyEncodable]?` - Optional context for the
    Paymaster.

#### Protocol: `PublicKeyCredential`

* **Description**: Represents a public key credential, with the following
  derived structures:
  * `RegistrationCredential`
  * `AuthenticationCredential`
* **Properties**:
  * `id`: `String` - The unique identifier for the credential.
  * `type`: `String` - The type of the credential.
  * `authenticatorAttachment`: `String` - The attachment type of the
    authenticator.
  * `response`: `AuthenticatorResponse` - The response from the authenticator.
  * `clientExtensionResults`: `AuthenticationExtensionsClientOutputs?` -
    Optional client extension results.

#### Structure: `RegistrationCredential`

* **Description**: Represents a registration credential.
* **Conforms To**: `PublicKeyCredential`
* **Properties**:
  * `rawId`: `String` - The raw identifier for the credential.
  * `authenticatorAttachment`: `String` - The attachment type of the
    authenticator.
  * `type`: `String` - The type of the credential.
  * `id`: `String` - The unique identifier for the credential.
  * `response`: `AuthenticatorAttestationResponse` - The attestation response
    from the authenticator.
  * `clientExtensionResults`: `AuthenticationExtensionsClientOutputs?` -
    Optional client extension results.

#### Structure: `AuthenticationCredential`

* **Description**: Represents an authentication credential.
* **Conforms To**: `PublicKeyCredential`
* **Properties**:
  * `rawId`: `String` - The raw identifier for the credential.
  * `authenticatorAttachment`: `String` - The attachment type of the
    authenticator.
  * `type`: `String` - The type of the credential.
  * `id`: `String` - The unique identifier for the credential.
  * `response`: `AuthenticatorAssertionResponse` - The assertion response from
    the authenticator.
  * `clientExtensionResults`: `AuthenticationExtensionsClientOutputs?` -
    Optional client extension results.

#### Protocol: `UserOperation`

* **Description**: Represents a user operation, with the following derived
  classes:
  * `UserOperationV07`
* **Properties**:
  * `sender`: `String?` - The address of the sender.
  * `nonce`: `BigInt?` - The nonce of the operation.
  * `callData`: `String?` - The data to be sent in the call.
  * `callGasLimit`: `BigInt?` - The gas limit for the call.
  * `verificationGasLimit`: `BigInt?` - The gas limit for verification.
  * `preVerificationGas`: `BigInt?` - The gas used before verification.
  * `maxPriorityFeePerGas`: `BigInt?` - The maximum priority fee per gas.
  * `maxFeePerGas`: `BigInt?` - The maximum fee per gas.
  * `signature`: `String?` - The signature of the operation.

#### Class: `UserOperationV07`

* **Description**: Data class representing a user operation for version 0.7.
* **Conforms To**: `UserOperation`
* **Properties**:
  * `sender`: `String?` - The address of the sender.
  * `nonce`: `BigInt?` - The nonce of the operation.
  * `callData`: `String?` - The data to be sent in the call.
  * `callGasLimit`: `BigInt?` - The gas limit for the call.
  * `verificationGasLimit`: `BigInt?` - The gas limit for verification.
  * `preVerificationGas`: `BigInt?` - The gas used before verification.
  * `maxPriorityFeePerGas`: `BigInt?` - The maximum priority fee per gas.
  * `maxFeePerGas`: `BigInt?` - The maximum fee per gas.
  * `signature`: `String?` - The signature of the operation.
  * `factory`: `String?` - The factory address.
  * `factoryData`: `String?` - The data for the factory.
  * `paymaster`: `String?` - The Paymaster address.
  * `paymasterVerificationGasLimit`: `BigInt?` - The gas limit for Paymaster
    verification.
  * `paymasterPostOpGasLimit`: `BigInt?` - The gas limit for Paymaster
    post-operation.
  * `paymasterData`: `String?` - The data for the Paymaster.

#### Enum: `WebAuthnMode`

* **Description**: Represents the WebAuthn modes.
* **Entries**:
  * `Register` - Mode for registering a new credential.
  * `Login` - Mode for logging in with an existing credential.

#### Enum: `ArbitrumToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`
  * `ARB`

#### Enum: `ArbitrumSepoliaToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `ArcTestnetToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `AvalancheToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `AvalancheFujiToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `BaseToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `BaseSepoliaToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `OptimismToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`
  * `OP`

#### Enum: `OptimismSepoliaToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `PolygonToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `PolygonAmoyToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `UnichainToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Enum: `UnichainSepoliaToken`

* **Description**: Enum representing various tokens supported by
  `encodeTransfer`. The format is `{chain}_{symbol}`.
* **Entries**:
  * `USDC`

#### Structure: `ModularWallet`

* **Description**: Represents a wallet entity within the system.
* **Conforms To**: `Codable`
* **Properties**:
  * `id`: `String?` - The unique identifier of the wallet.
  * `address`: `String?` - The blockchain address of the wallet.
  * `blockchain`: `String?` - The blockchain network the wallet is associated
    with.
  * `state`: `String?` - The current state of the wallet.
  * `name`: `String?` - The name of the wallet.
  * `scaCore`: `String?` - The SCA (Strong Customer Authentication) core
    identifier.
  * `scaConfiguration`: `ScaConfiguration?` - The SCA configuration associated
    with the wallet.
  * `createDate`: `String?` - The creation date of the wallet.
  * `updateDate`: `String?` - The last update date of the wallet.

##### Methods

###### `getInitCode`

* **Description**: Retrieves the initialization code for the wallet.
* **Returns**: `String?` - The initialization code from the SCA configuration,
  if available.

***

### Chains

#### Protocol: `Chain`

* **Description**: Abstract class representing the necessary definitions of a
  blockchain for the SDK.
* **Predefined Chains**:
  * `Arbitrum`
  * `ArbitrumSepolia`
  * `ArcTestnet`
  * `Avalanche`
  * `AvalancheFuji`
  * `Base`
  * `BaseSepolia`
  * `Monad`
  * `MonadTestnet`
  * `Optimism`
  * `OptimismSepolia`
  * `Polygon`
  * `PolygonAmoy`
  * `Unichain`
  * `UnichainSepolia`
* **Properties**:
  * `chainId`: `Int` - The unique identifier for the blockchain.


# Modular Wallet Operations
Source: https://developers.circle.com/wallets/modular/key-features



Modular wallets are built on smart accounts that extend functionality through
modules. This allows developers to tailor specific use cases and enable key
operations such as:

* [Create a Circle Smart Account](#create-a-circle-smart-account): Set up a
  passkey-backed smart account and bundler client for seamless Web3 integration.
* [Send a user operation](#send-a-user-operation). Enable blockchain operations
  without requiring users to send a transaction directly.
* [Send a gasless user operation](#send-a-gasless-user-operation). Enables
  developers to cover network fees on behalf of users, simplifying blockchain
  interactions.
* [Batch transactions in one user operation](#batch-transactions-in-one-user-operation).
  Combine multiple transactions into a single call for efficiency.
* [Execute user operations in parallel](#execute-user-operations-in-parallel).
  Execute independent transactions simultaneously using 2D nonces.
* [Sign and verify messages](#sign-and-verify-messages). Perform secure
  operations like signing messages and verifying signatures.
* [Use the EIP-1193 provider](#use-the-eip-1193-provider). Expose modular
  wallets to third-party Web3 SDKs.

Explore these key features in more detail below.

## Create a Circle Smart Account

Circle Smart Accounts allow users to set up passkeys and utilize biometrics
verification for signing, which provides a seamless Web3 experience. Smart
Accounts are built on top of **Viem** and adhere to the **ERC-6900** and
**ERC-4337 (v0.7)** standards. Advanced use cases are supported through modules.

<CodeGroup>
  ```javascript Web SDK theme={null}
  // 1. register or login with a passkey
  const passkeyTransport = toPasskeyTransport(clientUrl, clientKey);
  const credential = await toWebAuthnCredential({
    transport: passkeyTransport,
    mode: WebAuthnMode.Register, //or WebAuthnMode.Login if login
    username: "my-passkey",
  });

  // 2. create a public client
  const modularTransport = toModularTransport(
    clientUrl + "/polygonAmoy",
    clientKey,
  );
  const client = createPublicClient({
    chain: polygonAmoy,
    transport: modularTransport,
  });

  // 3. create a circle smart account
  const smartAccount = await toCircleSmartAccount({
    client,
    owner: toWebAuthnAccount({
      credential,
    }),
  });

  // 4. create a bundler client
  const bundlerClient = createBundlerClient({
    smartAccount,
    chain: polygonAmoy,
    transport: modularTransport,
  });
  ```

  ```swift iOS SDK theme={null}
  import CircleModularWalletsCore

  let CLIENT_KEY = "xxxxxxx:xxxxx"

  Task {
      do {
          // 1. Register or login with a passkey and
          //    Create a Passkey Transport with client key
          let transport = toPasskeyTransport(clientKey: CLIENT_KEY)

          let credential =
              try await toWebAuthnCredential(
                  transport: transport,
                  userName: "MyExampleName", // userName
                  mode: WebAuthnMode.register // or WebAuthnMode.login
              )

          // 2. Create a WebAuthn owner account from the credential
          let webAuthnAccount = toWebAuthnAccount(
              credential
          )

          // 3. Create modular transport from client key and client url
          let modularTransport = toModularTransport(
              clientKey: CLIENT_KEY,
              url: clientUrl
          )

          // 4. Create a bundler client
          let bundlerClient = BundlerClient(
              chain: PolygonAmoy,
              transport: modularTransport
          )

          // 5. Create smart account (CircleSmartAccount)
          //    and set the WebAuthn account as the owner
          let smartAccount =
              try await toCircleSmartAccount(
                  client: bundlerClient,
                  owner: webAuthnAccount
              )
  ```

  ```java Android SDK theme={null}
  val CLIENT_KEY = "xxxxxxx:xxxxx"

  CoroutineScope(Dispatchers.IO).launch {
      try {
          // 1. Register or login with a passkey and
          //    Create a Passkey Transport with client key
          val transport = toPasskeyTransport(context, CLIENT_KEY, clientUrlWithoutChain)

          val credential = toWebAuthnCredential(
              context,
              transport,
              "MyExampleName", // userName
              WebAuthnMode.Register // or WebAuthnMode.Login
          )
          // 2. Create a WebAuthn owner account from the credential
          val webAuthnAccount = toWebAuthnAccount(
              credential,
          )

          // 3. Create modular transport from client url and client key
          val modularTransport = toModularTransport(
              context,
              CLIENT_KEY,
              clientUrl
          )

          // 4. create a bundlerClient
          val bundlerClient = BundlerClient(
              PolygonAmoy,
              modularTransport,
          )

          // 5. Create smart account (CircleSmartAccount)
          //    and set the WebAuthn account as the owner
          val smartAccount = toCircleSmartAccount(
              bundlerClient,
              webAuthnAccount,
          )
  ```

  ```java Android SDK (Java) theme={null}
  final String CLIENT_KEY = "xxxxxxx:xxxxx";
  try {
      // 1. Register or login with a passkey and
      //    Create a Passkey Transport with client key
      HttpTransport transport = toPasskeyTransport(
          context,
          CLIENT_KEY,
          clientUrlWithoutChain
      );
      CompletableFuture<WebAuthnCredential> suspendResult = new CompletableFuture<>();
      toWebAuthnCredential(
          context,
          transport,
          "MyExampleName",
          WebAuthnMode.Register, // or WebAuthnMode.Login
          new CustomContinuation<>(suspendResult)
      ); // see CustomContinuation in "Creating a Custom Continuation" from Android SDK
      WebAuthnCredential credential = suspendResult.join();
      // 2. Create a WebAuthn owner account from the credential
      WebAuthnAccount webAuthnAccount = toWebAuthnAccount(credential);
      // 3. Create modular transport from chain and client key
      Transport modularTransport = toModularTransport(
          context,
          CLIENT_KEY,
          clientUrl
      );
      // 4. Create a bundler client
      BundlerClient bundlerClient = new BundlerClient(PolygonAmoy.INSTANCE, modularTransport);
      // 5. Create Smart Account (CircleSmartAccount)
      //    and set the WebAuthn account as the owner
      CompletableFuture<CircleSmartAccount> suspendAccount = new CompletableFuture<>();
      toCircleSmartAccount(pubClient, webAuthnAccount, new CustomContinuation<>(suspendAccount));
      CircleSmartAccount smartAccount = suspendSmartAccount.join();
  } catch (Exception e) {
      e.printStackTrace()
  }
  ```
</CodeGroup>

## Send a user operation

The sample code below demonstrates how to send a transaction, also known as a
User Operation (**userOp**) in the context of **Account Abstraction (AA)**, to
the Bundler.

<CodeGroup>
  ```javascript Web SDK theme={null}
  // 5. send a user operation
  const userOpHash = await bundlerClient.sendUserOperation({
    calls: [
      {
        to: "0x...abc",
        value: parseEther("1"),
      },
    ],
  });

  // 6. wait for transaction receipt
  const { receipt } = await bundlerClient.waitForUserOperationReceipt({
    userOpHash,
  });
  ```

  ```swift iOS SDK theme={null}
          // 6. Send a User Operation to the Bundler.
          //    Here we send 1 ETH to a random address.
          let userOpHash = try await bundlerClient.sendUserOperation(
              account: smartAccount,
              calls: [
                  EncodeCallDataArg(
                      to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
                      value: UnitUtils.parseEtherToWei("1")
                  )
              ]
          )
          // 7. wait for transaction receipt
          let receipt = try await bundlerClient.waitForUserOperationReceipt(userOpHash: userOpHash)
      }
      catch {
          print(error)
      }
  }
  ```

  ```java Android SDK theme={null}
          // 6. Send a User Operation to the Bundler.
          //    Here we send 1 ETH to a random address.
          val userOpHash = bundlerClient.sendUserOperation(
              context,
              smartAccount,
              arrayOf(
                  EncodeCallDataArg(
                      "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // to
                      parseEther("1"), // value
                  )
              )
          )
          // 7. wait for transaction receipt
          val receipt = bundlerClient.waitForUserOperationReceipt(userOpHash)
      }
      catch (e: Exception) {
          e.printStackTrace()
      }
  }
  ```

  ```java Android SDK (Java) theme={null}
          // 6. Send an User Operation to the Bundler.
          //    Here we send 1 ETH to a random address.
          EncodeCallDataArg ethTransfer = new EncodeCallDataArg(
              "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // to
              parseEther("1") // value
          );
          UserOperationV07 partialUserOp = new UserOperationV07();
          CompletableFuture<String> suspendUserOpHash = new CompletableFuture<>();
          bundlerClient.sendUserOperation(
              context,
              smartAccount,
              new EncodeCallDataArg[] {
                  ethTransfer
              },
              partialUserOp,
              new CustomContinuation<>(suspendUserOpHash)
          );
          String userOpHash = suspendUserOpHash.join();
          // 7. wait for transaction receipt
          CompletableFuture<UserOperationReceipt> suspendReceipt = new CompletableFuture<>();
          bundlerClient.waitForUserOperationReceipt(userOpHash, new CustomContinuation<>(suspendReceipt));
          UserOperationReceipt receipt = suspendReceipt.join();
      }
      catch (Exception e) {
          e.printStackTrace()
      }
  }
  ```
</CodeGroup>

## Send a gasless user operation

Gasless transactions, in the context of **Account Abstraction (AA)**, allow
users to perform blockchain operations without needing to hold native tokens for
gas fees. Circle provides the **Gas Station** service, enabling developers to
sponsor network fees on behalf of users. This feature addresses the common
challenge of requiring native tokens for onchain activities, simplifying
blockchain interactions for end users by eliminating the need to manage token
balances.

<Note>
  **Info:**

  To use Gas Station on the mainnet:

  * Set up a policy in the Circle Console.
  * Sponsored fees are charged to the payment method on file.

  To enable Gas Station in your app, set the `paymaster` parameter to `true` when
  invoking any applicable `*userOperation*()` method. See sample code below that
  sponsors gas fees.
</Note>

<CodeGroup>
  ```javascript Web SDK theme={null}
  import { http, parseEther } from "viem";
  import {
    createBundlerClient,
    createPaymasterClient,
  } from "viem/account-abstraction";
  import { polygonAmoy } from "viem/chains";
  import { toModularTransport } from "@circle-fin/modular-wallets-core";

  const clientUrl = "your-client-url";
  const clientKey = "your-client-key";

  // 1. Create modular transport from client url and clientKey
  const modularTransport = toModularTransport(clientUrl, clientKey);

  // 2. Create a bundler client
  const bundlerClient = createBundlerClient({
    chain: polygonAmoy,
    transport: modularTransport,
  });

  // 3. Specify `paymaster: true` to sponsor gas fees
  const userOpHash = await bundlerClient.sendUserOperation({
    smartAccount, // Assume `smartAccount` is an instance of `toCircleSmartAccount`
    calls: [
      {
        to: "0x1234567890123456789012345678901234567890",
        value: parseEther("0.1"),
      },
    ],
    paymaster: true,
  });
  ```

  ```swift iOS SDK theme={null}
  import CircleModularWalletsCore

  let CLIENT_KEY = "xxxxxxx:xxxxx"

  Task {
      do {
          // 1. Create modular transport from clientKey and client url
          let modularTransport = toModularTransport(
              clientKey: CLIENT_KEY,
              url: clientUrl
          )

          // 2. Create a bundler client
          let bundlerClient = BundlerClient(
              chain: PolygonAmoy,
              transport: modularTransport
          )

          // 3. Pass Paymaster.True() as paymaster parameter to sendUserOperation() /
          //    estimateUserOperationGas() / prepareUserOperation() to sponsor gas fees
          let userOpHash = bundlerClient.sendUserOperation(
              account: smartAccount,
              calls: [
                  EncodeCallDataArg(
                      to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
                      value: BigInt.zero
                  )
              ],
              paymaster: Paymaster.True()
          )
      } catch {
          print("Error: ...")
      }
  }
  ```

  ```java Android SDK theme={null}
  val CLIENT_KEY = "xxxxxxx:xxxxx"

  CoroutineScope(Dispatchers.IO).launch {
      try {
          // 1. Create modular transport from client url and clientKey
          val modularTransport = toModularTransport(
              context,
              CLIENT_KEY,
              clientUrl
          )

          // 2. create a bundlerClient
          val bundlerClient = BundlerClient(
              PolygonAmoy,
              modularTransport,
          )

          // 3. Pass Paymaster.True() as paymaster parameter to sendUserOperation() /
          //    estimateUserOperationGas() / prepareUserOperation() to sponsor gas fees
          val userOpHash = bundlerClient.sendUserOperation(
              context,
              smartAccount,
              arrayOf(
                  EncodeCallDataArg(
                      "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
                      BigInteger.ZERO
                  )
              ),
              paymaster = Paymaster.True()
          )
      } catch (e: Exception) {
          e.printStackTrace()
      }
  }
  ```

  ```java Android SDK (Java) theme={null}
  final String CLIENT_KEY = "xxxxxxx:xxxxx";
  try {
      // 1. Create modular transport with client url and client key
      Transport modularTransport = toModularTransport(
          context,
          CLIENT_KEY,
          clientUrl
      );
      // 2. Create a bundler client
      BundlerClient bundlerClient = new BundlerClient(PolygonAmoy.INSTANCE, modularTransport);

      // 3. Pass Paymaster.True() as paymaster parameter to sendUserOperation() /
      //    estimateUserOperationGas() / prepareUserOperation() to sponsor gas fees
      EncodeCallDataArg ethTransfer = new EncodeCallDataArg(
          "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // to
          BigInteger.ZERO // value
      );
      UserOperationV07 partialUserOp = new UserOperationV07();
      CompletableFuture<String> suspendUserOpHash = new CompletableFuture<>();
      bundlerClient.sendUserOperation(
          context,
          smartAccount,
          new EncodeCallDataArg[]{
              ethTransfer
          },
          partialUserOp,
          new Paymaster.True(),
          new CustomContinuation<>(suspendUserOpHash)
      );
      String hash = suspendUserOpHash.join();
  } catch (Exception e) {
      e.printStackTrace()
  }
  ```
</CodeGroup>

## Batch transactions in one user operation

Modular wallets support sending multiple transactions into a single call. This
approach simplifies the user experience and improves gas efficiency. For
instance, users can approve multiple transfers or swaps with a single signature.

See the sample code below for sending batch transactions.

<CodeGroup>
  ```javascript Web SDK theme={null}
  import { parseEther } from "viem";
  import { createBundlerClient } from "viem/account-abstraction";
  import { polygonAmoy } from "viem/chains";
  import { toModularTransport } from "@circle-fin/modular-wallets-core";

  const clientUrl = "your-client-url";
  const clientKey = "your-client-key";

  // 1. Create modular transport from client url and clientKey
  const modularTransport = toModularTransport(clientUrl, clientKey);

  // 2. Create a bundler client
  const bundlerClient = createBundlerClient({
    chain: polygonAmoy,
    transport: modularTransport,
  });

  // 3. Send batch transactions in user operation using the bundler client
  const userOpHash = await bundlerClient.sendUserOperation({
    smartAccount, // Assume `smartAccount` is an instance of `toCircleSmartAccount`
    calls: [
      {
        to: "0x1234567890123456789012345678901234567890",
        value: parseEther("1"),
      },
      {
        to: "0x9876543210987654321098765432109876543210",
        value: parseEther("2"),
      },
    ],
  });
  ```

  ```swift iOS SDK theme={null}
  import CircleModularWalletsCore

  let CLIENT_KEY = "xxxxxxx:xxxxx"

  Task {
      do {
          // 1. Register or login with a passkey and
          //    Create a Passkey Transport with client key
          let transport = toPasskeyTransport(clientKey: CLIENT_KEY)

          let credential = try await toWebAuthnCredential(
              transport: transport,
              userName: "MyExampleName", // userName
              mode: WebAuthnMode.register // or WebAuthnMode.login
          )

          // 2. Create a WebAuthn owner account from the credential.
          let webAuthnAccount = toWebAuthnAccount(
              credential
          )

          // 3. Create modular transport from clientKey and client url
          let modularTransport = toModularTransport(
              clientKey: CLIENT_KEY,
              url: clientUrl
          )

          // 4. Create a bundler client
          let bundlerClient = BundlerClient(
              chain: PolygonAmoy,
              transport: modularTransport
          )

          // 5. Create smart account (CircleSmartAccount)
          //    and set the WebAuthn account as the owner
          let smartAccount = try await toCircleSmartAccount(
              client: bundlerClient,
              owner: webAuthnAccount
          )

          // 6. Send batch transactions in user operation to the Bundler.
          //    Here we send 1 and 2 ETH to random addresses.
          let userOpHash = bundlerClient.sendUserOperation(
              account: smartAccount,
              calls: [
                  EncodeCallDataArg(
                      to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
                      value: UnitUtils.parseEtherToWei("1")
                  ),
                  EncodeCallDataArg(
                      to: "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      value: UnitUtils.parseEtherToWei("2")
                  )
              ]
          )
      } catch {
          print(error)
      }
  }
  ```

  ```java Android SDK theme={null}
  val CLIENT_KEY = "xxxxxxx:xxxxx"

  CoroutineScope(Dispatchers.IO).launch {
      try {
          // 1. Register or login with a passkey and
          //    Create a Passkey Transport with client key
          val transport = toPasskeyTransport(context, CLIENT_KEY, clientUrlWithoutChain)

          val credential = toWebAuthnCredential(
              context,
              transport,
              "MyExampleName", // userName
              WebAuthnMode.Register // or WebAuthnMode.Login
          )

          // 2. Create a WebAuthn owner account from the credential.
          val webAuthnAccount = toWebAuthnAccount(
              credential,
          )

          // 3. Create modular transport from client url and client key
          val modularTransport = toModularTransport(
              context,
              CLIENT_KEY,
              clientUrl
          )

          // 4. Create a bundlerClient
          val bundlerClient = BundlerClient(
              PolygonAmoy,
              modularTransport,
          )

          // 5. Create smart account (CircleSmartAccount)
          //    and set the WebAuthn account as the owner
          val smartAccount = toCircleSmartAccount(
              bundlerClient,
              webAuthnAccount,
          )

          // 6. Send batch transactions in user operation to the Bundler.
          //    Here we send 1 and 2 ETH to random addresses.
          val userOpHash = bundlerClient.sendUserOperation(
              context,
              smartAccount,
              arrayOf(
                  EncodeCallDataArg(
                      "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // to
                      parseEther("1"), // value
                  ),
                  EncodeCallDataArg(
                      "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", // to
                      parseEther("2"), // value
                  )
              )
          )
      } catch (e: Exception) {
          e.printStackTrace()
      }
  }
  ```

  ```java Android SDK (Java) theme={null}
  final String CLIENT_KEY = "xxxxxxx:xxxxx";
  try {
      // 1. Register or login with a passkey and
      //    Create a Passkey Transport with client key
      HttpTransport transport = toPasskeyTransport(
          context,
          CLIENT_KEY,
          clientUrlWithoutChain
      );
      CompletableFuture<WebAuthnCredential> suspendResult = new CompletableFuture<>();
      toWebAuthnCredential(
          context,
          transport,
          "MyExampleName",
          WebAuthnMode.Register, // or WebAuthnMode.Login
          new CustomContinuation<>(suspendResult)
      ); // see CustomContinuation in "Creating a Custom Continuation" from Android SDK
      WebAuthnCredential credential = suspendResult.join();

      // 2. Create a WebAuthn owner account from the credential.
      WebAuthnAccount webAuthnAccount = toWebAuthnAccount(credential);

      // 3. Create modular transport with client url and client key
      Transport modularTransport = toModularTransport(
          context,
          CLIENT_KEY,
          clientUrl
      );

      // 4. Create a bundler client
      BundlerClient bundlerClient = new BundlerClient(PolygonAmoy.INSTANCE, modularTransport);

      // 5. Create smart account (CircleSmartAccount)
      //    and set the WebAuthn account as the owner
      CompletableFuture<CircleSmartAccount> suspendAccount = new CompletableFuture<>();
      toCircleSmartAccount(bundlerClient, webAuthnAccount, new CustomContinuation<>(suspendAccount));
      CircleSmartAccount smartAccount = suspendSmartAccount.join();

      // 6. Send batch transactions in user operation to the Bundler.
      //    Here we send 1 and 2 ETH to random addresses.
      EncodeCallDataArg ethTransfer1 = new EncodeCallDataArg(
                  "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // to
                  parseEther("1") // value
      );
      EncodeCallDataArg ethTransfer2 = new EncodeCallDataArg(
                  "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", // to
                  parseEther("2") // value
      );
      UserOperationV07 partialUserOp = new UserOperationV07();
      CompletableFuture<String> suspendUserOpHash = new CompletableFuture<>();
      bundlerClient.sendUserOperation(
              context,
              smartAccount,
              new EncodeCallDataArg[]{
                      ethTransfer1,
                      ethTransfer2
              },
              partialUserOp,
              new Paymaster.True(),
              new CustomContinuation<>(suspendUserOpHash)
      );
      String hash = suspendUserOpHash.join();
  } catch (Exception e) {
      e.printStackTrace()
  }
  ```
</CodeGroup>

## Execute user operations in parallel

Traditional **Externally Owned Accounts (EOA)** process transactions
sequentially using a linear nonce (e.g., 1, 2, 3). This requires each
transaction to complete before the next begins.

In contrast, **smart accounts** support **2D nonces**, which consist of:

* **Nonce key**
* **Nonce value**

This two-dimensional approach enables parallel transaction execution for
independent operations.

### Example Scenario

A user wants to execute three trades:

1. Swap 100 USDT for DAI (transaction 1)
2. Swap 100 DAI for USDC (transaction 2)
3. Swap 1 WETH for USDC (transaction 3)

Transactions 1 and 2 are dependent and must execute sequentially. Transaction 3,
however, is independent and can execute in parallel with the first two.

<Note>
  **Info:**

  To enable parallel transactions:

  * Ensure the `nonceKey` is greater than 0; a `nonceKey` of 0 defaults to linear
    nonces.
  * Avoid dependencies between `userOps`.
  * Don't wait for each `userOp` to execute, as this negates the benefits of
    parallelism.
</Note>

To send parallel transactions through `userOps`, use "nonce keys" to compute a
nonce. See sample code below.

<CodeGroup>
  ```javascript Web SDK theme={null}
  // Assume `userOps` is an array of user operations to be sent
  // and `smartAccount` is an instance of `toCircleSmartAccount` to handle signing

  const signedUserOps: UserOperation[] = [];

  // Sequentially sign each userOp and store the result
  userOps.forEach(async (userOp, index) => {
    try {
      const nonce = await smartAccount.getNonce({
        // Use the nonceKey to compute nonce
        key: BigInt(userOp.nonce ?? index + 1),
      });
      const signature = await smartAccount.signUserOperation({
        ...userOp,
        nonce,
      });
      signedUserOps.push({ ...userOp, nonce, signature });
    } catch (error) {
      // Handle the error (e.g., skip, retry)
      console.error("Error signing user operation:", error);
    }
  });

  // Send all signed user operations in parallel
  await Promise.all(
    signedUserOps.map(async (userOp) => {
      try {
        return await bundlerClient.sendUserOperation({
          smartAccount,
          ...userOp,
        });
      } catch (error) {
        // Handle the error (e.g., retry)
        console.error("Error sending user operation:", error);
      }
    })
  );
  ```

  ```swift iOS SDK theme={null}
  var signedUserOps: [UserOperationV07] = []

  // Sequentially sign each userOp and store the result
  for (index, userOp) in userOps.enumerated() {
      do {
          let nonceKey = userOp.nonce ?? BigInt(index + 1)
          let nonce = try await smartAccount.getNonce(key: nonceKey)
          var signedUserOp = userOp
          signedUserOp.nonce = nonce
          signedUserOp.signature = try await smartAccount.signUserOperation(
              chainId: smartAccount.client.chain.chainId,
              userOp: signedUserOp
          )
          signedUserOps.append(signedUserOp)
      } catch {
          // Handle the error (e.g., skip, retry)
          print("Error signing user operation: \(error)")
      }
  }

  // Send all signed user operations in parallel
  await withTaskGroup(of: Void.self) { group in
      for userOp in signedUserOps {
          group.addTask {
              do {
                  let sendResult = try await bundlerClient.sendUserOperation(
                      account: smartAccount,
                      calls: nil,
                      partialUserOp: userOp
                  )
                  print(sendResult)
              } catch {
                  // Handle the error (e.g., retry)
                  print("Error sending user operation: \(error)")
              }
          }
      }
  }
  ```

  ```java Android SDK theme={null}
  val signedUserOps = mutableListOf<UserOperationV07>()

  // Sequentially sign each userOp and store the result
  userOps.forEachIndexed { index, userOp ->
      CoroutineScope(Dispatchers.IO).launch {
          try {
              val chain = PolygonAmoy
              val nonceKey = userOp.nonce ?: BigInteger("${index + 1}")
              val nonce = smartAccount.getNonce(key = nonceKey)
              val signature = smartAccount.signUserOperation(
                  context,
                  chain.chainId,
                  userOp.copy(nonce = nonce)
              )
              signedUserOps.add(userOp.copy(nonce = nonce, signature = signature))
          } catch (error: Exception) {
              // Handle error (e.g., log or skip operation)
              Log.e(TAG, "Error signing user operation at index $index: ${error.message}")
          }
      }
  }

  // Send all signed user operations in parallel
  CoroutineScope(Dispatchers.IO).launch {
      val sendOperations = signedUserOps.map { userOp ->
          async {
              try {
                  bundlerClient.sendUserOperation(
                      context,
                      smartAccount,
                      calls = null,
                      partialUserOp = userOp
                  )
              } catch (error: Exception) {
                  // Handle error (e.g., retry logic)
                  Log.e(TAG, "Error sending user operation: ${error.message}")
              }
          }
      }
      // Wait for all send operations to complete
      sendOperations.awaitAll()
  }
  ```

  ```java Android SDK (Java) theme={null}
  List<UserOperationV07> signedUserOps = new ArrayList<>();

  // Sequentially sign each userOp and store the result
  for (int i = 0; i < userOps.size(); i++) {
      try {
          Chain chain = PolygonAmoy.INSTANCE;
          UserOperationV07 userOp = userOps.get(i);
          BigInteger nonceKey = userOp.getNonce() == null ? BigInteger.valueOf(i + 1) : userOp.getNonce();
          CompletableFuture<BigInteger> suspendNonce = new CompletableFuture<>();
          smartAccount.getNonce(nonceKey, new CustomContinuation<>(suspendNonce));
          BigInteger nonce = suspendNonce.join();
          userOp.setNonce(nonce);

          CompletableFuture<String> suspendSignature = new CompletableFuture<>();
          smartAccount.signUserOperation(ApplicationProvider.getApplicationContext(), chain.getChainId(), userOp, new CustomContinuation<>(suspendSignature));
          String signature = suspendSignature.join();
          userOp.setSignature(signature);
          signedUserOps.add(userOp);
      } catch (Exception error) {
          // Handle error (e.g., log or skip operation)
          Log.e(TAG, String.format("Error signing user operation at index %d: %s", i, error.message))
      }
  }

  // Send all signed user operations in parallel
  List<CompletableFuture<String>> sendOperations = signedUserOps.stream()
      .map(userOp -> {
          try {
              CompletableFuture<String> suspendUserOpHash = new CompletableFuture<>();
              bundlerClient.sendUserOperation(
                  context,
                  smartAccount,
                  null, // calls
                  userOp,
                  new Paymaster.True(),
                  new CustomContinuation<>(suspendUserOpHash));
              return suspendUserOpHash;
          } catch (Exception e) {
              e.printStackTrace();
              throw new RuntimeException(e);
          }
      })
      .collect(Collectors.toList());

      CompletableFuture<Void> all = CompletableFuture.allOf(sendOperations.toArray(new CompletableFuture[0]));
      // Wait for all send operations to complete
  all.join();
  ```
</CodeGroup>

## Sign and verify messages

Circle Smart Accounts enable signing and verifying various data types:

* **Message**. Signs a message using a passkey, generating an Ethereum-specific
  EIP-191 signature.
* **Typed Data**. Signs typed data using a passkey, generating an
  Ethereum-specific EIP-712 signature.

See the sample code below for signing and verifying messages.

<CodeGroup>
  ```javascript Web SDK theme={null}
  import { createPublicClient } from "viem";
  import { toWebAuthnAccount } from "viem/account-abstraction";
  import { polygonAmoy } from "viem/chains";
  import {
    toCircleSmartAccount,
    toModularTransport,
    toPasskeyTransport,
    toWebAuthnCredential,
    WebAuthnMode,
  } from "@circle-fin/modular-wallets-core";

  const clientUrl = "your-client-url";
  const clientKey = "your-client-key";

  // 1. Register or login with a passkey
  const credential = await toWebAuthnCredential({
    transport: toPasskeyTransport(clientUrl, clientKey),
    mode: WebAuthnMode.Register, // or WebAuthnMode.Login
    username: "my-passkey",
  });

  // 2. Create public client
  const client = createPublicClient({
    chain: polygonAmoy,
    transport: toModularTransport(clientUrl, clientKey),
  });

  // 3. Create Circle Smart Account
  const smartAccount = await toCircleSmartAccount({
    client,
    owner: toWebAuthnAccount({ credential }),
  });

  // 4. Sign message with Circle Smart Account
  const message = "TestSignMessage";
  const signature = await smartAccount.signMessage(message);

  // 5. Verify the signature
  const isValid = await client.verifyMessage({
    address: smartAccount.address,
    message,
    signature,
  });
  ```

  ```swift iOS SDK theme={null}
  import CircleModularWalletsCore

  let CLIENT_KEY = "xxxxxxx:xxxxx"

  Task {
      do {
          // 1. Register or login with a passkey and
          //    Create a Passkey Transport with client key
          let transport = toPasskeyTransport(clientKey: CLIENT_KEY)

          let credential = try await toWebAuthnCredential(
              transport: transport,
              userName: "MyExampleName", // userName
              mode: WebAuthnMode.register // or WebAuthnMode.login
          )

          // 2. Create a WebAuthn owner account from the credential.
          let webAuthnAccount = toWebAuthnAccount(
              credential
          )

          // 3. Create modular transport from clientKey and client url
          let modularTransport = toModularTransport(
              clientKey: CLIENT_KEY,
              url: clientUrl
          )

          // 4. Create a bundler client
          let bundlerClient = BundlerClient(
              chain: PolygonAmoy,
              transport: modularTransport
          )

          // 5. Create smart account (CircleSmartAccount) and set the WebAuthn account as the owner
          let smartAccount = try await toCircleSmartAccount(
              client: bundlerClient,
              owner: webAuthnAccount
          )

          // 6. Sign message by SmartAccount
          let message = "TestSignMessage"
          let signature = smartAccount.signMessage(message)

          // 7. Verify signature
          let digest = Data(message.utf8).sha3(.keccak256)
          let functionName = "isValidSignature"
          let input1 = ABI.Element.InOut(name: "digest", type: .bytes(length: 32))
          let input2 = ABI.Element.InOut(name: "signature", type: .dynamicBytes)
          let output = ABI.Element.InOut(name: "magicValue", type: .bytes(length: 4))
          let function = ABI.Element.Function(
              name: functionName,
              inputs: [input1, input2],
              outputs: [output],
              constant: false,
              payable: false
          )
          let params: [Any] = [digest, signature]
          guard let data = function.encodeParameters(params) else {
              return
          }

          guard let fromAddress = EthereumAddress(from), let toAddress = EthereumAddress(to) else {
              return false
          }

          var transaction = CodableTransaction(to: toAddress, data: data)
          transaction.from = fromAddress

          guard let callResult = try? await Utils().ethCall(
              transport: transport,
              transaction: transaction
          ) else {
              return
          }

          guard let callResultData = hexToData(hex: callResult),
                let decoded = try? function.decodeReturnData(callResultData) else {
              return
          }

          guard let magicValue = decoded["0"] as? Data else {
              return
          }

          let isValid = (EIP1271_VALID_SIGNATURE == magicValue.bytes)
      } catch {
          print(error)
      }
  }
  ```

  ```java Android SDK theme={null}
  val CLIENT_KEY = "xxxxxxx:xxxxx"

  CoroutineScope(Dispatchers.IO).launch {
      try {
          // 1. Register or login with a passkey and
          //    Create a Passkey Transport with client key
          val transport = toPasskeyTransport(context, CLIENT_KEY, clientUrlWithoutChain)

          val credential = toWebAuthnCredential(
              context,
              transport,
              "MyExampleName", // userName
              WebAuthnMode.Register // or WebAuthnMode.Login
          )

          // 2. Create a WebAuthn owner account from the credential.
          val webAuthnAccount = toWebAuthnAccount(
              credential,
          )

          // 3. Create modular transport from client url and client key
          val modularTransport = toModularTransport(
              context,
              CLIENT_KEY,
              clientUrl
          )

          // 4. Create a bundlerClient
          val bundlerClient = BundlerClient(
              PolygonAmoy,
              modularTransport,
          )

          // 5. Create smart account (CircleSmartAccount)
          //    and set the WebAuthn account as the owner
          val smartAccount = toCircleSmartAccount(
              bundlerClient,
              webAuthnAccount,
          )

          // 6. Sign message by SmartAccount
          val message = "TestSignMessage"
          val signature = smartAccount.signMessage(context, message)

          // 7. Verify signature
          val digest = toSha3Bytes(hashMessage(message.toByteArray()))
          val function = Function(
              "isValidSignature",
              listOf<Type<*>>(Bytes32(digest), DynamicBytes(Numeric.hexStringToByteArray(signature))),
              listOf<TypeReference<*>>(
                  object : TypeReference<Bytes4>() {})
          )
          val data = FunctionEncoder.encode(function)
          val resp = bundlerClient.call(
              smartAccount.getAddress(),
              CIRCLE_WEIGHTED_WEB_AUTHN_MULTISIG_PLUGIN.address,
              data)
          val decoded = FunctionReturnDecoder.decode(resp, function.outputParameters)
          val isValid = EIP1271_VALID_SIGNATURE.contentEquals(decoded[0].value as ByteArray)
      } catch (e: Exception) {
          e.printStackTrace()
      }
  }
  ```

  ```java Android SDK (Java) theme={null}
  final String CLIENT_KEY = "xxxxxxx:xxxxx";
  try {
      // 1. Register or login with a passkey and
      //    Create a Passkey Transport with client key
      HttpTransport transport = toPasskeyTransport(
          context,
          CLIENT_KEY,
          clientUrlWithoutChain
      );
      CompletableFuture<WebAuthnCredential> suspendResult = new CompletableFuture<>();
      toWebAuthnCredential(
          context,
          transport,
          "MyExampleName",
          WebAuthnMode.Register, // or WebAuthnMode.Login
          new CustomContinuation<>(suspendResult)
      ); // see CustomContinuation in "Creating a Custom Continuation" from Android SDK
      WebAuthnCredential credential = suspendResult.join();

      // 2. Create a WebAuthn owner account from the credential.
      WebAuthnAccount webAuthnAccount = toWebAuthnAccount(credential);

      // 3. Create modular transport with client url and client key
      Transport modularTransport = toModularTransport(
          context,
          CLIENT_KEY,
          clientUrl
      );

      // 4. Create a bundler client
      BundlerClient bundlerClient = new BundlerClient(PolygonAmoy.INSTANCE, modularTransport);

      // 5. Create smart account (CircleSmartAccount)
      //    and set the WebAuthn account as the owner
      CompletableFuture<CircleSmartAccount> suspendAccount = new CompletableFuture<>();
      toCircleSmartAccount(bundlerClient, webAuthnAccount, new CustomContinuation<>(suspendAccount));
      CircleSmartAccount smartAccount = suspendSmartAccount.join();

      // 6. Sign message by SmartAccount
      String message = "TestSignMessage";
      CompletableFuture<String> suspendMessage = new CompletableFuture<>();
      smartAccount.signMessage(
          ApplicationProvider.getApplicationContext(),
          message, new CustomContinuation<>(suspendMessage)
      );
      String signature = suspendMessage.join();

      // 7. Verify signature
      byte[] digest = toSha3Bytes(hashMessage(message.getBytes(StandardCharsets.UTF_8)));
      Function function = new Function(
          "isValidSignature",
          Arrays.asList(
              new Bytes32(digest),
              new DynamicBytes(Numeric.hexStringToByteArray(signature))
          ),
          Arrays.asList(new TypeReference<Bytes4>() {})
      );
      String data = FunctionEncoder.encode(function);
      CompletableFuture<String> suspendSignature = new CompletableFuture<>();
      bundlerClient.call(
          smartAccount.getAddress(),
          CIRCLE_WEIGHTED_WEB_AUTHN_MULTISIG_PLUGIN.INSTANCE.getAddress(),
          data,
          new CustomContinuation<>(suspendSignature)
      );
      String resp = suspendSignature.join();
      List<Type> decoded = FunctionReturnDecoder.decode(resp, function.getOutputParameters());
      boolean isValid = Arrays.equals(
          MscaConstantsKt.getEIP1271_VALID_SIGNATURE(),
          ((Bytes4) decoded.get(0)).getValue()
      );
  } catch (Exception e) {
      e.printStackTrace()
  }
  ```
</CodeGroup>

## Use the EIP-1193 provider

The modular wallets SDK can also function as a provider, enabling third-party
wallet SDKs to connect to Circle's services. The following example demonstrates
an **EIP-1193 provider** implementation for the Web SDK.

```javascript JavaScript theme={null}
import Web3 from "web3"

import { polygonAmoy } from "viem/chains"
import {
  createClient,
  createPublicClient,
  http,
  type Hex,
} from "viem"
import {
  type P256Credential,
  type SmartAccount,
  WebAuthnAccount,
  createBundlerClient,
  toWebAuthnAccount,
} from "viem/account-abstraction"

import {
  EIP1193Provider,
  WebAuthnMode,
  toCircleSmartAccount,
  toModularTransport,
  toPasskeyTransport,
  toWebAuthnCredential,
} from "w3s-web-core-sdk"

/* ========== Replace these with your values ========== */
const clientKey = "YOUR_CLIENT_KEY"
const clientUrl = "YOUR_CLIENT_URL"
const infuraUrl = "YOUR_INFURA_ENDPOINT_URL" // E.g. "https://polygon-mumbai.infura.io/v3/xxx"

/* ========== Creating Circle Passkey Transport ========== */
const passkeyTransport = toPasskeyTransport(clientUrl, clientKey)
const modularTransport = toModularTransport(`${clientUrl}/polygonAmoy`, clientKey)

/* ========== Creating client ========== */
const client = createClient({
  chain: polygonAmoy,
  transport: modularTransport,
})

let web3            // Web3 instance
let account         // Circle Smart Account
let credential      // Passkey credential

/**
 * Initialize the Web3 instance with Circle Smart Account.
 */
export async function init() {
  try {
    credential = JSON.parse(localStorage.getItem("credential") || "null")
    if (!credential) {
      console.log("No credential found in localStorage. Please register or login first.")
      return
    }

    // Create Circle Smart Account
    account = await toCircleSmartAccount({
      client,
      owner: toWebAuthnAccount({ credential }) as WebAuthnAccount,
    })

    // Create PublicClient and BundlerClient
    const publicClientInstance = createPublicClient({
      chain: polygonAmoy,
      transport: http(infuraUrl),
    })
    const bundlerClientInstance = createBundlerClient({
      account,
      chain: polygonAmoy,
      transport: modularTransport,
    })

    // Transform to EIP1193 provider
    const provider = new EIP1193Provider(bundlerClientInstance, publicClientInstance)

    // Init Web3
    web3 = new Web3(provider)

    console.log("Initialized successfully!")
    console.log("Smart Account Address:", account.address)
  } catch (err) {
    console.error("Init Error:", err)
  }
}

/**
 * Register a new account with Passkey (WebAuthn) and store it in localStorage.
 * @param {string | undefined} username - The username.
 */
export async function register(username) {
  try {
    const result = await toWebAuthnCredential({
      transport: passkeyTransport,
      mode: WebAuthnMode.Register,
      username,
    })

    localStorage.setItem("credential", JSON.stringify(result))
    console.log("Register success:", result)
    console.log("Call `init()` to initialize your account.")
  } catch (err) {
    console.error("Register fail:", err)
  }
}

/**
 * Login with Passkey (WebAuthn) and store it in localStorage.
 */
export async function login() {
  try {
    const result = await toWebAuthnCredential({
      transport: passkeyTransport,
      mode: WebAuthnMode.Login,
    })

    localStorage.setItem("credential", JSON.stringify(result))
    console.log("Login success:", result)
    console.log("Call `init()` to initialize your account.")
  } catch (err) {
    console.error("Login fail:", err)
  }
}

/* ========== Case 1: Request accounts ========== */
export async function requestAccounts() {
  try {
    if (!web3) {
      throw new Error("web3 not initialized. Please call `init()` first.")
    }
    const accounts = await web3.eth.getAccounts()
    console.log("Accounts:", accounts)
    return accounts
  } catch (err) {
    console.error("Request Accounts Error:", err)
  }
}

/* ========== Case 2: Personal sign ========== */
export async function personalSign() {
  try {
    if (!web3) {
      throw new Error("web3 not initialized. Please call `init()` first.")
    }
    const accounts = await web3.eth.getAccounts()

    const signature = await web3.eth.personal.sign(
      "Hello World",
      accounts[0],
      "passphrase"
    )

    console.log("Personal Sign Result:", signature)
    return signature
  } catch (err) {
    console.error("Personal Sign Error:", err)
  }
}

/* ========== Case 3: Sign typed data (EIP-712 / v4) ========== */
export async function signTypedData() {
  try {
    if (!web3) {
      throw new Error("web3 not initialized. Please call `init()` first.")
    }
    const accounts = await web3.eth.getAccounts()
    const from = accounts[0]

    // Prepare the typed Data
    const domain = {
      name: "MyDApp",
      version: "1.0",
      chainId: 80002,
      verifyingContract: "0x1111111111111111111111111111111111111111",
    }
    const message = {
      content: "Hello from typed data!",
      sender: from,
      timestamp: Math.floor(Date.now() / 1000),
    }
    const dataToSign = {
      domain,
      message,
      primaryType: "Message",
      types: {
        EIP712Domain: [
          { name: "name", type: "string" },
          { name: "version", type: "string" },
          { name: "chainId", type: "uint256" },
          { name: "verifyingContract", type: "address" },
        ],
        Message: [
          { name: "content", type: "string" },
          { name: "sender", type: "address" },
          { name: "timestamp", type: "uint256" },
        ],
      },
    }

    const signature = await web3.eth.signTypedData(from, dataToSign)

    console.log("Signature", signature)

    return signature
  } catch (err) {
    console.error("Sign Typed Data Error:", err)
  }
}

/* ========== Case 4: Sign transaction (sendTransaction) ========== */
export async function sendTransaction(to, value) {
  try {
    if (!web3) {
      throw new Error("web3 not initialized. Please call `init()` first.")
    }
    if (!to || !value) {
      throw new Error("Please provide `to` address and `value` in ETH.")
    }

    const accounts = await web3.eth.getAccounts()
    const suggestedGasPrice = ((await web3.eth.getGasPrice()) * 11n) / 10n

    const txResult = await web3.eth.sendTransaction({
      from: accounts[0],
      to,
      value: web3.utils.toWei(value, "ether"),
      gas: 53638, // Estimated gas limit for a simple transaction
      gasPrice: suggestedGasPrice,
    })

    console.log("Transaction:", txResult)
    return txResult.transactionHash
  } catch (err) {
    console.error("SendTx Error:", err)
  }
}

register("your-name")

// Or you have registered already:
login()

init()

// Request accounts
requestAccounts()

// Personal sign
personalSign()

// sign typed data
signTypedData()

// Send transaction
sendTransaction("0xRecipientAddress", "0.01")
```


# Modules
Source: https://developers.circle.com/wallets/modular/modules



Modules are the building blocks of modular wallets. Built on smart contract
accounts (SCAs), they extend the business logic of Web3 applications. Each
module provides a solution component for a new use case. You can enable specific
modules in your app to meet specific business needs, such as automated
transactions, subscription billing, or event-triggered actions when integrated
with Circle Contracts. This makes USDC more programmable and enhances its role
as a medium of exchange.

<Note>
  **Note:** Modules are built on Circle's modular smart contract accounts (MSCA)
  technology and support the following standards:

  * ERC-4337: Enables account abstraction, allowing operations without an initial
    Ether balance, improving flexibility.
  * ERC-6900: Provides a framework for modular smart contracts that are
    customizable and extendable.
</Note>

You can also create custom modules to expand the ecosystem based on this
standard.

## Supported modules

The default signer for a Circle Smart Account is passkey (WebAuthn). The table
below lists that module and optional modules you can attach.

| Module Name            | Description                                                                                                                                                                                                                                                                                                                       | Module Address                                                                                                                                                                                          |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Passkey (WebAuthn)** | Default signer for the smart account. Users register or log in with a passkey; signing uses the key on the user's device. For auth, backup, and recovery, see [Passkeys](/wallets/modular/passkeys).                                                                                                                              | Built-in (default signer).                                                                                                                                                                              |
| **Address Book**       | Only allows you to transfer assets to a list of allowlisted addresses that is enforced onchain. Useful if you are building a vault for your treasury. <br /> <br /> • Add a list of address you allow sending ERC20, 721 or 1155 assets too <br /> • Any transfers of these assets outside that list of address will fail onchain | ✅ Available: <br /> MSCA version: **circle\_6900\_v1** <br /> Mainnet address: <br /> `0x0000000d81083B16EA76dfab46B0315B0eDBF3d0` <br /> Testnet address: `0x0000000d81083B16EA76dfab46B0315B0eDBF3d0` |


# Passkey and Smart Account
Source: https://developers.circle.com/wallets/modular/passkey-and-smart-account

Describes passkey as signer and the Circle Smart Account flow for modular wallets.

Before you run the quickstart, it helps to understand how passkeys and Circle
Smart Accounts work together.

## Passkey

A passkey is the signer for a modular wallet. The user registers or logs in with
a passkey (for example, biometrics, or device unlock); the key material stays on
their device and your app never holds it. There is no seed phrase or password
for the user to manage. For more on passkeys, backup, and recovery, see
[Passkeys](/wallets/modular/passkeys).

## Smart account and flow

The passkey is the owner of a Circle Smart Account. In the quickstart, you use
the modular wallets SDK to create the smart account with that passkey as owner,
then create a bundler client to send user operations. To sponsor gas so the user
does not need native tokens, set <code>paymaster: true</code> when sending the
user operation (Circle [Gas Station](/wallets/gas-station) covers the fee). For
more capabilities (batch, parallel execution, signing), see
[Modular Wallet Operations](/wallets/modular/key-features).


# Passkey
Source: https://developers.circle.com/wallets/modular/passkeys



Circle's **Passkey** enables the integration of secure smart contract
functionality through the **WebAuthn** standard. By using the Passkey as a
signer, it simplifies user onboarding and enhances the signing experience.
Passkey also offers a secure and seamless way to manage private keys, allowing
your users to interact with smart contracts safely and efficiently.

## Passkeys Overview

Passkeys simplify private key management in Web3, improving user experience.
Users no longer need to handle private keys directly or worry about losing their
12-word seed phrase, which could result in lost funds.

### What is a Passkey?

A passkey is a cryptographic key pair generated and **securely stored on user
devices**, such as laptops, phones, or password managers like 1Password. Unlike
passwords, passkeys cannot be shared and are resistant to phishing and breaches.

<Note>
  Passkey adoption is growing, with Apple and Google promoting this standard. Passkeys are now available on many devices, including:

  * **Apple**: iPhones, iPads, MacBooks
  * **Android**: Phones and tablets
  * **Browsers**: Chrome, Edge, Firefox (on Windows, Mac, and Android)
  * **FIDO2 security keys**: YubiKey and similar devices

  See the full
  [passkey support matrix](https://passkeys.dev/device-support/#matrix) for device
  and platform compatibility across various operating systems and browsers.
</Note>

### Benefits of Passkeys

* **Faster Registration and Login**. Users can register and log in using
  biometric authentication, such as Face ID or fingerprints.
* **Ease of Use**. Passkeys sync with password managers like iCloud Keychain,
  Google Password Manager, or 1Password, allowing seamless access across devices
  within the same ecosystem.
* **Cross-Device Usage**. Passkeys can be used across different ecosystems via
  **Bluetooth**. For example, users can sign in on another device by scanning a
  QR code with their phone, as long as the phone is near the laptop and the user
  approves the sign-in on their phone.\
  **Note:** If you sign in on the same device where the passkey was created, the
  device will prompt you to authenticate using biometrics — no Bluetooth
  required. For more details, see
  [this guide](https://blog.1password.com/passkeys-faqs/#do-you-need-a-bluetooth-connection-to-use-a-passkey).

## Passkey Implementation

Circle's **Passkey** feature is built using **Smart Contract Passkey** alongside
**webAuthnAccount**. A dedicated **Passkey Server** is implemented to enable
secure registration and authentication processes through the **WebAuthn**
standard.

* **Smart Contract Passkey**. A digital key that authorizes blockchain
  transactions, ensuring only authorized users can execute actions.
* **WebAuthnAccount**. WebAuthn is a web standard for secure authentication
  using public key cryptography instead of passwords. WebAuthnAccount connects
  to Circle's Passkey Server to retrieve passkeys registration and login
  credentials, enabling the generation of passkeys and performing signing
  operations.

Passkeys use the **secp256r1** curve for generating signatures. When invoking
**webAuthnAccount**, the signing methods return both the signature and the
associated **WebAuthn** data.

## Passkey Backup and Recovery

As passkeys replace traditional private keys in Web3 authentication, having a
reliable backup and recovery strategy becomes essential. This section explains
how passkeys are synchronized across user devices and what fallback options
Circle provides in case users lose access to their original passkey, including
support for recovery keys with secure, self-custodial properties.

Passkeys are natively synchronized across user devices via secure cloud storage
services like **Apple iCloud Keychain** or
[Google Password Manager](https://developers.google.com/identity/passkeys/supported-environments),
ensuring convenience and accessibility. However, **device-bound passkeys** (for
example, YubiKey) do not support synchronization, as they remain exclusive to
the device where they were created. This offers higher security but less
convenience:

* **Apple iCloud Keychain**. Syncs passkeys across Apple devices as long as the
  user is signed in with their Apple ID.
* **Google Password Manager**. Enabled by default as a passkey provider on
  Android, and accessible in Chrome and other supported browsers.

Despite these measures, users may accidentally erase their passkey setup or lose
a hardware security key. To address this risk, Circle provides an additional
recovery method to ensure continued account access. For more details and sample
code, visit the
[How to set up passkey recovery](/wallets/modular/recover-passkey) guide.

<Note>
  **Key Benefits:**

  * **Self-Custodial**: No central authority required for recovery
  * **Equivalent Permissions**: Recovery keys have the same permissions as
    passkeys at the contract level
  * **Standard Compatibility**: Recovery keys use standard ECDSA signatures,
    compatible with Ethereum tooling
  * **Multiple Recovery Keys**: Support for registering multiple recovery keys for
    added flexibility and security
</Note>

<Warning>
  **Caution:**

  The passkey and any recovery methods that users set up are the only ways to
  access their wallets. Neither Circle nor developers can possibly recover user
  wallets under any circumstances.
</Warning>

## How to Use Passkey

Explore the following resources to integrate the Passkey functionality into your
Web3 applications:

* [Modular Wallets Quickstart](/wallets/modular/create-a-wallet-and-send-gasless-txn)
  showcases how your app users can authenticate using a passkey.
* [Sample App](https://github.com/circlefin/modularwallets-web-sdk/tree/master/examples/circle-smart-account)
  in the [Modular Wallet Web SDK](/wallets/modular/web-sdk) (and the
  [Android](/wallets/modular/android-sdk) and [iOS](/wallets/modular/ios-sdk)
  SDKs) provide implementation examples.


# How To Set Up Passkey Recovery
Source: https://developers.circle.com/wallets/modular/recover-passkey



## Overview

Passkey recovery allows users to regain access to their smart accounts if they
lose their primary passkey. This mechanism enables users to register an
Externally Owned Account (EOA) as a recovery key. The recovery key can later be
used to generate a new passkey and restore access to the smart account—ensuring
users maintain full control in a non-custodial setup. For a complete code
sample, see the
[Passkey Recovery Example](https://github.com/circlefin/modularwallets-web-sdk/tree/master/examples/passkey-recovery)
in the modular wallets web SDK.

The recovery process includes two phases:

1. **Registration**: The user registers an EOA to act as a recovery key. This
   key is submitted to the network and added as a signer on the smart account.

<Note>
  > **Note:** Registration must be completed while the user still has access to
  > their original passkey. This ensures that the recovery key is securely >
  > authorized.
</Note>

2. **Recovery**: If the primary passkey is lost, the user can use the recovery
   key to register a new passkey and resume access.

## Prerequisites

Before you implement passkey backup and recovery, make sure you have the
following:

* An initialized **bundler client**
* An existing **Circle Smart Account** already configured with a passkey as the
  primary signer
* Required dependencies from a supported **wallet library** and the **modular
  wallets SDK**

<Note>
  **Note:** This guide uses [**viem**](https://viem.sh/) to generate mnemonics
  and create accounts. You can use any wallet library that supports mnemonic
  generation and EOA creation, such as [ethers.js](https://docs.ethers.org/) or
  [web3.js](https://web3js.readthedocs.io/).
</Note>

## Steps

To set up passkey backup and recovery, use the following functions from the
modular wallets SDK:

* `registerRecoveryAddress`: Registers an EOA as a recovery key.
* `executeRecovery`: Adds a new WebAuthn credential using the recovery key.
* `estimateRegisterRecoveryAddressGas`: Estimates gas for registering a recovery
  key.
* `estimateExecuteRecoveryGas`: Estimates gas for executing the recovery
  process.

<Note>
  These functions use **ERC-4337 user operations** to interact with the smart
  account.
</Note>

### 1. Register a Recovery Address

To allow your users to recover their passkeys, your application should prompt
them to associate a recovery address with their smart account while they still
have access to their original passkey. The following code sample shows how to
register a recovery address and generate a recovery mnemonic. This mnemonic can
then be used later to recover their passkey and associated smart account.

<Note>
  **Note:** The user must store the generated mnemonic securely. It serves as
  the only credential for recovery if the passkey is lost.
</Note>

```ts theme={null}
import { english, generateMnemonic, mnemonicToAccount } from "viem/accounts";
import { recoveryActions } from "@circle-fin/modular-wallets-core";

// Extend bundler client with recovery actions
const recoveryClient = bundlerClient.extend(recoveryActions);

// Generate recovery mnemonic (make sure the user stores this securely)
const mnemonic = generateMnemonic(english);
const recoveryEoa = mnemonicToAccount(mnemonic);

// Register recovery address with the smart account
await recoveryClient.registerRecoveryAddress({
  account,
  recoveryAddress: recoveryEoa.address,
  paymaster: true, // Optional: use a paymaster to sponsor gas
});
```

This creates a mapping between the smart account and the recovery address.

### 2. Initiate the Recovery Process

If a user loses their passkey, they can use the mnemonic from the recovery
address to start the recovery flow.

```ts theme={null}
// Recreate the recovery account from the saved mnemonic
const localAccount = mnemonicToAccount(savedMnemonic);

// Initialize a temporary smart account using the recovery EOA
const newAccount = await toCircleSmartAccount({
  client,
  owner: localAccount,
});

// Register a new WebAuthn passkey credential
const newCredential = await toWebAuthnCredential({
  transport: passkeyTransport,
  mode: WebAuthnMode.Register,
  username: "<RECOVERY_PASSKEY_USERNAME>",
});
```

This sets up a temporary account from the recovery key and prepares a new
passkey to replace the lost one.

### 3. Execute Recovery

After registering the new passkey, call `executeRecovery` to complete the
recovery and restore access to the smart account.

```ts theme={null}
await recoveryClient.executeRecovery({
  account: newAccount, // Temporary account used for signing
  credential: newCredential, // New WebAuthn credential
  paymaster: true, // Optional: use a paymaster to sponsor gas
});
```

This associates the new `WebAuthn` credential with the smart account.

### 4. Use the Recovered Account

After a successful recovery, the user can access the smart account using their
new passkey.

```ts theme={null}
const recoveredAccount = await toCircleSmartAccount({
  client,
  owner: toWebAuthnAccount({ credential: newCredential }) as WebAuthnAccount,
});

// The user can now sign transactions and use the wallet as normal
```

## Implementation tips

Use the following tips to improve the reliability and user experience of your
passkey recovery implementation.

### Gas fees

Recovery operations require network gas fees. To improve the user experience,
you can either sponsor the gas or estimate and display it to users in advance.
Circle recommends using the [Gas Station](/wallets/gas-station) to sponsor gas,
as it creates a smoother experience.

**Recommended approaches:**

1. **Sponsor gas fees** using Circle Gas Station.
2. **Estimate gas fees** and display them to users:

```ts theme={null}
const registerGasEstimate =
  await recoveryClient.estimateRegisterRecoveryAddressGas({
    account,
    recoveryAddress: recoveryEoa.address,
  });

const costInEth = formatEther(
  registerGasEstimate.totalGas * registerGasEstimate.maxFeePerGas,
);

// Display cost to user
console.log(`Estimated cost: ${costInEth} ETH`);
```

### Error handling

The recovery implementation includes built-in validation and error handling for
common edge cases:

* Detects existing address mappings to support idempotent operations
* Validates that a smart account object is provided for signing
* Handles registration or credential issues gracefully

Each recovery function uses a user operation that requires a valid smart account
to sign the transaction. Validation occurs automatically, whether the account is
passed directly or
[hoisted into the context](https://viem.sh/account-abstraction/actions/bundler/sendUserOperation#account-hoisting).

<Tip>
  **Tip:** Always wrap recovery logic in `try/catch` blocks to handle errors
  cleanly and provide actionable feedback to users.
</Tip>

## Best practices

Follow these best practices to increase user trust, security, and recoverability
when implementing passkey backup and recovery.

### 1. Educate users

* Clearly explain that losing both the **passkey** and **recovery key** results
  in permanent loss of access.
* Use onboarding tips or modals to reinforce the importance of recovery setup.
* Encourage users to store their **recovery mnemonic** securely—preferably in a
  password manager, secure notes app, or hardware vault.
* For a conceptual walkthrough, refer to the
  [User flow examples](#user-flow-examples), which outlines how users might
  register a recovery key and recover their wallet.

### 2. Offer redundancy

* Allow users to register multiple recovery keys (EOAs) to improve account
  resilience.
* Encourage users to store each recovery key in a separate, secure location to
  avoid single points of failure.

### 3. Test thoroughly

* Test the recovery flow across supported devices and browsers before deploying
  to production.
* Simulate common edge cases (e.g., loss of passkey, malformed mnemonic) to
  verify that fallback logic and error handling behave as expected.
* Consider including recovery flow testing in your CI/CD process if you're using
  automated test wallets.

## User flow examples

The following user flows describe a possible implementation of the passkey
backup and recovery process in your app. The flows are divided into two parts:

* **Generate your recovery key**
* **Recover your smart account**

### Generate your recovery key

After the user signs in with their existing passkey, guide them to set up a
recovery key. We recommend offering this option post-onboarding, with access
placed under a **Settings** or **Security** section in your app.

The following steps outline a possible user flow for registering a recovery key:

1. Select **Generate recovery key** under **Settings** or **Security** section.
2. Click **Continue** to begin generating your recovery key.
3. Verify your identity by signing in with your passkey using your touch ID or
   your device password.
4. Click **Confirm** to register your recovery key on the selected blockchain
   network.\
   **Note:** The app displays an estimated gas fee for registering the recovery
   key before submission.
5. Sign with your passkey to authorize adding the recovery key (EOA) as a signer
   to your smart account.
6. Once registered, securely store the recovery key (mnemonic).

### Recover your smart account

After the user has securely stored a recovery key, they can use it to regain
access if their original passkey is lost. This flow should be accessible from
your app's sign-in screen or recovery page.

The following steps outline a possible user flow for recovering a smart account
using a registered recovery key:

1. Select **Recover your wallet** from the sign-in screen next to "Lost your
   passkey?"
2. Enter your recovery key, then click **Start recovery process**.
3. After the key is validated, click **Continue** to create a new passkey.
4. Sign with your recovery key to authorize the new passkey.
5. Click **Confirm** to register the new passkey on the blockchain network.
6. After successful registration, the app displays a confirmation message.
7. The app redirects to your wallet dashboard where you can resume normal
   operations.

## Summary

Passkey backup and recovery provides a secure, self-custodial way for users to
regain access to their smart accounts. By implementing this feature, you give
users a reliable recovery option if they lose access to their primary passkey.
This approach reduces the risk of permanent account loss and maintains the core
principle of user control. Circle recommends pairing recovery setup with strong
user education, redundant recovery methods, and thorough testing to ensure a
seamless experience in production.


# Modular Wallets Web SDK
Source: https://developers.circle.com/wallets/modular/web-sdk



Welcome to Circle's modular wallets web SDK documentation. The SDK enables
developers to integrate modular wallets to build secure, scalable Web3
applications by leveraging tools for key management, smart account interactions,
gasless transactions, and blockchain communication.

## Installation

Follow the steps on the
[NPM package repository](https://www.npmjs.com/package/@circle-fin/modular-wallets-core)
to install and set up the modular wallets web SDK.

## API Documentation

The following sections detail the SDK's transport mechanisms, client
interactions, account management, providers, utilities, interfaces, and types.

<Note>
  **Note:** The Web SDK integrates with [Viem](https://viem.sh/)'s interfaces.
  Commonly used methods, interfaces, enums, etc., from Viem that are relevant to
  our SDK will be specifically noted in the sections below.
</Note>

### Transports

Transports handle communication between the SDK and blockchain networks or APIs.
They form the foundation for executing requests, such as JSON-RPC calls,
ensuring secure and efficient interactions.

#### Function: toModularTransport

* Description: Creates a custom transport instance with the given clientUrl and
  clientKey.
* Parameters:
  * clientUrl: string - The Client URL to use.
  * clientKey: string - The Client key to use.
* Returns: CustomTransport - The custom transport instance.

#### Function: toPasskeyTransport

* Description: Creates a custom transport instance with the given clientUrl and
  clientKey.
* Parameters:
  * clientUrl: string - The Client URL to use.
  * clientKey: string - The Client key to use.
* Returns: CustomTransport - The custom transport instance.

#### Understanding toModularTransport and toPasskeyTransport

##### Key Differences

| Aspect               | toModularTransport                                         | toPasskeyTransport                                               |
| -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- |
| **Purpose**          | Handles modular wallet-related blockchain actions.         | Handles passkey-based user authentication.                       |
| **Service**          | Talks to Circle Modular Wallet API for wallet operations.  | Talks to Circle Relying Party (RP) API for authentication flows. |
| **Focus**            | Blockchain and wallet operations (transactions, balances). | WebAuthn-based secure login and registration.                    |
| **Interaction**      | Blockchain-focused (for example, Arbitrum Sepolia).        | Credential-focused (for example, verifying passkeys).            |
| **Example Use Case** | Sending gasless transactions                               | Registering or logging into a modular wallet.                    |

##### How They Work Together

* **User Authentication**:
  * Use toPasskeyTransport for registering a wallet or logging in with a
    passkey.
  * This verifies the WebAuthn credential with Circle's RP API.
* **Blockchain Operations**:
  * After authentication, use toModularTransport to interact with the wallet
    onchain (for example, sending transactions or fetching balances).

### Clients

#### Function: createBundlerClient (viem)

* Description: Creates a Bundler Client for interacting with ERC-4337 Bundlers,
  enabling the sending and retrieval of User Operations through Bundler Actions.
* Parameters:
  * config: BundlerClientConfig - The configuration object containing the
    following properties:
    * transport: Transport - The transport mechanism used for making RPC
      requests.
    * chain?: Chain - Specifies the blockchain chain to interact with.
    * Other optional properties can be found in the
      [Viem Bundler Client Documentation](https://viem.sh/account-abstraction/clients/bundler#parameters).
* Returns: BundlerClient - A Bundler Client.

##### **Bundler Actions**

The Bundler Client supports the following key actions:

* estimateUserOperationGas - Calculates the gas required for a User Operation.
* sendUserOperation - Submits a User Operation to the bundler for processing.
* getUserOperationReceipt - Retrieves the receipt for a User Operation.

For the full list of actions and detailed documentation, see the
[Viem Bundler Actions Documentation](https://viem.sh/account-abstraction/actions/bundler/estimateUserOperationGas).

<Note>
  **Limitations**

  The `eth_getUserOperationReceipt` and `eth_getUserOperationByHash` methods scan
  logs from recently mined blocks and are not designed for historical data.
  Requests for user operations outside the supported range may be rejected due to
  block range limitations.

  **Default range:** 150 blocks

  **Networks with unlimited range:** Arbitrum, Base, Polygon, and Optimism

  **Best practice:** Use this method soon after submitting the user operation to
  confirm inclusion, not for historical analysis.
</Note>

#### Function: createPublicClient (viem)

* Description: Creates a public client for interacting with blockchain nodes.
  This client is used for tasks such as querying blockchain data and sending
  transactions.
* Parameters:
  * config: PublicClientConfig - The configuration object containing the
    following properties:
    * transport: Transport - The transport mechanism used for making RPC
      requests.
    * chain?: Chain - Specifies the blockchain chain to interact with.
    * Other optional properties can be found in the
      [Viem Public Client Documentation](https://viem.sh/docs/clients/public#parameters).
* Returns: PublicClient - A Public Client.

##### **Public Client Actions**

The Public Client supports the following key actions:

* getBlock - Retrieves information about a block using its number, hash, or a
  specific tag
* getTransaction - Fetches details of a transaction using its hash.
* getBalance - Returns the balance of the specified address.
* call - Executes a "call" to a contract function and retrieves the result
  without modifying the blockchain state.
* sendTransaction - Submits a signed transaction to the blockchain network for
  processing.
* verifyMessage - Confirms whether a given message was signed by the specified
  address.

For the full list of actions and detailed documentation, see the
[Viem Public Actions Documentation](https://viem.sh/docs/actions/public/introduction).

#### Function: createRpClient

* Description: Creates an RP Client for interacting with the RP API
* Parameters:
  * config: RpClientConfig - The configuration object containing the following
    properties:
    * transport: Transport - The transport mechanism used for making RPC
      requests. (required)
    * cacheTime?: number (default: 4\_000) - Time (in milliseconds) that cached
      data will remain in memory.
    * key?: string - A key for the client.
    * name?: string - A name for the client.
    * pollingInterval?: number (default: 4\_000) - Frequency (in milliseconds)
      for polling enabled actions & events.
    * rpcSchema?: rpcSchema - Typed JSON-RPC schema for the client.
* Returns: RpClient\<transport, rpcSchema> - An RP Client.

### Accounts

#### Function: toCircleSmartAccount

* Description: Creates a Circle smart account.
* Parameters:
  * client: Client - The client instance.
  * owner: WebAuthnAccount | LocalAccount - The owner account associated with
    the Circle smart account.
  * address?: Address - The address.
  * name?: string (default: "passkey-\{timestamp}", e.g.
    2025-01-01T00:00:00.000Z) - The wallet name assigned to the newly registered
    account.
  * nonce?: bigint - The Nonce.
* Returns: Promise\<ToCircleSmartAccountReturnType>

#### Function: toWebAuthnCredential

* Description: Logs in or registers a user and returns a WebAuthnCredential.
* Parameters:
  * mode: WebAuthnMode - The mode of the WebAuthn credential (Login or
    Register).
  * transport: Transport - The transport used to communicate with the RP API.
  * credentialId?: string - The existing credential ID for passkey login.
  * username?: string - The username for passkey registration.
* Returns: Promise\<WebAuthnCredential>

### Providers

#### Class: ModularWalletsProvider

* Description: Provider for connecting to the modular wallets API and executing
  Web3 API requests.
* Parameters:
  * clientUrl: string - The Client URL to use.
  * clientKey: string - The Client key to use.

##### Methods

###### request

* Description: Sends a Web3 API request to the modular wallets API using the
  specified method and payload, with optional request configuration.
* Parameters:
  * payload: Web3APIPayload\<API, Method> - The payload for the Web3 API
    request, including the method name and its parameters.
  * requestOptions?: RequestInit - Optional configuration for the HTTP request,
    such as headers or request mode.
* Returns: Promise\<ResultType> - A promise resolving to the result of the API
  call.

#### Class: PaymasterProvider

* Description: Provider for connecting to the Paymaster API, enabling
  interaction with
  [ERC-7677 compliant Paymasters](https://eips.ethereum.org/EIPS/eip-7677) to
  sponsor User Operation gas fees.
* Parameters:
  * clientUrl: string - The Client URL to use.
  * clientKey: string - The Client key to use.

##### Methods

###### request

* Description: Sends a request to the Paymaster API using the specified method
  and payload, with optional request configuration.
* Parameters:
  * payload: Web3APIPayload\<API, Method> - The payload for the API request,
    including the method name and its parameters.
  * requestOptions?: RequestInit - Optional configuration for the HTTP request,
    such as headers or request mode.
* Returns: Promise\<ResultType> - A promise resolving to the result of the API
  call.

#### Class: RpProvider

* Description: Provider for connecting to the RP API and executing Web3 API
  requests.
* Parameters:
  * clientUrl: string - The Client URL to use.
  * clientKey: string - The Client key to use.

##### Methods

###### request

* Description: Sends a request to the RP API using the specified method and
  payload, with optional request configuration.
* Parameters:
  * payload: Web3APIPayload\<API, Method> - The payload for the API request,
    including the method name and its parameters.
  * requestOptions?: RequestInit - Optional configuration for the HTTP request,
    such as headers or request mode.
* Returns: Promise\<ResultType> - A promise resolving to the result of the API
  call.

#### Class: EIP1193Provider

* Description: An EIP-1193 wrapper provider for connecting to the Modular
  Wallets API and the public RPC endpoint and executing Web3 API requests via
  the passed-in bundler client instance.
* Parameters:
  * bundlerClient: BundlerClient - The bundler client instance.
  * publicClient: PublicClient - The public client instance.

##### Methods

###### request

* Description: Sends a request to the modular wallets API using the specified
  method and payload, with optional request configuration.
* Parameters:
  * payload: Web3APIPayload\<API, Method> - The payload for the API request,
    including the method name and its parameters.
  * requestOptions?: RequestInit - Optional configuration for the HTTP request,
    such as headers or request mode.
* Returns: Promise\<ResultType> - A promise resolving to the result of the API
  call.

### Utilities

#### Function: createAddressMapping

* Description: Creates an address mapping for recovery.
* Parameters:
  * client: Client\<Transport> - The Client to use.
  * params: CreateAddressMappingParameters - Parameters to use.
* Returns: Promise\<CreateAddressMappingReturnType> - The mapping result.

#### Function: encodeTransfer

* Description: Encodes the ERC20 transfer for user operations.
* Parameters:
  * to: `0x${string}` - The recipient address.
  * token: `0x${string}` - The token contract address. Supported tokens and
    their information are listed below.
  * amount: bigInt - The amount to transfer.
* Returns: EncodeTransferReturnType - The encoded transfer.
* Supported Tokens:

##### Mainnet USDC

| Blockchain Network | Enum                            | Contract Address                                                                                                                    |
| ------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum           | ContractAddress.Arbitrum\_USDC  | [`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`](https://arbiscan.io/token/0xaf88d065e77c8cc2239327c5edb3a432268e5831)                |
| Avalanche          | ContractAddress.Avalanche\_USDC | [`0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`](https://snowtrace.io/token/0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E?chainid=43114) |
| Base               | ContractAddress.Base\_USDC      | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913)               |
| Monad              | ContractAddress.Monad\_USDC     | [`0x754704Bc059F8C67012fEd69BC8A327a5aafb603`](https://monadvision.com/token/0x754704Bc059F8C67012fEd69BC8A327a5aafb603)            |
| Optimism           | ContractAddress.Optimism\_USDC  | [`0x0b2c639c533813f4aa9d7837caf62653d097ff85`](https://optimism.blockscout.com/address/0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85)  |
| Polygon            | ContractAddress.Polygon\_USDC   | [`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`](https://polygonscan.com/token/0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359)            |
| Unichain           | ContractAddress.Unichain\_USDC  | [`0x078D782b760474a361dDA0AF3839290b0EF57AD6`](https://unichain.blockscout.com/address/0x078D782b760474a361dDA0AF3839290b0EF57AD6)  |

##### Mainnet Native Tokens

| Blockchain Network | Token Name (Symbol) | Enum                          | Contract Address                                                                                                                 |
| ------------------ | ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum           | Arbitrum (ARB)      | ContractAddress.Arbitrum\_ARB | [`0x912CE59144191C1204E64559FE8253a0e49E6548`](https://arbiscan.io/token/0x912ce59144191c1204e64559fe8253a0e49e6548)             |
| Optimism           | Optimism (OP)       | ContractAddress.Optimism\_OP  | [`0x4200000000000000000000000000000000000042`](https://optimistic.etherscan.io/token/0x4200000000000000000000000000000000000042) |

##### Testnet USDC

| Blockchain Network | Enum                                  | Contract Address                                                                                                                            |
| ------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Arbitrum Sepolia   | ContractAddress.ArbitrumSepolia\_USDC | [`0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d`](https://sepolia.arbiscan.io/token/0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d)                |
| Arc Testnet        | ContractAddress.ArcTestnet\_USDC      | [`0x3600000000000000000000000000000000000000`](https://testnet.arcscan.app/address/0x3600000000000000000000000000000000000000)              |
| Avalanche Fuji     | ContractAddress.AvalancheFuji\_USDC   | [`0x5425890298aed601595a70AB815c96711a31Bc65`](https://testnet.snowtrace.io/token/0x5425890298aed601595a70AB815c96711a31Bc65?chainid=43113) |
| Base Sepolia       | ContractAddress.BaseSepolia\_USDC     | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://sepolia.basescan.org/token/0x036CbD53842c5426634e7929541eC2318f3dCF7e)               |
| Monad Testnet      | ContractAddress.MonadTestnet\_USDC    | [`0x534b2f3A21130d7a60830c2Df862319e593943A3`](https://testnet.monadexplorer.com/token/0x534b2f3A21130d7a60830c2Df862319e593943A3)          |
| Optimism Sepolia   | ContractAddress.OptimismSepolia\_USDC | [`0x5fd84259d66Cd46123540766Be93DFE6D43130D7`](https://optimism-sepolia.blockscout.com/address/0x5fd84259d66Cd46123540766Be93DFE6D43130D7)  |
| Polygon Amoy       | ContractAddress.PolygonAmoy\_USDC     | [`0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582`](https://amoy.polygonscan.com/token/0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582)               |
| Unichain Sepolia   | ContractAddress.UnichainSepolia\_USDC | [`0x31d0220469e10c4E71834a79b1f276d740d3768F`](https://unichain-sepolia.blockscout.com/address/0x31d0220469e10c4E71834a79b1f276d740d3768F)  |

#### Function: estimateExecuteRecoveryGas

* Description: Estimates the gas required to execute and finalize the recovery
  process.
* Parameters:
  * client: Client\<Transport, Chain | undefined, SmartAccount | undefined> -
    The Client to use.
  * params: EstimateExecuteRecoveryGasParameters - Parameters to use.
* Returns: Promise\<EstimateUserOperationGasReturnType> - The mapping result.

#### Function: estimateRegisterRecoveryAddressGas

* Description: Estimates the gas required to register a recovery address during
  the recovery process.
* Parameters:
  * client: Client\<Transport, Chain | undefined, SmartAccount | undefined> -
    The Client to use.
  * params: EstimateRegisterRecoveryAddressGasParameters - Parameters to use.
* Returns: Promise\<EstimateUserOperationGasReturnType> - An estimate of gas
  values necessary to register a recovery address.

#### Function: executeRecovery

* Description: Executes and finalizes the recovery process.
* Parameters:
  * client: Client\<Transport, Chain | undefined, SmartAccount | undefined> -
    The Client to use.
  * params: ExecuteRecoveryParameters - Parameters to use.
* Returns: Promise\<`0x${string}`> - The user operation hash from executing
  recovery onchain.

#### Function: getAddress

* Description: Gets the Circle smart wallet address for the user.
* Parameters:
  * client: Client\<Transport> - The Client to use.
  * params: GetAddressParameters - Parameters to use.
* Returns: Promise\<ModularWallet> - Circle smart wallet creation response.

#### Function: getAddressMapping

* Description: Gets the address mapping for a given owner.
* Parameters:
  * client: Client\<Transport> - The Client to use.
  * params: GetAddressMappingParameters - Parameters to use.
* Returns: Promise\<GetAddressMappingReturnType> - The mapping result.

#### Function: getLoginOptions

* Description: Returns the login options, including a challenge for
  verification.
* Parameters:
  * client: Client\<Transport> - The Client to use.
  * params: GetLoginOptionsParameters - Parameters to use.
* Returns: Promise\<CustomPublicKeyCredentialRequestOptions> - Credential
  Request Options.

#### Function: getLoginVerification

* Description: Returns the login verification response to indicate if it's
  verified or not.
* Parameters:
  * client: Client\<Transport> - The Client to use.
  * params: GetLoginVerificationParameters - Parameters to use.
* Returns: Promise\<GetLoginVerificationReturnType> - WebAuthn Verification
  Response.

#### Function: getModularWalletAddress

* Description: Gets the Circle modular wallet address.
* Parameters:
  * parameters: GetCircleSmartAccountAddressParameters - The configuration
    object containing the following properties:
    * client: CircleModularWalletClient - The Circle modular wallet client
      instance.
    * owner: WebAuthnAccount - The owner.
    * name?: string - The Circle Smart Account wallet name.
* Returns: Promise\<GetAddressReturnType> - The Circle modular wallet address.

#### Function: getRegistrationOptions

* Description: Returns the registration options, including a challenge for
  verification.
* Parameters:
  * client: Client\<Transport> - The Client to use.
  * params: GetRegistrationOptionsParameters - Parameters to use.
* Returns: Promise\<CustomPublicKeyCredentialCreationOptions> - Credential
  Creation Options.

#### Function: getRegistrationVerification

* Description: Returns the registration verification response to indicate if
  it's verified or not.
* Parameters:
  * client: Client\<Transport> - The Client to use.
  * params: GetRegistrationVerificationParameters - Parameters to use.
* Returns: Promise\<GetRegistrationVerificationReturnType> - WebAuthn
  Verification Response.

### Function: getUserOperationGasPrice

* Description: Gets the user operation gas price.
* Parameters:
  * client: Client\<Transport> - The Client to use..
* Returns: Promise\<GetUserOperationGasPriceResponse> - The user operation gas
  price.

#### Function: modularWalletActions

* Description: Returns the modular wallets actions.
* Parameters:
  * client: Client\<Transport> - The Client to use.
* Returns: ModularWalletActions - modular wallets actions.

#### Function: parseEther (viem)

* Description: Converts a string representation of ether to numerical wei.
* Properties:
  * value: string - The string representation of ether.
* Returns: bigint - The numerical value in wei. For more information, see the
  [Viem documentation](https://viem.sh/docs/utilities/parseEther).

#### Function: parseGwei (viem)

* Description: Converts a string representation of gwei to numerical wei.
* Properties:
  * value: string - The string representation of gwei..
* Returns: bigint - The numerical value in wei. For more information, see the
  [Viem documentation](https://viem.sh/docs/utilities/parseGwei).

#### Function: recoveryActions

* Description: Returns the Recovery actions.
* Parameters:
  * client: Client\<Transport> - The Client to use.
* Returns: RecoveryActions - Recovery Actions.

#### Function: registerRecoveryAddress

* Description: Registers a recovery address during the recovery process.
* Parameters:
  * client: Client\<Transport, Chain | undefined, SmartAccount | undefined> -
    The Client to use.
  * params: RegisterRecoveryAddressParameters - Parameters to use.
* Returns: Promise\<`0x${string}`> - The user operation hash from registering
  the recovery address onchain.

#### Function: rpActions

* Description: Returns the RP actions.
* Parameters:
  * client: Client\<Transport> - The Client to use.
* Returns: RpActions - Rp Actions.

#### Function: toCircleModularWalletClient

* Description: Transforms a client into a Circle modular wallet client using
  decorators.
* Parameters:
  * client: Client - The client instance.
* Returns: CircleModularWalletClient - A decorated Circle modular wallet client.

#### Function: walletClientToLocalAccount

* Description: Creates a Local Account from a Wallet Client.
* Parameters:
  * walletClient: WalletClient - The Wallet Client to use.
* Returns: LocalAccount - A Local Account.

#### Function: webAuthnSign

* Description: Signs a hash and parses it to a ABI-encoded webauthn signature.
  The dynamic part of the secp256r1 signature.
* Parameters:
  * parameters: WebAuthnSignParameters - The configuration object containing the
    following properties:
    * hash: Hash - The hash to sign.
    * owner: WebAuthnAccount - The owner of the account.
* Returns: Promise\<`0x${string}`> - The ABI-encoded webauthn signature.

### Enums

#### AccountType

* Description: Enum class representing the different types of accounts.
* Members:
  * Local - An account that is stored locally and supports private key-based
    signing.
  * WebAuthn - An account that relies on WebAuthn for authentication and
    signing.

#### ContractAddress

* Description: Enum class representing the supported token contract addresses.
* Members:
  * Arbitrum\_ARB - The Arbitrum governance token contract address.
  * Arbitrum\_USDC - The USDC token contract address on Arbitrum.
  * ArbitrumSepolia\_USDC - The USDC token contract address on Arbitrum testnet.
  * ArcTestnet\_USDC - The USDC token contract address on Arc testnet.
  * AvalancheFuji\_USDC - The USDC token contract address on Avalanche testnet.
  * Base\_USDC - The USDC token contract address on Base.
  * BaseSepolia\_USDC - The USDC token contract address on Base testnet.
  * Monad\_USDC - The USDC token contract address on Monad mainnet.
  * MonadTestnet\_USDC - The USDC token contract address on Monad testnet.
  * Optimism\_OP - The Optimism governance token contract address.
  * Optimism\_USDC - The USDC token contract address on Optimism.
  * OptimismSepolia\_USDC - The USDC token contract address on Optimism testnet.
  * Polygon\_USDC - The USDC token contract address on Polygon.
  * PolygonAmoy\_USDC - The USDC token contract address on Polygon testnet.
  * Unichain\_USDC - The USDC token contract address on Unichain.
  * UnichainSepolia\_USDC - The USDC token contract address on Unichain testnet.

#### OwnerIdentifierType

* Description: Enum class representing the owner identifier types for address
  mapping.
* Members:
  * EOA - The Externally Owned Account (EOA) owner identifier.
  * WebAuthn - The WebAuthn owner identifier.

#### WebAuthnMode

* Description: Enum class representing the WebAuthn modes.
* Members:
  * Login - Mode for logging in with an existing credential.
  * Register - Mode for registering a new credential.

### Interfaces

#### AuthenticatorAssertionResponse

* Description: Represents a digital signature from a WebAuthn credential,
  allowing servers to verify and authenticate a user during actions like signing
  in.
* Properties:
  * userHandle: ArrayBuffer - A read-only property providing an opaque
    identifier for linking a user account to its credentials.
    [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/AuthenticatorAssertionResponse)

#### AuthenticatorAttestationResponse

* Description: Represents a digital signature from a WebAuthn credential,
  allowing servers to verify and authenticate a user during actions like signing
  in.
* Methods:
  * getPublicKey(): ArrayBuffer - Returns an ArrayBuffer containing the DER
    SubjectPublicKeyInfo of the new credential, or null if unavailable.
    [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/AuthenticatorAttestationResponse)

#### CreateCredentialParameters

* Description: Defines the parameters required to create a WebAuthn credential.
* Properties:
  * credential: PublicKeyCredential - The WebAuthn Credential.
  * rpId: string | undefined - The RP ID.

#### CustomPublicKeyCredentialCreationOptions

* Description: Defines the parameters required to create a WebAuthn credential
  with support for custom user entities and advanced authentication options.
* Properties:
  * challenge: string - A unique challenge generated by the server to prevent
    replay attacks.
  * pubKeyCredParams: PublicKeyCredentialParameters\[] - The list of acceptable
    credential types and cryptographic algorithms.
  * rp: PublicKeyCredentialRpEntity - The relying party (RP) entity initiating
    the credential creation.
  * user: CustomPublicKeyCredentialUserEntity - Information about the user for
    whom the credential is being created.
  * attestation?: AttestationConveyancePreference - Indicates the desired
    attestation type (e.g., none, indirect, or direct).
  * authenticatorSelection?: AuthenticatorSelectionCriteria - Specifies criteria
    for selecting the authenticator to use.
  * excludeCredentials?: PublicKeyCredentialDescriptor\[] - Credentials to
    exclude during the creation process to prevent duplication.
  * extensions?: AuthenticationExtensionsClientInputs - Additional extensions
    for client-side processing during credential creation.
  * timeout?: number - The time (in milliseconds) the operation is allowed to
    take before timing out.

#### CustomPublicKeyCredentialDescriptor

* Description: Represents a descriptor for a WebAuthn credential.
* Properties:
  * id: string - The unique identifier for the credential.
  * type: "public-key" - The type of credential, which is always "public-key"
    for WebAuthn.
  * transports?: AuthenticatorTransport\[] - The list of supported transport
    methods.

#### CustomPublicKeyCredentialRequestOptions

* Description: Defines the parameters for requesting a WebAuthn credential.
* Properties:
  * challenge: string - A unique challenge generated by the server to prevent
    replay attacks.
  * allowCredentials?: CustomPublicKeyCredentialDescriptor\[] - A list of
    credentials that are allowed to authenticate the user.
  * extensions?: AuthenticationExtensionsClientInputs - Additional extensions
    for client-side processing during the authentication process.
  * rpId?: string - The relying party (RP) ID associated with the authentication
    request.
  * timeout?: number - The time (in milliseconds) the operation is allowed to
    take before timing out.
  * userVerification?: UserVerificationRequirement - Specifies the user
    verification level required.

#### CustomPublicKeyCredentialUserEntity

* Description: Represents information about a user entity for creating or
  managing WebAuthn credentials.
* Properties:
  * displayName: string - The user's display name.
  * id: string - A unique identifier for the user.
  * name: string - The user's name (for example, username or email).

#### EstimateExecuteRecoveryGasParameters

* Description: Defines the parameters required to estimate gas to execute
  recovery.
* Properties:
  * credential: P256Credential - The newly registered passkey credential.

#### EstimateRegisterRecoveryAddressGasParameters

* Description: Defines the parameters required to estimate gas to register a
  recovery address.
* Properties:
  * recoveryAddress: `0x${string}` - The derived address of the recovery key.

#### ExecuteRecoveryParameters

* Description: Defines the parameters required to execute recovery.
* Properties:
  * credential: P256Credential - The newly registered passkey credential.

#### GetLoginVerificationReturnType

* Description: Represents the return type for a login verification request.
* Properties:
  * publicKey: string - The public key associated with the login verification
    process.

#### GetRegistrationVerificationReturnType

* Description: Represents the return type for a registration verification
  request.
* Properties:
  * verified?: null | boolean - The verification status, which can be true
    (verified), false (not verified), or null (no status available).

#### GetUserOperationGasPriceReturnType

* Description: Represents the return type for the
  circle\_getUserOperationGasPrice RPC method.
* Properties:
  * low: GasPriceLevel - The low gas price level.
  * medium: GasPriceLevel - The medium gas price level.
  * high: GasPriceLevel - The high gas price level.
  * deployed?: boolean - The deployed verification gas.
  * notDeployed?: boolean - The non-deployed verification gas.

#### RegisterRecoveryAddressParameters

* Description: Defines the parameters required to register a recovery address.
* Properties:
  * recoveryAddress: `0x${string}` - The recovery address.

#### ToCircleModularWalletClientParameters

* Description: Defines the parameters required to create a Circle Modular Wallet
  Client.
* Properties:
  * client: Client - The client instance used to interact with the Circle
    Modular Wallet.

#### ToWebAuthnAccountParameters

* Description: Defines the parameters required to convert an account to a
  WebAuthn-based account.
* Properties:
  * mode: WebAuthnMode - The WebAuthn mode to be used.
  * transport: Transport - The transport mechanism used for interacting with the
    WebAuthn API.
  * credentialId?: string - The ID of the WebAuthn credential.
  * username?: string - The username associated with the account.

#### WebAuthnCredential

* Description: Represents a WebAuthn credential.
* Properties:
  * id: string - The unique identifier for the WebAuthn credential.
  * publicKey: `0x${string}` - The public key associated with the credential, in
    hexadecimal format.
  * raw: PublicKeyCredential - The raw WebAuthn credential object.
  * rpId: undefined | string - The relying party (RP) ID linked to the
    credential.

### Types

#### CircleModularWalletClient

* Description: Represents a client for interacting with modular wallets.
* Type Definition:

```javascript JavaScript theme={null}
type CircleModularWalletClient: Client<
    Transport,
    Chain | undefined,
    Account | undefined,
    ExtendedRpcSchema<RpcSchema>,
    ModularWalletActions,
>
```

#### CircleSmartAccountImplementation

* Description: Extends the SmartAccountImplementation with additional factory
  arguments and signing capabilities specific to Circle's modular smart contract
  accounts.
* Type Definition:

```javascript JavaScript theme={null}
type CircleSmartAccountImplementation = Assign<
  SmartAccountImplementation<
    typeof entryPoint07Abi,
    "0.7",
    {
      abi: typeof entryPoint07Abi;
      factory: {
        abi: typeof CIRCLE_MSCA_6900_V1_EP07_FACTORY_ABI;
        address: Address;
      };
    }
<Note>
  >,
</Note>
  {
    getFactoryArgs: NonNullable<
      SmartAccountImplementation["getFactoryArgs"]
<Note>
    >;
</Note>
    sign: NonNullable<SmartAccountImplementation["sign"]>;
  }
>
```

#### CreateAddressMappingReturnType

* Description: The return type for adding an address mapping.
* Type Definition:

```javascript JavaScript theme={null}
CreateAddressMappingReturnType: AddressMappingResponse[]
```

#### CreateAddressMappingRpcSchema

* Description: The RPC schema for adding an address mapping.
* Type Definition:

```javascript JavaScript theme={null}
type CreateAddressMappingRpcSchema = {
  Method: "circle_createAddressMapping",
  Parameters: [CreateAddressMappingParameters],
  ReturnType: CreateAddressMappingReturnType,
};
```

#### CreateRpClientErrorType

* Description: Represents possible error types for creating an RP Client,
  combining standard client error types and additional error types.
* Type Definition:

```javascript JavaScript theme={null}
type CreateRpClientErrorType = CreateClientErrorType | ErrorType;
```

#### ExtendedRpcSchema\<rpcSchema>

* Description: Extends the base RPC schema by appending the Modular Wallet RPC
  schema. If rpcSchema is provided and extends RpcSchema, it combines both;
  otherwise, it defaults to the Modular Wallet RPC schema.
* Type Definition:

```javascript JavaScript theme={null}
type ExtendedRpcSchema = rpcSchema extends RpcSchema
  ? [...ModularWalletRpcSchema, ...rpcSchema]
  : ModularWalletRpcSchema
```

#### GetAddressMappingReturnType

* Description: The return type for getting an address mapping.
* Type Definition:

```javascript JavaScript theme={null}
GetAddressMappingReturnType: AddressMappingResponse[]
```

#### GetAddressMappingRpcSchema

* Description: Get the address mapping for the specified owner.
* Type Definition:

```javascript JavaScript theme={null}
type GetAddressMappingRpcSchema = {
  Method: "circle_getAddressMapping",
  Parameters: [GetAddressMappingParameters],
  ReturnType: GetAddressMappingReturnType,
};
```

#### GetAddressParameters

* Description: Defines the parameters required for retrieving an address.
* Type Definition:

```javascript JavaScript theme={null}
type GetAddressParameters = [
  {
    metadata?: { name?: string };
    scaConfiguration: {
      initialOwnershipConfiguration: Omit<
        InitialOwnershipConfiguration,
        "ownershipContractAddress"
<Note>
      >;
</Note>
      scaCore: string;
    };
  },
]
```

#### GetAddressReturnType

* Description: The Get Circle modular wallet address response.
* Type Definition:

```javascript JavaScript theme={null}
type GetAddressReturnType = ModularWallet;
```

#### GetAddressRpcSchema

* Description: Defines the RPC schema for the circle\_getAddress method
* Type Definition:

```javascript JavaScript theme={null}
type GetAddressRpcSchema = {
  Method: "circle_getAddress";
  Parameters?: [
    {
      scaConfiguration: {
        initialOwnershipConfiguration: Omit<
          InitialOwnershipConfiguration,
          "ownershipContractAddress"
<Note>
        >;
</Note>
        scaCore: string;
      };
    }
  ];
  ReturnType: GetAddressReturnType;
}
```

#### GetLoginOptionsParameters

* Description: Defines the parameters required to retrieve login options.
* Type Definition:

```javascript JavaScript theme={null}
type GetLoginOptionsParameters = {
  userId: string,
};
```

#### GetLoginOptionsReturnType

* Description: Defines the parameters required to retrieve login options.
* Type Definition:

```javascript JavaScript theme={null}
type GetLoginOptionsReturnType = CustomPublicKeyCredentialRequestOptions;
```

#### GetLoginOptionsRpcSchema

* Description: Defines the RPC schema for the rp\_getLoginOptions method.
* Type Definition:

```javascript JavaScript theme={null}
type GetLoginOptionsRpcSchema = {
  Method: "rp_getLoginOptions";
  Parameters?: [userId: string];
  ReturnType: GetLoginOptionsReturnType;
}
```

#### GetLoginVerificationParameters

* Description: Defines the parameters required to verify a login attempt.
* Type Definition:

```javascript JavaScript theme={null}
type GetLoginVerificationParameters = {
  credential: PublicKeyCredential,
};
```

#### GetLoginVerificationRpcSchema

* Description: Defines the RPC schema for the rp\_getLoginVerification method.
* Type Definition:

```javascript JavaScript theme={null}
type GetLoginVerificationRpcSchema = {
  Method: "rp_getLoginVerification";
  Parameters?: [authenticationCredential: PublicKeyCredential];
  ReturnType: GetLoginVerificationReturnType;
}
```

#### GetRegistrationOptionsParameters

* Description: Defines the parameters required to retrieve registration options.
* Type Definition:

```javascript JavaScript theme={null}
type GetRegistrationOptionsParameters = {
  username: string,
};
```

#### GetRegistrationOptionsReturnType

* Description: Represents the return type for retrieving registration options.
* Type Definition:

```javascript JavaScript theme={null}
type GetRegistrationOptionsReturnType =
  CustomPublicKeyCredentialCreationOptions;
```

#### GetRegistrationOptionsRpcSchema

* Description: Defines the RPC schema for the rp\_getRegistrationOptions method.
* Type Definition:

```javascript JavaScript theme={null}
type GetRegistrationOptionsRpcSchema = {
  Method: "rp_getRegistrationOptions";
  Parameters?: [username: string];
  ReturnType: GetRegistrationOptionsReturnType;
}
```

#### GetRegistrationVerificationParameters

* Description: Defines the parameters required to verify a registration attempt.
* Type Definition:

```javascript JavaScript theme={null}
type GetRegistrationVerificationParameters = {
  credential: PublicKeyCredential,
};
```

#### GetRegistrationVerificationRpcSchema

* Description: Defines the RPC schema for the rp\_getRegistrationVerification
  method.
* Type Definition:

```javascript JavaScript theme={null}
type GetRegistrationVerificationRpcSchema = {
  Method: "rp_getRegistrationVerification";
  Parameters?: [registrationCredential: PublicKeyCredential];
  ReturnType: GetRegistrationVerificationReturnType;
}
```

#### GetUserOperationGasPriceRpcSchema

* Description: Defines the RPC schema for the circle\_getUserOperationGasPrice
  method.
* Type Definition:

```javascript JavaScript theme={null}
type GetUserOperationGasPriceRpcSchema = {
  Method: "circle_getUserOperationGasPrice",
  Parameters?: [],
  ReturnType: GetUserOperationGasPriceReturnType,
};
```

#### ModularWalletActions

* Description: Represents the available actions for a modular wallet,
* Type Definition:

```javascript JavaScript theme={null}
type ModularWalletActions = {
  getAddress: (
    parameters: GetAddressParameters
  ) => Promise<GetAddressReturnType>,
};
```

#### ModularWalletRpcSchema

* Description: Represents the RPC schema for modular wallets.
* Type Definition:

```javascript JavaScript theme={null}
type ModularWalletRpcSchema = [GetAddressRpcSchema];
```

#### RecoveryActions

* Description: Represents the actions available for the passkey recovery
  process.
* Type Definition:

```javascript JavaScript theme={null}
type RecoveryActions = {
  estimateExecuteRecoveryGas: (
    parameters: EstimateExecuteRecoveryGasParameters
  ) => Promise<EstimateUserOperationGasReturnType>,
  estimateRegisterRecoveryAddressGas: (
    parameters: EstimateRegisterRecoveryAddressGasParameters
  ) => Promise<EstimateUserOperationGasReturnType>,
  executeRecovery: (
    parameters: ExecuteRecoveryParameters
  ) => Promise<SendUserOperationReturnType>,
  registerRecoveryAddress: (
    params: RegisterRecoveryAddressParameters
  ) => Promise<SendUserOperationReturnType>,
};
```

#### RpActions

* Description: Represents the actions available for the RP (Relying Party) API.
* Type Definition:

```javascript JavaScript theme={null}
type RpActions = {
  getLoginOptions: (
    parameters: GetLoginOptionsParameters
  ) => Promise<GetLoginOptionsReturnType>,
  getLoginVerification: (
    parameters: GetLoginVerificationParameters
  ) => Promise<GetLoginVerificationReturnType>,
  getRegistrationOptions: (
    parameters: GetRegistrationOptionsParameters
  ) => Promise<GetRegistrationOptionsReturnType>,
  getRegistrationVerification: (
    parameters: GetRegistrationVerificationParameters
  ) => Promise<GetRegistrationVerificationReturnType>,
};
```

#### RpClient\<transport, rpcSchema>

* Description: Represents a prettified RP (Relying Party) client.
* Type Definition:

```javascript JavaScript theme={null}
type RpClient = Prettify<
  Client<
    transport,
    undefined,
    undefined,
    rpcSchema extends RpcSchema
      ? [...RpRpcSchema, ...rpcSchema]
      : RpRpcSchema,
    RpActions
  >
>
```

#### RpClientConfig\<transport, rpcSchema>

* Description: Represents the configuration options for creating an RP (Relying
  Party) client.
* Type Definition:

```javascript JavaScript theme={null}
type RpClientConfig = Prettify<
  Pick<
    ClientConfig<transport, undefined, undefined, rpcSchema>,
    "cacheTime" | "key" | "name" | "pollingInterval" | "rpcSchema" | "transport"
  >
>;
```

#### RpRpcSchema

* Description: Represents the RPC schema for the RP (Relying Party) client.
* Type Definition:

```javascript JavaScript theme={null}
type RpRpcSchema = [
  GetLoginOptionsRpcSchema,
  GetLoginVerificationRpcSchema,
  GetRegistrationOptionsRpcSchema,
  GetRegistrationVerificationRpcSchema
];
```

#### ToCircleSmartAccountParameters

* Description: Defines the parameters required to create a Circle Smart Account.
* Type Definition:

```javascript JavaScript theme={null}
type ToCircleSmartAccountParameters = {
  address?: Address,
  client: Client,
  name?: string,
  nonce?: bigint,
  owner: WebAuthnAccount,
};
```

#### ToCircleSmartAccountReturnType

* Description: Represents the return type for creating a Circle Smart Account.
* Type Definition:

```javascript JavaScript theme={null}
type ToCircleSmartAccountReturnType = Prettify<
  SmartAccount<CircleSmartAccountImplementation>
>;
```


# Monitored Tokens
Source: https://developers.circle.com/wallets/monitored-tokens



The Monitored Tokens feature in the Programmable Wallet aims to empower
developers with enhanced control over viewing token balances and transactions.
This feature enables developers to easily manage and filter out tokens unrelated
to their use case from Circle API responses, thereby selectively screening which
tokens end-users can see, providing a more streamlined and personalized
experience.

By utilizing the API endpoint
[`POST config/entity/monitoredTokens`](/api-reference/wallets/programmable-wallets/create-monitored-tokens),
developers can easily add tokens via their unique token IDs. This guide walks
you through the steps to interact with the Monitored Tokens feature, including
retrieving token IDs, adding tokens, and using API endpoints to get transaction
and wallet balances for specific tokens.

<Note>
  By default, there are no Monitored Tokens. This means that the system monitors
  all tokens as no filter exists. Calling [`GET
      /entity/config/monitoredTokens`](/api-reference/wallets/programmable-wallets/list-monitored-tokens)
  before configuring, returns 204, a no-content response.
</Note>

## Update Monitored Token List

To add tokens to the monitored token list, follow these steps:

1. Retrieve the Token ID: Circle Wallets support native coins, ERC-20, ERC-721,
   and ERC-1155.
   * Each token deposited into the Circle Wallet generates a specific token ID,
     which developers can obtain through the following methods:
     * **Documentation**: Consult the table below for the USDC token ID.
     * **Deposit Callback:** The callback response includes the corresponding
       token ID when a token is deposited.
     * **Querying Wallet Balance:**
       [`GET /wallets/{id}/balances`](/api-reference/wallets/developer-controlled-wallets/list-wallet-balance)
       or
       [`GET /wallets/{id}/nfts`](/api-reference/wallets/developer-controlled-wallets/list-wallet-nfts)
       retrieves the tokens in the wallet and their related token IDs.
     * **Querying Transaction:**
       [`GET /transactions`](/api-reference/wallets/developer-controlled-wallets/list-transactions)
       also retrieves the token IDs for inbound or outbound transactions.

2. Add tokens into the monitored token list: Once you have the token ID, make a
   [`POST config/entity/monitoredTokens`](/api-reference/wallets/programmable-wallets/create-monitored-tokens)
   request with the token IDs specified in the required field.

### USDC token IDs

| Blockchain       | Chain code    | Token ID                               | Token address                                                                                                                                                                                            |
| ---------------- | ------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Aptos            | APTOS         | `298eebe2-3131-5183-b528-f925f70848d0` | [`0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b`](https://explorer.aptoslabs.com/fungible_asset/0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b?network=mainnet) |
| Aptos Testnet    | APTOS-TESTNET | `e3cbdafc-42c3-58cc-ae4c-b31dbb10354c` | [`0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832`](https://explorer.aptoslabs.com/fungible_asset/0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832?network=testnet) |
| Arbitrum         | ARB           | `c87ffcb4-e2cf-5e67-84c6-388c965d2a66` | [`0xaf88d065e77c8cc2239327c5edb3a432268e5831`](https://arbiscan.io/token/0xaf88d065e77c8cC2239327C5EDb3A432268e5831)                                                                                     |
| Arbitrum Sepolia | ARB-SEPOLIA   | `4b8daacc-5f47-5909-a3ba-30d171ebad98` | [`0x75faf114eafb1bdbe2f0316df893fd58ce46aa4d`](https://sepolia.arbiscan.io/address/0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d)                                                                           |
| Arc Testnet      | ARC-TESTNET   | `15dc2b5d-0994-58b0-bf8c-3a0501148ee8` | `0x3600000000000000000000000000000000000000`                                                                                                                                                             |
| Avalanche        | AVAX          | `7efdfdbf-1799-5089-a588-31beb97ba755` | [`0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e`](https://snowtrace.io/token/0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E)                                                                                    |
| Avalanche Fuji   | AVAX-FUJI     | `ff47a560-9795-5b7c-adfc-8f47dad9e06a` | [`0x5425890298aed601595a70ab815c96711a31bc65`](https://testnet.snowtrace.io/token/0x5425890298aed601595a70ab815c96711a31bc65)                                                                            |
| Base             | BASE          | `aa7bb533-aeb8-535c-bd65-354aed91ea3d` | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)                                                                                    |
| Base Sepolia     | BASE-SEPOLIA  | `bdf128b4-827b-5267-8f9e-243694989b5f` | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://base-sepolia.blockscout.com/address/0x036CbD53842c5426634e7929541eC2318f3dCF7e)                                                                   |
| Ethereum         | ETH           | `b037d751-fb22-5f0d-bae6-47373e7ae3e3` | [`0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`](https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)                                                                                    |
| Ethereum Sepolia | ETH-SEPOLIA   | `5797fbd6-3795-519d-84ca-ec4c5f80c3b1` | [`0x1c7d4b196cb0c7b01d743fbc6116a902379c7238`](https://sepolia.etherscan.io/address/0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238)                                                                          |
| Monad            | MONAD         | `95401815-48ec-59eb-a06c-8fd1a8e82a8f` | [`0x754704Bc059F8C67012fEd69BC8A327a5aafb603`](https://monadvision.com/token/0x754704Bc059F8C67012fEd69BC8A327a5aafb603)                                                                                 |
| Monad Testnet    | MONAD-TESTNET | `17fe0589-b511-546c-9eff-84087524f47e` | [`0x534b2f3A21130d7a60830c2Df862319e593943A3`](https://testnet.monadexplorer.com/token/0x534b2f3A21130d7a60830c2Df862319e593943A3)                                                                       |
| Optimism         | OP            | `63ca9c9c-2f6d-594f-9070-ff2a4042be3a` | [`0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85`](https://optimistic.etherscan.io/token/0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85)                                                                         |
| Optimism Sepolia | OP-SEPOLIA    | `20749a68-e55b-57d3-8359-195543efc2d4` | [`0x5fd84259d66Cd46123540766Be93DFE6D43130D7`](https://sepolia-optimism.etherscan.io/address/0x5fd84259d66Cd46123540766Be93DFE6D43130D7)                                                                 |
| Polygon          | MATIC         | `db6905b9-8bcd-5537-8b08-f5548bdf7925` | [`0x3c499c542cef5e3811e1192ce70d8cc03d5c3359`](https://polygonscan.com/token/0x3c499c542cef5e3811e1192ce70d8cc03d5c3359)                                                                                 |
| Polygon Amoy     | MATIC-AMOY    | `36b6931a-873a-56a8-8a27-b706b17104ee` | [`0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582`](https://amoy.polygonscan.com/address/0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582)                                                                          |
| Solana           | SOL           | `33ca4ef6-2500-5d79-82bf-e3036139cc29` | [`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`](https://solscan.io/token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)                                                                                  |
| Solana Devnet    | SOL-DEVNET    | `8fb3cadb-0ef4-573d-8fcd-e194f961c728` | [`4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`](https://explorer.solana.com/address/4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU?cluster=devnet)                                                        |
| Unichain         | UNI           | `643096e8-e4c5-5ee7-a5d5-38c80fdc3f3b` | [`0x078D782b760474a361dDA0AF3839290b0EF57AD6`](https://unichain.blockscout.com/address/0x078D782b760474a361dDA0AF3839290b0EF57AD6)                                                                       |
| Unichain Sepolia | UNI-SEPOLIA   | `13ef30cd-309b-5c41-98cc-0fd68c4c8c44` | [`0x31d0220469e10c4E71834a79b1f276d740d3768F`](https://unichain-sepolia.blockscout.com/token/0x31d0220469e10c4E71834a79b1f276d740d3768F)                                                                 |

## Remove Monitored Tokens

To remove tokens from Monitored Tokens, use
[`POST /config/entity/monitoredTokens/delete`](/api-reference/wallets/programmable-wallets/delete-monitored-tokens)
to remove specific tokens. Specify the token IDs you want to delete, and they
are excluded from the list.

## Update Monitor

To replace tokens with Monitored Tokens, use
[`PUT /config/entity/monitoredTokens`](/api-reference/wallets/programmable-wallets/update-monitored-tokens)
to entirely replace the existing monitored token list by specifying the tokens
you want to monitor. The previous list is overwritten with the new tokens
provided.

## Change scope for Monitored Tokens

By default, all ERC-20, ERC-721, and ERC-1155 tokens deposited into your wallets
are monitored and returned in
[`GET /wallets/{id}/balances`](/api-reference/wallets/developer-controlled-wallets/list-wallet-balance),
[`GET /wallets/{id}/nfts`](/api-reference/wallets/developer-controlled-wallets/list-wallet-nfts),
[`GET /transactions`](/api-reference/wallets/developer-controlled-wallets/list-transactions)
APIs, and webhook callbacks.

However, after adding tokens to Monitored Tokens, the Monitored Tokens scope is
set to SELECTED by default, which means only the provided tokens are returned in
the preceding APIs and callbacks. To revert to monitoring all tokens, call
[`PUT /config/entity/monitoredTokens/scope`](/api-reference/wallets/programmable-wallets/update-monitored-tokens-scope)
and set the scope to MONITOR\_ALL.

It's important to note that even when the monitored token scope is set with
SELECTED, developers can view all tokens in the wallet balance and transactions.
This can be achieved by setting the `includeAll` field to `True` (default value
is `False`) in the
[`GET /wallets/{id}/balances`](/api-reference/wallets/developer-controlled-wallets/list-wallet-balance),
[`GET /wallets/{id}/nfts`](/api-reference/wallets/developer-controlled-wallets/list-wallet-nfts),
[`GET /transactions`](/api-reference/wallets/developer-controlled-wallets/list-transactions)
APIs. By doing so, the API responses include details for all tokens in the
wallet, irrespective of whether they are part of the monitored token list.


# Postman Collection
Source: https://developers.circle.com/wallets/postman

Use Circle's Postman collection to send API requests and explore the Programmable Wallets APIs.

Circle's Postman collection provides template requests to help you learn about
the Programmable Wallets APIs. These requests run on
[Postman](https://www.postman.com/), an API platform for learning, building, and
using APIs. The Postman Wallets workspace includes a collection that matches the
organization of the [API reference](/api-reference/wallets/common/ping).

## Run in Postman

To use the Postman collection, select **Run in Postman** below. You can fork the
collection to your workspace, view the collection in the public workspace, or
import the collection into Postman.

* **Fork**: Creates a copy of the collection while maintaining a link to the
  parent.
* **View**: Allows you to try out the API without importing anything into your
  Postman suite.
* **Import**: Creates a copy of the collection but does not maintain a link to
  Circle's copy.

| Collection | Link                                                                                                                                                                                                                                                                                                                                                |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Wallets    | [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/15022472-80b87d8a-844b-422e-9c2a-3a6ce86a2644?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D15022472-80b87d8a-844b-422e-9c2a-3a6ce86a2644%26entityType%3Dcollection%26workspaceId%3D73acd722-fab9-49b0-9382-086659476258) |

## Authorization

Paste your [API key](/api-reference/keys) in the Authorization tab of the
collection. To store your API key as a variable for more advanced testing, see
Postman's
[using variables](https://learning.postman.com/docs/sending-requests/variables/)
guide.

<Frame>
  <img />
</Frame>

## Entity secret

If you use developer-controlled wallets, you need to generate a unique 32-byte
entity secret. See the
[Register your entity secret](/wallets/dev-controlled/register-entity-secret)
quickstart for details. After you register your entity secret in the Circle
Console, add your **hex-encoded entity secret** (not the encrypted entity secret
ciphertext) as the variable value shown in the following image.

<Frame>
  <img />
</Frame>

Circle enforces uniqueness for your entity secret for each request. The helper
scripts included in the Postman collection re-encrypt the entity secret
ciphertext automatically before each call.

To enable this setup, run the "Get public key for entity" request one time. This
sets your entity public key as a variable that the collection uses to encrypt
your entity secret.

<Frame>
  <img />
</Frame>


# Sign Transactions
Source: https://developers.circle.com/wallets/sign-transactions

Sign transactions with developer-controlled wallets on EVM, Solana, or NEAR when you manage broadcasting yourself.

Signing APIs let you build a transaction in your application and have Circle
sign it. You then broadcast the signed transaction using your own node provider.
Use this flow when Circle doesn't provide full
[blockchain infrastructure](/wallets/blockchain-infrastructure) for your
blockchain, or when you prefer to manage broadcasting yourself. For an overview,
see [How Signing APIs Work](/wallets/signing-apis).

## Prerequisites

Before you begin, make sure you have:

* Obtained an [API key](/api-reference/keys) from the
  [Circle Console](https://console.circle.com/).
* Registered an [entity secret](/wallets/dev-controlled/register-entity-secret).
* Created a
  [developer-controlled wallet](/wallets/dev-controlled/create-your-first-wallet).
* Set up access to a node or RPC provider for your blockchain.
* Installed [Node.js 22+](https://nodejs.org/)

<Note>Only `EOA` wallets are supported for this signing flow.</Note>

<Tabs>
  <Tab title="EVM">
    ## Step 1. Set up your project

    ### 1.1. Create the project and install dependencies

    ```shell theme={null}
    # Create the project directory and initialize Node.js
    mkdir sign-transactions
    cd sign-transactions
    npm init -y

    # Set up module type and a script for EVM signing
    npm pkg set type=module
    npm pkg set scripts.sign-evm="tsx --env-file=.env sign-evm.ts"

    # Install runtime dependencies
    npm install @circle-fin/developer-controlled-wallets viem

    # Install dev dependencies
    npm install --save-dev tsx typescript @types/node
    ```

    ### 1.2. Configure TypeScript (optional)

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3. Set environment variables

    Create a `.env` file in the project directory:

    ```text .env theme={null}
    CIRCLE_API_KEY=YOUR_API_KEY
    CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
    ```

    * `CIRCLE_API_KEY` is your Circle Developer API key.
    * `CIRCLE_ENTITY_SECRET` is your registered entity secret.

    <Tip>
      Open `.env` in your editor rather than writing values with shell commands, and
      add `.env` to your `.gitignore`. This prevents credentials from leaking into
      your shell history or version control.
    </Tip>

    The `npm run start` command loads variables from `.env` using Node.js native
    env-file support.

    ## Step 2. Create a signing wallet

    ```ts theme={null}
    const response = await client.createWallets({
      accountType: "EOA",
      blockchains: ["EVM-TESTNET"],
      count: 1,
      walletSetId: "YOUR_WALLET_SET_ID",
    });
    ```

    <Note>Use `count` to create up to 200 wallets per request.</Note>

    If you already created a native wallet on Ethereum, Polygon, Avalanche,
    Arbitrum, or another EVM-compatible chain, a generic `EVM` wallet under the same
    wallet set maps to the same address. Do not use the generic `EVM` wallet in
    place of the native wallet on those chains, or transactions may become stuck.

    ## Step 3. Build and sign a transaction

    ```ts sign-evm.ts theme={null}
    import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
    import { arcTestnet } from "viem/chains";

    // Initialize the wallets client
    const client = initiateDeveloperControlledWalletsClient({
      apiKey: process.env.CIRCLE_API_KEY!,
      entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
    });

    async function main() {
      // Set signing inputs
      const walletId = "YOUR_WALLET_ID";
      const walletAddress = "YOUR_WALLET_ADDRESS";

      // Build an EVM transaction object for a signing test
      const txObject = {
        chainId: arcTestnet.id,
        nonce: "0",
        to: walletAddress,
        value: "0",
        gas: "21000",
        maxFeePerGas: "41500000000",
        maxPriorityFeePerGas: "1500000000",
      };

      // Sign the transaction
      const response = await client.signTransaction({
        walletId,
        transaction: JSON.stringify(txObject),
      });

      console.log(response.data);
    }

    main().catch((err) => {
      console.error("Error:", err.message || err);
      process.exit(1);
    });
    ```

    The transaction object must match the Ethereum JSON-RPC transaction shape. Use
    your own tooling to prepare it before calling `signTransaction()`. Include the
    correct `chainId` for your network. For supported `EVM-TESTNET` chains, see
    [Chain IDs for Signing Transactions](/wallets/sign-tx-chain-id). When building
    EIP-1559 transactions, include both `maxFeePerGas` and `maxPriorityFeePerGas`.

    ## Step 4. Review the response

    The signing response includes:

    * `signature`
    * `signedTransaction`
    * `txHash`

    You can use `signedTransaction` with your own broadcast flow or chain tooling.
  </Tab>

  <Tab title="Solana">
    ## Step 1. Set up your project

    ### 1.1. Create the project and install dependencies

    ```shell theme={null}
    # Create the project directory and initialize Node.js
    mkdir sign-transactions
    cd sign-transactions
    npm init -y

    # Set up module type and a script for Solana signing
    npm pkg set type=module
    npm pkg set scripts.sign-solana="tsx --env-file=.env sign-solana.ts"

    # Install runtime dependencies
    npm install @circle-fin/developer-controlled-wallets @solana/web3.js

    # Install dev dependencies
    npm install --save-dev tsx typescript @types/node
    ```

    ### 1.2. Configure TypeScript (optional)

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3. Set environment variables

    Create a `.env` file in the project directory:

    ```text .env theme={null}
    CIRCLE_API_KEY=YOUR_API_KEY
    CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
    ```

    * `CIRCLE_API_KEY` is your Circle Developer API key.
    * `CIRCLE_ENTITY_SECRET` is your registered entity secret.

    <Tip>
      Open `.env` in your editor rather than writing values with shell commands, and
      add `.env` to your `.gitignore`. This prevents credentials from leaking into
      your shell history or version control.
    </Tip>

    The `npm run` command in this tutorial loads variables from `.env` using Node.js
    native env-file support.

    ## Step 2. Create a signing wallet

    ```ts theme={null}
    const response = await client.createWallets({
      accountType: "EOA",
      blockchains: ["SOL-DEVNET"],
      count: 1,
      walletSetId: "YOUR_WALLET_SET_ID",
    });
    ```

    <Note>Use `count` to create up to 200 wallets per request.</Note>

    Fund the `SOL-DEVNET` wallet with devnet `SOL` before broadcasting signed
    transactions, or the account will not have the balance needed to pay fees
    onchain.

    ## Step 3. Build and sign a transaction

    ```ts sign-solana.ts theme={null}
    import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
    import {
      Connection,
      PublicKey,
      SystemProgram,
      Transaction,
      clusterApiUrl,
    } from "@solana/web3.js";

    // Initialize the wallets client
    const client = initiateDeveloperControlledWalletsClient({
      apiKey: process.env.CIRCLE_API_KEY!,
      entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
    });

    async function main() {
      // Set transaction inputs
      const walletId = "YOUR_SOLANA_WALLET_ID";
      const senderAddress = "YOUR_WALLET_ADDRESS";
      const recipientAddress = senderAddress;

      // Connect to the Solana RPC provider
      const connection = new Connection(clusterApiUrl("devnet"), "confirmed");

      // Build the Solana transaction for a signing test
      const instruction = SystemProgram.transfer({
        fromPubkey: new PublicKey(senderAddress),
        toPubkey: new PublicKey(recipientAddress),
        lamports: 0,
      });

      const { blockhash } = await connection.getLatestBlockhash();
      const transaction = new Transaction().add(instruction);
      transaction.recentBlockhash = blockhash;
      transaction.feePayer = new PublicKey(senderAddress);

      const rawTransaction = transaction.serialize({
        requireAllSignatures: false,
        verifySignatures: false,
      });

      // Sign the raw transaction
      const response = await client.signTransaction({
        walletId,
        rawTransaction: rawTransaction.toString("base64"),
      });

      // Broadcast the signed transaction
      const signedTransaction = Buffer.from(
        response.data?.signedTransaction ?? "",
        "base64",
      );

      const txid = await connection.sendRawTransaction(signedTransaction);

      console.log(response.data);
      console.log("Broadcast transaction ID:", txid);
    }

    main().catch((err) => {
      console.error("Error:", err.message || err);
      process.exit(1);
    });
    ```

    Base64 encode the raw transaction before you send it to `signTransaction()`. The
    signing request can succeed before the account is funded, but the broadcast step
    can still fail if the wallet has not received devnet `SOL`.

    ## Step 4. Review the response

    The signing response includes:

    * `signature`
    * `signedTransaction`

    If you broadcast the signed payload in the same script, you should also see the
    broadcast transaction ID.
  </Tab>

  <Tab title="NEAR">
    ## Step 1. Set up your project

    ### 1.1. Create the project and install dependencies

    ```shell theme={null}
    # Create the project directory and initialize Node.js
    mkdir sign-transactions
    cd sign-transactions
    npm init -y

    # Set up module type and a script for NEAR signing
    npm pkg set type=module
    npm pkg set scripts.sign-near="tsx --env-file=.env sign-near.ts"

    # Install runtime dependencies
    npm install @circle-fin/developer-controlled-wallets near-api-js

    # Install dev dependencies
    npm install --save-dev tsx typescript @types/node
    ```

    ### 1.2. Configure TypeScript (optional)

    <Tip>
      This step is optional. It helps prevent missing types in your IDE or editor.
    </Tip>

    Create a `tsconfig.json` file:

    ```shell theme={null}
    npx tsc --init
    ```

    Then, update the `tsconfig.json` file:

    ```shell theme={null}
    cat <<'EOF' > tsconfig.json
    {
      "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "types": ["node"]
      }
    }
    EOF
    ```

    ### 1.3. Set environment variables

    Create a `.env` file in the project directory:

    ```text .env theme={null}
    CIRCLE_API_KEY=YOUR_API_KEY
    CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
    ```

    * `CIRCLE_API_KEY` is your Circle Developer API key.
    * `CIRCLE_ENTITY_SECRET` is your registered entity secret.

    <Tip>
      Open `.env` in your editor rather than writing values with shell commands, and
      add `.env` to your `.gitignore`. This prevents credentials from leaking into
      your shell history or version control.
    </Tip>

    The `npm run` command in this tutorial loads variables from `.env` using Node.js
    native env-file support.

    ## Step 2. Create a signing wallet

    ```ts theme={null}
    const response = await client.createWallets({
      accountType: "EOA",
      blockchains: ["NEAR-TESTNET"],
      count: 1,
      walletSetId: "YOUR_WALLET_SET_ID",
    });
    ```

    <Note>Use `count` to create up to 200 wallets per request.</Note>

    Fund the `senderAccount` NEAR testnet account before broadcasting signed
    transactions, or the account will not have enough `NEAR` to pay network fees.

    Use these values from the wallet creation response in the next step:

    * `walletId` = the wallet `id`
    * `walletPublicKey` = the wallet `initialPublicKey`
    * `address` = the wallet's implicit account ID onchain

    For the signing script, `senderAccount` is the NEAR testnet account where you
    added the wallet `initialPublicKey` as a full-access key. It is not the Circle
    wallet `address` unless you specifically set up and fund that implicit account
    for signing.

    Before you continue, create or use an existing NEAR testnet account and add the
    wallet `initialPublicKey` as an access key on that account. Then use that
    account ID as `senderAccount` in the signing step. For setup guidance, see
    [Create an Account](https://docs.near.org/getting-started/create-account) and
    [NEAR CLI](https://docs.near.org/tools/cli).

    ## Step 3. Build and sign a transaction

    ```ts sign-near.ts theme={null}
    import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
    import {
      Account,
      JsonRpcProvider,
      nearToYocto,
      actions,
      encodeTransaction,
    } from "near-api-js";

    // Initialize the wallets client
    const client = initiateDeveloperControlledWalletsClient({
      apiKey: process.env.CIRCLE_API_KEY!,
      entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
    });

    const NEAR_CONFIG = {
      networkId: "testnet",
      nodeUrl: "https://rpc.testnet.near.org",
    };

    async function main() {
      // Set transaction inputs
      const walletId = "YOUR_NEAR_WALLET_ID";
      const walletPublicKey = "YOUR_NEAR_INITIAL_PUBLIC_KEY";
      const senderAccount = "YOUR_NEAR_TESTNET_ACCOUNT";
      const recipientAccount = senderAccount;

      // Connect to the NEAR RPC provider
      const provider = new JsonRpcProvider({ url: NEAR_CONFIG.nodeUrl });
      const sender = new Account(senderAccount, provider);

      const transactionActions = [actions.transfer(nearToYocto("0"))];

      // Build and serialize the NEAR transaction for a signing test
      const transaction = await sender.createTransaction({
        receiverId: recipientAccount,
        actions: transactionActions,
        publicKey: walletPublicKey,
      });

      const rawTransaction = Buffer.from(encodeTransaction(transaction)).toString(
        "base64",
      );

      // Sign the raw transaction
      const response = await client.signTransaction({
        walletId,
        rawTransaction,
      });

      console.log(response.data);
    }

    main().catch((err) => {
      console.error("Error:", err.message || err);
      process.exit(1);
    });
    ```

    Base64 encode the raw transaction before you send it to `signTransaction()`.

    For example, if the create-wallet response includes:

    ```text theme={null}
    {
      id: "40313ab7-9abd-57f3-a067-617df1530383",
      address: "8c18a0fb0717bc82f6cc7ca019e2cbd92ca5cb0767f47ef2cb2a70a0d561ad88",
      initialPublicKey: "ARsrrXKzD5C9Bj9BxEzTQNNsBUGk35FM3vyUL5PbgwLj"
    }
    ```

    and you add `initialPublicKey` to `my-circle-signer.testnet`, then set:

    ```ts theme={null}
    const walletId = "40313ab7-9abd-57f3-a067-617df1530383";
    const walletPublicKey = "ARsrrXKzD5C9Bj9BxEzTQNNsBUGk35FM3vyUL5PbgwLj";
    const senderAccount = "my-circle-signer.testnet";
    ```

    ## Step 4. Review the response

    The signing response includes:

    * `signature`
    * `signedTransaction`
    * `txHash`

    Broadcast that signed payload through your own RPC or node provider.
  </Tab>
</Tabs>


# EVM Testnet Chain IDs for Signing
Source: https://developers.circle.com/wallets/sign-tx-chain-id

Chain IDs supported by EVM testnet wallets for signing transactions.

`EVM-TESTNET` wallets support signing on the blockchains listed below. For
mainnet `EVM` wallets, you can sign on any EVM-compatible blockchain using its
standard chain ID. Find chain IDs at [chainlist.org](https://chainlist.org).

<Note>
  This list covers blockchains outside Circle's natively supported testnets.
  Circle-supported testnets such as Arc Testnet use their own chain codes and
  are listed in [Supported Blockchains](/wallets/supported-blockchains). They do
  not require an `EVM-TESTNET` wallet.
</Note>

For instructions on how to sign transactions, see
[Sign Transactions on EVM Chains](/wallets/sign-tx-evm).

| Chain ID    | Blockchain                               |
| ----------- | ---------------------------------------- |
| 9           | Ubiq Network Testnet                     |
| 16          | Flare Testnet Coston                     |
| 18          | ThunderCore Testnet                      |
| 21          | Elastos Smart Chain Testnet              |
| 31          | Rootstock Testnet                        |
| 41          | Telos EVM Testnet                        |
| 43          | Darwinia Pangolin Testnet                |
| 45          | Darwinia Pangoro Testnet                 |
| 65          | OKExChain Testnet                        |
| 69          | Optimism Kovan                           |
| 83          | Meter Testnet                            |
| 97          | BNB Smart Chain Testnet                  |
| 114         | Flare Testnet Coston2                    |
| 120         | ENULS Testnet                            |
| 123         | Fuse Sparknet                            |
| 155         | Tenet Testnet                            |
| 170         | HOO Smart Chain Testnet                  |
| 226         | LACHAIN Testnet                          |
| 296         | Hedera Testnet                           |
| 322         | KCC Testnet                              |
| 335         | DFK Chain Test                           |
| 338         | Cronos Testnet                           |
| 363         | Theta Sapphire Testnet                   |
| 364         | Theta Amber Testnet                      |
| 365         | Theta Testnet                            |
| 568         | Dogechain Testnet                        |
| 588         | Metis Stardust Testnet                   |
| 647         | SX Network Testnet                       |
| 740         | Canto Testnet                            |
| 919         | Mode Testnet                             |
| 940         | PulseChain Testnet                       |
| 941         | PulseChain Testnet v2b                   |
| 942         | PulseChain Testnet v3                    |
| 943         | PulseChain Testnet v4                    |
| 999         | Wanchain Testnet                         |
| 1007        | Newton Testnet                           |
| 1028        | BitTorrent Chain Testnet                 |
| 1112        | WEMIX3.0 Testnet                         |
| 1115        | Core Blockchain Testnet                  |
| 1230        | Ultron Testnet                           |
| 1338        | Elysium Testnet                          |
| 1402        | Polygon zkEVM Testnet old                |
| 1422        | Polygon zkEVM Testnet Pre Audit-Upgraded |
| 1442        | Polygon zkEVM Testnet                    |
| 1686        | Mint Testnet                             |
| 1819        | Cube Chain Testnet                       |
| 1891        | Lightlink Pegasus Testnet                |
| 1945        | ONUS Chain Testnet                       |
| 2153        | Findora Testnet                          |
| 2154        | Findora Forge                            |
| 2221        | Kava Testnet                             |
| 2358        | Kroma Sepolia                            |
| 2522        | Fraxtal Testnet                          |
| 3141        | Filecoin - Hyperspace testnet            |
| 4002        | Fantom Testnet                           |
| 4062        | Nahmii 3 Testnet                         |
| 4202        | Lisk Sepolia Testnet                     |
| 4690        | IoTeX Network Testnet                    |
| 5001        | Mantle Testnet                           |
| 5003        | Mantle Sepolia Testnet                   |
| 5553        | Nahmii Testnet                           |
| 5611        | opBNB Testnet                            |
| 5700        | Syscoin Tanenbaum Testnet                |
| 5851        | Ontology Testnet                         |
| 7001        | ZetaChain Athens 3 Testnet               |
| 7701        | Canto Tesnet                             |
| 7771        | Bitrock Testnet                          |
| 9000        | Evmos Testnet                            |
| 9527        | Rangers Protocol Testnet Robin           |
| 9728        | Boba BNB Testnet                         |
| 10200       | Gnosis Chiado Testnet                    |
| 12345       | Step Testnet                             |
| 13337       | Beam Testnet                             |
| 20729       | Callisto Testnet                         |
| 22040       | AirDAO Testnet                           |
| 23888       | Blast Testnet                            |
| 31337       | GoChain Testnet                          |
| 31415       | Filecoin - Wallaby testnet               |
| 43113       | Avalanche Fuji Testnet                   |
| 43851       | ZKFair Testnet                           |
| 44787       | Celo Alfajores Testnet                   |
| 46688       | Fusion Testnet                           |
| 49797       | Energi Testnet                           |
| 54211       | Haqq Chain Testnet                       |
| 55556       | REI Chain Testnet                        |
| 57000       | Rollux Testnet                           |
| 59140       | Linea Testnet                            |
| 62320       | Celo Baklava Testnet                     |
| 71401       | Godwoken Testnet v1                      |
| 80002       | Amoy                                     |
| 84532       | Base Sepolia Testnet                     |
| 88880       | Chiliz Scoville Testnet                  |
| 128123      | Etherlink Testnet                        |
| 167004      | Taiko (Alpha-2 Testnet)                  |
| 314159      | Filecoin - Calibration testnet           |
| 333888      | Polis Testnet                            |
| 421614      | Arbitrum Sepolia                         |
| 432201      | Dexalot Subnet Testnet                   |
| 534351      | Scroll Sepolia Testnet                   |
| 534353      | Scroll Alpha Testnet                     |
| 534354      | Scroll Pre-Alpha Testnet                 |
| 666888      | Hela Official Runtime Testnet            |
| 723107      | TixChain Avalanche Subnet                |
| 3141592     | Filecoin - Butterfly testnet             |
| 3441005     | Manta Pacific Testnet                    |
| 5201420     | Electroneum Testnet                      |
| 11155111    | Sepolia                                  |
| 11155420    | OP Sepolia Testnet                       |
| 28122024    | Ancient8 Testnet                         |
| 31415926    | Filecoin - Local testnet                 |
| 168587773   | Blast Sepolia Testnet                    |
| 245022926   | Neon EVM Devnet                          |
| 245022940   | Neon EVM TestNet                         |
| 999999999   | Zora Sepolia Testnet                     |
| 1313161555  | Aurora Testnet                           |
| 1666700000  | Harmony Testnet Shard 0                  |
| 1666700001  | Harmony Testnet Shard 1                  |
| 1666900000  | Harmony Devnet Shard 0                   |
| 1666900001  | Harmony Devnet Shard 1                   |
| 11297108099 | Palm Testnet                             |


# Transaction Signing and Authorization
Source: https://developers.circle.com/wallets/signing-and-authorization-models

How signing and authorization work across Circle Wallets products, including who initiates and approves transactions, where keys live, and the transaction signing lifecycle.

How transactions are initiated and authorized depends on the
[wallet type you choose](/wallets/account-types). The wallet type determines who
controls signing (your backend or your users) and where keys live.

## Who initiates and who approves transactions

Every onchain transaction must be initiated and authorized before it is
broadcast. Initiating means requesting the transaction. Authorizing means
approving the signing. The following table shows who handles each and where keys
are held for each wallet type.

| Wallet type          | Who initiates                                                                                                                 | Who authorizes                                                                                                     | Keys                                                                                                  |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Developer-controlled | Your backend (API/SDK). Your users can also initiate a request from your app after you authenticate them and assign a wallet. | Your backend, using the entity secret.                                                                             | MPC. You hold the entity secret. Circle hosts MPC nodes, or you host them (for example, on-premises). |
| User-controlled      | Your app calls user APIs or SDKs (client or server) for the signed-in end user.                                               | Your user, by authenticating in your app. Circle cannot sign without your user's approval.                         | MPC. Only your user can complete signing.                                                             |
| Modular              | Your app (SDK), on behalf of your user.                                                                                       | Your user (passkey). Circle cannot sign without your user's approval. The passkey never leaves your user's device. | Passkey on your user's device (or cloud backup).                                                      |

For details on how keys are secured (MPC and passkeys), see
[Key management](/wallets/key-management).

## Transaction signing lifecycle

1. **Initiate:** A client (your backend or your app) calls Circle APIs to create
   a transaction signing request (for example, transfer, contract call).
2. **Authorize:** The party that controls the key approves the signing. In
   developer-controlled wallets, your backend approves using the entity secret.
   In user-controlled and modular wallets, your user authenticates using a
   confirmation UI, PIN, or biometrics, and approves in your app.
3. **Sign:** Circle (with MPC or passkey participation) produces the signature.
4. **Broadcast:** The signed transaction is sent to the blockchain. For
   supported blockchains, Circle can handle broadcasting, or you can choose to
   use the [signing APIs](/wallets/signing-apis) with your own node.

<Info>
  **Submitted vs finalized**

  Sending a transaction to the blockchain (submitted) and the blockchain
  processing it to finality (complete) are two separate events. Circle's API
  response does not indicate finality. State changes (for example, sent,
  confirmed, failed) are delivered asynchronously. Set up
  [Webhook notifications](/wallets/webhook-notifications-for-wallets) to receive
  them.
</Info>


# How Signing APIs Work
Source: https://developers.circle.com/wallets/signing-apis

Learn how Circle's signing APIs work for developer-controlled wallets when you manage broadcasting yourself.

Circle provides signing APIs that allow developer-controlled wallets to sign
transactions, messages, or typed data. Use these APIs when Circle doesn't
provide full [blockchain infrastructure](/wallets/blockchain-infrastructure) for
your blockchain, or when you prefer to manage broadcasting yourself.

For step-by-step instructions, see
[Sign Transactions on EVM Chains](/wallets/sign-tx-evm),
[Solana](/wallets/sign-tx-solana), or [NEAR](/wallets/sign-tx-near).

## Signing endpoints

Circle provides four signing endpoints for developer-controlled wallets. You
call one endpoint per request, depending on what you are signing:

* [Sign transaction](/api-reference/wallets/developer-controlled-wallets/sign-transaction):
  Sign a raw transaction for broadcasting to a blockchain.
* [Sign message](/api-reference/wallets/developer-controlled-wallets/sign-message):
  Sign an arbitrary message using EIP-191 (EVM) or a plain message (NEAR).
* [Sign typed data](/api-reference/wallets/developer-controlled-wallets/sign-typed-data):
  Sign structured data using EIP-712 (EVM only).
* [Sign delegate action](/api-reference/wallets/developer-controlled-wallets/sign-delegate-action):
  Sign a delegate action to authorize another account to act on your behalf
  (NEAR only).

## The signing flow

To sign and broadcast a transaction:

1. Build the raw transaction in your application, including nonce, gas
   parameters, and any blockchain-specific encoding. For example, NEAR requires
   Borsh serialization before signing.
2. Call the
   [Sign transaction](/api-reference/wallets/developer-controlled-wallets/sign-transaction)
   endpoint. Circle signs the transaction and returns the signed payload.
3. Broadcast the signed transaction to a node provider of your choice.

The following diagram illustrates this flow.

```mermaid theme={null}
sequenceDiagram
    participant App as Your application
    participant Circle as Circle Signing API
    participant Node as Your node provider

    App->>Circle: Send raw transaction to signing endpoint
    Circle-->>App: Return signed transaction
    App->>Node: Broadcast signed transaction
    Node-->>App: Transaction hash
```

When you manage broadcasting, you are also responsible for monitoring
transaction status, deposit detection, and balance retrieval.

## Signing for EVM wallets

For blockchains in the [Supported Blockchains](/wallets/supported-blockchains)
Other EVM category, create a wallet using `blockchain: EVM` for mainnet or
`blockchain: EVM-TESTNET` for testing. These are virtual blockchain parameters
not tied to a specific blockchain. You specify the target blockchain using
`chainId` at signing time. For a list of supported testnet chain IDs, see
[EVM Testnet Chain IDs for Signing](/wallets/sign-tx-chain-id).

<Warning>
  An EVM wallet shares the [same
  address](/wallets/unified-wallet-addressing-evm) as other wallets in the same
  wallet set. If you sign a transaction targeting a blockchain by [chain
  ID](/wallets/sign-tx-chain-id), the transaction executes from the wallet on
  that blockchain. For example, signing a transaction with chain ID `42161`
  executes from your Arbitrum wallet, even if you intended to sign for a
  different blockchain. Verify the chain ID before signing to avoid unintended
  transactions and stuck funds.
</Warning>

## SCA wallets and lazy deployment

[Smart contract account (SCA) wallets](/wallets/account-types#smart-contract-accounts-sca-and-msca)
use lazy deployment. The wallet contract is not deployed onchain until the first
transaction. Calls to
[Sign message](/api-reference/wallets/developer-controlled-wallets/sign-message)
or
[Sign typed data](/api-reference/wallets/developer-controlled-wallets/sign-typed-data)
before the wallet is deployed will fail. The wallet must complete at least one
onchain transaction before signing arbitrary messages or typed data.


# Supported Blockchains
Source: https://developers.circle.com/wallets/supported-blockchains

Supported blockchains for Circle Wallets, including account types, token standards, and API limitations by blockchain.

Circle Wallets supports multiple blockchains. Account type support, token
standards, and API coverage vary by blockchain.

## Supported blockchains by account type

The following tables list supported blockchains and account types.
Developer-controlled and user-controlled wallets support Externally Owned
Accounts (EOA) and Smart Contract Accounts (SCA). Modular wallets use Modular
Smart Contract Accounts (MSCA) only. For a full comparison, see
[Choose your wallet and account types](/wallets/account-types).

<Note>
  For "Other EVM blockchains," create wallets using the `EVM` or `EVM-TESTNET`
  chain code. Wallet addresses are consistent across all EVM-compatible
  blockchains. See
  [Unified wallet addressing across EVM chains](/wallets/unified-wallet-addressing-evm).
</Note>

### Mainnet

| Blockchain            | Chain code |                        EOA                       | SCA | MSCA |
| --------------------- | :--------: | :----------------------------------------------: | :-: | :--: |
| Aptos                 |   `APTOS`  |                         ✅                        |  ❌  |   ❌  |
| Arbitrum              |    `ARB`   |                         ✅                        |  ✅  |   ✅  |
| Avalanche             |   `AVAX`   |                         ✅                        |  ✅  |   ✅  |
| Base                  |   `BASE`   |                         ✅                        |  ✅  |   ✅  |
| Ethereum              |    `ETH`   |                         ✅                        |  ✅  |   ❌  |
| Monad                 |   `MONAD`  |                         ✅                        |  ✅  |   ✅  |
| NEAR                  |   `NEAR`   | [Signing only](#blockchain-specific-limitations) |  ❌  |   ❌  |
| Optimism              |    `OP`    |                         ✅                        |  ✅  |   ✅  |
| Polygon PoS           |   `MATIC`  |                         ✅                        |  ✅  |   ✅  |
| Solana                |    `SOL`   |                         ✅                        |  ❌  |   ❌  |
| Unichain              |    `UNI`   |                         ✅                        |  ✅  |   ✅  |
| Other EVM blockchains |    `EVM`   |                         ✅                        |  ❌  |   ❌  |

### Testnet

| Blockchain            |    Chain code   |                        EOA                       | SCA | MSCA |
| --------------------- | :-------------: | :----------------------------------------------: | :-: | :--: |
| Aptos Testnet         | `APTOS-TESTNET` |                         ✅                        |  ❌  |   ❌  |
| Arbitrum Sepolia      |  `ARB-SEPOLIA`  |                         ✅                        |  ✅  |   ✅  |
| Arc Testnet           |  `ARC-TESTNET`  |                         ✅                        |  ✅  |   ✅  |
| Avalanche Fuji        |   `AVAX-FUJI`   |                         ✅                        |  ✅  |   ✅  |
| Base Sepolia          |  `BASE-SEPOLIA` |                         ✅                        |  ✅  |   ✅  |
| Ethereum Sepolia      |  `ETH-SEPOLIA`  |                         ✅                        |  ✅  |   ❌  |
| Monad Testnet         | `MONAD-TESTNET` |                         ✅                        |  ✅  |   ✅  |
| NEAR Testnet          |  `NEAR-TESTNET` | [Signing only](#blockchain-specific-limitations) |  ❌  |   ❌  |
| Optimism Sepolia      |   `OP-SEPOLIA`  |                         ✅                        |  ✅  |   ✅  |
| Polygon PoS Amoy      |   `MATIC-AMOY`  |                         ✅                        |  ✅  |   ✅  |
| Solana Devnet         |   `SOL-DEVNET`  |                         ✅                        |  ❌  |   ❌  |
| Unichain Sepolia      |  `UNI-SEPOLIA`  |                         ✅                        |  ✅  |   ✅  |
| Other EVM blockchains |  `EVM-TESTNET`  |                         ✅                        |  ❌  |   ❌  |

## Supported tokens and standards

* **Aptos**: native coin, Fungible Asset
* **EVM-compatible blockchains**: native coin, ERC-20, ERC-721, and ERC-1155
* **Solana**: native coin, SPL

## Blockchain-specific limitations

Every [Wallets API](/api-reference/wallets) endpoint is available on all
supported blockchains, except for the blockchains listed below.

* **Aptos**:
  * NFT lookup is not supported.
  * Balance queries return tokens in primary storage only. Tokens in secondary
    storage
    ([AIP-21](https://github.com/aptos-labs/aptos-core/releases/tag/aptos-node-v1.5.0))
    are excluded.
  * Contract execution
    ([developer-controlled](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-contract-execution),
    [user-controlled](/api-reference/wallets/user-controlled-wallets/create-user-transaction-contract-execution-challenge))
    is limited to batch transfers. The `abiFunctionSignature` and
    `contractAddress` fields must use fixed values. The request body below shows
    the required values (`entitySecretCiphertext` is required for
    developer-controlled wallets only).

    ```json JSON theme={null}
    {
      "idempotencyKey": "{{$YourUUID}}",
      "walletId": "639ff7f1-2fed-5de4-9976-c1706ca1ef88",
      "feeLevel": "MEDIUM",
      "abiFunctionSignature": "aptos_account::batch_transfer_fungible_assets(metadata:object::Object<fungible_asset::Metadata>,recipients:vector<address>,amounts:vector<u64>)",
      "abiParameters": [
        "0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832",
        [
          "0xe78568bcfc30070fae04c1c4ba267eecc228e077672e18086baa042cbfb0ba70",
          "0xb8019c3e505fafe00edd1ba95c34f3f78e957da668c23ecb56ccd3a59ee8f21e"
        ],
        ["1", "1"]
      ],
      "contractAddress": "0x1",
      "refId": "aptos-testnet-contractExecution",
      "entitySecretCiphertext": "{{entity-secret-ciphertext}}"
    }
    ```

* **Arbitrum**: Accelerate and cancel transactions are not supported.

* **NEAR**: Developer-controlled wallets support signing only
  ([sign transaction](/api-reference/wallets/developer-controlled-wallets/sign-transaction)
  and
  [sign delegate action](/api-reference/wallets/developer-controlled-wallets/sign-delegate-action)).
  Transfers, balances, NFT lookup, and contract execution are not supported.
  User-controlled wallets are not supported.

* **Other EVM blockchains**: Wallet creation and signing are supported.
  Transfers are supported for developer-controlled wallets only. Contract
  execution, accelerate, and cancel are not supported.

* **Solana**: Contract execution is not supported. Signing typed data is not
  supported. Accelerate and cancel transactions are not supported.


# Transaction Rate Limits and Optimizations
Source: https://developers.circle.com/wallets/transaction-limits-and-optimizations



In this guide, you'll learn about the transaction rate limits imposed by
supported blockchains and Circle Wallets. You'll also get client-side
optimization tips to ensure smooth transaction processing within your
applications.

## Transaction Queue Limits

### Blockchain Account Queue Limit

EVM-compatible blockchains typically use a Mempool system. The Mempool queues
transactions sent from a wallet up to a certain limit defined by the full node.
If you exceed this limit, you receive an error from the full node. All queued
transactions in the Mempool can potentially be included in a single block.
Therefore, you can estimate the theoretical transaction throughput as
`queueLimit` / `blockTime`. However, various factors can influence whether your
transaction gets included in a block, such as priority fees, network congestion,
and network liveness. In contrast, the Solana blockchain does not use a Mempool
system and, thus, does not have a queue limit. This contributes to its
transaction throughput being significantly higher.

#### Account queue limit in different blockchains

| Blockchain          | EOA wallet      | SCA wallet          |
| ------------------- | --------------- | ------------------- |
| Ethereum            | 32 transactions | 1 transaction       |
| Polygon             | 16 transactions | 1 transaction       |
| Avalanche           | 32 transactions | 1 transaction       |
| Solana (no Mempool) | Unlimited       | Not supported by PW |

#### Circle Wallets Transaction Queue Limit

The overall transaction throughput is fundamentally constrained by the
blockchain account queue limit and the blockchain's inherent throughput. To
mitigate the impact of these limitations, Circle Wallets provide a queuing
mechanism for transactions that exceed the blockchain limit for a certain
duration. There is a limit on the number of transactions your wallet can queue
in the Circle Wallets service to prevent resource wastage and false
expectations. This limit affects the user experience when too many transaction
requests are made. When you reach this limit, you receive an error message:

<Danger>
  "Wait for pending transactions to be included on the blockchain before
  submitting new requests. EVM chains restrict the number of queued transactions
  per sender address." (Error code 155264)
</Danger>

More detailed error descriptions and suggestions can be found in the
[Transaction error codes](/wallets/error-codes#transaction-error-codes-155201---155299)
section.

To check the number of pending transactions and their status, use the
[list transactions API](/api-reference/wallets/developer-controlled-wallets/list-transactions).
The transaction state should be one of the following: `INITIATED`, `CLEARED`,
`QUEUED`, `SENT`, `STUCK`.

## Client-side Optimizations

While transaction queuing provides a convenient feature, fee fluctuations and
network congestion can still impact transaction processing times. Below are some
tips to ensure a smooth experience, especially when dealing with a high volume
of transaction requests.

### Higher Fees

Consider setting the `fee_level` parameter to at least `MEDIUM` or `HIGH`. This
ensures that your transactions are processed with higher priority in a
reasonable timeframe, reducing delays for subsequent transactions.

### Managing Transactions

This section describes how to monitor and manage transactions that are pending
but still processing normally (for example, in the `QUEUED` or `SENT` states).
If a transaction remains unconfirmed for an extended period and enters the
`STUCK` state, see [Handling Stuck Transactions](#handling-stuck-transactions).

You can monitor and manage pending transactions in several ways.

<Note>
  **Recommended approach**

  Use [webhook notifications](/wallets/webhook-logs) as the primary method for
  tracking transaction status. Webhooks provide real-time updates and are more
  efficient than polling API endpoints. If you need to proactively check
  transaction status or implement custom retry logic, you can also use the Get or
  List API endpoints, but be aware that frequent polling may lead to increased
  resource use and rate limiting.
</Note>

1. **Monitor Transaction Status**: Use the
   [get transaction API](/api-reference/wallets/developer-controlled-wallets/get-transaction)
   if you know the transaction ID, or the
   [list transactions API](/api-reference/wallets/developer-controlled-wallets/list-transactions)
   to query multiple transactions or filter by state.
2. **Cancellation or Acceleration**: Use the
   [cancel transaction API](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-cancel)
   or
   [accelerate transaction API](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-accelerate)
   to manage transactions that have been pending for an extended period.
3. **Transaction notifications**: Implement
   [webhook events](/wallets/webhook-logs) to confirm the completion of
   transactions before sending more requests.

### Handling Stuck Transactions

In rare cases, a transaction might remain unconfirmed onchain for an extended
period because its network fee is too low to meet the current blockchain
requirements. When this happens, the transaction enters the `STUCK` state.

A `STUCK` transaction is one that has been sent to the blockchain but could not
be included in a block because the network fee is below the level required for
inclusion. This state specifically refers to transactions that are underpriced
relative to current network conditions, such as when gas prices rise during high
congestion, or when the provided `feeLevel` or the custom `priorityFee` and
`maxFee` values are too low.

To resolve a stuck transaction:

1. **Accelerate it**: Use the
   [accelerate transaction API](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-accelerate)
   to resubmit the transaction with a higher fee. The acceleration API
   automatically applies a `HIGH` fee level.
2. **Cancel it**: If you prefer not to accelerate the transaction, use the
   [cancel transaction API](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-cancel)
   to cancel it before it's mined. Note that this action also incurs gas fees.

After taking one of these actions, monitor the transaction status using
[webhook notifications](/wallets/webhook-logs) (recommended) or the
[list transactions API](/api-reference/wallets/developer-controlled-wallets/list-transactions)
to confirm that the state has updated.

If a transaction remains in the `STUCK` state, you must either accelerate or
cancel it. Leaving it unresolved may block subsequent transactions from the same
wallet.

The `STUCK` state is not a terminal failure but a signal that manual or
programmatic intervention is required to ensure confirmation.

<Note>
  For details on asynchronous transaction states and error codes, see
  [Transaction States and Errors](/wallets/asynchronous-states-and-statuses).
</Note>

### Multiple Sender Wallets

Using multiple sender wallets can help bypass the per-wallet queue limit and
increase the level of parallel processing. This strategy is generally effective
across various blockchains.

### Batch Transactions with Smart Contracts

Leveraging smart contracts for batch transactions can significantly reduce the
number of transactions needed for repetitive tasks. For instance, instead of
sending 1,000,000 transfer transactions individually, you can deploy an airdrop
contract that processes transfers to 500 wallets in a single execution call,
requiring only 2,000 transactions in total. Although a single contract execution
call may incur higher gas costs than a simple transfer, it is often more gas and
time-efficient for batch transactions.

For more details, please refer to our
[Airdrop template for Circle Contracts](/contracts/airdrop) .

## Summary

By understanding the transaction queue limits and exploiting the above
optimization tips, you can improve the transaction throughput of your
applications, thereby increasing their overall efficiency when interacting with
blockchain networks.


# How-to: Troubleshoot Failed Transactions
Source: https://developers.circle.com/wallets/troubleshoot-failed-transactions

Diagnose and resolve failed transactions using error details, parameter checks, and the Tenderly debugging tool.

## Overview

* Helps you interpret `errorReason` and `errorDetails` fields returned on failed
  transactions.
* Guides you through systematic checks to identify the root cause of a failure.

## Prerequisites

Before you begin:

* You have a failed transaction with an `errorReason` of `ESTIMATION_ERROR` or
  another error code.
* You have reviewed the error fields in the transaction object. See
  [Transaction states and errors](/wallets/asynchronous-states-and-statuses) for
  a full list of error codes and their meanings.

## Steps

### Step 1. Read the error message

Check the `errorDetails` field carefully. Many errors are self-explanatory, for
example, "Insufficient balance" or "Not authorized." Cross-reference the value
against the
[ESTIMATION\_ERROR details](/wallets/asynchronous-states-and-statuses#estimation_error-details)
tables to identify the category and recommended remedy.

### Step 2. Verify contract addresses

Confirm that you are interacting with the correct contract on the correct
network. A transaction sent to the wrong contract address or the wrong network
will fail or produce unexpected results.

### Step 3. Verify transaction parameters

Ensure all addresses, amounts, and other parameters are correct:

* Recipient addresses are valid and non-zero.
* Token amounts meet or exceed any minimum thresholds.
* ABI signatures match the function being called.

### Step 4. Check token balances and allowances

Many errors stem from insufficient balances or missing approvals:

* Verify the wallet has enough of the token being transferred.
* For ERC-20 interactions involving a spending contract, confirm the wallet has
  called `approve()` to grant sufficient allowance.

### Step 5. Review contract state

Some operations are only valid in certain contract states. Confirm that the
contract is not paused and that any role-based access requirements are
satisfied.

### Step 6. Verify authorization

Ensure the calling wallet has the permissions required by the contract. Check
for role assignments and blocklist status if you are working with regulated
tokens such as USDC.

### Step 7. Retry time-sensitive operations

For errors related to expired signatures, nonces, or network conditions, retry
the operation:

* Generate a fresh signature or nonce if the original has expired.
* Retry after a short delay if the error suggests an RPC node was temporarily
  unavailable.

## Debug with Tenderly

For complex errors where `errorDetails` does not provide enough information, use
[Tenderly](https://tenderly.co/) to simulate and inspect the failing
transaction. Tenderly lets you step through execution and identify exactly where
and why the transaction reverts.


# Unified Wallet Addressing on EVM Chains
Source: https://developers.circle.com/wallets/unified-wallet-addressing-evm

Support same address wallets across multiple EVM chains.

To provide a seamless wallet experience for your users across multiple EVM
blockchains, you may want to offer wallets that maintain the **same address** on
each chain. Unified addressing benefits your users in two key ways:

* It creates a unified experience across chains and reduces the number of wallet
  addresses users need to manage.
* It provides a recovery path if users accidentally deposit tokens to an address
  on an unsupported chain. For **user-controlled wallets**, this happens
  automatically when you pass the user JWT token during
  [wallet creation](/api-reference/wallets/user-controlled-wallets/create-user-wallet).

For **developer-controlled wallets**, you need to implement the following
capabilities:

* Create wallets across multiple EVM chains using a shared `walletSetId` and
  `refId`.
* Derive wallets and add them on-demand for supported chains that users opt
  into.
* Recover assets from unsupported EVM chains by signing and broadcasting
  transactions.
* Understand how address indexes work to maintain consistency.
* Follow best practices to manage wallet set limits effectively.

## Batch create wallets across supported chains

For chains you support by default, use the
[`POST /wallets`](/api-reference/wallets/developer-controlled-wallets/create-wallet)
API to create wallets in batches.

Include the following in your request:

* `walletSetId` to group wallets that will share an address index.
* An array of `blockchains` representing the chains to support.
* An array of `refIds` to associate each wallet back to a user ID in your
  system.

When a wallet is created with a `refId`, all EVM wallets sharing that `refId` in
that API call will have the same address. You can retrieve these wallets using
the
[`GET /wallets`](/api-reference/wallets/developer-controlled-wallets/get-wallets)
API.

## Derive wallets on demand for supported chains

For EVM chains that users can opt into, or in cases where assets are deposited
to a chain not enabled by default, use the
[`PUT /wallets/{id}/blockchains/{blockchain}`](/api-reference/wallets/developer-controlled-wallets/derive-wallet)
API to derive a wallet.

Provide the following in this request:

* Provide the existing `walletId` and `refId` for the user.
* Specify the new EVM chain to create the wallet on.

This will generate a wallet on the specified EVM chain with the **same address**
as the existing wallet.

## Recover tokens on unsupported EVM chains

For unsupported EVM chains:

* Create a wallet with `blockchain: EVM`.
* Use the
  [Sign transaction](/api-reference/wallets/developer-controlled-wallets/sign-transaction)
  API to move the assets out.

<Note>
  **Note:** For unsupported EVM chains, you are responsible for broadcasting the
  signed transaction to the chain yourself.
</Note>

This gives you the flexibility to support recovery scenarios across **any**
EVM-compatible chain.

## Understand how wallet addresses are derived

Wallet addresses are derived based on the index in the `walletSet`. A single
index (for example, `0x3`) maps to the same address on all EVM chains.

### Wallet creation behavior

* If you call **POST /wallets** for a single chain with no existing wallets, it
  starts at index `0x1` and increments.
* If you call **POST /wallets** across multiple chains, it uses the latest
  available index and assigns the same address across chains.
* If you call **POST /wallets** again for an individual chain, it increments
  only on that chain.
* If you call **POST /wallets** for a new chain (no existing wallets), it starts
  at `0x1`.
* Use
  [`PUT /wallets/{id}/blockchains/{blockchain}`](/api-reference/wallets/developer-controlled-wallets/derive-wallet)
  to derive wallets and fill address gaps across chains.

### Address index example

The example below illustrates how address indexes work across chains.

| EVM Chain | 0x1 | 0x2 | 0x3 | 0x4 | 0x5 |
| --------- | --- | --- | --- | --- | --- |
| Ethereum  | 1   | 2   | 3   |     | 7   |
| Polygon   |     |     | 3   | 4   | 7   |
| Arbitrum  | 5   | 6   |     |     | 7   |

Walkthrough of the address derivation logic:

1. **Step 1–2**: Creating wallets on Ethereum only results in `0x1`, then `0x2`.
2. **Step 3**: Creating wallets on Ethereum + Polygon at once results in both
   getting `0x3`.
3. **Step 4**: Creating a new wallet only on Polygon now returns `0x4`.
4. **Step 5–6**: Creating wallets on Arbitrum (new chain) starts at `0x1`, then
   `0x2`.
5. **Step 7**: Creating wallets across Ethereum, Polygon, and Arbitrum takes the
   latest index and creates them at `0x5`.

To fill gaps in the table, derive wallets using
[`PUT /wallets/{id}/blockchains/{blockchain}`](/api-reference/wallets/developer-controlled-wallets/derive-wallet).

<Note>
  **Do not assign a unique `walletSetId` per user.**

  You're limited to **1,000 wallet sets** total, with **up to 10 million wallets
  per wallet set**. For details, see
  [wallet sets](/w3s/programmable-wallets-primitives#wallet-sets).
</Note>

## Summary

Using Circle's wallet APIs, you can create and manage wallets that share the
same address across multiple EVM chains. This unified approach improves the user
experience and enables safe asset recovery, even on unsupported chains. By
leveraging `walletSetId`, `refId`, and the appropriate API endpoints, you can
batch-create wallets, add support for new chains on demand, and maintain
consistent wallet derivation logic across your application.


# User-Controlled Wallets
Source: https://developers.circle.com/wallets/user-controlled

Understand how user-controlled wallets work, when to use them, and how Circle enables user-owned keys with social or email authentication, or PIN validation.

User-controlled wallets allow you to create wallets for your users that give
them full control of their keys with a Web2-like experience. Users onboard with
popular authentication mechanisms (social login, email OTP, or PIN with security
questions), then approve transactions and signatures from their device. For a
comparison of all wallet products, see
[Choose your wallet product and account types](/wallets/account-types).

## Key features

<CardGroup>
  <Card title="User retains custody" icon="key">
    Users have full control of their private keys secured with
    <Tooltip>2-of-2 MPC</Tooltip>
    . Your app or backend never holds user keys. See [Key
    management](/wallets/key-management) for more details.
  </Card>

  <Card title="Seamless onboarding" icon="fingerprint">
    Choose from social login (Google, Apple, Facebook), email OTP, or PIN with
    security questions to authenticate your users. Optional biometrics with PIN.
  </Card>

  <Card title="Customizable UIs" icon="display">
    For social login and email OTP, Circle provides confirmation UIs for
    transfers and signing that you can customize or turn off to build and match
    your own branding.
  </Card>
</CardGroup>

## What you can build

<CardGroup>
  <AccordionGroup>
    <Accordion title="Payments and P2P apps" icon="arrow-right-arrow-left">
      Build payment or remittance apps with USDC, with faster settlement and low
      fees versus traditional rails, no custody or key management for you. Users
      approve transfers in your app; you execute using Circle APIs.
    </Accordion>

    <Accordion title="Commerce and checkout" icon="cart-shopping">
      Build marketplaces and subscriptions with in-app crypto checkout. One-tap
      approval, higher conversion, no external wallets or seed phrases. Users
      approve; you run checkout and complete the transfer using Circle APIs.
    </Accordion>

    <Accordion title="DeFi and onchain apps" icon="cube">
      Build lending, swapping, yield/earn, or other DeFi flows with user
      custody. Users sign (for example,
      <Tooltip>EIP-191</Tooltip>
      ,
      <Tooltip>EIP-712</Tooltip>
      ) from your app, with no key export or separate wallet; optional gas
      sponsorship hides gas complexity. You orchestrate the flow and never hold
      keys.
    </Accordion>
  </AccordionGroup>

  <AccordionGroup>
    <Accordion title="Social and creator apps" icon="users">
      Enable tipping, creator payouts, and in-app rewards in USDC. You provide
      the social or content layer; users hold the wallet. SDK creates wallets
      and runs transfers with user approval.
    </Accordion>

    <Accordion title="Gaming and rewards" icon="gamepad">
      Build games or loyalty apps where users earn, hold, or spend USDC or
      in-game assets. Keep engagement in-app, with no external wallets or seed
      phrases. Users approve (rewards, purchases); you create wallets and run
      transfers using the SDK and APIs.
    </Accordion>

    <Accordion title="Fintech and embedded finance" icon="building-columns">
      Embed USDC into savings, payroll, B2B payments, or remittance. Users keep
      custody; you avoid holding assets. Social, email, or PIN for familiar
      onboarding. Users approve from your UI; you execute using Circle APIs.
    </Accordion>
  </AccordionGroup>
</CardGroup>

## Account types

On EVM chains, a user-controlled wallet is created as either an externally owned
account (EOA) or a smart contract account (SCA). Pick one based on your needs.
For non-EVM chains such as Aptos or Solana, see
[Choose your wallet product and account types](/wallets/account-types) for a
full breakdown by blockchain.

<CardGroup>
  <Card title="EOA (Externally Owned Account)" icon="wallet">
    Select when the source wallet can hold native token for gas, you want simple
    key-controlled accounts, and you don't need multiple operations in one
    transaction (batch execution).
  </Card>

  <Card title="SCA (Smart Contract Account)" icon="cube">
    Select when you need gas paid by a relayer or platform (gas sponsorship),
    batch execution, or other programmable behavior. For details on gas
    sponsorship, see [Gas Station](/wallets/gas-station).
  </Card>
</CardGroup>

## Get started

Choose how users authenticate, then follow a quickstart to create wallets and
see the full flow:

<Card title="Authentication types" icon="fingerprint" href="/wallets/user-controlled/authentication-methods">
  Compare social logins, email OTP, and PIN: onboarding UX and signing UX so you
  can pick the right type for your app.
</Card>

<CardGroup>
  <Card title="Create user wallets with social login" icon="wallet" href="/wallets/user-controlled/create-user-wallets-with-social-login">
    Build a web app that allows users to sign in with Google and get a
    user-controlled wallet with USDC balance.
  </Card>

  <Card title="Create user wallets with email" icon="envelope" href="/wallets/user-controlled/create-user-wallets-with-email">
    Authenticate users with an OTP sent by email and create a user-owned wallet
    linked to your app.
  </Card>

  <Card title="Create user wallets with PIN" icon="key" href="/wallets/user-controlled/create-user-wallets-with-pin">
    Allow users to set a PIN (and optional biometrics) to create and authorize a
    user-controlled wallet from your app.
  </Card>
</CardGroup>


# Android Mobile SDK
Source: https://developers.circle.com/wallets/user-controlled/android-sdk

Set up the client-side Android SDK for user-controlled wallets in your mobile application.

The Circle Android SDK enables user-controlled wallets within your mobile
application. Three authentication methods are supported, namely **social
logins**, **email**, or **PIN**, which includes security questions for recovery.
This allows you to authenticate your users in a seamless way and create
user-controlled wallets for them.

By integrating this client-side SDK, your users can securely create wallets and
make transactions using social accounts or email. If you choose the PIN
authentication method, your users can input sensitive data, like PINs or
security answers, in a secure way. Moreover, the SDK encrypts the request body
sent by the application, protecting your users' information.

<Note>
  **Note:** The Web and Mobile SDKs preserve the user keyshare with the
  individual, giving them complete control. You must use the SDKs with the
  user-controlled wallet product. Additionally, the Web and Mobile SDKs support
  only the user-controlled wallet product.
</Note>

At Circle, we understand the importance of end-to-end security for your
application and the need to create a tailored and seamless user experience for
your end-users. Hence, Circle's SDK also exposes functionality for you to
customize the description and layout. See the
[Android SDK UI Customization API](/wallets/user-controlled/android-sdk-ui-customization-api)
article to customize the SDK.

## Install the SDKs

The Android SDK supports Android API level 21+. Earlier versions are not
supported.

## Maven (recommended)

Add the maven repository to your gradle file. It's suggested that load settings
from `local.properties`:

```gradle Gradle theme={null}
repositories {
    ...
    maven {
            Properties properties = new Properties()
            // Load local.properties.
            properties.load(new File(rootDir.absolutePath + "/local.properties").newDataInputStream())

            url properties.getProperty('pwsdk.maven.url')
            credentials {
                    username properties.getProperty('pwsdk.maven.username')
                    password properties.getProperty('pwsdk.maven.password')
        }
    }
}
```

Add the maven setting values in the `local.properties` file:

```gradle Gradle theme={null}
pwsdk.maven.url=https://maven.pkg.github.com/circlefin/w3s-android-sdk
pwsdk.maven.username=<GITHUB_USERNAME>
# Fine-grained personal access tokens or classic with package write permission.
pwsdk.maven.password=<GITHUB_PAT>
```

Add the dependency:

```gradle Gradle theme={null}
dependencies {
    implementation 'circle.programmablewallet:sdk:version'
}
```

## Manual

You can also manually set up the Android SDK by downloading it from
[GitHub: circlefin/w3s-android-sdk](https://github.com/circlefin/w3s-android-sdk).

## SDK architecture

You must use Web, iOS, or Android SDKs to access the user-controlled
Programmable Wallet product. The SDK secures, manages, and communicates with
your server to ensure your user's keyshare, always stays with them and is not
exposed to your servers.

To learn more, see
[SDK Architecture for User-Controlled Wallets](/wallets/user-controlled/sdk-architecture).

## SDK API references

## WalletSdk

`object WalletSdk`

| Public Methods                       |                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @Throws(Throwable::class) <br />Unit | `init(context: Context?, config: WalletSdk.Configuration?)` <br /> <br />Configure the Circle endpoint for SDK to connect, throw Throwable if the parameters are null or endpoint and appId's format are invalid.                                                                                                                                                                  |
| Unit                                 | `setLayoutProvider(provider: LayoutProvider?)` <br /> <br />Set a LayoutProvider derived class for customization, e.g. error code message, font and color. <br />Ignore when the parameter is null.                                                                                                                                                                                |
| Unit                                 | `setViewSetterProvider(provider: ViewSetterProvider?)` <br /> <br />Set a ViewSetterProvider derived class for image customization.                                                                                                                                                                                                                                                |
| @Throws(Throwable::class) <br />Unit | `setSecurityQuestions(questions: Array<SecurityQuestion?>?)` <br /> <br />Set the security question list, throw Throwable when the SecurityQuestion array is empty or contains any question whose title length is not between 2 and 512.                                                                                                                                           |
| Unit                                 | `execute(activity: Activity?, userToken: String?, encryptionKey: String?, challengeId: Array<String?>?, callback: Callback<ExecuteResult>?)` <br /> <br />Execute the operations by challengeId and call the callback after sending the request to Circle endpoint. <br />Ignore when callback is null. <br />Callback will receive onError() when parameters are null or invalid. |
| Unit                                 | `performLogin(activity: Activity?, provider: SocialProvider, deviceToken: String, deviceEncryptionKey: String, callback: SocialCallback<LoginResult>?)` <br /> <br />Execute Social provider login flow to get userToken, encryptionKey, refreshToken and OAuthInfo object                                                                                                         |
| Unit                                 | `verifyOTP( activity: Activity?, otpToken: String, deviceToken: String,  deviceEncryptionKey: String, callback: Callback2<LoginResult>?)` <br /> <br />Prompt OTP input UI to verify email OTP, then get userToken, encryptionKey, and refreshToken                                                                                                                                |
| Unit                                 | `performLogout(activity: Activity?, provider: SocialProvider, callback: LogoutCallback?)` <br /> <br />Clean login data, includes provider's data and userSecret                                                                                                                                                                                                                   |
| String                               | `getDeviceId(context: Context?)` <br /> <br />Extract device id.                                                                                                                                                                                                                                                                                                                   |
| Unit                                 | `addEventListener(listener: EventListener?)` <br /> <br />Register an EventListener for the app to handle events, e.g. forgot PIN. <br />Ignore when the parameter is null.                                                                                                                                                                                                        |
| Unit                                 | `removeEventListener(listener: EventListener?)` <br /> <br />Unregister an EventListener. <br />Ignore when the parameter is null.                                                                                                                                                                                                                                                 |
| Unit                                 | `moveTaskToFront(context: Context?)` <br /> <br />Bring the SDK UI to foreground. If the app launches another Activity in onEven() and onError() and makes the SDK UI in background, use this API to go back to the SDK UI. <br />Ignore when the parameter is null.                                                                                                               |
| Unit                                 | `setBiometricsPin(activity: Activity?, userToken: String?, encryptionKey: String?, callback: Callback<ExecuteResult>?)` <br /> <br />Setup BiometricsForPin and call the callback after operation. <br />Ignore when callback is null. <br />Callback will receive onError() when parameters are null or invalid.                                                                  |
| Unit                                 | `setCustomUserAgent(userAgent: String?)` <br /> <br />Set custom user agent value. <br />Ignore when the parameter is null.                                                                                                                                                                                                                                                        |
| String                               | `sdkVersion()` <br /> <br />Get SDK version.                                                                                                                                                                                                                                                                                                                                       |

### EventListener

EventListener interface that receives events when an event is triggered.

`interface EventListener`

| Public Methods |                                                                              |
| -------------- | ---------------------------------------------------------------------------- |
| abstract Unit  | `onEvent(event: ExecuteEvent)` <br /> <br />Called when the event triggered. |

### ExecuteEvent

ExecuteEvent, see WalletSdk.addEventListener().

`enum ExecuteEvent`

| Enum values |
| ----------- |
| forgotPin   |
| resendOtp   |

### SocialProvider

To specify a specific Social provider to operate on. See
WalletSdk.performLogin() and WalletSdk.performLogout().

`enum SocialProvider`

| Enum values |
| ----------- |
| Google      |
| Facebook    |
| Apple       |

### LoginResult

LoginResult for Social login.

`data class LoginResult`

| Constructors                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor(userToken: String?, encryptionKey: String?, refreshToken: String?,  oauthInfo: OauthInfo?)` <br /> <br />Data structure to contain results after social login. |

### OauthInfo

OauthInfo for Social login.

`data class OauthInfo`

| Constructors                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor(provider: String?, scope: Array<String>?, socialUserUUID: String?, socialUserInfo: SocialUserInfo?)` <br /> <br />Data structure to contain relative Oauth information of social login. |

### SocialUserInfo

SocialUserInfo for Social login.

`data class SocialUserInfo`

| Constructors                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor(name: String?, email: String?, phone: String?)` <br /> <br />Data structure to contain relative user information of social login. |

### WalletSdk.Configuration

SDK Configuration for WalletSdk init.

`data class Configuration`

| Constructors                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor(endPoint: String?, appId: String?)` <br /> <br />Init with Circle endpoint. SDK will connect to this endpoint.                                                                                                       |
| `constructor(endpoint: String?, appId: String?, settingsManagement: SettingsManagement?)` <br /> <br />Init with Circle endpoint. SDK will connect to this endpoint. The SettingsManagement can bring extra setting flags to use. |

### SettingsManagement

SettingsManagement is used to bring extra setting flags to Configuration that
would be used when initial WalletSdk.

`data class SettingsManagement`

| Constructors                                          |
| :---------------------------------------------------- |
| `constructor(isEnableBiometricsPin: Boolean = false)` |

| Properties |                                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| Boolean    | `isEnableBiometricsPin` <br /> <br />Flag that decides whether to use biometrics to protect PIN or not. |

## LayoutProvider

LayoutProvider helps perform customization during runtime.

`open class LayoutProvider`

| Public Methods                  |                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| open TextConfig?                | `getTextConfig(key: String)` <br /> <br />Define strings with specific configurations for general string customization. Returned TextConfig will replace strings.xml, colors.xml, and styles.xml values. <br /> <br />All keys are listed in [C Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#c-index-table---resourcekey).                                             |
| open Array\<IconTextConfig?>?   | `getIconTextConfigs(key: Resource.IconTextsKey)` <br /> <br />Define icon and string sets with specific configurations for icon text list item customization. <br /> <br />All keys are listed in [B Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#b-index-table---resourceicontextskey).                                                                               |
| open <br />Array\<TextConfig?>? | `getTextConfigs(key: Resource.TextsKey)` <br /> <br />Define strings with specific configurations for special text customization. <br /> <br />All keys are listed in [A Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#a-index-table---resourcetextskey).                                                                                                               |
| open String?                    | `getErrorString(code: ApiError.ErrorCode)` <br /> <br />Define the error description. <br /> <br />All error codes are listed in ApiError.ErrorCode.                                                                                                                                                                                                                                             |
| open String?                    | `getDateFormat()` <br /> <br />Get display date format, e.g. the answer of a security question in which inputType is datePicker. <br /> <br />Only those 3 strings are valid values: <br /> <br />1. “YYYY-MM-DD”,<br />2. “DD/MM/YYYY”<br />3. “MM/DD/YYYY” <br />If it returns an invalid value, the default value would be “YYYY-MM-DD”.All supported formats are listed Resource.DateFormat. |
| open Boolean                    | `isDebugging()` <br /> <br />`true`: default value, check returned value, and print warn level log <br />`false`: skip checking and turn off the log.                                                                                                                                                                                                                                            |

### Resource.DateFormat

`interface DateFormat`

| Constants |                                                                                                                                                                               |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| String    | `YYYYMMDD_HYPHEN = "YYYY-MM-DD"` <br />`DDMMYYYY_SLASH = "DD/MM/YYYY"` <br />`MMDDYYYY_SLASH = "MM/DD/YYYY"` <br /> <br />Available values of LayoutProvider.getDateFormat(). |

### Resource.Key

`interface Key`

| Static Fields |                                                                                                     |
| ------------- | --------------------------------------------------------------------------------------------------- |
| String        | `circlepw_show_pin = "circlepw_show_pin"` <br />`circlepw_hide_pin = "circlepw_hide_pin"` <br />... |

See
[C Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#c-index-table---resourcekey).

### TextConfig

Data class for text customization.

`data class TextConfig`

| Constructors                                                             |
| :----------------------------------------------------------------------- |
| `constructor(text: String?, gradientColors: IntArray?, font: Typeface?)` |
| `constructor(text: String?, textColor: Int, font: Typeface?)`            |
| `constructor(text: String?)`                                             |

| Properties                                                                                                                                             |                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| String?                                                                                                                                                | `text` <br /> <br />Text to display.                                                                                                                                                        |
| [@CorlorInt](https://developer.android.com/reference/androidx/annotation/ColorInt) IntArray?                                                           | `gradientColors` <br /> <br />Array of Gradient text color. Only used by <br />`TextsKey.enterPinCodeHeadline`, <br />`TextsKey.securityIntroHeadline`, <br />`TextsKey.newPinCodeHeadline` |
| [@CorlorInt](https://developer.android.com/reference/androidx/annotation/ColorInt) IntArray?                                                           | `textColor` <br /> <br />Text color.                                                                                                                                                        |
| [Typeface?](https://developer.android.com/reference/android/graphics/Typeface#createFromAsset\(android.content.res.AssetManager,%20java.lang.String\)) | `font` <br /> <br />Font.                                                                                                                                                                   |

### IconTextConfig

Data class for icon text list item customization.

`data class IconTextConfig`

| Constructors                                                      |
| :---------------------------------------------------------------- |
| `constructor(setter: IImageViewSetter?, textConfig: TextConfig?)` |

| Properties        |                                                                     |
| ----------------- | ------------------------------------------------------------------- |
| IImageViewSetter? | `setter` <br /> <br />The ImageView setter for image customization. |
| TextConfig?       | `textConfig` <br /> <br />Text config for text customization.       |

### Resource.TextsKey

`enum TextsKey`

| Enum Values                    |
| ------------------------------ |
| securityQuestionHeaders        |
| securitySummaryQuestionHeaders |
| enterPinCodeHeadline           |
| securityIntroHeadline          |
| newPinCodeHeadline             |
| securityIntroLink              |
| recoverPinCodeHeadline         |

See
[A Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#a-index-table---resourcetextskey).

### Resource.IconTextsKey

`enum IconTextsKey`

| Enum Constants            |
| ------------------------- |
| securityConfirmationItems |

See
[B Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#b-index-table---resourceicontextskey).

## IImageViewSetter

The ImageView setter interface for image customization.

`interface IImageViewSetter`

| Public Methods |                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| abstract Unit  | apply(iv: [ImageView?](https://developer.android.com/reference/android/widget/ImageView) ) <br /> <br />Called when the ImageView needs to be set. |

### LocalImageSetter

The implemented ImageView setter for image customization with local image.

`class LocalImageSetter: IImageViewSetter`

| Constructors                   |
| :----------------------------- |
| `constructor(drawableId: Int)` |

| Properties                                                                                  |                                                        |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| @[DrawableRes](https://developer.android.com/reference/androidx/annotation/DrawableRes) Int | `drawableId` <br /> <br />The resource ID of drawable. |

| Public Methods |                                                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unit           | apply(iv: [ImageView](https://developer.android.com/reference/android/widget/ImageView)) <br /> <br />Set drawable to the imageView with drawableId. |

### RemoteImageSetter

The implemented ImageView setter for image customization with a remote image.

`class RemoteImageSetter: IImageViewSetter`

| Constructors                                 |
| :------------------------------------------- |
| `constructor(drawableId: Int)`               |
| `constructor(drawableId: Int, url: String?)` |

| Properties                                                                                  |                                                        |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| @[DrawableRes](https://developer.android.com/reference/androidx/annotation/DrawableRes) Int | `drawableId` <br /> <br />The resource ID of drawable. |
| String                                                                                      | `url` <br /> <br />Image URL.                          |

| Public Methods |                                                                                                                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unit           | apply(iv: [ImageView](https://developer.android.com/reference/android/widget/ImageView)) <br /> <br />Set a remote image from the URL to the ImageView. Use the drawable as the placeholder. |

## IToolbarSetter

The Toolbar setter interface for image customization.

`interface IToolbarSetter`

| Public Methods |                                                                                                                                                             |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| abstract Unit  | apply(toolbar: [Toolbar?](https://developer.android.com/reference/androidx/appcompat/widget/Toolbar)) <br /> <br />Called when the Toolbar needs to be set. |

### LocalToolbarImageSetter

`class LocalToolbarImageSetter: IToolbarSetter`

| Constructors                   |
| :----------------------------- |
| `constructor(drawableId: Int)` |

| Properties                                                                                  |                                                        |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| @[DrawableRes](https://developer.android.com/reference/androidx/annotation/DrawableRes) Int | `drawableId` <br /> <br />The resource ID of drawable. |

| Public Methods |                                                                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Unit           | apply(toolbar: [Toolbar?](https://developer.android.com/reference/androidx/appcompat/widget/Toolbar)) <br /> <br />Set drawable as navigation icon to the Toolbar. |

### RemoteToolbarImageSetter

The implemented Toolbar setter for image customization with a remote image.

`class RemoteToolbarImageSetter: IToolbarSetter`

| Constructors                                 |
| :------------------------------------------- |
| `constructor(drawableId: Int)`               |
| `constructor(drawableId: Int, url: String?)` |

| Properties                                                                                  |                                                        |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| @[DrawableRes](https://developer.android.com/reference/androidx/annotation/DrawableRes) Int | `drawableId` <br /> <br />The resource ID of drawable. |
| String?                                                                                     | `url` <br /> <br />Image URL.                          |

| Public Methods |                                                                                                                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unit           | apply(toolbar: [Toolbar?](https://developer.android.com/reference/androidx/appcompat/widget/Toolbar)) <br />Set a remote image from the URL to the toolbar. Use drawable as the placeholder. |

## ViewSetterProvider

ViewSetterProvider supports performing image customization during runtime.

`open class ViewSetterProvider` extends Object

| Public Methods         |                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| open IImageViewSetter? | `getImageSetter(type: Resource.Icon)` <br /> <br />Return implemented IImageViewSetter for performing general image customization. <br />e.g. LocalImageSetter, RemoteImageSetter <br /> <br />All keys are listed in [D Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#d-index-table).                                               |
| open IToolbarSetter?   | `getToolbarImageSetter(  <br />    type: Resource.ToolbarIcon  <br />)` <br /> <br />Return implemented IToolbarSetter for performing Toolbar image customization. <br />e.g. LocalToolbarImageSetter, RemoteToolbarImageSetter <br /> <br />All keys are listed in [E Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#e-index-table). |

### Resource.Icon

`enum Icon`

| Enum Values          |
| -------------------- |
| securityIntroMain    |
| selectCheckMark      |
| dropdownArrow        |
| errorInfo            |
| securityConfirmMain  |
| biometricsAllowMain  |
| showPin              |
| hidePin              |
| alertWindowIcon      |
| swipeItemIcon        |
| swipeBtConfirmed     |
| transactionTokenIcon |
| networkFeeTipIcon    |
| requestIcon          |
| showLessDetailArrow  |
| showMoreDetailArrow  |

[D Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#d-index-table).

### Resource.ToolbarIcon

`enum ToolbarIcon`

| Enum Values |
| ----------- |
| close       |
| back        |

[E Index Table](/wallets/user-controlled/android-sdk-ui-customization-api#e-index-table)

### SecurityQuestion

Data class for security questions customization.

See WalletSdk.setSecurityQuestions().

`data class SecurityQuestion`

| Constructors                                                      |
| :---------------------------------------------------------------- |
| constructor(title: String)                                        |
| constructor(title: String, inputType: SecurityQuestion.InputType) |

| Properties                 |                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| String                     | `title` <br /> <br />The question string.                                                   |
| SecurityQuestion.InputType | `inputType` <br /> <br />The input type of the question. Support text input and timePicker. |

### SecurityQuestion.InputType

`public enum InputType`

| Enum Values |
| ----------- |
| text        |
| datePicker  |

### Callback

A generic callback interface for SDK API calls

`interface Callback<R>`

| Public Methods      |                                                                                                                                                                                                                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| abstract Boolean    | `onError(error: Throwable)` <br /> <br />The callback is triggered when a failure occurs in operation or is canceled by the user. <br />Return true - The app will handle the following step, SDK will keep the Activity. <br />Return false - The app won't handle the following step, SDK will finish the Activity.                                    |
| abstract <br />Unit | `onResult(result: R)` <br /> <br />R - Type of result such as ExecuteResult <br />Callback when the operation is executed successfully. Finish the Activity after this callback is triggered.                                                                                                                                                            |
| abstract Boolean    | `onWarning(warning: ExecuteWarning, result: R?)` <br /> <br />The callback is triggered when operation executed with warning. <br />R - Type of result such as ExecuteResult <br />Return true - App will handle the following step, SDK will keep the Activity. <br />Return false - App won't handle the following step, SDK will finish the Activity. |

### Callback2

The callback interface for verifyOTP()

`interface Callback2<R>`

| Public Methods      |                                                                                                                                                                                                                                                                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| abstract Boolean    | `onError(error: Throwable)` <br /> <br />The callback is triggered when a failure occurs in operation or is canceled by the user. <br />Return true - The app will handle the following step, SDK will keep the Activity. <br />Return false - The app won't handle the following step, SDK will finish the Activity. |
| abstract <br />Unit | `onResult(result: R)` <br /> <br />R - Type of result such as ExecuteResult <br />Callback when the operation is executed successfully. Finish the Activity after this callback is triggered.                                                                                                                         |

### SocialCallback

The callback interface for performLogin()

`interface SocialCallback<R>`

| Public Methods      |                                                                                                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| abstract <br />Unit | `onError(error: Throwable)` <br /> <br />The callback is triggered when a failure occurs in operation or is canceled by the user.                                                             |
| abstract <br />Unit | `onResult(result: R)` <br /> <br />R - Type of result such as ExecuteResult <br />Callback when the operation is executed successfully. Finish the Activity after this callback is triggered. |

### LogoutCallback

The callback interface for performLogout()

`interface LogoutCallback`

| Public Methods      |                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| abstract <br />Unit | `onError(error: Throwable)` <br /> <br />The callback is triggered when a failure occurs in operation or is canceled by the user. |
| abstract <br />Unit | `onComplete()` <br /> <br />Callback when social logout operation completed.                                                      |

### ExecuteWarning

`enum ExcuteWarning`

| Properties |                                                               |
| ---------- | ------------------------------------------------------------- |
| Int        | `warningType` <br /> <br />Warning type.                      |
| String     | `warningString` <br /> <br />Description of the warning type. |

| Enum Values                                                                                                |
| ---------------------------------------------------------------------------------------------------------- |
| biometricsUserSkip(155711, "User skipped the setting of using biometrics to protect PIN this time.")       |
| biometricsUserDisableForPin(155712, "User disabled the function of using biometrics to protect PIN.")      |
| biometricsUserLockout(155713, "Too many attempts. Try again later.")                                       |
| biometricsUserLockoutPermanent(155714, "Too many attempts. Biometrics sensor disabled.")                   |
| biometricsUserNotAllowPermission(155715, "User didn't grant the permission to use biometrics"), //IOS ONLY |
| biometricsInternalError(155716, "Biometrics internal error - %s");                                         |

### ExecuteResult

`data class ExecuteResult`

| Constructors                                                                                                                           |
| :------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor(     resultType: ExecuteResultType,     status: ExecuteResultStatus,     data: ExecuteResultData = ExecuteResultData() )` |

| Properties          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ExecuteResultType   | `resultType` <br /> <br />The type of the operation that the challenge represents. The possible values are : <br /> <br />UNKNOWN(-1), <br />SET\_PIN(0), <br />RESTORE\_PIN(1), <br />CHANGE\_PIN(2), <br />SET\_SECURITY\_QUESTIONS(3), <br />CREATE\_WALLET(4), <br />CREATE\_TRANSACTION(5), <br />ACCELERATE\_TRANSACTION(6), <br />CANCEL\_TRANSACTION(7), <br />CONTRACT\_EXECUTION(8), <br />SIGN\_MESSAGE(9), <br />SIGN\_TYPEDDATA(10), <br />SIGN\_TRANSACTION(11), <br />SET\_BIOMETRICS\_PIN(1000) |
| ExecuteResultStatus | `status` <br /> <br />The status of the execution. The possible values are : <br /> <br />UNKNOWN(-1) <br />PENDING(0) <br />IN\_PROGRESS(1) <br />COMPLETE(2) <br />FAILED(3) <br />EXPIRED(4)                                                                                                                                                                                                                                                                                                                 |
| ExecuteResultData   | `data` <br /> <br />The data of the execution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

### ExecuteResultType

`enum ExecuteResultType`

| Properties |                                                 |
| ---------- | ----------------------------------------------- |
| Int        | `value` <br /> <br />The int value of the enum. |

| Enum Values                 |
| --------------------------- |
| UNKNOWN(-1)                 |
| SET\_PIN(0)                 |
| RESTORE\_PIN(1)             |
| CHANGE\_PIN(2)              |
| SET\_SECURITY\_QUESTIONS(3) |
| CREATE\_WALLET(4)           |
| CREATE\_TRANSACTION(5)      |
| ACCELERATE\_TRANSACTION(6)  |
| CANCEL\_TRANSACTION(7)      |
| CONTRACT\_EXECUTION(8)      |
| SIGN\_MESSAGE(9)            |
| SIGN\_TYPEDDATA(10)         |
| SIGN\_TRANSACTION(11)       |
| INITIALIZE(12)              |
| WALLET\_UPGRADE(13)         |
| SET\_BIOMETRICS\_PIN(1000)  |

### ExecuteResultStatus

`enum ExecuteResultStatus`

| Properties |                                                 |
| ---------- | ----------------------------------------------- |
| Int        | `value` <br /> <br />The int value of the enum. |

| Enum Values     |
| --------------- |
| UNKNOWN (-1)    |
| PENDING(0)      |
| IN\_PROGRESS(1) |
| COMPLETED(2)    |
| FAILED(3)       |
| EXPIRED(4)      |

### ExecuteResultData

`data class ExecuteResultData`

| Constructors                             |
| :--------------------------------------- |
| `constructor(signature: String? = null)` |

| Properties |                                                                                                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| String?    | `signature` <br /> <br />The signature for SIGN\_MESSAGE, SIGN\_TYPEDDATA and SIGN\_TRANSACTION. <br />For SIGN\_TRANSACTION, the signature encodes the v, r, s parameters in big-endian format. |
| String?    | `signedTransaction` <br /> <br />Signed transaction string for SIGN\_TRANSACTION. Will be a hex string with ‘0x' prefix for EVM chains.                                                          |
| String?    | `txHash` <br /> <br />The hash of the transaction for SIGN\_TRANSACTION.                                                                                                                         |

## APIError

Error class for PW SDK

`abstract class ApiError:[Throwable](https://developer.android.com/reference/java/lang/Throwable)`

| Properties                  |                                                  |
| --------------------------- | ------------------------------------------------ |
| abstract ApiError.ErrorCode | `code` <br />Error code.                         |
| open String                 | `message` <br />Get human-readable error message |

### ApiError.ErrorCode

`public enum ErrorCode`

| Properties |                                          |
| ---------- | ---------------------------------------- |
| Int        | `value` <br />The int value of the enum. |

| Enum Value                                  | Description                                                                                                             |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| undefined(-1)                               | Used when an error is defined on the server but not in the SDK. Overrides `unknown(-1)` if a server-defined code exists |
| unknown(-1)                                 | An unspecified error occurred                                                                                           |
| success(0)                                  | The operation completed successfully                                                                                    |
| apiParameterMissing(1)                      | A required API parameter is missing                                                                                     |
| apiParameterInvalid(2)                      | An API parameter provided is invalid                                                                                    |
| forbidden(3)                                | The request is forbidden due to insufficient permissions                                                                |
| unauthorized(4)                             | Authentication failed or user is not authorized                                                                         |
| retry(9)                                    | Temporary issue; retry the operation                                                                                    |
| customerSuspended(10)                       | The customer's account is suspended                                                                                     |
| pending(11)                                 | The operation is pending and not yet completed                                                                          |
| invalidSession(12)                          | The session is invalid or has expired                                                                                   |
| invalidPartnerId(13)                        | The provided partner ID is invalid                                                                                      |
| invalidMessage(14)                          | Message format is invalid                                                                                               |
| invalidPhone(15)                            | The phone number provided is invalid                                                                                    |
| userAlreadyExisted(155101)                  | The user already exists in the system                                                                                   |
| userNotFound(155102)                        | The specified user was not found                                                                                        |
| userTokenNotFound(155103)                   | The user token was not found                                                                                            |
| userTokenExpired(155104)                    | The user token has expired                                                                                              |
| invalidUserToken(155105)                    | The user token provided is invalid                                                                                      |
| userWasInitialized(155106)                  | The user has already been initialized                                                                                   |
| userHasSetPin(155107)                       | The user has already set a PIN                                                                                          |
| userHasSetSecurityQuestion(155108)          | The user has already set security questions                                                                             |
| userWasDisabled(155109)                     | The user account has been disabled                                                                                      |
| userDoesNotSetPinYet(155110)                | The user has not set a PIN yet                                                                                          |
| userDoesNotSetSecurityQuestionYet(155111)   | The user has not set security questions yet                                                                             |
| incorrectUserPin(155112)                    | The PIN entered is incorrect                                                                                            |
| incorrectDeviceId(155113)                   | The device ID provided is incorrect                                                                                     |
| incorrectAppId(155114)                      | The application ID provided is incorrect                                                                                |
| incorrectSecurityAnswers(155115)            | The security answers provided are incorrect                                                                             |
| invalidChallengeId(155116)                  | The challenge ID provided is invalid                                                                                    |
| invalidApproveContent(155117)               | The approval content is invalid                                                                                         |
| invalidEncryptionKey(155118)                | The encryption key provided is invalid                                                                                  |
| userPinLocked(155119)                       | The user's PIN is locked due to multiple failed attempts                                                                |
| securityAnswersLocked(155120)               | The user's security answers are locked due to multiple failed attempts                                                  |
| walletIsFrozen(155501)                      | The wallet is frozen and cannot perform operations                                                                      |
| maxWalletLimitReached(155502)               | The user has reached the maximum number of wallets allowed                                                              |
| walletSetIdMutuallyExclusive(155503)        | The wallet set ID is mutually exclusive and cannot be used with the current operation                                   |
| metadataUnmatched(155504)                   | The metadata provided does not match the expected format or values                                                      |
| userCanceled(155701)                        | The user canceled the operation                                                                                         |
| launchUiFailed(155702)                      | Failed to launch the user interface                                                                                     |
| pinCodeNotMatched(155703)                   | The PIN code entered does not match the expected value                                                                  |
| insecurePinCode(155704)                     | The PIN code entered is considered insecure                                                                             |
| hintsMatchAnswers(155705)                   | The hints provided match the security answers, which is not allowed                                                     |
| networkError(155706)                        | A network error occurred during the operation                                                                           |
| biometricsSettingNotEnabled(155708)         | Biometrics settings are not enabled on the device                                                                       |
| deviceNotSupportBiometrics(155709)          | The device does not support biometric authentication                                                                    |
| biometricsKeyPermanentlyInvalidated(155710) | The biometric key has been permanently invalidated                                                                      |
| biometricsUserSkip(155711)                  | The user skipped biometric authentication                                                                               |
| biometricsUserDisableForPin(155712)         | The user disabled biometrics for PIN authentication                                                                     |
| biometricsUserLockout(155713)               | The user is temporarily locked out of biometric authentication                                                          |
| biometricsUserLockoutPermanent(155714)      | The user is permanently locked out of biometric authentication                                                          |
| biometricsUserNotAllowPermission(155715)    | The user did not grant permission for biometric authentication                                                          |
| biometricsInternalError(155716)             | An internal error occurred during biometric authentication                                                              |
| invalidUserTokenFormat(155718)              | The user token format is invalid                                                                                        |
| userTokenMismatch(155719)                   | The user token does not match the expected value                                                                        |
| socialLoginFailed(155720)                   | Social login failed                                                                                                     |
| loginInfoMissing(155721)                    | Login information is missing                                                                                            |
| walletIdNotFound(156001)                    | The specified wallet ID was not found                                                                                   |
| tokenIdNotFound(156002)                     | The specified token ID was not found                                                                                    |
| transactionIdNotFound(156003)               | The specified transaction ID was not found                                                                              |
| entityCredentialNotFound(156004)            | The specified entity credential was not found                                                                           |
| walletSetIdNotFound(156005)                 | The specified wallet set ID was not found                                                                               |

## Static Customized String

### res/values/strings.xml

```xml XML theme={null}
<resources>
    <string name="circlepw_continue">Continue</string>
    <string name="circlepw_next">Next</string>
    <string name="circlepw_question_label">Question:</string>
</resources>
```

## Static Customized UI Layout

### res/values/color.xml

```xml XML theme={null}
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="circlepw_text_main">#1A1A1A</color>
    <color name="circlepw_text_auxiliary">#3D3D3D</color>
    <color name="circlepw_text_action">#136FD8</color>
    <color name="circlepw_text_action_pressed">#B3136FD8</color>
</resources>
```

### res/values/styles.xml

```xml XML theme={null}
<resources>
    <style name="circlepw_heading3">
        <item name="android:fontFamily">@font/avenir_heavy</item>
        <item name="android:fontWeight" tools:targetApi="o">600</item>
        <item name="android:textSize">24sp</item>
    </style>
    <style name="circlepw_heading4">
        <item name="android:fontFamily">@font/avenir_heavy</item>
        <item name="android:fontWeight" tools:targetApi="o">600</item>
        <item name="android:textSize">20sp</item>
    </style>
</resources>
```

### res/values/dimens.xml

```xml XML theme={null}
<resources>
    <dimen name="circlepw_bottom_bt_margin_top">10dp</dimen>
    <dimen name="circlepw_intro_title_margin_bottom">24dp</dimen>
    <dimen name="circlepw_intro_custom_grab_icon_size">48dp</dimen>
</resources>
```

## Sample Code

```java Java theme={null}
// Set endpoint and app ID
try {
    WalletSdk.init(getApplicationContext(), new WalletSdk.Configuration(endpoint, appId));
} catch (Throwable e){
    e.printStackTrace();
    return;
}

// setViewSetterProvider
WalletSdk.setViewSetterProvider(new MyViewSetterProvider());
// setLayoutProvider
WalletSdk.setLayoutProvider(new MyLayoutProvider(getApplicationContext()));
// Regester EventListener
WalletSdk.addEventListener(new EventListener() {
    @Override
       public void onEvent(ExecuteEvent event) {
           switch (event){
                  case forgotPin:
                    startActivity(forgotPinIntent);
                  break;
           }
       }
});

// setSecurityQuestion
SecurityQuestion[] questions = new SecurityQuestion[]{
                    new SecurityQuestion("What is your father's middle name?"),
                    new SecurityQuestion("What is your favorite sports team?"),
                    new SecurityQuestion("What is your mother's maiden name?"),
                    new SecurityQuestion("What is the name of your first pet?"),
                    new SecurityQuestion("What is the name of the city you were born in?"),
                    new SecurityQuestion("What is the name of the first street you lived on?"),
                    new SecurityQuestion("When is your father's birthday?", SecurityQuestion.InputType.datePicker)};
WalletSdk.setSecurityQuestions(questions);
```

```java Java theme={null}
// There are two ways to use Configuration. Below is the way with SettingsManagement.
// We can use SettingsManagement to bring the setting flag. SettingsManagement provide the setting flag
// EnableBiometricsPin to enable/disable the function "Use biometrics to protect PIN" currently.
// But if we do not use the settingsManagement, the default value of EnableBiometricsPin is false.
try {
    SettingsManagement settingsManagement = new SettingsManagement();
    settingsManagement.setEnableBiometricsPin(true); //Set "true" to enable, "false" to disable
    WalletSdk.init(getApplicationContext(), new WalletSdk.Configuration(endpoint, appId, settingsManagement));
} catch (Throwable e){
    e.printStackTrace();
    return;
}

```

```java Java theme={null}
// Execute
WalletSdk.execute(getActivity(), userToken, encryptionKey,
          new String[]{challengeId},
          new Callback<ExecuteResult>() {
                @Override
                public boolean onError(Throwable error) {
                      if(error instanceof ApiError){
                              ApiError apiError = (ApiError) error;
                              if(apiError.getCode() == ApiError.ErrorCode.userCanceled){
                // App won't handle next step, SDK finishes the Activity.
                                  return false;
                               }
                                startActivity(errorUiIntent);
                // App will handle next step, SDK keeps the Activity.
                               return true;
                       }

                }


                @Override
                public void onResult(ExecuteResult result) {
                       // success
                }


                @Override
                public boolean onWarning(ExecuteWarning warning, ExecuteResult executeResult) {
                // App won't handle next step, SDK finishes the Activity.
                        return false;
                }
});

```

```java Java theme={null}
// Extend LayoutProvider and override
class MyLayoutProvider extends LayoutProvider {
        Context context;
        Typeface typeface;
        int color;
        public MyLayoutProvider(Context context) {
            this.context = context;
        }

        @Override
        public TextConfig getTextConfig(String key) {
            switch (key){
                case Resource.Key.circlepw_security_intros_description:
                    typeface = ResourcesCompat.getFont(context, R.font.en);
                    color = Color.parseColor("#105AAB");
                    return new TextConfig("customized description", color, typeface);
            }
            return super.getTextConfig(key);
        }


@Override
public IconTextConfig[] getIconTextConfigs(Resource.IconTextsKey key) {
            switch (key){
                case securityConfirmationItems: // SQ confirmation introduction items
                    return new IconTextConfig[]{
                            new IconTextConfig(
                                    new LocalImageSetter(R.drawable.intro_item0_icon),
                                    new TextConfig("This is the only way to recover my account access. ")),
                            new IconTextConfig(
                                    new RemoteImageSetter(R.drawable.error, "https://path/icon2.svg"),
                                    new TextConfig("Circle won't store my answers so it's my responsibility to remember them.")),
                            new IconTextConfig(
                                    new RemoteImageSetter(R.drawable.error, "https://path/icon3.svg"),
                                    new TextConfig("I will lose access to my wallet and my digital assets if I forget my answers. "))
                    };
}
   return super.getIconTextConfigs(key);
       }
@Override
        public TextConfig[] getTextConfigs(Resource.TextsKey key) {
            switch (key){
                case securityQuestionHeaders:
                    return new TextConfig[]{
                            new TextConfig("Choose your 1st question"),
                            new TextConfig("Choose your 2nd question")
                    };
                case securitySummaryQuestionHeaders:
                    return new TextConfig[]{
                            new TextConfig("1st Question"),
                            new TextConfig("2nd Question")
                    };
                case newPinCodeHeadline:
                case enterPinCodeHeadline:
                    return new TextConfig[]{
                            new TextConfig("Enter your "),
                            new TextConfig("PIN", getHeadingColor(), null),
                    };
                case securityIntroHeadline:
                    return new TextConfig[]{
                            new TextConfig("Set up your "),
                            new TextConfig("Recovery Method", getHeadingColor(), null),
                    };
            }
            return super.getTextConfigs(key);
        }

        private int getHeadingColor(){
              return Color.parseColor("#0073C3");
        }

        @Override
        public String getErrorString(ApiError.ErrorCode code) {
            switch (code){
                case userCanceled:
                    return context.getString(R.string.user_canceled);
            }
            return super.getErrorString(code);
        }

        @Override
        public String getDateFormat(){
            return Resource.DateFormat.MMDDYYYY_SLASH; // "​​MM/DD/YYYY"
        }

        @Override
        public boolean isDebugging(){
            return BuildConfig.DEBUG;
        }

    }

```

```java Java theme={null}
// Extend ViewSetterProvider and override
    class MyViewSetterProvider extends ViewSetterProvider{

        @Override
        public IToolbarSetter getToolbarImageSetter(Resource.ToolbarIcon type) {
            switch (type){
                case back:
                    return new LocalToolbarImageSetter(R.drawable.ic_back);
                case close:
                    return new RemoteToolbarImageSetter(R.drawable.error, "https://path/close.svg");
            }
            return super.getToolbarImageSetter(type);
        }
    @Override
        public IImageViewSetter getImageSetter(Resource.Icon type) {
            switch (type){
                case securityIntroMain:
                    return new LocalImageSetter(R.drawable.main);
                case selectCheckMark:
                    return new RemoteImageSetter(R.drawable.error, "https://path/check.svg");
                case dropdownArrow:
                    return new RemoteImageSetter(R.drawable.error, "https://path/arrow.svg");
                case errorInfo:
                    return new RemoteImageSetter(R.drawable.error, "https://path/errorinfo.svg");
                case securityConfirmMain:
                    return new RemoteImageSetter(R.drawable.error, "https://path/main2.svg");
            }
            return super.getImageSetter(type);
        }
    }

```

```java Java theme={null}
// setBiometricsPin
WalletSdk.setBiometricsPin(this, userToken, encryptionKey, new Callback<ExecuteResult>() {
            @Override
            public boolean onError(Throwable error) {
                error.printStackTrace();
                if (error instanceof ApiError) {
                    ApiError apiError = (ApiError) error;
                    switch (apiError.getCode()) {
                        case incorrectUserPin:
                        case userPinLocked:
                        case securityAnswersLocked:
                        case incorrectSecurityAnswers:
                        case pinCodeNotMatched:
                        case insecurePinCode:
                            return true; // App will handle next step, SDK will keep the Activity.
                    }
                }
                return false; // App won't handle next step, SDK will finish the Activity.
            }

            @Override
            public void onResult(ExecuteResult executeResult) {
                //success
            }

            @Override
            public boolean onWarning(ExecuteWarning warning, ExecuteResult executeResult) {
                return false; // App won't handle next step, SDK will finish the Activity.
            }
        });



```


# Android SDK UI Customization API
Source: https://developers.circle.com/wallets/user-controlled/android-sdk-ui-customization-api

Android SDK UI and key mapping reference for customizations.

This document describes the different customizable sections of the Programmable
Wallet SDK customization API. To get the most flexibility out of the SDK, use
this reference with the [SDK API](/wallets/user-controlled/android-sdk).

## Text, Color, and Font Customization

For text-related customization, there are two types of customization, dynamic
and static:

* For dynamic customization, update the source code's desired string, color, and
  font (as typeface).
* For Static customization, add or update the strings.xml file located at
  `src/main/res/values/strings.xml`. To avoid the static customization being
  overwritten by the dynamic customization, use the null value for the text
  argument when initializing with the`TextConfig()` constructor, for example:

<CodeGroup>
  ```java Java theme={null}
  new TextConfig(null, color, typeface);
  ```

  ```kotlin Kotlin theme={null}
  TextConfig(null, color, typeface)
  ```
</CodeGroup>

Please reference the UI screenshots below with each string's mapping code, then
use the mapping code to find the `Resource.TextsKey` name in the Index Table for
more detail of customization support and usage for each text string.

<Note>
  **Note:**

  Some strings do not support static or dynamic customization for text, color,
  font and gradientColors using the `TextConfig()` constructor.

  The detail of supporting scope can be found in the index table and the note
  column. If the app still customizes those unsupported values, it will give a
  WARN level log printed to logcat, filtered with CustomizeChecker for log
  abstraction.
</Note>

<Frame>
  <img />
</Frame>

The correct usage for unsupported value when initializing with the
`TextConfig()` constructor is as follows:

<CodeGroup>
  ```java Java theme={null}
  new TextConfig("Your Text Here", null /*gradientColors*/, null); //color is 0 by default.
  new TextConfig("", 0 /*color*/, null);
  new TextConfig("Your Text Here");
  ```

  ```kotlin Kotlin theme={null}
  TextConfig("Your Text Here", null /*gradientColors*/, null) //color is 0 by default.
  TextConfig("", 0 /*color*/, null)
  TextConfig("Your Text Here")
  ```
</CodeGroup>

## New PIN Code

### A1 / C1\~C5

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Confirm PIN Code

### C6\~C7

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Enter PIN Code

### A2 / C8\~C9, C5-1, C5-2

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Security Intros

### A3~~A4 / C10~~C11

<Frame>
  <img />
</Frame>

## Security Questions Customization

Please reference the Security Question section in the
[SDK](/wallets/user-controlled/android-sdk#securityquestion) for how to
customize the question by using `setSecurityQuestions` method.

### A5 / C12\~C25

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Security Summary

### A6 / C26\~C32

<Frame>
  <img />
</Frame>

## Security Confirm

### C33\~C37 / B1

<Frame>
  <img />
</Frame>

## Recover PIN Code

### A7 / C39\~C60

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Alert Pop Window

### C61\~C62

<Frame>
  <img />
</Frame>

## Confirm Transaction

### C63\~C90

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Signature Request

### C91\~C98

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Verify OTP

### C99\~C105

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<br />

## A Index Table - Resource.TextsKey

| #  | Resource.TextsKey              | TextConfigs length                   | TextConfig.text | TextConfig.textColor | TextConfig.font | TextConfig.gradientColors | `colors.xml`              | `styles.xml`       | Note🔖                                                                                                                                                        |
| -- | ------------------------------ | ------------------------------------ | --------------- | -------------------- | --------------- | ------------------------- | ------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A1 | newPinCodeHeadline             | Free                                 | ✅               | ✅🔖                  | ✅               | ✅🔖                       | circlepw\_text\_main      | circlepw\_heading3 | textColor will be applied if gradientColors is null.                                                                                                          |
| A2 | enterPinCodeHeadline           | Free                                 | ✅               | ✅🔖                  | ✅               | ✅🔖                       | circlepw\_text\_main      | circlepw\_heading3 | textColor will be applied if gradientColors is null.                                                                                                          |
| A3 | securityIntroHeadline          | Free                                 | ✅               | ✅🔖                  | ✅               | ✅🔖                       | circlepw\_text\_main      | circlepw\_heading4 | textColor will be applied if gradientColors is null.                                                                                                          |
| A4 | securityIntroLink              | 2🔖                                  | ✅               | ✅🔖                  | ✅🔖             | ❌                         | circlepw\_text\_action    | circlepw\_body2    | TextConfigs: \[DisplayText, URL]Only display when the array length is not less then 2 and the URL is not empty.Set color / font according to TextConfig\[0].  |
| A5 | securityQuestionHeaders        | \<= 5🔖                              | ✅               | ✅🔖                  | ✅🔖             | ❌                         | circlepw\_text\_auxiliary | circlepw\_body2    | TextConfigs over the length limit will be ignored.                                                                                                            |
| A6 | securitySummaryQuestionHeaders | Same as securityQuestionHeaders (A5) | ✅               | ✅                    | ✅               | ❌                         | circlepw\_text\_main2     | circlepw\_heading5 | TextConfigs over the length limit will be ignored.                                                                                                            |
| A7 | recoverPinCodeHeadline         | Free                                 | ✅               | ✅🔖                  | ✅               | ✅🔖                       | circlepw\_text\_main      | circlepw\_heading3 | textColor will be applied if gradientColors is null.                                                                                                          |

<br />

## B Index Table - Resource.IconTextsKey

Use this Index Table to reference the Dynamic special Icon, Text, Color, and
Font Customization. Both the **icon image** and the **text** fields are
dynamically configured together.

Use `RemoteImageSetter` or `LocalImageSetter` for icon images:

* **RemoteImageSetter** constructor:
  * `RemoteImageSetter(int drawableId, String url)`
* **LocalImageSetter** constructor:
  * `LocalImageSetter(int drawableId)`

The SDK uses [glide](https://github.com/bumptech/glide) as the image loader for
remote images. For the cache strategy, please see
[DiskCacheStrategy.AUTOMATIC](https://bumptech.github.io/glide/javadocs/420/com/bumptech/glide/load/engine/DiskCacheStrategy.html#AUTOMATIC).

| #  | Resource.IconTextsKey     | TextConfigs length | TextConfig.text | TextConfig.textColor | TextConfig.font | TextConfig.gradientColors | `colors.xml`         | `styles.xml`    | Note🔖                                             |
| -- | ------------------------- | ------------------ | --------------- | -------------------- | --------------- | ------------------------- | -------------------- | --------------- | -------------------------------------------------- |
| B1 | securityConfirmationItems | \<= 4🔖            | ✅               | ✅                    | ✅               | ❌                         | circlepw\_text\_main | circlepw\_body2 | TextConfigs over the length limit will be ignored. |

<br />

## C Index Table - Resource.Key

<Note>
  **Note:**

  The `gradientColors` field is not supported for the Keys in this table. If you
  dynamically set the color as `gradientColor`, the effect will be ignored and the
  `WARN` level log will be printed.
</Note>

| #     | Resource.Key                                               | `string.xml`                                              | text | textColor | font | `colors.xml`                            | `styles.xml`                 | Note                                                                                                                    |
| ----- | ---------------------------------------------------------- | --------------------------------------------------------- | ---- | --------- | ---- | --------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| C1    | circlepw\_new\_pincode\_subhead                            | circlepw\_new\_pincode\_subhead                           | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C2    | circlepw\_pin\_digit\_config                               | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_pinDigitText       | Normal                                                                                                                  |
|       |                                                            |                                                           |      |           |      | circlepw\_main\_bt\_background          |                              | Succeed                                                                                                                 |
|       |                                                            |                                                           |      |           |      | circlepw\_error                         |                              | Failed                                                                                                                  |
| C5    | circlepw\_pincode\_error\_config                           | ❌🔖                                                       | ❌🔖  | ✅         | ✅    | circlepw\_error                         | circlepw\_body2              | For text, see Error Message:incorrectUserPin(155112)userPinLocked(155119)pinCodeNotMatched(155703)                      |
| C5-1  | circlepw\_pin\_remain\_attemps\_template                   | circlepw\_pin\_remain\_attemps\_template                  | ✅🔖  | ❌         | ❌    | ❌                                       | ❌                            | e.g. You have %s attempts left.                                                                                         |
| C5-2  | circlepw\_pin\_lock\_period\_template                      | circlepw\_pin\_lock\_period\_template                     | ✅🔖  | ❌         | ❌    | ❌                                       | ❌                            | e.g. You've used up all PIN attempts. Please wait for %s mins to retry later..                                          |
| C6    | circlepw\_confirm\_pincode\_headline                       | circlepw\_confirm\_pincode\_headline                      | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_heading3           |                                                                                                                         |
| C7    | circlepw\_confirm\_pincode\_subhead                        | circlepw\_confirm\_pincode\_subhead                       | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C8    | circlepw\_enter\_pincode\_subhead                          | circlepw\_enter\_pincode\_subhead                         | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C9    | circlepw\_enter\_pincode\_forgot\_pin                      | circlepw\_enter\_pincode\_forgot\_pin                     | ✅    | ✅         | ✅    | circlepw\_text\_action                  | circlepw\_actionText         |                                                                                                                         |
| C10   | circlepw\_security\_intros\_description                    | circlepw\_security\_intros\_description                   | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary2              | circlepw\_body2              |                                                                                                                         |
| C11   | circlepw\_continue                                         | circlepw\_continue                                        | ✅    | ✅         | ✅    | circlepw\_main\_bt\_text                | circlepw\_mainButtonText     | Normal                                                                                                                  |
|       |                                                            |                                                           |      |           |      | circlepw\_main\_bt\_text\_pressed       |                              | Pressed                                                                                                                 |
|       |                                                            |                                                           |      |           |      | circlepw\_disabled\_main\_bt\_text      |                              | Disabled                                                                                                                |
| C12   | circlepw\_security\_questions\_title                       | circlepw\_security\_questions\_title                      | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_toolbarTitle       |                                                                                                                         |
| C13   | circlepw\_security\_questions\_required\_mark              | circlepw\_security\_questions\_required\_mark             | ✅    | ✅         | ✅    | circlepw\_error                         | circlepw\_metadata1          |                                                                                                                         |
| C14   | circlepw\_security\_questions\_question\_input\_config     | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_body1              |                                                                                                                         |
| C15   | circlepw\_security\_questions\_question\_placeholder       | circlepw\_security\_questions\_question\_placeholder      | ✅🔖  | ✅🔖       | ❌    | circlepw\_placeholder                   | circlepw\_body1              | Set ​​TextView's textColorHint and hint. Apply circlepw\_security\_questions\_question\_input\_config (C14)'s font.     |
| C16   | circlepw\_security\_questions\_answer\_header              | circlepw\_security\_questions\_answer\_header             | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C17   | circlepw\_security\_questions\_answer\_input\_config       | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_body1              |                                                                                                                         |
| C18   | circlepw\_security\_questions\_answer\_placeholder         | circlepw\_security\_questions\_answer\_placeholder        | ✅🔖  | ✅🔖       | ❌🔖  | circlepw\_placeholder                   | circlepw\_body1              | Set ​​TextView's textColorHint and hint. Apply circlepw\_security\_questions\_answer\_input\_config (C17)'s font.       |
| C19   | circlepw\_security\_questions\_answer\_hint\_header        | circlepw\_security\_questions\_answer\_hint\_header       | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C20   | circlepw\_security\_questions\_answer\_hint\_input\_config | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_body1              |                                                                                                                         |
| C21   | circlepw\_security\_questions\_answer\_hint\_placeholder   | circlepw\_security\_questions\_answer\_hint\_placeholder  | ✅🔖  | ✅🔖       | ❌🔖  | circlepw\_placeholder                   | circlepw\_body1              | Set ​​TextView's textColorHint and hint. Apply circlepw\_security\_questions\_answer\_hint\_input\_config (C20)'s font. |
| C22   | circlepw\_security\_questions\_error\_config               | ❌🔖                                                       | ❌🔖  | ✅         | ✅    | circlepw\_error                         | circlepw\_metadata1          | For text, see Error Message:hintsMatchAnswers(155705)                                                                   |
| C23   | circlepw\_next                                             | circlepw\_next                                            | ✅    | ✅         | ✅    | circlepw\_main\_bt\_text                | circlepw\_mainButtonText     | Normal                                                                                                                  |
|       |                                                            |                                                           |      |           |      | circlepw\_main\_bt\_text\_pressed       |                              | Pressed                                                                                                                 |
|       |                                                            |                                                           |      |           |      | circlepw\_disabled\_main\_bt\_text      |                              | Disabled                                                                                                                |
| C24   | circlepw\_select\_question\_title                          | circlepw\_select\_question\_title                         | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_toolbarTitle       |                                                                                                                         |
| C25   | circlepw\_select\_question\_item\_config                   | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_body1              |                                                                                                                         |
| C26   | circlepw\_security\_summary\_title                         | circlepw\_security\_summary\_title                        | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_toolbarTitle       |                                                                                                                         |
| C27   | circlepw\_question\_label                                  | circlepw\_question\_label                                 | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary2              | circlepw\_body2              |                                                                                                                         |
| C28   | circlepw\_security\_summary\_question\_value\_config       | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_summary                 | circlepw\_body2              |                                                                                                                         |
| C29   | circlepw\_answer\_label                                    | circlepw\_answer\_label                                   | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary2              | circlepw\_body2              |                                                                                                                         |
| C30   | circlepw\_security\_summary\_answer\_value\_config         | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_summary                 | circlepw\_caption2           |                                                                                                                         |
| C31   | circlepw\_hint\_label                                      | circlepw\_hint\_label                                     | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary2              | circlepw\_body2              |                                                                                                                         |
| C32   | circlepw\_security\_summary\_hint\_value\_config           | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_summary                 | circlepw\_body2              |                                                                                                                         |
| C33   | circlepw\_security\_confirm\_title                         | circlepw\_security\_confirm\_title                        | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_toolbarTitle       |                                                                                                                         |
| C34   | circlepw\_security\_confirm\_headline                      | circlepw\_security\_confirm\_headline                     | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_heading4           |                                                                                                                         |
| C35   | circlepw\_security\_confirm\_input\_headline               | circlepw\_security\_confirm\_input\_headline              | ✅    | ✅         | ✅    | circlepw\_text\_main2                   | circlepw\_caption1           |                                                                                                                         |
| C36   | circlepw\_security\_confirm\_input\_placeholder            | circlepw\_security\_confirm\_input\_placeholder           | ✅🔖  | ✅🔖       | ❌🔖  | circlepw\_placeholder                   | circlepw\_body1              | Set ​​TextView's textColorHint and hint. Apply circlepw\_security\_confirm\_input\_config (C37)'s font.                 |
| C37   | circlepw\_security\_confirm\_input\_config                 | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_body1              |                                                                                                                         |
| C37-1 | circlepw\_security\_confirm\_input\_match                  | circlepw\_security\_confirm\_input\_match                 | ✅    | ❌         | ❌    | ❌                                       | ❌                            | The text is the answer that requires user type. e.g. I agree                                                            |
| C38   | circlepw\_recover\_pincode\_error\_config                  | ❌🔖                                                       | ❌🔖  | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_body2              | For text, see Error Message:incorrectSecurityAnswers(155115)securityAnswersLocked(155120)                               |
| C38-1 | circlepw\_answer\_remain\_attemps\_template                | circlepw\_answer\_remain\_attemps\_template               | ✅🔖  | ❌         | ❌    | ❌                                       | ❌                            | e.g. You have %s attempts left.                                                                                         |
| C38-2 | circlepw\_answer\_lock\_period\_template                   | circlepw\_answer\_lock\_period\_template                  | ✅🔖  | ❌         | ❌    | ❌                                       | ❌                            | e.g. Please wait for %s mins to retry later                                                                             |
| C39   | circlepw\_recover\_pincode\_question\_config               | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_main2                   | circlepw\_body1              |                                                                                                                         |
| C40   | circlepw\_hint\_tag                                        | circlepw\_hint\_tag                                       | ✅    | ✅         | ✅    | circlepw\_tag\_text                     | circlepw\_metadata2          |                                                                                                                         |
| C41   | circlepw\_recover\_pincode\_answer\_hint\_config           | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_tag\_following\_text          | circlepw\_metadata1          |                                                                                                                         |
| C42   | circlepw\_recover\_pincode\_answer\_input\_header          | ✅                                                         | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C43   | circlepw\_recover\_pincode\_answer\_input\_placeholder     | circlepw\_recover\_pincode\_answer\_input\_placeholder    | ✅🔖  | ✅🔖       | ❌🔖  | circlepw\_placeholder                   | circlepw\_body1              | Set ​​TextView's textColorHint and hint. Apply circlepw\_recover\_pincode\_input\_config (C44)'s font.                  |
| C44   | circlepw\_recover\_pincode\_input\_config                  | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_body1              |                                                                                                                         |
| C45   | circlepw\_confirm                                          | circlepw\_confirm                                         | ✅    | ✅         | ✅    | circlepw\_main\_bt\_text                | circlepw\_mainButtonText     | Normal                                                                                                                  |
|       |                                                            |                                                           |      |           |      | circlepw\_main\_bt\_text\_pressed       |                              | Pressed                                                                                                                 |
|       |                                                            |                                                           |      |           |      | circlepw\_disabled\_main\_bt\_text      |                              | Disabled                                                                                                                |
| C46   | circlepw\_pin\_biometrics\_allow\_title                    | circlepw\_pin\_biometrics\_allow\_title                   | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_heading3           |                                                                                                                         |
| C47   | circlepw\_pin\_biometrics\_allow\_subtitle                 | circlepw\_pin\_biometrics\_allow\_subtitle                | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C48   | circlepw\_skip                                             | circlepw\_skip                                            | ✅    | ✅         | ✅    | circlepw\_second\_bt\_text              | circlepw\_secondButton       | Normal                                                                                                                  |
|       |                                                            |                                                           |      |           |      | circlepw\_second\_bt\_text              |                              | Pressed                                                                                                                 |
|       |                                                            |                                                           |      |           |      | circlepw\_second\_bt\_text\_disabled    |                              | Disabled                                                                                                                |
| C49   | circlepw\_pin\_biometrics\_disable                         | circlepw\_pin\_biometrics\_disable                        | ✅    | ✅         | ✅    | circlepw\_plain\_bt\_text               | circlepw\_plainButton        | Normal                                                                                                                  |
|       |                                                            |                                                           |      |           |      | circlepw\_plain\_bt\_text               |                              | Pressed                                                                                                                 |
|       |                                                            |                                                           |      |           |      | circlepw\_plain\_bt\_text\_disabled     |                              | Disabled                                                                                                                |
| C50   | circlepw\_pin\_biometrics\_encrypt\_title                  | circlepw\_pin\_biometrics\_encrypt\_title                 | ✅    | ❌         | ❌    | ❌                                       | ❌                            |                                                                                                                         |
| C51   | circlepw\_pin\_biometrics\_encrypt\_negative\_text         | circlepw\_pin\_biometrics\_encrypt\_negative\_text        | ✅    | ❌         | ❌    | ❌                                       | ❌                            |                                                                                                                         |
| C52   | circlepw\_pin\_biometrics\_encrypt\_subtitle               | circlepw\_pin\_biometrics\_encrypt\_subtitle              | ✅    | ❌         | ❌    | ❌                                       | ❌                            |                                                                                                                         |
| C53   | circlepw\_pin\_biometrics\_encrypt\_desc                   | circlepw\_pin\_biometrics\_encrypt\_desc                  | ✅    | ❌         | ❌    | ❌                                       | ❌                            |                                                                                                                         |
| C54   | circlepw\_pin\_biometrics\_decrypt\_title                  | circlepw\_pin\_biometrics\_decrypt\_title                 | ✅    | ❌         | ❌    | ❌                                       | ❌                            |                                                                                                                         |
| C55   | circlepw\_pin\_biometrics\_decrypt\_negative\_text         | circlepw\_pin\_biometrics\_decrypt\_negative\_text        | ✅    | ❌         | ❌    | ❌                                       | ❌                            |                                                                                                                         |
| C56   | circlepw\_pin\_biometrics\_decrypt\_subtitle               | circlepw\_pin\_biometrics\_decrypt\_subtitle              | ✅    | ❌         | ❌    | ❌                                       | ❌                            |                                                                                                                         |
| C57   | circlepw\_pin\_biometrics\_decrypt\_desc                   | circlepw\_pin\_biometrics\_decrypt\_desc                  | ✅    | ❌         | ❌    | ❌                                       | ❌                            |                                                                                                                         |
| C58   | circlepw\_pin\_biometrics\_update\_title                   | circlepw\_pin\_biometrics\_update\_title                  | ✅🔖  | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_heading3           | After the auto-fill PIN verify fails, the following biometrics setting page title will use this.                        |
| C59   | circlepw\_pin\_biometrics\_update\_subtitle                | circlepw\_pin\_biometrics\_update\_subtitle               | ✅🔖  | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              | After the auto-fill PIN verify fails, the following biometrics setting page subtitle will use this.                     |
| C60   | circlepw\_enter\_pincode\_use\_biometrics                  | circlepw\_enter\_pincode\_use\_biometrics                 | ✅    | ✅         | ✅    | circlepw\_pressed\_assist\_text\_color  | circlepw\_actionText         |                                                                                                                         |
| C61   | circlepw\_alert\_pop\_window\_description\_config          | ❌🔖                                                       | ❌🔖  | ✅         | ✅    | circlepw\_alert\_pop\_description\_text | circlepw\_body2              | For text, see Error Message: <br />biometricsKeyPermanentlyInvalidated(155710)                                          |
| C62   | circlepw\_alert\_pop\_window\_confirm                      | circlepw\_alert\_pop\_window\_confirm                     | ✅    | ✅         | ✅    | circlepw\_alert\_pop\_btn\_text         | circlepw\_actionText         |                                                                                                                         |
| C63   | circlepw\_transaction\_request\_title                      | circlepw\_transaction\_request\_title                     | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_heading3           |                                                                                                                         |
| C64   | circlepw\_transaction\_request\_subtitle                   | circlepw\_transaction\_request\_subtitle                  | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C65   | circlepw\_transaction\_request\_main\_currency             | ❌                                                         | ✅🔖  | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txAmountMainText   | Append currency name as unit after amount, e.g. 20 USDC                                                                 |
| C66   | circlepw\_transaction\_request\_exchange\_value            | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_exchange                | circlepw\_txExchangeText     |                                                                                                                         |
| C67   | circlepw\_transaction\_request\_from\_label                | circlepw\_transaction\_request\_from\_label               | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoText         |                                                                                                                         |
| C68   | circlepw\_transaction\_request\_from                       | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C69   | circlepw\_transaction\_request\_to\_label                  | circlepw\_transaction\_request\_to\_label                 | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoText         |                                                                                                                         |
| C70   | circlepw\_transaction\_request\_to\_config                 | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C71   | circlepw\_transaction\_request\_to\_contract\_name         | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C72   | circlepw\_transaction\_request\_to\_contract\_url          | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C73   | circlepw\_transaction\_request\_network\_fee\_label        | circlepw\_transaction\_request\_network\_fee\_label       | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoText         |                                                                                                                         |
| C74   | circlepw\_transaction\_request\_network\_fee               | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C75   | circlepw\_transaction\_request\_exchange\_network\_fee     | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_exchange                | circlepw\_txInfoExchangeText |                                                                                                                         |
| C76   | circlepw\_transaction\_request\_total\_label               | circlepw\_transaction\_request\_total\_label              | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoText         |                                                                                                                         |
| C77   | circlepw\_transaction\_request\_total\_config              | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C78   | circlepw\_transaction\_request\_exchange\_total\_value     | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_exchange                | circlepw\_txInfoExchangeText |                                                                                                                         |
| C79   | circlepw\_transaction\_request\_error\_config              | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_error                         | circlepw\_body2              |                                                                                                                         |
| C80   | circlepw\_transaction\_request\_fee\_tip                   | circlepw\_transaction\_request\_fee\_tip                  | ✅    | ✅         | ✅    | circlepw\_tip\_text                     | circlepw\_feeTipText         |                                                                                                                         |
| C81   | circlepw\_contract\_interaction\_contract\_address\_label  | circlepw\_contract\_interaction\_contract\_address\_label | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoText         |                                                                                                                         |
| C82   | circlepw\_contract\_interaction\_contract\_address\_config | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C83   | circlepw\_contract\_interaction\_data\_details             | circlepw\_contract\_interaction\_data\_details            | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C84   | circlepw\_contract\_interaction\_abi\_function\_label      | circlepw\_contract\_interaction\_abi\_function\_label     | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoText         |                                                                                                                         |
| C85   | circlepw\_contract\_interaction\_abi\_function\_config     | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoValueText    |                                                                                                                         |
| C86   | circlepw\_contract\_interaction\_abi\_parameter\_label     | circlepw\_contract\_interaction\_abi\_parameter\_label    | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoText         |                                                                                                                         |
| C87   | circlepw\_contract\_interaction\_call\_data\_label         | circlepw\_contract\_interaction\_call\_data\_label        | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_txInfoText         |                                                                                                                         |
| C88   | circlepw\_contract\_interaction\_call\_data\_config        | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_interactive             | circlepw\_contractDataText   |                                                                                                                         |
| C89   | circlepw\_transaction\_request\_raw\_tx\_description       | circlepw\_transaction\_request\_raw\_tx\_description      | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C90   | circlepw\_transaction\_request\_raw\_tx\_config            | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C91   | circlepw\_signature\_request\_title                        | circlepw\_signature\_request\_title                       | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_heading3           |                                                                                                                         |
| C92   | circlepw\_signature\_request\_contract\_name               | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_prompt                  | circlepw\_signNameText       |                                                                                                                         |
| C93   | circlepw\_signature\_request\_contract\_url                | ❌                                                         | ✅    | ✅         | ✅    | circlepw\_text\_sign\_url               | circlepw\_signUrlText        |                                                                                                                         |
| C94   | circlepw\_signature\_request\_subtitle                     | circlepw\_signature\_request\_subtitle                    | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C95   | circlepw\_signature\_request\_description                  | circlepw\_signature\_request\_description                 | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C96   | circlepw\_signature\_request\_msg\_config                  | ❌                                                         | ❌    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C97   | circlepw\_sign                                             | circlepw\_sign                                            | ✅    | ✅         | ✅    | circlepw\_main\_bt\_text                | circlepw\_mainButtonText     | Normal                                                                                                                  |
|       |                                                            |                                                           |      |           |      | circlepw\_main\_bt\_text\_pressed       |                              | Pressed                                                                                                                 |
|       |                                                            |                                                           |      |           |      | circlepw\_disabled\_main\_bt\_text      |                              | Disabled                                                                                                                |
| C98   | circlepw\_try\_again                                       | circlepw\_try\_again                                      | ✅    | ✅         | ✅    | circlepw\_main\_bt\_text                | circlepw\_mainButtonText     | Normal                                                                                                                  |
|       |                                                            |                                                           |      |           |      | circlepw\_main\_bt\_text\_pressed       |                              | Pressed                                                                                                                 |
|       |                                                            |                                                           |      |           |      | circlepw\_disabled\_main\_bt\_text      |                              | Disabled                                                                                                                |
| C99   | circlepw\_email\_otp\_title                                | circlepw\_email\_otp\_title                               | ✅    | ✅         | ✅    | circlepw\_text\_main                    | circlepw\_heading3           |                                                                                                                         |
| C100  | circlepw\_email\_otp\_description                          | circlepw\_email\_otp\_description                         | ✅    | ✅         | ✅    | circlepw\_text\_auxiliary               | circlepw\_body2              |                                                                                                                         |
| C101  | circlepw\_email\_otp\_email                                | ❌                                                         | ✅    | ❌         | ❌    |                                         |                              |                                                                                                                         |
| C102  | circlepw\_email\_otp\_head\_config                         | ❌                                                         | ❌    | ✅         | ✅    |                                         |                              |                                                                                                                         |
| C103  | circlepw\_email\_otp\_dash                                 | circlepw\_email\_otp\_dash                                | ✅    | ✅         | ✅    |                                         |                              |                                                                                                                         |
| C104  | circlepw\_email\_otp\_send\_again\_hint                    | circlepw\_email\_otp\_send\_again\_hint                   | ✅    | ✅         | ✅    |                                         |                              |                                                                                                                         |
| C105  | circlepw\_email\_otp\_send\_again                          | circlepw\_email\_otp\_send\_again                         | ✅    | ✅         | ✅    |                                         |                              |                                                                                                                         |

<br />

## Error Messages

When using this table, reference the **ApiError** heading in the
[WalletSDK section](/wallets/user-controlled/ios-sdk#walletsdk) of the SDK.

| Possible display location | ApiError.ErrorCode                          | Default Value                                                           | Note                                                      |
| ------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- |
| C5, C38, C79              | unknown(-1)                                 | Unknown error                                                           |                                                           |
|                           | success(0)                                  | Success                                                                 |                                                           |
| C5, C38, C79              | apiParameterMissing(1)                      | API parameter missing                                                   |                                                           |
| C5, C38, C79              | apiParameterInvalid(2)                      | API parameter invalid                                                   |                                                           |
| C5, C38, C79              | forbidden(3)                                | Forbidden                                                               |                                                           |
| C5, C38, C79              | unauthorized(4)                             | Unauthorized                                                            |                                                           |
| C5, C38, C79              | retry(9)                                    | Retry                                                                   |                                                           |
| C5, C38                   | customerSuspended(10)                       | Customer suspended                                                      |                                                           |
| C5, C38                   | pending(11)                                 | Pending                                                                 |                                                           |
| C5, C38                   | invalidSession(12)                          | Invalid session                                                         |                                                           |
| C5, C38                   | invalidPartnerId(13)                        | Invalid partner ID                                                      |                                                           |
| C5, C38                   | invalidMessage(14)                          | Invalid Message published to a SQS queue.                               |                                                           |
| C5, C38, C79              | invalidPhone(15)                            | Invalid phone number '%s', format should be in E.164.                   |                                                           |
| C5, C79                   | walletIdNotFound(156001)                    |                                                                         |                                                           |
| C5, C79                   | tokenIdNotFound(156002)                     |                                                                         |                                                           |
| C5, C79                   | transactionIdNotFound(156003)               |                                                                         |                                                           |
| C5, C79                   | entityCredentialNotFound(156004)            |                                                                         |                                                           |
| C5, C79                   | walletSetIdNotFound(156005)                 |                                                                         |                                                           |
|                           | userAlreadyExisted(155101)                  | user already existed                                                    |                                                           |
|                           | userNotFound(155102)                        | user not found                                                          |                                                           |
| C5, C38, C79              | userTokenNotFound(155103)                   | user token not found                                                    |                                                           |
| C5, C38, C79              | userTokenExpired(155104)                    | user token expired                                                      |                                                           |
| C5, C38, C79              | invalidUserToken(155105)                    | invalid user token                                                      |                                                           |
| C5                        | userWasInitialized(155106)                  | user was initialized                                                    |                                                           |
| C5                        | userHasSetPin(155107)                       | user has set pin                                                        |                                                           |
| C38                       | userHasSetSecurityQuestion(155108)          | user has set security question                                          |                                                           |
| C5, C38, C79              | userWasDisabled(155109)                     | user was disabled                                                       |                                                           |
| C5, C79                   | userDoesNotSetPinYet(155110)                | user does not set pin yet                                               |                                                           |
| C38                       | userDoesNotSetSecurityQuestionYet(155111)   | user does not set security questions yet                                |                                                           |
| C5, C79                   | incorrectUserPin(155112)                    | The PIN you entered is incorrect.                                       |                                                           |
|                           | incorrectDeviceId(155113)                   | incorrect device id                                                     |                                                           |
|                           | incorrectAppId(155114)                      | app id not found                                                        |                                                           |
| C38                       | incorrectSecurityAnswers(155115)            | The answers you entered are incorrect.                                  |                                                           |
|                           | invalidChallengeId(155116)                  | invalid challenge id                                                    |                                                           |
| C5, C79                   | invalidApproveContent(155117)               | invalid approve content                                                 |                                                           |
| C5, C38, C79              | invalidSecretKey(155118)                    | invalid secret key                                                      |                                                           |
| C5, C79                   | userPinLocked(155119)                       |                                                                         | Just display circlepw\_pin\_lock\_period\_template (C5-2) |
| C38                       | securityAnswersLocked(155120)               | The answers you entered are incorrect.                                  |                                                           |
| C5, C79                   | walletIsFrozen(155501)                      | Wallet is Frozen                                                        |                                                           |
| C5, C79                   | maxWalletLimitReached(155502)               | Max wallet limit reached                                                |                                                           |
| C5, C79                   | walletSetIdMutuallyExclusive(155503)        | WalletSetId can not be used together with blockchain and address filter |                                                           |
| C5, C79                   | metadataUnmatched(155504)                   | metadata array length does not match wallet count                       |                                                           |
|                           | userCanceled(155701)                        | User canceled                                                           |                                                           |
|                           | launchUiFailed(155702)                      |                                                                         |                                                           |
| C5                        | pinCodeNotMatched(155703)                   | The PIN you entered is not the same as the first one.                   |                                                           |
| C5                        | insecurePinCode(155704)                     | Your PIN can't have repeating or consecutive numbers.                   |                                                           |
| C22                       | hintsMatchAnswers(155705)                   | Your hint can't be the same as the answer.                              |                                                           |
|                           | biometricsSettingNotEnabled(155708)         | "Biometrics instead of PIN" is disabled                                 |                                                           |
|                           | deviceNotSupportBiometrics(155709)          | The device system doesn't support biometrics                            |                                                           |
| C61                       | biometricsKeyPermanentlyInvalidated(155710) | Failed to decrypt biometrics key                                        |                                                           |
|                           | biometricsUserSkip(155711)                  | The user has not enabled biometrics yet                                 |                                                           |
|                           | biometricsUserDisableForPin(155712)         | The user refused to enable biometrics                                   |                                                           |
|                           | biometricsUserLockout(155713)               | Too many requests. Try again later.                                     |                                                           |
|                           | biometricsUserLockoutPermanent(155714)      | Too many requests. The biometrics sensor on the device is locked.       |                                                           |
|                           | biometricsUserNotAllowPermission(155715)    | The user didn't allow to enable biometrics.                             |                                                           |
|                           | biometricsInternalError(155716)             | Unexpected error for biometrics: %s                                     |                                                           |

<br />

## Using`strings.xml` for Static Customization

The example values in the `strings.xml` file below can be used for Static
Customization. The fields also show the default string values in the SDK if you
do not set dynamic customization.

Please reference this example and add/update any desired text string in your
strings.xml under the `res/values` folder.

To avoid dynamic customization, return a TextConfig that doesn't contain text or
null in **getTextConfig(String key)** and **getTextConfigs(Resource.TextsKey
key)** function. For example, a configuration that doesn't have
`new TextConfig(null, color, typeface)`, return null, or
`super.getTextConfig(key)` in its switch statement.

```coffeescript XML theme={null}
<resources>
    <!-- [General] -->
    <string name="circlepw_continue">Continue</string>
    <string name="circlepw_next">Next</string>
    <string name="circlepw_skip">Skip</string>
    <string name="circlepw_question_label">Question:</string>
    <string name="circlepw_answer_label">Answer:</string>
    <string name="circlepw_hint_label">Hint:</string>
    <string name="circlepw_hint_tag">Hint</string>
    <string name="circlepw_empty"></string>
    <string name="circlepw_empty_placeholder">-</string>
    <string name="circlepw_confirm">Confirm</string>
    <string name="circlepw_pin_remain_attemps_template">You have %s attempts left.</string>
    <string name="circlepw_pin_lock_period_template">You've used up all PIN attempts. Please wait for %s mins to retry later.</string>
    <string name="circlepw_answer_remain_attemps_template">You have %s attempts left.</string>
    <string name="circlepw_answer_lock_period_template">Please wait for %s mins to retry later.</string>
    <string name="circlepw_sign">Sign</string>
    <string name="circlepw_try_again">Try again</string>

    <!-- [Page] EnterPINCode -->
    <string name="circlepw_enter_pincode_subhead">Let us know if it's really you.</string>
    <string name="circlepw_enter_pincode_forgot_pin">Forgot PIN?</string>
    <string name="circlepw_enter_pincode_use_biometrics">Use Biometrics</string>

    <!-- [Page] NewPINCode -->
    <string name="circlepw_new_pincode_subhead">Your PIN can't have repeating (e.g. 000000) or consecutive (e.g. 123456) numbers.</string>
    <!-- [Page] ConfirmPINCode -->
    <string name="circlepw_confirm_pincode_headline">Re-enter your PIN to confirm</string>
    <string name="circlepw_confirm_pincode_subhead"></string>
    <!-- [Page] SecurityIntros -->
    <string name="circlepw_security_intros_description">This is the only way to recover wallet access if you forget your PIN. Pick 2 security questions and provide answers for access recovery.</string>

    <!-- [Page] SecurityQuestions -->
    <string name="circlepw_security_questions_title">Recovery method</string>
    <string name="circlepw_security_questions_required_mark">*</string>
    <string name="circlepw_security_questions_question_placeholder">Select one question</string>
    <string name="circlepw_security_questions_answer_header">Provide an answer</string>
    <string name="circlepw_security_questions_answer_placeholder">Type your answer here</string>
    <string name="circlepw_security_questions_answer_hint_header">Provide an answer hint (optional)</string>
    <string name="circlepw_security_questions_answer_hint_placeholder">Type your hint here</string>

    <!-- [Page] SelectQuestion -->
    <string name="circlepw_select_question_title">Select one question</string>
    <!-- [Page] SecuritySummary -->
    <string name="circlepw_security_summary_title">Summary</string>

    <!-- [Page] SecurityConfirm -->
    <string name="circlepw_security_confirm_title">Confirmation</string>
    <string name="circlepw_security_confirm_headline">Keep your questions safe</string>
    <string name="circlepw_security_confirm_input_headline">Type \"I agree\" to proceed:</string>
    <string name="circlepw_security_confirm_input_placeholder">Type \"I agree\" here</string>
    <string name="circlepw_security_confirm_input_match">I agree</string>

    <!-- [Page] RecoverPINCode -->
    <string name="circlepw_recover_pincode_answer_input_header">Enter your answer here</string>
    <string name="circlepw_recover_pincode_answer_input_placeholder">Type your answer here</string>

    <!-- [PageBiometricsAllowFragment] -->
    <string name="circlepw_pin_biometrics_allow_title">Allow Biometrics for Web3 Access</string>
    <string name="circlepw_pin_biometrics_allow_subtitle">Elevate your experience with effortless biometrics  recognition</string>
    <string name="circlepw_pin_biometrics_disable">Don\'t ask me again</string>
    <string name="circlepw_pin_biometrics_encrypt_title">Verify It\'s Youe</string>
    <string name="circlepw_pin_biometrics_encrypt_negative_text">Cancel</string>
    <string name="circlepw_pin_biometrics_encrypt_subtitle"></string>
    <string name="circlepw_pin_biometrics_encrypt_desc"></string>
    <string name="circlepw_pin_biometrics_decrypt_title">Verify It\'s Youe</string>
    <string name="circlepw_pin_biometrics_decrypt_negative_text">Cancel</string>
    <string name="circlepw_pin_biometrics_decrypt_subtitle"></string>
    <string name="circlepw_pin_biometrics_decrypt_desc"></string>

    <string name="circlepw_pin_biometrics_update_title">Update Biometrics for Web3 Access</string>
    <string name="circlepw_pin_biometrics_update_subtitle">Please update your biometrics</string>
    <string name="circlepw_alert_pop_window_title">Alert</string>
    <string name="circlepw_alert_pop_window_confirm">OK</string>
    <!-- [HostSsoPinFragment] -->
    <string name="circlepw_transaction_request_title">Confirm transaction</string>
    <!-- [HostSsoPinFragment] -->
    <string name="circlepw_transaction_request_subtitle">Please click confirm to proceed the transaction</string>
    <string name="circlepw_transaction_request_from_label">From</string>
    <string name="circlepw_transaction_request_to_label">To</string>
    <string name="circlepw_transaction_request_network_fee_label">Network fee</string>
    <string name="circlepw_transaction_request_total_label">Total</string>
    <string name="circlepw_transaction_request_fee_tip">Please note this is an estimated fee. Network fees may vary based on network traffic and transaction complexity.</string>
    <string name="circlepw_transaction_request_raw_tx_description">Transaction details:</string>
    <string name="circlepw_signature_request_title">Signature Request</string>
    <string name="circlepw_signature_request_subtitle">Click on sign button to provide a signature for verification.</string>
    <string name="circlepw_signature_request_description">You are signing:</string>
    <string name="circlepw_contract_interaction_title">Contract Interaction</string>
    <string name="circlepw_contract_interaction_subtitle">Please click confirm to proceed the  contract execution.</string>
    <string name="circlepw_contract_interaction_contract_address_label">Contract address</string>
    <string name="circlepw_contract_interaction_data_details">Data Details</string>
    <string name="circlepw_contract_interaction_abi_function_label">ABI Function</string>
    <string name="circlepw_contract_interaction_abi_parameter_label">ABI Parameters</string>
    <string name="circlepw_contract_interaction_call_data_label">Call Data</string>
    <!-- [HostVerifyOtpFragment] -->
    <string name="circlepw_email_otp_title">Enter verification code</string>
    <!-- [PageVerifyOtpFragment] -->
    <string name="circlepw_email_otp_description">The one-time passcode has been sent to %s</string>
    <string name="circlepw_email_otp_email">your email</string>
    <string name="circlepw_email_otp_dash">-</string>
    <string name="circlepw_email_otp_send_again_hint">Don't receive the code?</string>
    <string name="circlepw_email_otp_send_again">Send again</string>
</resources>
```

## Image Customization

The SDK uses [glide](https://github.com/bumptech/glide) as the image loader for
remote images. For the cache strategy, please see
[DiskCacheStrategy.AUTOMATIC](https://bumptech.github.io/glide/javadocs/420/com/bumptech/glide/load/engine/DiskCacheStrategy.html#AUTOMATIC). Use
`RemoteImageSetter` or `LocalImageSetter` for icon images:

* **RemoteImageSetter** constructor:
  * `RemoteImageSetter(int drawableId, String url)`
* **LocalImageSetter** constructor:
  * `LocalImageSetter(int drawableId)`

Each image has its suggested size of **width** and **height** shown in the index
table's **ImageView size** column. Follow the suggested size to avoid the
possibility of a broken layout or unexpected display.

## Resource.Icon

### D1\~D14

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## D Index Table

| #   | Resource.Icon        | ImageView size (dp) |        |
| --- | -------------------- | ------------------- | ------ |
|     |                      | width               | height |
| D1  | securityIntroMain    | 144                 | 144    |
| D2  | selectCheckMark      | 24                  | 24     |
| D3  | dropdownArrow        | 40                  | 40     |
| D4  | errorInfo            | 21                  | 21     |
| D5  | securityConfirmMain  | 144                 | 144    |
| D6  | biometricsAllowMain  | 80                  | 80     |
| D7  | showPin              | 20                  | 15     |
| D8  | hidePin              | 20                  | 15     |
| D9  | alertWindowIcon      | 24                  | 24     |
| D10 | transactionTokenIcon | 36                  | 36     |
| D11 | networkFeeTipIcon    | 16                  | 16     |
| D12 | showLessDetailArrow  | 20                  | 20     |
| D13 | showMoreDetailArrow  | 20                  | 20     |
| D14 | requestIcon          | 72                  | 72     |

<br />

## Resource.ToolbarIcon

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## E Index Table

| #  | Resource.ToolbarIcon | ImageView size (dp) |            |
| -- | -------------------- | :-----------------: | ---------- |
|    |                      |      **width**      | **height** |
| E1 | close                |          24         | 24         |
| E2 | back                 |         24          | 24         |

## Color Customization

Colors can be customized in a Static way as a static string; with the UI
screenshots and Key mapping index table below, the colors of each string can be
defined in the colors.xml.Note that some keys are not specified in the
screenshot but can be referenced from the A and C index table in the colors.xml
column.

## New, Confirm, and Enter PIN Code

<Frame>
  <img />
</Frame>

## Security Intro

<Frame>
  <img />
</Frame>

## Security Questions

<Frame>
  <img />
</Frame>

## Security Summary

<Frame>
  <img />
</Frame>

## Security Confirm

<Frame>
  <img />
</Frame>

## Recover PIN Code

<Frame>
  <img />
</Frame>

## Biometrics Setup

<Frame>
  <img />
</Frame>

## Confirm Transaction

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Contract Interaction

<Frame>
  <img />
</Frame>

## Signature Request

<Frame>
  <img />
</Frame>

## Verify Email OTP

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## F Index Table

| #   | `colors.xml`                                 | Color Code | Note                                  |
| --- | -------------------------------------------- | ---------- | ------------------------------------- |
| F1  | circlepw\_text\_main                         | # 1A1A1A   |                                       |
| F2  | circlepw\_text\_auxiliary                    | # 3D3D3D   |                                       |
| F3  | circlepw\_text\_action                       | # 136FD8   | Normal action text color              |
| F4  | circlepw\_text\_action\_pressed              | # B3136FD8 | Pressed action text color             |
| F5  | circlepw\_placeholder                        | # A3A3A3   |                                       |
| F6  | circlepw\_error                              | # F55538   |                                       |
| F7  | circlepw\_error\_background                  | # FDF2F2   |                                       |
| F8  | circlepw\_text\_main2                        | # 1C1C1C   |                                       |
| F9  | circlepw\_text\_auxiliary2                   | # 707070   |                                       |
| F10 | circlepw\_text\_summary                      | # 0073C3   |                                       |
| F11 | circlepw\_disabled\_main\_bt\_text           | # 80FFFFFF | Disabled button text color            |
| F12 | circlepw\_main\_bt\_text                     | # FFFFFF   | Normal button text color              |
| F13 | circlepw\_main\_bt\_text\_pressed            | # FFFFFF   | Pressed button text color             |
| F14 | circlepw\_disabled\_main\_bt\_background     | # 800073C3 | Disabled button background color      |
| F15 | circlepw\_main\_bt\_background               | # 0073C3   | Normal button background color        |
| F16 | circlepw\_main\_bt\_background\_pressed      | # 1AA3FF   | Pressed button background color       |
| F17 | circlepw\_success                            | # 0B9C4A   |                                       |
| F18 | circlepw\_input\_boarder                     | # E8E8E8   | Normal input field border             |
| F19 | circlepw\_input\_boarder\_focused            | # 46B5FF   | Focused input field border            |
| F20 | circlepw\_tag\_text                          | # 005339   | Tag text color                        |
| F21 | circlepw\_tag\_background                    | # E1F2FF   | Tag background color                  |
| F22 | circlepw\_tag\_following\_text               | # 0073C3   |                                       |
| F23 | circlepw\_divider                            | # F0EFEF   |                                       |
| F24 | circlepw\_pin\_dot\_base                     | # FFFFFF   | PIN dot unfilled color                |
| F25 | circlepw\_pin\_dot\_base\_boarder            | # 707070   | PIN dot unfilled border color         |
| F26 | circlepw\_pin\_dot\_activated                | # 0073C3   | PIN dot filled color                  |
| F27 | circlepw\_background                         | # FFFFFF   | General background color              |
| F28 | circlepw\_security\_confirm\_main\_bg        | # E9EEFE   |                                       |
| F29 | circlepw\_disabled\_input\_background        | # F5F5F5   | Disabled input field background color |
| F30 | circlepw\_second\_bt\_text                   | # 0073C3   |                                       |
| F31 | circlepw\_second\_bt\_text\_disabled         | # 800073C3 |                                       |
| F32 | circlepw\_second\_bt\_border                 | # 0073C3   |                                       |
| F33 | circlepw\_second\_bt\_border\_disabled       | # 800073C3 |                                       |
| F34 | circlepw\_second\_bt\_background             | # FFFFFF   |                                       |
| F35 | circlepw\_second\_bt\_background\_pressed    | # F1F9FE   |                                       |
| F36 | circlepw\_second\_bt\_background\_disabled   | # 80F1F9FE |                                       |
| F37 | circlepw\_plain\_bt\_text                    | # 0073C3   |                                       |
| F38 | circlepw\_plain\_bt\_text\_disabled          | # 800073C3 |                                       |
| F39 | circlepw\_plain\_bt\_background              | # FFFFFF   |                                       |
| F40 | circlepw\_plain\_bt\_background\_pressed     | # F1F9FE   |                                       |
| F41 | circlepw\_plain\_bt\_background\_disabled    | # 80F1F9FE |                                       |
| F42 | circlepw\_text\_prompt                       | # 29233B   |                                       |
| F43 | circlepw\_text\_interactive                  | # 0073C3   |                                       |
| F44 | circlepw\_interactive\_bg                    | # F9F9FC   |                                       |
| F45 | circlepw\_text\_exchange                     | # F0EFEF   |                                       |
| F46 | circlepw\_tip\_text                          | # FFFFFF   |                                       |
| F47 | circlepw\_transaction\_request\_fee\_tip\_bg | # 29233B   |                                       |
| F48 | circlepw\_text\_sign\_url                    | # 8E8E93   |                                       |
| F49 | circlepw\_otp\_head\_text                    | # 000000   |                                       |
| F50 | circlepw\_otp\_hint\_text                    | # 6B6580   |                                       |
| F51 | circlepw\_otp\_action\_text                  | # 007AFF   |                                       |

## Using `colors.xml` for Static Customization

The example values in the `colors.xml` file can be used for Static
Customization. The fields also show the default string values in the SDK if you
do not set dynamic customization.

Please reference this example and add/update any desired text color in your
`colors.xml` under the `res/values` folder of the App project.

To avoid dynamic customization, return a TextConfig that contains text only with
no color value in the **getTextConfig(String key)** and
**getTextConfigs(Resource.TextsKey key)** functions. For example, use a
configuration with `new TextConfig(key, 0, typeface)`, return null, or
`super.getTextConfig(key)` in its switch statement.

```coffeescript XML theme={null}
<resources>
    <color name="circlepw_text_main">#1A1A1A</color>
    <color name="circlepw_text_auxiliary">#3D3D3D</color>
    <color name="circlepw_text_action">#136FD8</color>
    <color name="circlepw_text_action_pressed">#B3136FD8</color>
    <color name="circlepw_placeholder">#A3A3A3</color>
    <color name="circlepw_error">#F55538</color>
    <color name="circlepw_error_background">#FDF2F2</color>
    <color name="circlepw_text_main2">#1C1C1C</color>
    <color name="circlepw_text_auxiliary2">#707070</color>
    <color name="circlepw_text_summary">#0073C3</color>
    <color name="circlepw_disabled_main_bt_text">#80FFFFFF</color>
    <color name="circlepw_disabled_main_bt_background">#800073C3</color>
    <color name="circlepw_main_bt_text">#ffffff</color>
    <color name="circlepw_main_bt_background">#0073C3</color>
    <color name="circlepw_main_bt_text_pressed">#ffffff</color>
    <color name="circlepw_main_bt_background_pressed">#1AA3FF</color>
    <color name="circlepw_second_bt_text">#0073C3</color>
    <color name="circlepw_second_bt_text_disabled">#800073C3</color>
    <color name="circlepw_second_bt_border">#0073C3</color>
    <color name="circlepw_second_bt_border_disabled">#800073C3</color>
    <color name="circlepw_second_bt_background">#FFFFFF</color>
    <color name="circlepw_second_bt_background_pressed">#F1F9FE</color>
    <color name="circlepw_second_bt_background_disabled">#80F1F9FE</color>
    <color name="circlepw_plain_bt_text">#0073C3</color>
    <color name="circlepw_plain_bt_text_disabled">#800073C3</color>
    <color name="circlepw_plain_bt_background">#FFFFFF</color>
    <color name="circlepw_plain_bt_background_pressed">#F1F9FE</color>
    <color name="circlepw_plain_bt_background_disabled">#80F1F9FE</color>
    <color name="circlepw_success">#0B9C4A</color>
    <color name="circlepw_input_boarder">#E8E8E8</color>
    <color name="circlepw_input_boarder_focused">#46B5FF</color>
    <color name="circlepw_tag_text">#005339</color>
    <color name="circlepw_tag_background">#E1F2FF</color>
    <color name="circlepw_tag_following_text">#0073C3</color>
    <color name="circlepw_divider">#F0EFEF</color>
    <color name="circlepw_pin_dot_base">#ffffff</color>
    <color name="circlepw_pin_dot_base_boarder">#707070</color>
    <color name="circlepw_pin_dot_activated">#0073C3</color>
    <color name="circlepw_background">#FFFFFF</color>
    <color name="circlepw_security_confirm_main_bg">#E9EEFE</color>
    <color name="circlepw_disabled_input_background">#F5F5F5</color>
    <color name="circlepw_alert_pop_window_background">#B3111827</color>
    <color name="circlepw_alert_pop_title_text">#1D1B20</color>
    <color name="circlepw_alert_pop_description_text">#49454F</color>
    <color name="circlepw_alert_pop_btn_text">#000000</color>
    <color name="circlepw_pin_dot_focused_boarder">#1894E8</color>
    <color name="circlepw_text_prompt">#29233B</color>
    <color name="circlepw_text_exchange">#979797</color>
    <color name="circlepw_text_sign_url">#8E8E93</color>
    <color name="circlepw_transaction_request_fee_tip_bg">#29233B</color>
    <color name="circlepw_tip_text">#FFFFFF</color>
    <color name="circlepw_interactive_bg">#F9F9FC</color>
    <color name="circlepw_text_interactive">#0073C3</color>
    <color name="transparent">#00000000</color>
    <color name="circlepw_otp_head_text">#000000</color>
    <color name="circlepw_otp_hint_text">#6B6580</color>
    <color name="circlepw_otp_action_text">#007AFF</color>
</resources>
```

## Style Customization

Styles can be customized in a Static way as a static style by using the UI
screenshots and Key mapping index table below. The styles of each string can be
defined in the `styles.xml` file.

To avoid dynamic customization,  return `TextConfig` that contains text only in
`getTextConfig(String key)` and `getTextConfigs(Resource.TextsKey key)`
functions. For example, use `new TextConfig(“Your text here”)` or
`super.getTextConfig(key)` to ignore that key in the switch statement.

<Note>
  **Note:**

  Some keys (error message) are not specified in the screenshot but can be
  referenced from the A and C index table at the `styles.xml`file column.
</Note>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## G Index Table

| #   | `styles.xml`                   |
| --- | ------------------------------ |
| G1  | circlepw\_heading3             |
| G2  | circlepw\_heading4             |
| G3  | circlepw\_heading5             |
| G4  | circlepw\_body1                |
| G5  | circlepw\_body2                |
| G6  | circlepw\_caption1             |
| G7  | circlepw\_caption2             |
| G8  | circlepw\_metadata1            |
| G9  | circlepw\_metadata2            |
| G10 | circlepw\_actionText           |
| G11 | circlepw\_pinDigitText         |
| G12 | circlepw\_mainButtonText       |
| G13 | circlepw\_toolbarTitle         |
| G14 | circlepw\_datePicker           |
| G15 | circlepw\_secondButtonText     |
| G16 | circlepw\_plainButtonText      |
| G17 | circlepw\_txAmountMainText     |
| G18 | circlepw\_txInfoText           |
| G19 | circlepw\_txInfoValueText      |
| G20 | circlepw\_detailToggleText     |
| G21 | circlepw\_contractDataText     |
| G22 | circlepw\_txExchangeText       |
| G23 | circlepw\_txInfoExchangeText   |
| G24 | circlepw\_feeTipText           |
| G25 | circlepw\_otpHeadText          |
| G26 | circlepw\_otpSendAgainHintText |
| G27 | circlepw\_signNameText         |
| G28 | circlepw\_signUrlText          |

## Using the `styles.xml` file for Static Customization

The example values in the `styles.xml` file can be used for Static
Customization. The fields also show the default style values in the SDK if you
do not set dynamic customization.

Please reference this example and add or update any desired text styles in your
`styles.xml` file under the `res/values` folder of the App project.

The style can be used to define **textSize** and **fontWeight**, and it can also
be used in conjunction with the static colors key defined in colors.xml, such as
in the following:

```coffeescript XML theme={null}
<item name="colorControlActivated">@color/circlepw_input_boarder_focused</item>
```

```coffeescript XML theme={null}
<resources>
    <style name="circlepw_heading3">
        <item name="android:textSize">24sp</item>
    </style>
    <style name="circlepw_heading4">
        <item name="android:textSize">20sp</item>
    </style>
    <style name="circlepw_heading5">
        <item name="android:textSize">18sp</item>
    </style>
    <style name="circlepw_body1">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_body2">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_caption1">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_caption2">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_metadata1">
        <item name="android:textSize">12sp</item>
    </style>
    <style name="circlepw_metadata2">
        <item name="android:textSize">10sp</item>
    </style>
    <style name="circlepw_actionText">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_pinDigitText">
        <item name="android:textSize">40sp</item>
    </style>
    <style name="circlepw_mainButtonText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_secondButtonText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_plainButtonText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_toolbarTitle">
        <item name="android:textSize">18sp</item>
    </style>

    <style name="circlepw_datePicker" parent="Theme.AppCompat.Light.Dialog">
        <!-- Top background-->
        <item name="colorAccent">@color/circlepw_main_bt_background</item>
        <!--selected Item color-->
        <item name="colorControlActivated">@color/circlepw_main_bt_background</item>
        <!-- arrow bordercolor(<>)-->
        <item name="android:selectableItemBackgroundBorderless">@color/circlepw_background</item>
        <!--Calender Background color -->
        <item name="android:windowBackground">@color/circlepw_background</item>
        <!-- Ok Cancel Color-->
        <item name="colorOnPrimary">@color/circlepw_main_bt_background</item>
        <!-- Week TextColor-->
        <item name="android:textColorSecondary">@color/circlepw_text_main</item>
        <!-- Calender Number color arrow color (< >) -->
        <item name="android:textColorPrimary">@color/circlepw_text_main</item>
        <!--day , month-->
        <item name="android:textColorPrimaryInverse">@color/circlepw_background</item>
        <!-- year-->
        <item name="android:textColorSecondaryInverse">@color/circlepw_background</item>
    </style>

    <style name="circlepw_txAmountMainText">
        <item name="android:textSize">40sp</item>
    </style>
    <style name="circlepw_txInfoText">
        <item name="android:textSize">15sp</item>
    </style>
    <style name="circlepw_txInfoValueText">
        <item name="android:textSize">15sp</item>
    </style>
    <style name="circlepw_detailToggleText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_contractDataText">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_txExchangeText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_txInfoExchangeText">
        <item name="android:textSize">13sp</item>
    </style>
    <style name="circlepw_feeTipText">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_otpHeadText">
        <item name="android:textSize">24sp</item>
    </style>
    <style name="circlepw_otpSendAgainHintText">
        <item name="android:textSize">15sp</item>
    </style>
    <style name="circlepw_signName" parent="circlepw_signNameText">
        <item name="android:textColor">@color/circlepw_text_prompt</item>
    </style>
    <style name="circlepw_signUrl" parent="circlepw_signUrlText">
        <item name="android:textColor">@color/circlepw_text_sign_url</item>
    </style>
</resources>
```


# Authentication Types
Source: https://developers.circle.com/wallets/user-controlled/authentication-methods

Authenticate your users using social login, email, or PIN

Circle provides several authentication mechanisms so you can build a familiar
onboarding experience. Choose social logins, email, or PIN and security
questions to authenticate users and create user-controlled wallets.

* **Social logins:** Users sign in with Google, Apple, or Facebook (OAuth 2.0).
* **Email:** Send a one-time password (OTP) by email for identity verification.
* **PIN:** Users set a PIN to authorize transactions; optional biometrics for
  fingerprint or face.

## Authentication type differences

| Type       | Onboarding                                                                                                                                      | Signing                                                                                                                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Social** | User is redirected to the provider (Google, Apple, Facebook) to choose the account and sign in. Circle creates the wallet after authentication. | When the user sends a transaction or signs, Circle can show UIs to preview and confirm (customizable or disable). See [Confirmation UIs](/wallets/user-controlled/confirmation-uis). |
| **Email**  | User enters email; Circle sends an OTP. User verifies identity by entering the code.                                                            | Same as social: when the user sends or signs, Circle can show preview/confirm UIs (customizable or disable).                                                                         |
| **PIN**    | User sets a 6-digit PIN and answers to security questions during signup.                                                                        | No built-in transaction UIs. User previews the request elsewhere, then confirms by entering PIN or using biometrics (if enabled).                                                    |

For key management details, see [Key management](/wallets/key-management). For
signing UI options, see
[Confirmation UIs](/wallets/user-controlled/confirmation-uis).

## Social logins

Users sign in with Google, Facebook, or Apple; Circle creates a wallet for them.

<Accordion title="Example: Social login UX">
  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>
</Accordion>

<Note>
  **Additional social providers:** To offer another provider, request it via
  [Circle on Discord](https://discord.com/invite/buildoncircle).
</Note>

### Create a wallet with social logins

1. Obtain provider IDs:
   [Google Client ID](https://developers.google.com/identity/oauth2/web/guides/get-google-api-clientid),
   [Facebook App ID](https://developers.facebook.com/docs/development),
   [Apple App/Service ID](https://developer.apple.com/help/account/manage-identifiers/register-an-app-id/).
2. In [Circle Developer Console](https://console.circle.com/), go to
   **Configurator > Authentication Methods > Social Logins** and add the IDs.
3. Keep your app's ID settings and the Console in sync.

Full walkthrough:
[Create user wallets with social login](/wallets/user-controlled/create-user-wallets-with-social-login).

<Warning>
  **Important:**

  * Circle cannot recover lost credentials or unblock accounts for social logins.
    Users must contact the respective social provider directly. Recovering a
    banned Facebook account can take weeks.
  * Each social account (Google, Apple, Facebook) links to one unique user ID.
    Signing up with multiple providers (for example, Google then Apple) creates
    separate user IDs.
</Warning>

### User onboarding with social logins

1. `POST /users/social/token` with `deviceId` → receive `deviceToken` and
   `deviceEncryptionKey`.
2. Invoke the client-side SDK `performLogin` with `deviceToken` and
   `deviceEncryptionKey`.
3. Circle runs the social login flow and returns `userID`, `userToken`,
   `encryptionKey`, `refreshToken`, and `OAuthInfo`.

<Accordion title="Example: User onboarding flow (social)">
  <Frame>
    <img />
  </Frame>
</Accordion>

After onboarding, initialize the user and create a wallet. Steps are the same
for social and email; see
[Initialize user and create wallet (social and email)](#initialize-user-and-create-wallet-social-and-email)
below.

<Accordion title="Example: Initialize user and create wallet (social)">
  <Frame>
    <img />
  </Frame>
</Accordion>

## Email

Users sign up with their email; Circle sends an OTP and creates a wallet for
them after verification.

<Accordion title="Example: Email OTP UX">
  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>

  <Frame>
    <img />
  </Frame>
</Accordion>

<Note>
  **Customize UI:** The OTP prompt is predefined; you can customize copy, colors,
  and images. See
  [Web SDK UI Customizations](/wallets/user-controlled/web-sdk-ui-customizations).

  **Send again:** When the user taps **Send again**, the SDK emits an event; call
  `POST /users/email/resendOTP` to send a new OTP.
</Note>

### Create a wallet with email

1. In [Circle Developer Console](https://console.circle.com/), go to **Wallets >
   User Controlled > Configurator > Email**.
2. Enter SMTP credentials (stored encrypted).
3. Set **From**, **Subject**, and **Email Template**; include `{{ email.otp }}`
   in the template.
4. Use **SEND TEST EMAIL** to verify.

Full walkthrough:
[Create user wallets with email](/wallets/user-controlled/create-user-wallets-with-email).

<Info>
  **`{{ email.otp }}`:** This placeholder must appear in the email template so users receive the OTP.
</Info>

### User onboarding with email

1. `POST /users/email/token` with `deviceId` → receive `otpToken`,
   `deviceToken`, `deviceEncryptionKey`.
2. Your SMTP sends the OTP email to the user.
3. Pass `verifyOTP`, `deviceToken`, and `deviceEncryptionKey` to the client-side
   SDK; user enters OTP.
4. Circle validates and returns `userID`, `userToken`, `encryptionKey`, and
   `refreshToken`.

<Accordion title="Example: User onboarding flow (email)">
  <Frame>
    <img />
  </Frame>
</Accordion>

### Initialize user and create wallet (social and email)

After onboarding (social or email), initialize the user and create a wallet:

1. `POST /user/initialize` with `userToken` in the body.
2. Circle returns `challengeId`.
3. Pass `challengeId` to the client-side SDK to create the Web3 wallet.

<Accordion title="Example: Initialize user and create wallet (email)">
  <Frame>
    <img />
  </Frame>
</Accordion>

### User token and refresh token

User and refresh tokens apply to **email** (and social logins; not PIN). Same
token and refresh behavior applies to social logins.

The user token is the session identifier and expires 14 days after generation;
users are then logged out. To avoid frequent logouts, send a `POST` request to
[`/users/token/refresh`](/api-reference/wallets/user-controlled-wallets/refresh-user-token)
with the existing user token, its `refreshToken`, and a new user token; the
response returns the new user token.

## PIN

Users set a 6-digit PIN (and optional security questions) to authorize
transactions. Keys are held by the user. Optional biometrics allow signing with
fingerprint or face on supported devices.

<Warning>
  **PIN and security questions:** Users are responsible for remembering their
  PIN and security answers. Ensure they understand this; lost PIN and answers
  can mean lost access.
</Warning>

### About PIN

The PIN is encrypted on the user's device. It is required to authorize wallet
actions. After three incorrect attempts, the PIN locks for 30 minutes.

### Biometrics

When enabled, users can approve signing with fingerprint or facial recognition
so a PIN is not required every time.

<Accordion title="Example: Biometrics UX">
  <Frame>
    <img />
  </Frame>
</Accordion>

### Wallet recovery through security questions

Users set security-question answers during signup. If they lose or lock their
PIN, they can recover by answering those questions. After three incorrect
recovery answers, recovery locks for 30 minutes.

<Accordion title="Example: PIN and recovery setup">
  <Frame>
    <img />
  </Frame>
</Accordion>

Full walkthrough:
[Create user wallets with PIN](/wallets/user-controlled/create-user-wallets-with-pin).
To restore access after a lost PIN:
[Recover an account](/wallets/user-controlled/recover-account).


# Confirmation UIs
Source: https://developers.circle.com/wallets/user-controlled/confirmation-uis



For the social logins and email authentication methods, by default, Circle
presents your user with a UI to preview the transaction or signing details
before sending transactions or signatures onto the blockchain. These
confirmation UIs are applicable to the following APIs:

* `POST`
  [`/user/transactions/transfer`](/api-reference/wallets/user-controlled-wallets/create-user-transaction-transfer-challenge)
* `POST`
  [`/user/transactions/contractExecution`](/api-reference/wallets/user-controlled-wallets/create-user-transaction-contract-execution-challenge)
* `POST`
  [`/user/sign/transaction`](/api-reference/wallets/user-controlled-wallets/sign-user-transaction)
* `POST`
  [`/user/sign/message`](/api-reference/wallets/user-controlled-wallets/sign-user-message)
* `POST`
  [`/user/sign/typedData`](/api-reference/wallets/user-controlled-wallets/sign-user-typed-data)

You can customize various elements of the UIs, which enables your application to
deliver context for on-chain actions.

<Note>
  **NOTE**

  Confirmation UIs are not available for the PIN authentication method. With PIN,
  you can fully customize the transaction and signing details pages while we
  provide a SDK UI for users to enter a PIN for authorization purposes. For more,
  see [Authentication Types](/wallets/user-controlled/authentication-methods).
</Note>

## Predefined confirmation UIs

These confirmation UIs are predefined by Circle. The following example shows the
UI for confirming an outbound transfer on the web app:

<Frame>
  <img />
</Frame>

There are some nuances to consider in regards to the confirmation UI
customization:

* **From** and **To** addresses: Circle masks addresses so that only the first
  and last five digits are displayed. You can pass a string to personalize these
  addresses, such as “John's Solana wallet.”
* **Fiat currency amount**: This field is optional and is only displayed if
  configured. To configure it, you define the exchange rate to calculate the
  fiat currency amount, and then pass the amount to the SDK.
* **Network Fee**: This is an optional field and is only displayed if passed to
  the SDK. You can send a `POST` request to the `/createtransferestimatefee` or
  `/createtransactionestimatefee` endpoints to get the estimate fee and pass the
  fee in the response to the SDK for display. If you offer an SCA wallet with
  paymaster functionalities, you can pass a string, such as “sponsored by
  Circle.”

## Example customizations for confirmation UIs

For detailed instructions on customizing UIs for web, iOS, and Android, see the
following docs:

* [Web SDK UI Customizations API](/wallets/user-controlled/web-sdk-ui-customizations)
* [iOS SDK UI Customization API](/wallets/user-controlled/ios-sdk-ui-customization-api)
* [Android SDK UI Customization API](/wallets/user-controlled/android-sdk-ui-customization-api)

Below are examples of customizations for confirmation UIs for an outbound
transfer, contract execution, and sign message or typed data:

## Outbound Transfer

<Frame>
  <img />
</Frame>

The following table shows which UI elements can be customized based on the
example:

| UI Element               | Example                                                                                                                                            | Customization options                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `x` icon                 | `x` icon in the top-left                                                                                                                           | Icon image                                |
| Title                    | Confirm transaction                                                                                                                                | Text, color, size, font                   |
| Subtitle                 | Please click confirm to proceed with the transaction.                                                                                              | Text, color, size, font                   |
| Token symbol             | USDC token image                                                                                                                                   | Image                                     |
| Token name               | USDC                                                                                                                                               | Text, color, size, font                   |
| Fiat currency and amount | USD 20                                                                                                                                             | Text, color, size, font                   |
| From address             | 0x391…e4r43                                                                                                                                        | Text, color, size, font                   |
| To address               | 0x391...0244i                                                                                                                                      | Text, color, size, font                   |
| Network fee              | 0.0002 ETH                                                                                                                                         | Text, color, size, font                   |
| Network fee hint         | `!` icon <br /> <br />Hover text: Please note this is an estimated fee. Network fees may vary based on network traffic and transaction complexity. | Icon image, hover text, color, size, font |
| Confirmation button      | CONFIRM                                                                                                                                            | Text, color, size, font                   |

## Contract Execution

<Frame>
  <img />
</Frame>

The following table shows which UI elements can be customized based on the
example:

| UI Element               | Example                                                                                                                                            | Customization options                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `x` icon                 | `x` icon in the top-left                                                                                                                           | Icon image, location                      |
| Title                    | Contract interaction                                                                                                                               | Text, color, size, font                   |
| Subtitle                 | Please click confirm to proceed with the contract execution.                                                                                       | Text, color, size, font                   |
| Token symbol             | USDC token image                                                                                                                                   | Image                                     |
| Token name               | USDC                                                                                                                                               | Text, color, size, font                   |
| Fiat currency and amount | USD 20                                                                                                                                             | Text, color, size, font                   |
| From address             | 0x391...e4r43                                                                                                                                      | Text, color, size, font                   |
| Contract address         | Fi0x2...c1380                                                                                                                                      | Text, color, size, font                   |
| Network fee              | 0.0002 ETH                                                                                                                                         | Text, color, size, font                   |
| Network fee hint         | `!` icon <br /> <br />Hover text: Please note this is an estimated fee. Network fees may vary based on network traffic and transaction complexity. | Icon image, hover text, color, size, font |
| Function type            | burn(uint256)                                                                                                                                      | Text, color, size, font                   |
| ABI Parameters           | 10000                                                                                                                                              | Text, color, size, font                   |
| Confirmation button      | CONFIRM                                                                                                                                            | Text, color, size, font                   |

## Sign Message or Typed Data

<Frame>
  <img />
</Frame>

The following table shows which UI elements can be customized based on the
example:

| UI Element          | Example                                                                                                                                                | Customization options   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
| `x` icon            | `x` icon in the top-left                                                                                                                               | Icon image              |
| Title               | Signature Request                                                                                                                                      | Text, color, size, font |
| Contract name       | koalla.org                                                                                                                                             | Text, color, size, font |
| Contract address    | `https://koalla.org`                                                                                                                                   | Text, color, size, font |
| Description         | Click on sign button to provide a signature for verification <br /> <br />You are signing: <br />I own a KOALLA Membership NFT to claim this promotion | Text, color, size, font |
| Confirmation button | SIGN                                                                                                                                                   | Text, color, size, font |

## Sign Transaction

<Frame>
  <img />
</Frame>

## Sign Raw Transaction

<Frame>
  <img />
</Frame>

## Full UI Customization

To use your own UIs, you can opt out of Circle's predefined confirmation UIs.

1. From the Circle Developer Console sidebar, select **Configurator > Wallet
   Security Settings**.
2. Toggle the **Confirmation UIs** setting off to disable confirmation UIs.

<Warning>
  **CAUTION**

  You may want to opt out of Circle's confirmation UIs to further streamline your
  application's user experience. Perhaps signature details are difficult for your
  users to understand or transaction confirmations, which are required for every
  transaction, interrupt your application's flow. This can especially be the case
  for gaming applications.
</Warning>

While you may want to opt out of Circle's confirmation UIs, it is highly
recommended that you enable them to strengthen the security of your application
for your users. If you decide to disable it, it means you can submit
transactions on behalf of your users without their consent; therefore, you must
provide context or disclaimers on your application that your users must
acknowledge.


# Create User Wallets with Email OTP
Source: https://developers.circle.com/wallets/user-controlled/create-user-wallets-with-email



In this quickstart, you build a web app that:

* Authenticates users with a one-time passcode (OTP) sent by email
* Creates a user-owned wallet and connects it to your app
* Displays the wallet address and the USDC balance it holds

## Prerequisites

Before you begin, ensure you have:

* A [Mailtrap](https://mailtrap.io/) account with **Email Sandbox** enabled.
* A [Circle Developer Console](https://console.circle.com/) account.
* A Circle Developer API key:\
  **Console → Keys → Create a key → API key → Standard Key**.
* [Node.js 18+](https://nodejs.org/) installed.

## Step 1. Get Mailtrap SMTP credentials

In this step, you copy SMTP credentials from Mailtrap so Circle can send OTP
codes to users.

1. Log in to your [Mailtrap](https://mailtrap.io/) account.
2. In the left navigation, click **Transactional → Sandboxes**.
3. Open the default sandbox project (**My Sandbox**) or create a new one.
4. In the sandbox view, select the **SMTP Settings** tab.
5. Copy the following SMTP values:

   * **Host**
   * **Port**
   * **Username**
   * **Password**

   You need them for the next step.

## Step 2. Configure the Circle Console

In this step, you add your Mailtrap SMTP credentials to the Circle Console so
Circle can send emails with OTP codes. You also obtain your App ID, which
identifies your user-controlled wallets configuration in the Circle Console.

1. Log in to the [Circle Developer Console](https://console.circle.com/).
2. Navigate to **Wallets → User Controlled → Configurator**.
3. Under **Authentication Methods**, click **Email**.
4. Enter a **From** email address (for example, `no-reply@example.com`).
5. Enter the SMTP values you copied from Mailtrap:
   * **Host**
   * **Port**
   * **Username**
   * **Password**
6. (Optional) Customize your OTP email from, subject, and message body.
7. Go to the **Configurator** page and copy your **App ID**. You need it for the
   next step.

## Step 3. Create the web application

In this step, you create a web app that lets users authenticate with an OTP code
sent to their email address, and create a blockchain wallet.

### 3.1. Create the Next.js project

In your terminal:

```shell theme={null}
npx create-next-app@latest circle-email-otp --yes
cd circle-email-otp
```

### 3.2. Install dependencies

Install the user-controlled wallets Web SDK:

```shell theme={null}
npm install @circle-fin/w3s-pw-web-sdk
```

### 3.3. Add environment variables

Create a `.env.local` file in your project directory:

```shell theme={null}
touch .env.local
```

Open the `.env.local` file and add the following:

```text .env.local theme={null}
CIRCLE_API_KEY=<YOUR_CIRCLE_API_KEY>
NEXT_PUBLIC_CIRCLE_APP_ID=<YOUR_CIRCLE_APP_ID>
```

* `YOUR_CIRCLE_API_KEY` is your Circle Developer API key.
* `YOUR_CIRCLE_APP_ID` is the Circle Wallet App ID obtained in Step 2.

### 3.4. Simplify the default layout

Replace the contents of `app/layout.tsx` with the minimal layout below:

```ts app/layout.tsx twoslash expandable theme={null}
// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

<Info>
  Next.js requires an `app/layout.tsx` file, but the default one created by
  `create-next-app` includes fonts and styling that can cause build errors in
  some environments.
</Info>

### 3.5. Add unified backend route

Create a file named `app/api/endpoints/route.ts` and add the code below:

```ts app/api/endpoints/route.ts twoslash expandable theme={null}
// app/api/endpoints/route.ts
import { NextResponse } from "next/server";

const CIRCLE_BASE_URL =
  process.env.NEXT_PUBLIC_CIRCLE_BASE_URL ?? "https://api.circle.com";
const CIRCLE_API_KEY = process.env.CIRCLE_API_KEY as string;

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const { action, ...params } = body ?? {};

    if (!action) {
      return NextResponse.json({ error: "Missing action" }, { status: 400 });
    }

    switch (action) {
      case "requestEmailOtp": {
        const { deviceId, email } = params;
        if (!deviceId || !email) {
          return NextResponse.json(
            { error: "Missing deviceId or email" },
            { status: 400 },
          );
        }

        const response = await fetch(
          `${CIRCLE_BASE_URL}/v1/w3s/users/email/token`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${CIRCLE_API_KEY}`,
            },
            body: JSON.stringify({
              idempotencyKey: crypto.randomUUID(),
              deviceId,
              email,
            }),
          },
        );

        const data = await response.json();
        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // { deviceToken, deviceEncryptionKey, otpToken }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "initializeUser": {
        const { userToken } = params;
        if (!userToken) {
          return NextResponse.json(
            { error: "Missing userToken" },
            { status: 400 },
          );
        }

        const response = await fetch(
          `${CIRCLE_BASE_URL}/v1/w3s/user/initialize`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${CIRCLE_API_KEY}`,
              "X-User-Token": userToken,
            },
            body: JSON.stringify({
              idempotencyKey: crypto.randomUUID(),
              accountType: "SCA",
              blockchains: ["ARC-TESTNET"],
            }),
          },
        );

        const data = await response.json();

        if (!response.ok) {
          // e.g. 155106 user already initialized
          return NextResponse.json(data, { status: response.status });
        }

        // { challengeId }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "listWallets": {
        const { userToken } = params;
        if (!userToken) {
          return NextResponse.json(
            { error: "Missing userToken" },
            { status: 400 },
          );
        }

        const response = await fetch(`${CIRCLE_BASE_URL}/v1/w3s/wallets`, {
          method: "GET",
          headers: {
            accept: "application/json",
            "content-type": "application/json",
            Authorization: `Bearer ${CIRCLE_API_KEY}`,
            "X-User-Token": userToken,
          },
        });

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // { wallets: [...] }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "getTokenBalance": {
        const { userToken, walletId } = params;
        if (!userToken || !walletId) {
          return NextResponse.json(
            { error: "Missing userToken or walletId" },
            { status: 400 },
          );
        }

        const response = await fetch(
          `${CIRCLE_BASE_URL}/v1/w3s/wallets/${walletId}/balances`,
          {
            method: "GET",
            headers: {
              accept: "application/json",
              Authorization: `Bearer ${CIRCLE_API_KEY}`,
              "X-User-Token": userToken,
            },
          },
        );

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // { tokenBalances: [...] }
        return NextResponse.json(data.data, { status: 200 });
      }

      default:
        return NextResponse.json(
          { error: `Unknown action: ${action}` },
          { status: 400 },
        );
    }
  } catch (error) {
    console.error("Error in /api/endpoints:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 },
    );
  }
}
```

This route serves as a single backend entry point for all Circle API endpoints
used by the app, mapping frontend actions to thin wrapper handlers that call the
corresponding endpoints:

| Handler           | Description                                                                                                                                                                                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestEmailOtp` | calls [POST /v1/w3s/users/email/token](/api-reference/wallets/user-controlled-wallets/create-device-token-email-login) to initiate email authentication and return temporary verification tokens required by the Web SDK to verify the OTP entered by the user. |
| `initializeUser`  | calls [POST /v1/w3s/user/initialize](/api-reference/wallets/user-controlled-wallets/create-user-with-pin-challenge) to create or initialize a user and return a `challengeId` required for wallet creation.                                                     |
| `listWallets`     | calls [GET /v1/w3s/wallets](/api-reference/wallets/user-controlled-wallets/list-wallets) to retrieve the wallets associated with the authenticated user.                                                                                                        |
| `getTokenBalance` | calls [GET /v1/w3s/wallets//balances](/api-reference/wallets/user-controlled-wallets/list-wallet-balance) to retrieve digital asset balances for the specified user-controlled wallet.                                                                          |

<Info>
  This quickstart calls `listWallets` and `getTokenBalance` directly for
  simplicity. In production, apps typically store wallet and balance data in a
  backend database and keep it in sync using Circle webhooks for scalability.
</Info>

To understand how the request fields and response data for these handlers and
their corresponding endpoints are used, follow the app flow in
[Step 4](#step-4-run-the-app-flow) below.

### ​3.6. Add UI and frontend code

Replace the contents of `app/page.tsx` with the code below:

```ts app/page.tsx twoslash expandable theme={null}
// app/page.tsx
"use client";

import { useEffect, useRef, useState } from "react";
import { W3SSdk } from "@circle-fin/w3s-pw-web-sdk";

const appId = process.env.NEXT_PUBLIC_CIRCLE_APP_ID as string;

type LoginResult = {
  userToken: string;
  encryptionKey: string;
};

type Wallet = {
  id: string;
  address: string;
  blockchain: string;
  [key: string]: unknown;
};

export default function HomePage() {
  const sdkRef = useRef<W3SSdk | null>(null);

  const [sdkReady, setSdkReady] = useState(false);
  const [deviceId, setDeviceId] = useState<string>("");
  const [deviceIdLoading, setDeviceIdLoading] = useState(false);

  const [email, setEmail] = useState<string>("");

  const [deviceToken, setDeviceToken] = useState<string>("");
  const [deviceEncryptionKey, setDeviceEncryptionKey] = useState<string>("");
  const [otpToken, setOtpToken] = useState<string>("");

  const [loginResult, setLoginResult] = useState<LoginResult | null>(null);

  const [challengeId, setChallengeId] = useState<string | null>(null);
  const [wallets, setWallets] = useState<Wallet[]>([]);
  const [usdcBalance, setUsdcBalance] = useState<string | null>(null);

  const [status, setStatus] = useState<string>("Ready");
  const [isError, setIsError] = useState<boolean>(false);

  // Initialize SDK on mount
  useEffect(() => {
    let cancelled = false;

    const initSdk = async () => {
      try {
        const onLoginComplete = (error: unknown, result: any) => {
          if (cancelled) return;

          if (error || !result) {
            // Always treat this as a soft failure
            const err = (error || {}) as any;
            const message: string =
              err?.message || "Email authentication failed.";

            console.log("Email auth failed:", {
              code: err?.code,
              message,
            });

            setIsError(true);
            setStatus(message);
            setLoginResult(null);
            return;
          }

          // Success: we get userToken + encryptionKey for challenges
          setLoginResult({
            userToken: result.userToken,
            encryptionKey: result.encryptionKey,
          });
          setIsError(false);
          // Keep this neutral so later wallet-status messages aren't confusing
          setStatus("Email verified. Click Initialize user to continue");
        };

        const sdk = new W3SSdk(
          {
            appSettings: { appId },
          },
          onLoginComplete,
        );

        sdkRef.current = sdk;

        if (!cancelled) {
          setSdkReady(true);
          setIsError(false);
          setStatus("SDK initialized. Ready to request OTP.");
        }
      } catch (err) {
        console.log("Failed to initialize Web SDK:", err);
        if (!cancelled) {
          setIsError(true);
          setStatus("Failed to initialize Web SDK");
        }
      }
    };

    void initSdk();

    return () => {
      cancelled = true;
    };
  }, []);

  // Get / cache deviceId
  useEffect(() => {
    const fetchDeviceId = async () => {
      if (!sdkRef.current) return;

      try {
        const cached =
          typeof window !== "undefined"
            ? window.localStorage.getItem("deviceId")
            : null;

        if (cached) {
          setDeviceId(cached);
          return;
        }

        setDeviceIdLoading(true);
        const id = await sdkRef.current.getDeviceId();
        setDeviceId(id);

        if (typeof window !== "undefined") {
          window.localStorage.setItem("deviceId", id);
        }
      } catch (error) {
        console.log("Failed to get deviceId:", error);
        setIsError(true);
        setStatus("Failed to get deviceId");
      } finally {
        setDeviceIdLoading(false);
      }
    };

    if (sdkReady) {
      void fetchDeviceId();
    }
  }, [sdkReady]);

  // Load USDC balance
  async function loadUsdcBalance(userToken: string, walletId: string) {
    try {
      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "getTokenBalance",
          userToken,
          walletId,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("Failed to load USDC balance:", data);
        setIsError(true);
        setStatus("Failed to load USDC balance");
        return null;
      }

      const balances = (data.tokenBalances as any[]) || [];

      const usdcEntry =
        balances.find((t) => {
          const symbol = t.token?.symbol || "";
          const name = t.token?.name || "";
          return symbol.startsWith("USDC") || name.includes("USDC");
        }) ?? null;

      const amount = usdcEntry?.amount ?? "0";
      setUsdcBalance(amount);
      // Note: loadWallets may overwrite this with a more specific status
      setIsError(false);
      setStatus("Wallet details and USDC balance loaded.");
      return amount;
    } catch (err) {
      console.log("Failed to load USDC balance:", err);
      setIsError(true);
      setStatus("Failed to load USDC balance");
      return null;
    }
  }

  // Load wallets for current user
  const loadWallets = async (
    userToken: string,
    options?: { source?: "afterCreate" | "alreadyInitialized" },
  ) => {
    try {
      setIsError(false);
      setStatus("Loading wallet details...");
      setUsdcBalance(null);

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "listWallets",
          userToken,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("List wallets failed:", data);
        setIsError(true);
        setStatus("Failed to load wallet details");
        return;
      }

      const wallets = (data.wallets as Wallet[]) || [];
      setWallets(wallets);

      if (wallets.length > 0) {
        await loadUsdcBalance(userToken, wallets[0].id);

        if (options?.source === "afterCreate") {
          setIsError(false);
          setStatus(
            "Wallet created successfully! 🎉 Wallet details and USDC balance loaded.",
          );
        } else if (options?.source === "alreadyInitialized") {
          setIsError(false);
          setStatus(
            "User already initialized. Wallet details and USDC balance loaded.",
          );
        }
      } else {
        setIsError(false);
        setStatus("Wallet creation in progress. Click Initialize user again to refresh.");
      }
    } catch (err) {
      console.log("Failed to load wallet details:", err);
      setIsError(true);
      setStatus("Failed to load wallet details");
    }
  };

  const handleRequestOtp = async () => {
    if (!email) {
      setIsError(true);
      setStatus("Please enter an email address.");
      return;
    }

    if (!deviceId) {
      setIsError(true);
      setStatus("Missing deviceId. Try again.");
      return;
    }

    // Reset auth + wallet state
    setLoginResult(null);
    setChallengeId(null);
    setWallets([]);
    setUsdcBalance(null);

    try {
      setIsError(false);
      setStatus("Requesting OTP...");

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "requestEmailOtp",
          deviceId,
          email,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("Failed to request OTP:", data);
        setIsError(true);
        setStatus(data.error || data.message || "Failed to request OTP");
        return;
      }

      setDeviceToken(data.deviceToken);
      setDeviceEncryptionKey(data.deviceEncryptionKey);
      setOtpToken(data.otpToken);

      // Give the SDK the session info so verifyOtp() works
      const sdk = sdkRef.current;
      if (sdk) {
        sdk.updateConfigs({
          appSettings: { appId },
          loginConfigs: {
            deviceToken: data.deviceToken,
            deviceEncryptionKey: data.deviceEncryptionKey,
            otpToken: data.otpToken,
            email: { email },
          },
        });
      }

      setIsError(false);
      setStatus(
        "OTP sent! Check your Mailtrap sandbox inbox, then click Verify email OTP.",
      );
    } catch (err) {
      console.log("Error requesting OTP:", err);
      setIsError(true);
      setStatus("Failed to request OTP");
    }
  };

  const handleVerifyOtp = () => {
    const sdk = sdkRef.current;
    if (!sdk) {
      setIsError(true);
      setStatus("SDK not ready");
      return;
    }

    if (!deviceToken || !deviceEncryptionKey || !otpToken) {
      setIsError(true);
      setStatus("Missing OTP session data. Request a new code.");
      return;
    }

    setIsError(false);
    setStatus("Opening OTP verification window...");

    // Opens Circle's hosted OTP UI; on completion, onLoginComplete fires
    sdk.verifyOtp();
  };

  const handleInitializeUser = async () => {
    if (!loginResult?.userToken) {
      setIsError(true);
      setStatus("Missing userToken. Please verify your email first.");
      return;
    }

    try {
      setIsError(false);
      setStatus("Initializing user...");

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "initializeUser",
          userToken: loginResult.userToken,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        if (data.code === 155106) {
          await loadWallets(loginResult.userToken, {
            source: "alreadyInitialized",
          });
          setChallengeId(null);
          return;
        }

        const errorMsg = data.code
          ? `[${data.code}] ${data.error || data.message}`
          : data.error || data.message;
        setIsError(true);
        setStatus("Failed to initialize user: " + errorMsg);
        return;
      }

      setChallengeId(data.challengeId);
      setIsError(false);
      setStatus(`User initialized. Click Create wallet to continue.`);
    } catch (err: any) {
      if (err?.code === 155106 && loginResult?.userToken) {
        await loadWallets(loginResult.userToken, {
          source: "alreadyInitialized",
        });
        setChallengeId(null);
        return;
      }

      const errorMsg = err?.code
        ? `[${err.code}] ${err.message}`
        : err?.message || "Unknown error";
      setIsError(true);
      setStatus("Failed to initialize user: " + errorMsg);
    }
  };

  const handleExecuteChallenge = () => {
    const sdk = sdkRef.current;
    if (!sdk) {
      setIsError(true);
      setStatus("SDK not ready");
      return;
    }

    if (!challengeId) {
      setIsError(true);
      setStatus("Missing challengeId. Initialize user first.");
      return;
    }

    if (!loginResult?.userToken || !loginResult?.encryptionKey) {
      setIsError(true);
      setStatus("Missing login credentials. Please verify your email again.");
      return;
    }

    sdk.setAuthentication({
      userToken: loginResult.userToken,
      encryptionKey: loginResult.encryptionKey,
    });

    setIsError(false);
    setStatus("Executing challenge...");

    sdk.execute(challengeId, (error) => {
      const err = (error || {}) as any;

      if (error) {
        console.log("Execute challenge failed:", err);
        setIsError(true);
        setStatus("Failed to execute challenge: " + (err?.message ?? "Unknown error"));
        return;
      }

      setIsError(false);
      setStatus("Challenge executed. Loading wallet details...");

      void (async () => {
        // small delay to give Circle time to index the wallet
        await new Promise((resolve) => setTimeout(resolve, 2000));

        setChallengeId(null);
        await loadWallets(loginResult.userToken, { source: "afterCreate" });
      })().catch((e) => {
        console.log("Post-execute loadWallets failed:", e);
        setIsError(true);
        setStatus("Wallet created, but failed to load wallet details.");
      });
    });
  };

  const primaryWallet = wallets[0];

  return (
    <main>
      <div style={{ width: "50%", margin: "0 auto" }}>
        <h1>Create a user wallet with email OTP</h1>
        <p>Enter the email of the user you want to create a wallet for:</p>

        <div style={{ marginBottom: "12px" }}>
          <label>
            Email address:
            <input
              type="email"
              value={email}
              onChange={(e) => setEmail(e.target.value)}
              style={{ marginLeft: "8px", width: "70%" }}
              placeholder="you@example.com"
            />
          </label>
        </div>

        <div>
          <button
            onClick={handleRequestOtp}
            style={{ margin: "6px" }}
            disabled={!sdkReady || !deviceId || deviceIdLoading || !email}
          >
            1. Send email OTP
          </button>
          <br />
          <button
            onClick={handleVerifyOtp}
            style={{ margin: "6px" }}
            disabled={
              !sdkReady || !deviceToken || !deviceEncryptionKey || !otpToken || !!loginResult
            }
          >
            2. Verify email OTP
          </button>
          <br />
          <button
            onClick={handleInitializeUser}
            style={{ margin: "6px" }}
            disabled={!loginResult || !!challengeId || wallets.length > 0}
          >
            3. Initialize user (get challenge)
          </button>
          <br />
          <button
            onClick={handleExecuteChallenge}
            style={{ margin: "6px" }}
            disabled={!challengeId || wallets.length > 0}
          >
            4. Create wallet (execute challenge)
          </button>
        </div>

        <p>
          <strong>Status:</strong>{" "}
          <span style={{ color: isError ? "red" : "black" }}>{status}</span>
        </p>

        {primaryWallet && (
          <div style={{ marginTop: "12px" }}>
            <h2>Wallet details</h2>
            <p>
              <strong>Address:</strong> {primaryWallet.address}
            </p>
            <p>
              <strong>Blockchain:</strong> {primaryWallet.blockchain}
            </p>
            {usdcBalance !== null && (
              <p>
                <strong>USDC balance:</strong> {usdcBalance}
              </p>
            )}
          </div>
        )}

        <pre
          style={{
            whiteSpace: "pre-wrap",
            wordBreak: "break-all",
            lineHeight: "1.8",
            marginTop: "16px",
          }}
        >
          {JSON.stringify(
            {
              deviceId,
              email,
              deviceToken,
              deviceEncryptionKey,
              otpToken,
              userToken: loginResult?.userToken,
              encryptionKey: loginResult?.encryptionKey,
              challengeId,
              wallets,
              usdcBalance,
            },
            null,
            2,
          )}
        </pre>
      </div>
    </main>
  );
}
```

This page renders the UI and implements all browser-side logic for the email-OTP
authentication and wallet creation flow. It initializes the Web SDK, sends and
verifies OTP codes, manages short-lived state during the login process, and
coordinates the sequence of actions required to create and display the user's
wallet.

## Step 4. Run the app flow

1. Start the dev server:

```shell theme={null}
npm run dev
```

2. Open [http://localhost:3000](http://localhost:3000) in your browser to view the app.

3) Complete the email OTP authentication and wallet creation flow:
   1. Enter an **email address**: Choose an email address for the user who will
      authenticate. This email address is used only to receive a one-time
      passcode (OTP) during sign-in.

   2. Click **Send email OTP**: The Web SDK generates a unique `deviceId`, which
      identifies the user's browser. Your backend sends the `deviceId` and email
      address to Circle, which emails an OTP code and returns temporary
      verification tokens (`deviceToken`, `deviceEncryptionKey`, `otpToken`)
      used by the Web SDK to verify the OTP.

   3. Open your **Mailtrap Sandbox → Inbox** to view the OTP email sent by
      Circle. When using a Mailtrap Email Sandbox, OTP emails are received in
      the Mailtrap UI by default and are not delivered to the user's inbox,
      unless email forwarding is configured.

      <Info>
        In a production app, you should configure your SMTP provider to deliver
        OTP codes directly to users' email inboxes.
      </Info>

   4. Click **Verify email OTP**: Circle opens a hosted OTP verification window.
      The user enters the code they received. The Web SDK verifies the OTP with
      Circle, which then returns a `userToken` and `encryptionKey`. Together,
      they enable an authenticated Circle user session.

   5. Click **Initialize user**: Your backend initializes the user using the
      `userToken`. If the user hasn't created a wallet yet, Circle returns a
      `challengeId` to create one. If the user is already initialized, the app
      loads the existing wallet instead.

   6. Click **Create wallet**: The Web SDK executes the challenge using the
      `challengeId`. The user approves the action, and Circle creates the
      wallet.

4) Once the flow completes:
   * The app displays the wallet's address, blockchain, and USDC balance.
   * You can verify the user was created in the
     [Circle Dev Console](https://console.circle.com/):\
     **Wallets → User Controlled → Users**.

## Step 5. Fund the wallet

In this step, you fund the new wallet manually using the Circle Faucet and
confirm the updated balance in the app.

1. Copy the wallet address (`0x...`) from the web app UI.
2. Visit the official [Circle Faucet](https://faucet.circle.com/).
3. Select **Arc Testnet** as the blockchain network.
4. Paste the wallet address in the **Send to** field.
5. Click **Send USDC**.
6. Return to the app and walk through the flow again.\
   **Note:** Use the same email address to show the same wallet.
7. The app will display the updated USDC balance.

<Note>
  In this step, you're acting as the end user to fund your user-controlled
  wallet for testing. In production, app developers don't control user wallets
  or private keys. Instead, users typically fund wallets themselves, but apps
  may also fund using faucets or airdrops without requiring wallet access.
</Note>


# Create User Wallets with PIN
Source: https://developers.circle.com/wallets/user-controlled/create-user-wallets-with-pin



In this quickstart, you build a web app that:

* Lets users create or access a user-owned wallet using an app-defined user
  identifier
* Prompts users to set or confirm a PIN to authorize sensitive wallet actions
* Displays the user's wallet address and the USDC balance it holds

## Prerequisites

Before you begin, ensure you have:

* A [Circle Developer Console](https://console.circle.com/) account.
* A Circle Developer API key:\
  **Console → Keys → Create a key → API key → Standard Key**.
* [Node.js 18+](https://nodejs.org/) installed.

## Step 1. Get your Circle App ID

In this step, you obtain the App ID that identifies your user-controlled wallet
configuration in the Circle Developer Console, so it can manage the User IDs
created by your app.

1. Log in to the [Circle Developer Console](https://console.circle.com/).
2. Go to **Wallets → User Controlled → Configurator**, and copy your **App ID**.
   You need it for the next step.

<Tip>
  If you know your Circle API key, you can get your App ID directly from the command-line by querying the [Get configuration for entity](/api-reference/wallets/programmable-wallets/get-entity-config) endpoint:

  ```shell theme={null}
  curl -s https://api.circle.com/v1/w3s/config/entity \
    -H "Authorization: Bearer <YOUR_CIRCLE_API_KEY>" \
    -H "Accept: application/json"
  ```
</Tip>

## Step 2. Create the web application

In this step, you create a Next.js app that lets users set an authorization PIN
and use it to create a user-controlled wallet.

### 2.1. Create the Next.js project

In your terminal:

```shell theme={null}
npx create-next-app@latest circle-pin --yes
cd circle-pin
```

### 2.2. Install dependencies

Install the user-controlled wallets Web SDK:

```shell theme={null}
npm install @circle-fin/w3s-pw-web-sdk
```

### 2.3. Add environment variables

Create a `.env.local` file in your project directory:

```shell theme={null}
touch .env.local
```

Open the `.env.local` file and add the following:

```text .env.local theme={null}
CIRCLE_API_KEY=<YOUR_CIRCLE_API_KEY>
NEXT_PUBLIC_CIRCLE_APP_ID=<YOUR_CIRCLE_APP_ID>
```

* `YOUR_CIRCLE_API_KEY` is your Circle Developer API key.
* `YOUR_CIRCLE_APP_ID` is the Circle Wallet App ID obtained in Step 1.

### 2.4. Simplify the default layout

Replace the contents of `app/layout.tsx` with the minimal layout below:

```ts app/layout.tsx twoslash expandable theme={null}
// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

<Info>
  Next.js requires an `app/layout.tsx` file, but the default one created by
  `create-next-app` includes fonts and styling that can cause build errors in
  some environments.
</Info>

### 2.5. Add unified backend route

Create a file named `app/api/endpoints/route.ts` and add the code below:

```ts app/api/endpoints/route.ts twoslash expandable theme={null}
// app/api/endpoints/route.ts
import { NextResponse } from "next/server";

const CIRCLE_BASE_URL =
  process.env.NEXT_PUBLIC_CIRCLE_BASE_URL ?? "https://api.circle.com";
const CIRCLE_API_KEY = process.env.CIRCLE_API_KEY as string;

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const { action, ...params } = body ?? {};

    if (!action) {
      return NextResponse.json({ error: "Missing action" }, { status: 400 });
    }

    switch (action) {
      case "createUser": {
        const { userId } = params;

        if (!userId) {
          return NextResponse.json(
            { error: "Missing required field: userId" },
            { status: 400 },
          );
        }

        const response = await fetch(`${CIRCLE_BASE_URL}/v1/w3s/users`, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${CIRCLE_API_KEY}`,
          },
          body: JSON.stringify({
            userId,
          }),
        });

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // Returns: { id, createDate, pinStatus, status, ... }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "getUserToken": {
        const { userId } = params;

        if (!userId) {
          return NextResponse.json(
            { error: "Missing required field: userId" },
            { status: 400 },
          );
        }

        const response = await fetch(`${CIRCLE_BASE_URL}/v1/w3s/users/token`, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${CIRCLE_API_KEY}`,
          },
          body: JSON.stringify({
            userId,
          }),
        });

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // Returns: { userToken, encryptionKey }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "initializeUser": {
        const { userToken, accountType, blockchains } = params;
        if (!userToken) {
          return NextResponse.json(
            { error: "Missing userToken" },
            { status: 400 },
          );
        }

        // Build request body
        const requestBody: any = {
          idempotencyKey: crypto.randomUUID(),
        };

        // Add optional parameters with defaults
        if (accountType) requestBody.accountType = accountType;
        if (blockchains) requestBody.blockchains = blockchains;

        const response = await fetch(
          `${CIRCLE_BASE_URL}/v1/w3s/user/initialize`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${CIRCLE_API_KEY}`,
              "X-User-Token": userToken,
            },
            body: JSON.stringify(requestBody),
          },
        );

        const data = await response.json();

        if (!response.ok) {
          // Pass through Circle error payload (e.g. code 155106: user already initialized)
          return NextResponse.json(data, { status: response.status });
        }

        // Returns: { challengeId }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "listWallets": {
        const { userToken } = params;
        if (!userToken) {
          return NextResponse.json(
            { error: "Missing userToken" },
            { status: 400 },
          );
        }

        const response = await fetch(`${CIRCLE_BASE_URL}/v1/w3s/wallets`, {
          method: "GET",
          headers: {
            accept: "application/json",
            "content-type": "application/json",
            Authorization: `Bearer ${CIRCLE_API_KEY}`,
            "X-User-Token": userToken,
          },
        });

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // { wallets: [...] }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "getTokenBalance": {
        const { userToken, walletId } = params;
        if (!userToken || !walletId) {
          return NextResponse.json(
            { error: "Missing userToken or walletId" },
            { status: 400 },
          );
        }

        const response = await fetch(
          `${CIRCLE_BASE_URL}/v1/w3s/wallets/${walletId}/balances`,
          {
            method: "GET",
            headers: {
              accept: "application/json",
              Authorization: `Bearer ${CIRCLE_API_KEY}`,
              "X-User-Token": userToken,
            },
          },
        );

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // { tokenBalances: [...] }
        return NextResponse.json(data.data, { status: 200 });
      }

      default:
        return NextResponse.json(
          { error: `Unknown action: ${action}` },
          { status: 400 },
        );
    }
  } catch (error) {
    console.error("Error in /api/endpoints:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 },
    );
  }
}
```

This route serves as a single backend entry point for all Circle API endpoints
used by the app, mapping frontend actions to thin wrapper handlers that call the
corresponding endpoints:

| Handler           | Description                                                                                                                                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createUser`      | calls [POST /v1/w3s/users](/api-reference/wallets/user-controlled-wallets/create-user) to create (or retrieve) a Circle user using an application-defined `userId`.                                                                         |
| `getUserToken`    | calls [POST /v1/w3s/users/token](/api-reference/wallets/user-controlled-wallets/get-user-token) to create a short-lived user session, returning a `userToken` and `encryptionKey` required by the Web SDK to run PIN and wallet challenges. |
| `initializeUser`  | calls [POST /v1/w3s/user/initialize](/api-reference/wallets/user-controlled-wallets/create-user-with-pin-challenge) to initialize the user and return a `challengeId` required for wallet creation.                                         |
| `listWallets`     | calls [GET /v1/w3s/wallets](/api-reference/wallets/user-controlled-wallets/list-wallets) to retrieve the wallets associated with the user.                                                                                                  |
| `getTokenBalance` | calls [GET /v1/w3s/wallets//balances](/api-reference/wallets/user-controlled-wallets/list-wallet-balance) to retrieve digital asset balances for a specified user-controlled wallet.                                                        |

<Info>
  This quickstart calls `listWallets` and `getTokenBalance` directly for
  simplicity. In production, apps typically store wallet and balance data in a
  backend database and keep it in sync using Circle webhooks for scalability.
</Info>

To understand how the request fields and response data for these handlers and
their corresponding endpoints are used, follow the app flow in
[Step 3](#step-3-run-the-app-flow) below.

### ​2.6. Add UI and frontend code

Replace the contents of `app/page.tsx` with the code below:

```ts app/page.tsx twoslash expandable theme={null}
// app/page.tsx
"use client";

import { useEffect, useRef, useState } from "react";
import { W3SSdk } from "@circle-fin/w3s-pw-web-sdk";

const appId = process.env.NEXT_PUBLIC_CIRCLE_APP_ID as string;
const ACCOUNT_TYPE = "SCA";
const PRIMARY_WALLET_BLOCKCHAIN = "ARC-TESTNET";

type LoginResult = {
  userToken: string;
  encryptionKey: string;
};

type Wallet = {
  id: string;
  address: string;
  blockchain: string;
  [key: string]: unknown;
};

export default function HomePage() {
  const sdkRef = useRef<W3SSdk | null>(null);

  const [sdkReady, setSdkReady] = useState(false);
  const [deviceId, setDeviceId] = useState<string>("");

  const [userId, setUserId] = useState<string>("");

  const [loginResult, setLoginResult] = useState<LoginResult | null>(null);

  const [challengeId, setChallengeId] = useState<string | null>(null);
  const [wallets, setWallets] = useState<Wallet[]>([]);
  const [usdcBalance, setUsdcBalance] = useState<string | null>(null);

  const [status, setStatus] = useState<string>("Ready");
  const [isError, setIsError] = useState<boolean>(false);

  // Initialize SDK on mount
  useEffect(() => {
    let cancelled = false;

    const initSdk = async () => {
      try {
        const sdk = new W3SSdk({
          appSettings: { appId },
        });

        sdkRef.current = sdk;

        if (!cancelled) {
          setSdkReady(true);
          setIsError(false);
          setStatus("SDK initialized. Ready to create user.");
        }
      } catch (err) {
        console.log("Failed to initialize Web SDK:", err);
        if (!cancelled) {
          setIsError(true);
          setStatus("Failed to initialize Web SDK");
        }
      }
    };

    void initSdk();

    return () => {
      cancelled = true;
    };
  }, []);

  // Get / cache deviceId
  useEffect(() => {
    const fetchDeviceId = async () => {
      if (!sdkRef.current) return;

      try {
        const cached =
          typeof window !== "undefined"
            ? window.localStorage.getItem("deviceId")
            : null;

        if (cached) {
          setDeviceId(cached);
          return;
        }

        const id = await sdkRef.current.getDeviceId();
        setDeviceId(id);

        if (typeof window !== "undefined") {
          window.localStorage.setItem("deviceId", id);
        }
      } catch (error) {
        console.log("Failed to get deviceId:", error);
        setIsError(true);
        setStatus("Failed to get deviceId");
      }
    };

    if (sdkReady) {
      void fetchDeviceId();
    }
  }, [sdkReady]);

  // Load USDC balance
  async function loadUsdcBalance(userToken: string, walletId: string) {
    try {
      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "getTokenBalance",
          userToken,
          walletId,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("Failed to load USDC balance:", data);
        setIsError(true);
        setStatus("Failed to load USDC balance");
        return null;
      }

      const balances = (data.tokenBalances as any[]) || [];

      const usdcEntry =
        balances.find((t) => {
          const symbol = t.token?.symbol || "";
          const name = t.token?.name || "";
          return symbol.startsWith("USDC") || name.includes("USDC");
        }) ?? null;

      const amount = usdcEntry?.amount ?? "0";
      setUsdcBalance(amount);
      // Note: loadWallets may overwrite this with a more specific status
      setIsError(false);
      setStatus("Wallet details and USDC balance loaded.");
      return amount;
    } catch (err) {
      console.log("Failed to load USDC balance:", err);
      setIsError(true);
      setStatus("Failed to load USDC balance");
      return null;
    }
  }

  // Load wallets for current user
  const loadWallets = async (
    userToken: string,
    options?: { source?: "afterCreate" | "alreadyInitialized" },
  ) => {
    try {
      setIsError(false);
      setStatus("Loading wallet details...");
      setUsdcBalance(null);

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "listWallets",
          userToken,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("List wallets failed:", data);
        setIsError(true);
        setStatus("Failed to load wallet details");
        return;
      }

      const wallets = (data.wallets as Wallet[]) || [];
      setWallets(wallets);

      if (wallets.length > 0) {
        await loadUsdcBalance(userToken, wallets[0].id);

        if (options?.source === "afterCreate") {
          setIsError(false);
          setStatus(
            "Wallet created successfully! 🎉 Wallet details and USDC balance loaded.",
          );
        } else if (options?.source === "alreadyInitialized") {
          setIsError(false);
          setStatus(
            "User already initialized. Wallet details and USDC balance loaded.",
          );
        }
      } else {
        setIsError(false);
        setStatus("Wallet creation in progress. Click Initialize user again to refresh.");
      }
    } catch (err) {
      console.log("Failed to load wallet details:", err);
      setIsError(true);
      setStatus("Failed to load wallet details");
    }
  };

  const handleCreateUser = async () => {
    if (!userId) {
      setIsError(true);
      setStatus("Please enter a user ID.");
      return;
    }

    if (userId.length < 5) {
      setIsError(true);
      setStatus("User ID must be at least 5 characters.");
      return;
    }

    // Reset auth + wallet state
    setLoginResult(null);
    setChallengeId(null);
    setWallets([]);
    setUsdcBalance(null);

    try {
      setIsError(false);
      setStatus("Creating user...");

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "createUser",
          userId,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("Failed to create user:", data);
        setIsError(data.code === 155106);
        setStatus(data.error || data.message || "Failed to create user");
        return;
      }

      setIsError(false);
      setStatus("User created successfully! Click Get User Token to continue.");
    } catch (err) {
      console.log("Error creating user:", err);
      setIsError(true);
      setStatus("Failed to create user");
    }
  };

  const handleGetUserToken = async () => {
    if (!userId) {
      setIsError(true);
      setStatus("Please enter a user ID.");
      return;
    }

    if (userId.length < 5) {
      setIsError(true);
      setStatus("User ID must be at least 5 characters.");
      return;
    }

    try {
      setIsError(false);
      setStatus("Getting user token...");

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "getUserToken",
          userId,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("Failed to get user token:", data);
        setIsError(true);
        setStatus(data.error || data.message || "Failed to get user token");
        return;
      }

      // Set loginResult with userToken and encryptionKey from response
      setLoginResult({
        userToken: data.userToken,
        encryptionKey: data.encryptionKey,
      });

      setIsError(false);
      setStatus("User token retrieved successfully! Click Initialize user to continue.");
    } catch (err) {
      console.log("Error getting user token:", err);
      setIsError(true);
      setStatus("Failed to get user token");
    }
  };

  const handleInitializeUser = async () => {
    if (!loginResult?.userToken) {
      setIsError(true);
      setStatus("Missing userToken. Please get user token first.");
      return;
    }

    try {
      setIsError(false);
      setStatus("Initializing user...");

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "initializeUser",
          userToken: loginResult.userToken,
          accountType: ACCOUNT_TYPE,
          blockchains: [PRIMARY_WALLET_BLOCKCHAIN],
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        if (data.code === 155106) {
          await loadWallets(loginResult.userToken, {
            source: "alreadyInitialized",
          });
          setChallengeId(null);
          return;
        }

        const errorMsg = data.code
          ? `[${data.code}] ${data.error || data.message}`
          : data.error || data.message;
        setIsError(true);
        setStatus("Failed to initialize user: " + errorMsg);
        return;
      }

      setChallengeId(data.challengeId);
      setIsError(false);
      setStatus(`User initialized. Click Create wallet to continue.`);
    } catch (err: any) {
      if (err?.code === 155106 && loginResult?.userToken) {
        await loadWallets(loginResult.userToken, {
          source: "alreadyInitialized",
        });
        setChallengeId(null);
        return;
      }

      const errorMsg = err?.code
        ? `[${err.code}] ${err.message}`
        : err?.message || "Unknown error";
      setIsError(true);
      setStatus("Failed to initialize user: " + errorMsg);
    }
  };

  const handleExecuteChallenge = async () => {
    const sdk = sdkRef.current;
    if (!sdk) {
      setIsError(true);
      setStatus("SDK not ready");
      return;
    }

    if (!challengeId) {
      setIsError(true);
      setStatus("Missing challengeId. Initialize user first.");
      return;
    }

    if (!loginResult?.userToken || !loginResult?.encryptionKey) {
      setIsError(true);
      setStatus("Missing login credentials. Please get user token again.");
      return;
    }

    try {
      sdk.setAuthentication({
        userToken: loginResult.userToken,
        encryptionKey: loginResult.encryptionKey,
      });

      setIsError(false);
      setStatus("Executing challenge...");

      await sdk.execute(challengeId, (error, result) => {
        if (error) {
          console.log("Execute challenge failed:", error);
          setIsError(true);
          setStatus(
            "Failed to execute challenge: " +
              ((error as any)?.message ?? "Unknown error"),
          );
          return;
        }

        console.log("Challenge executed successfully:", result);
        setChallengeId(null);

        // Small delay to give Circle time to index the wallet
        setTimeout(async () => {
          if (loginResult?.userToken) {
            await loadWallets(loginResult.userToken, { source: "afterCreate" });
          }
        }, 2000);
      });
    } catch (err) {
      console.log("Execute challenge error:", err);
      setIsError(true);
      setStatus(
        "Failed to execute challenge: " +
          ((err as any)?.message ?? "Unknown error"),
      );
    }
  };

  const primaryWallet = wallets[0];

  return (
    <main>
      <div style={{ width: "50%", margin: "0 auto" }}>
        <h1>Create a user wallet using PIN</h1>
        <p>Enter the username or email of the user you want to create a wallet for:</p>

        <div style={{ marginBottom: "12px" }}>
          <label>
            User ID:
            <input
              type="text"
              value={userId}
              onChange={(e) => setUserId(e.target.value)}
              style={{ marginLeft: "8px", width: "70%" }}
              placeholder="Enter user ID (min 5 chars)"
              minLength={5}
            />
          </label>
        </div>

        <div>
          <button
            onClick={handleCreateUser}
            style={{ margin: "6px" }}
            disabled={!userId || userId.length < 5}
          >
            1. Create User
          </button>
          <br />
          <button
            onClick={handleGetUserToken}
            style={{ margin: "6px" }}
            disabled={!userId || userId.length < 5 || !!loginResult}
          >
            2. Get User Token
          </button>
          <br />
          <button
            onClick={handleInitializeUser}
            style={{ margin: "6px" }}
            disabled={!loginResult || !!challengeId || wallets.length > 0}
          >
            3. Initialize user (get challenge)
          </button>
          <br />
          <button
            onClick={handleExecuteChallenge}
            style={{ margin: "6px" }}
            disabled={!challengeId || wallets.length > 0}
          >
            4. Create wallet (execute challenge)
          </button>
        </div>

        <p>
          <strong>Status:</strong>{" "}
          <span style={{ color: isError ? "red" : "black" }}>{status}</span>
        </p>

        {primaryWallet && (
          <div style={{ marginTop: "12px" }}>
            <h2>Wallet details</h2>
            <p>
              <strong>Address:</strong> {primaryWallet.address}
            </p>
            <p>
              <strong>Blockchain:</strong> {primaryWallet.blockchain}
            </p>
            {usdcBalance !== null && (
              <p>
                <strong>USDC balance:</strong> {usdcBalance}
              </p>
            )}
          </div>
        )}

        <pre
          style={{
            whiteSpace: "pre-wrap",
            wordBreak: "break-all",
            lineHeight: "1.8",
            marginTop: "16px",
          }}
        >
          {JSON.stringify(
            {
              deviceId,
              userId,
              userToken: loginResult?.userToken,
              encryptionKey: loginResult?.encryptionKey,
              challengeId,
              wallets,
              usdcBalance,
            },
            null,
            2,
          )}
        </pre>
      </div>
    </main>
  );
}
```

This page handles the full client-side logic for the PIN-based wallet creation
flow. It initializes the Web SDK, creates a new user with a `userId`, retrieves
a `userToken`, and initializes the user's wallet on a specified blockchain. The
returned `challengeId` is executed using the SDK, prompting the user to
authorize the action with a PIN. After wallet creation, the app loads the wallet
details and USDC balance.

## Step 3. Run the app flow

1. Start the dev server:

```shell theme={null}
npm run dev
```

2. Open [http://localhost:3000](http://localhost:3000) in your browser to view the app.

3) Complete the PIN setup and wallet creation flow:
   1. Enter a **User ID**: Provide a unique identifier for the user (for
      example, a username or email address). In this PIN-only flow, the app
      receives the identifier directly from the user but doesn't perform
      authentication to verify ownership.

      <Note>
        A PIN by itself does not verify user identity. This quickstart focuses on
        PIN-based authorization only. In production, apps should authenticate
        users first (for example, with social login or email OTP) to establish a
        Circle-authenticated user session. PINs can then serve as a layer to
        authorize sensitive wallet actions.
      </Note>

   2. Click **Create User**: Your backend creates a Circle user record from the
      provided `userId`. Circle associates it with your Console account and
      user-controlled wallet configuration based on your API key.

   3. Click **Get User Token**: Your backend requests a short-lived `userToken`
      and `encryptionKey`. The Web SDK uses these credentials to authenticate
      the user session with Circle and submit subsequent user-scoped challenges.

   4. Click **Initialize user (get challenge)**: Your backend initializes the
      user using the `userToken`. If the user hasn't created a wallet yet,
      Circle returns a `challengeId` required to create one. If the user is
      already initialized, the app loads the existing wallet instead.

   5. Click **Create wallet (execute challenge)**: The Web SDK executes the
      challenge using the `challengeId`. Because wallet creation is a sensitive
      action, Circle opens a hosted UI where the user sets their authorization
      PIN and security questions. After the user approves the request, Circle
      creates the wallet.

4) Once the flow completes:
   * The app displays the wallet's address, blockchain, and USDC balance.
   * You can verify the user was created in the
     [Circle Dev Console](https://console.circle.com/):\
     **Wallets → User Controlled → Users**.

## Step 4. Fund the wallet

In this step, you fund the new wallet manually using the Circle Faucet and
confirm the updated balance in the app.

1. Copy the wallet address (`0x...`) from the web app UI.
2. Visit the official [Circle Faucet](https://faucet.circle.com/).
3. Select **Arc Testnet** as the blockchain network.
4. Paste the wallet address in the **Send to** field.
5. Click **Send USDC**.
6. Return to the app and walk through the flow again.\
   **Note:** Use the same email address to show the same wallet.
7. The app will display the updated USDC balance.

<Note>
  In this step, you're acting as the end user to fund your user-controlled
  wallet for testing. In production, app developers don't control user wallets
  or private keys. Instead, users typically fund wallets themselves, but apps
  may also fund using faucets or airdrops without requiring wallet access.
</Note>


# Create User Wallets with Social Login
Source: https://developers.circle.com/wallets/user-controlled/create-user-wallets-with-social-login



In this quickstart, you build a web app that:

* Lets users authenticate to your app using their Google account.
* Creates a user-owned wallet and connects it to your app.
* Displays the wallet address and the USDC balance it holds.

## Prerequisites

Before you begin, ensure you have:

* A [Circle Developer Console](https://console.circle.com/) account.
* A Circle Developer API key:\
  **Console → Keys → Create a key → API key → Standard Key**.
* A Google account to access the
  [Google Cloud Console](https://console.cloud.google.com/).
* [Node.js 18+](https://nodejs.org/) installed.

## Step 1. Configure the Google Console

In this step, you will set up Google OAuth so users can sign in to your app
using their Google account.

1. Log in to the [Google Cloud Console](https://console.cloud.google.com/)

2. Click **Select a project → New Project**, enter a name (for example, "Social
   Login Test"), and click **Create**.

3. Search for **Auth** in the **Google Cloud Search Bar**.

4. Select **Google Auth Platform**, click **Get started**, and enter:

   * `App name`: for example, "Social Login App"
   * `User support email`: select your email
   * `Audience`: select **External**
   * `Contact email addresses`: type your email again

   Click **Create** after agreeing to the policies.

5. Select **Create OAuth client**, and enter:

   * `Application type`: select **Web application**
   * `Client name`: for example, "Web client 1"
   * `Authorized redirect URIs`: type `http://localhost:3000`

   <Info>
     Users will be redirected to this URL after they log in with their Google
     account.
   </Info>

   Click **Create** to complete the Google OAuth setup.

6. Copy the Google OAuth **Client ID**, which identifies your app with Google's
   OAuth service. You need it for the next two steps.

<Note>
  **Important:** The above Google OAuth setup only allows your account to login
  with Google. If you want other users to authenticate: Select **Audience** from
  your **Google Auth Platform** menu, and click **Publish app**, or add more
  test users individually.
</Note>

## Step 2. Configure the Circle Console

In this step, you connect your Google OAuth client to your Circle Wallets
configuration so users can sign in through your app. You also obtain your App
ID, which identifies your user-controlled wallets configuration in the Circle
Console.

1. Log in to the [Circle Developer Console](https://console.circle.com/).
2. Navigate to **Wallets → User Controlled → Configurator**.
3. Click on **Authentication Methods → Social Logins**, select **Google**.\
   Paste your Google OAuth **Client ID** (from Step 1) into the **Client ID
   (Web)** field.
4. Go to the **Configurator** page and copy your **App ID**. You need it for the
   next step.

## Step 3. Create the web application

In this step, you will create a web app that lets users authenticate using
Google OAuth, and create a blockchain wallet.

### 3.1. Create the Next.js project

In your terminal:

```shell theme={null}
npx create-next-app@latest circle-social-login --yes
cd circle-social-login
```

### 3.2. Install dependencies

Install the user-controlled wallets Web SDK and supporting packages:

```shell theme={null}
npm install @circle-fin/w3s-pw-web-sdk cookies-next
```

### 3.3. Add environment variables

Create a `.env.local` file in the project directory:

```shell theme={null}
touch .env.local
```

Open the `.env.local` file and add the following:

```text .env.local theme={null}
CIRCLE_API_KEY=<YOUR_CIRCLE_API_KEY>
NEXT_PUBLIC_GOOGLE_CLIENT_ID=<YOUR_GOOGLE_WEB_CLIENT_ID>
NEXT_PUBLIC_CIRCLE_APP_ID=<YOUR_CIRCLE_APP_ID>
```

* `YOUR_CIRCLE_API_KEY` is your Circle Developer API key.
* `YOUR_GOOGLE_WEB_CLIENT_ID` is the Google OAuth Client ID created in Step 1.
* `YOUR_CIRCLE_APP_ID` is the Circle Wallet App ID obtained in Step 2.

### 3.4. Simplify the default layout

Replace the contents of `app/layout.tsx` with the minimal layout below:

```ts app/layout.tsx twoslash expandable theme={null}
// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

<Info>
  Next.js requires an `app/layout.tsx` file, but the default one created by
  `create-next-app` includes fonts and styling that can cause build errors in
  some environments.
</Info>

### 3.5. Add unified backend route

Create a file named `app/api/endpoints/route.ts` and add the code below:

```ts app/api/endpoints/route.ts twoslash expandable theme={null}
// app/api/endpoints/route.ts
import { NextResponse } from "next/server";

const CIRCLE_BASE_URL =
  process.env.NEXT_PUBLIC_CIRCLE_BASE_URL ?? "https://api.circle.com";
const CIRCLE_API_KEY = process.env.CIRCLE_API_KEY as string;

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const { action, ...params } = body ?? {};

    if (!action) {
      return NextResponse.json({ error: "Missing action" }, { status: 400 });
    }

    switch (action) {
      case "createDeviceToken": {
        const { deviceId } = params;
        if (!deviceId) {
          return NextResponse.json(
            { error: "Missing deviceId" },
            { status: 400 },
          );
        }

        const response = await fetch(
          `${CIRCLE_BASE_URL}/v1/w3s/users/social/token`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${CIRCLE_API_KEY}`,
            },
            body: JSON.stringify({
              idempotencyKey: crypto.randomUUID(),
              deviceId,
            }),
          },
        );

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // Returns: { deviceToken, deviceEncryptionKey }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "initializeUser": {
        const { userToken } = params;
        if (!userToken) {
          return NextResponse.json(
            { error: "Missing userToken" },
            { status: 400 },
          );
        }

        const response = await fetch(
          `${CIRCLE_BASE_URL}/v1/w3s/user/initialize`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${CIRCLE_API_KEY}`,
              "X-User-Token": userToken,
            },
            body: JSON.stringify({
              idempotencyKey: crypto.randomUUID(),
              accountType: "SCA",
              blockchains: ["ARC-TESTNET"],
            }),
          },
        );

        const data = await response.json();

        if (!response.ok) {
          // Pass through Circle error payload (e.g. code 155106: user already initialized)
          return NextResponse.json(data, { status: response.status });
        }

        // Returns: { challengeId }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "listWallets": {
        const { userToken } = params;
        if (!userToken) {
          return NextResponse.json(
            { error: "Missing userToken" },
            { status: 400 },
          );
        }

        const response = await fetch(`${CIRCLE_BASE_URL}/v1/w3s/wallets`, {
          method: "GET",
          headers: {
            accept: "application/json",
            "content-type": "application/json",
            Authorization: `Bearer ${CIRCLE_API_KEY}`,
            "X-User-Token": userToken,
          },
        });

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // Returns: { wallets: [...] }
        return NextResponse.json(data.data, { status: 200 });
      }

      case "getTokenBalance": {
        const { userToken, walletId } = params;
        if (!userToken || !walletId) {
          return NextResponse.json(
            { error: "Missing userToken or walletId" },
            { status: 400 },
          );
        }

        const response = await fetch(
          `${CIRCLE_BASE_URL}/v1/w3s/wallets/${walletId}/balances`,
          {
            method: "GET",
            headers: {
              accept: "application/json",
              Authorization: `Bearer ${CIRCLE_API_KEY}`,
              "X-User-Token": userToken,
            },
          },
        );

        const data = await response.json();

        if (!response.ok) {
          return NextResponse.json(data, { status: response.status });
        }

        // Returns: { tokenBalances: [...] }
        return NextResponse.json(data.data, { status: 200 });
      }

      default:
        return NextResponse.json(
          { error: `Unknown action: ${action}` },
          { status: 400 },
        );
    }
  } catch (error) {
    console.log("Error in /api/endpoints:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 },
    );
  }
}
```

This route serves as a single backend entry point for all Circle API endpoints
used by the app, mapping frontend actions to thin wrapper handlers that call the
corresponding endpoints:

| Handler             | Description                                                                                                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createDeviceToken` | calls [POST /v1/w3s/users/social/token](/api-reference/wallets/user-controlled-wallets/create-device-token-social-login) to create a device-bound session used by the Web SDK for social login authentication. |
| `initializeUser`    | calls [POST /v1/w3s/user/initialize](/api-reference/wallets/user-controlled-wallets/create-user-with-pin-challenge) to create or initialize a user and return a `challengeId` required for wallet creation.    |
| `listWallets`       | calls [GET /v1/w3s/wallets](/api-reference/wallets/user-controlled-wallets/list-wallets) to retrieve the wallets associated with the authenticated user.                                                       |
| `getTokenBalance`   | calls [GET /v1/w3s/wallets//balances](/api-reference/wallets/user-controlled-wallets/list-wallet-balance) to retrieve digital asset balances for the specified user-controlled wallet.                         |

<Info>
  This quickstart calls `listWallets` and `getTokenBalance` directly for
  simplicity. In production, apps typically store wallet and balance data in a
  backend database and keep it in sync using Circle webhooks for scalability.
</Info>

To understand how the request fields and response data for these handlers and
their corresponding endpoints are used, follow the app flow in
[Step 4](#step-4-run-the-app-flow) below.

### ​3.6. Add UI and frontend code

Replace the contents of `app/page.tsx` with the code below:

```ts app/page.tsx twoslash expandable theme={null}
// app/page.tsx
"use client";

import { useEffect, useRef, useState } from "react";
import { setCookie, getCookie } from "cookies-next";
import { SocialLoginProvider } from "@circle-fin/w3s-pw-web-sdk/dist/src/types";
import type { W3SSdk } from "@circle-fin/w3s-pw-web-sdk";

const appId = process.env.NEXT_PUBLIC_CIRCLE_APP_ID as string;
const googleClientId = process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID as string;

type LoginResult = {
  userToken: string;
  encryptionKey: string;
  // other fields (refreshToken, oAuthInfo, etc.) are ignored in this quickstart
};

type Wallet = {
  id: string;
  address: string;
  blockchain: string;
  [key: string]: unknown;
};

export default function HomePage() {
  const sdkRef = useRef<W3SSdk | null>(null);

  const [sdkReady, setSdkReady] = useState(false);
  const [deviceId, setDeviceId] = useState<string>("");
  const [deviceIdLoading, setDeviceIdLoading] = useState(false);

  const [deviceToken, setDeviceToken] = useState<string>("");
  const [deviceEncryptionKey, setDeviceEncryptionKey] = useState<string>("");

  const [loginResult, setLoginResult] = useState<LoginResult | null>(null);
  const [loginError, setLoginError] = useState<string | null>(null);

  const [challengeId, setChallengeId] = useState<string | null>(null);
  const [wallets, setWallets] = useState<Wallet[]>([]);
  const [usdcBalance, setUsdcBalance] = useState<string | null>(null);
  const [status, setStatus] = useState<string>("Ready");

  // Initialize SDK on mount, using cookies to restore config after redirect
  useEffect(() => {
    let cancelled = false;

    const initSdk = async () => {
      try {
        const { W3SSdk } = await import("@circle-fin/w3s-pw-web-sdk");

        const onLoginComplete = (error: unknown, result: any) => {
          if (cancelled) return;

          if (error) {
            const err = error as any;
            console.log("Login failed:", err);
            setLoginError(err.message || "Login failed");
            setLoginResult(null);
            setStatus("Login failed");
            return;
          }

          setLoginResult({
            userToken: result.userToken,
            encryptionKey: result.encryptionKey,
          });
          setLoginError(null);
          setStatus("Login successful. Credentials received from Google.");
        };

        const restoredAppId = (getCookie("appId") as string) || appId || "";
        const restoredGoogleClientId =
          (getCookie("google.clientId") as string) || googleClientId || "";
        const restoredDeviceToken = (getCookie("deviceToken") as string) || "";
        const restoredDeviceEncryptionKey =
          (getCookie("deviceEncryptionKey") as string) || "";

        const initialConfig = {
          appSettings: { appId: restoredAppId },
          loginConfigs: {
            deviceToken: restoredDeviceToken,
            deviceEncryptionKey: restoredDeviceEncryptionKey,
            google: {
              clientId: restoredGoogleClientId,
              redirectUri:
                typeof window !== "undefined" ? window.location.origin : "",
              selectAccountPrompt: true,
            },
          },
        };

        const sdk = new W3SSdk(initialConfig, onLoginComplete);
        sdkRef.current = sdk;

        if (!cancelled) {
          setSdkReady(true);
          setStatus("SDK initialized. Ready to create device token.");
        }
      } catch (err) {
        console.log("Failed to initialize Web SDK:", err);
        if (!cancelled) {
          setStatus("Failed to initialize Web SDK");
        }
      }
    };

    void initSdk();

    return () => {
      cancelled = true;
    };
  }, []);

  // Get / cache deviceId
  useEffect(() => {
    const fetchDeviceId = async () => {
      if (!sdkRef.current) return;

      try {
        const cached =
          typeof window !== "undefined"
            ? window.localStorage.getItem("deviceId")
            : null;

        if (cached) {
          setDeviceId(cached);
          return;
        }

        setDeviceIdLoading(true);
        const id = await sdkRef.current.getDeviceId();
        setDeviceId(id);

        if (typeof window !== "undefined") {
          window.localStorage.setItem("deviceId", id);
        }
      } catch (error) {
        console.log("Failed to get deviceId:", error);
        setStatus("Failed to get deviceId");
      } finally {
        setDeviceIdLoading(false);
      }
    };

    if (sdkReady) {
      void fetchDeviceId();
    }
  }, [sdkReady]);

  // Helper to load USDC balance for a wallet
  async function loadUsdcBalance(userToken: string, walletId: string) {
    try {
      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "getTokenBalance",
          userToken,
          walletId,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("Failed to load USDC balance:", data);
        setStatus("Failed to load USDC balance");
        return null;
      }

      const balances = (data.tokenBalances as any[]) || [];

      const usdcEntry =
        balances.find((t) => {
          const symbol = t.token?.symbol || "";
          const name = t.token?.name || "";
          return symbol.startsWith("USDC") || name.includes("USDC");
        }) ?? null;

      const amount = usdcEntry?.amount ?? "0";
      setUsdcBalance(amount);
      return amount;
    } catch (err) {
      console.log("Failed to load USDC balance:", err);
      setStatus("Failed to load USDC balance");
      return null;
    }
  }

  // Helper to load wallets for the current user
  const loadWallets = async (
    userToken: string,
    options?: { source?: "afterCreate" | "alreadyInitialized" },
  ) => {
    try {
      setStatus("Loading wallet details...");
      setUsdcBalance(null);

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "listWallets",
          userToken,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("List wallets failed:", data);
        setStatus("Failed to load wallet details");
        return;
      }

      const wallets = (data.wallets as Wallet[]) || [];
      setWallets(wallets);

      if (wallets.length > 0) {
        // Load USDC balance for the primary wallet
        await loadUsdcBalance(userToken, wallets[0].id);

        if (options?.source === "afterCreate") {
          setStatus(
            "Wallet created successfully! 🎉 Wallet details and USDC balance loaded.",
          );
        } else if (options?.source === "alreadyInitialized") {
          setStatus(
            "User already initialized. Wallet details and USDC balance loaded.",
          );
        } else {
          setStatus("Wallet details and USDC balance loaded.");
        }
      } else {
        setStatus("No wallets found for this user.");
      }
    } catch (err) {
      console.log("Failed to load wallet details:", err);
      setStatus("Failed to load wallet details");
    }
  };

  const handleCreateDeviceToken = async () => {
    if (!deviceId) {
      setStatus("Missing deviceId");
      return;
    }

    try {
      setStatus("Creating device token...");
      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "createDeviceToken",
          deviceId,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        console.log("Create device token failed:", data);
        setStatus("Failed to create device token");
        return;
      }

      setDeviceToken(data.deviceToken);
      setDeviceEncryptionKey(data.deviceEncryptionKey);

      setCookie("deviceToken", data.deviceToken);
      setCookie("deviceEncryptionKey", data.deviceEncryptionKey);

      setStatus("Device token created");
    } catch (err) {
      console.log("Error creating device token:", err);
      setStatus("Failed to create device token");
    }
  };

  const handleLoginWithGoogle = () => {
    const sdk = sdkRef.current;
    if (!sdk) {
      setStatus("SDK not ready");
      return;
    }

    if (!deviceToken || !deviceEncryptionKey) {
      setStatus("Missing deviceToken or deviceEncryptionKey");
      return;
    }

    // Persist configs so SDK can rehydrate after redirect
    setCookie("appId", appId);
    setCookie("google.clientId", googleClientId);
    setCookie("deviceToken", deviceToken);
    setCookie("deviceEncryptionKey", deviceEncryptionKey);

    sdk.updateConfigs({
      appSettings: {
        appId,
      },
      loginConfigs: {
        deviceToken,
        deviceEncryptionKey,
        google: {
          clientId: googleClientId,
          redirectUri: window.location.origin,
          selectAccountPrompt: true,
        },
      },
    });

    setStatus("Redirecting to Google...");
    sdk.performLogin(SocialLoginProvider.GOOGLE);
  };

  const handleInitializeUser = async () => {
    if (!loginResult?.userToken) {
      setStatus("Missing userToken. Please login with Google first.");
      return;
    }

    try {
      setStatus("Initializing user...");

      const response = await fetch("/api/endpoints", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          action: "initializeUser",
          userToken: loginResult.userToken,
        }),
      });

      const data = await response.json();

      if (!response.ok) {
        // 155106 = user already initialized
        if (data.code === 155106) {
          // User already initialized; load wallet details instead of trying to create again
          await loadWallets(loginResult.userToken, {
            source: "alreadyInitialized",
          });
          // No challenge to execute when wallet already exists
          setChallengeId(null);
          return;
        }

        const errorMsg = data.code
          ? `[${data.code}] ${data.error || data.message}`
          : data.error || data.message;
        setStatus("Failed to initialize user: " + errorMsg);
        return;
      }

      // Successful initialization → get challengeId
      setChallengeId(data.challengeId);
      setStatus(`User initialized. challengeId: ${data.challengeId}`);
    } catch (err) {
      const error = err as any;

      if (error?.code === 155106 && loginResult?.userToken) {
        await loadWallets(loginResult.userToken, {
          source: "alreadyInitialized",
        });
        setChallengeId(null);
        return;
      }

      const errorMsg = error?.code
        ? `[${error.code}] ${error.message}`
        : error?.message || "Unknown error";
      setStatus("Failed to initialize user: " + errorMsg);
    }
  };

  const handleExecuteChallenge = () => {
    const sdk = sdkRef.current;
    if (!sdk) {
      setStatus("SDK not ready");
      return;
    }

    if (!challengeId) {
      setStatus("Missing challengeId. Initialize user first.");
      return;
    }

    if (!loginResult?.userToken || !loginResult?.encryptionKey) {
      setStatus("Missing login credentials. Please login again.");
      return;
    }

    sdk.setAuthentication({
      userToken: loginResult.userToken,
      encryptionKey: loginResult.encryptionKey,
    });

    setStatus("Executing challenge...");

    sdk.execute(challengeId, (error) => {
      const err = (error || {}) as any;

      if (error) {
        console.log("Execute challenge failed:", err);
        setStatus(
          "Failed to execute challenge: " + (err?.message ?? "Unknown error"),
        );
        return;
      }

      setStatus("Challenge executed. Loading wallet details...");

      void (async () => {
        // small delay to give Circle time to index the wallet
        await new Promise((resolve) => setTimeout(resolve, 2000));

        // Challenge consumed; clear it and load wallet details (and balance)
        setChallengeId(null);
        await loadWallets(loginResult.userToken, { source: "afterCreate" });
      })().catch((e) => {
        console.log("Post-execute follow-up failed:", e);
        setStatus("Wallet created, but failed to load wallet details.");
      });
    });
  };

  const primaryWallet = wallets[0];

  return (
    <main>
      <div style={{ width: "50%", margin: "0 auto" }}>
        <h1>Create a user wallet with Google social login</h1>
        <p>Follow the buttons below to complete the flow:</p>

        <div>
          <button
            onClick={handleCreateDeviceToken}
            style={{ margin: "6px" }}
            disabled={!sdkReady || !deviceId || deviceIdLoading}
          >
            1. Create device token
          </button>
          <br />
          <button
            onClick={handleLoginWithGoogle}
            style={{ margin: "6px" }}
            disabled={!deviceToken || !deviceEncryptionKey}
          >
            2. Login with Google
          </button>
          <br />
          <button
            onClick={handleInitializeUser}
            style={{ margin: "6px" }}
            disabled={!loginResult || wallets.length > 0}
          >
            3. Initialize user (get challenge)
          </button>
          <br />
          <button
            onClick={handleExecuteChallenge}
            style={{ margin: "6px" }}
            disabled={!challengeId || wallets.length > 0}
          >
            4. Create wallet (execute challenge)
          </button>
        </div>

        <p>
          <strong>Status:</strong> {status}
        </p>

        {loginError && (
          <p style={{ color: "red" }}>
            <strong>Error:</strong> {loginError}
          </p>
        )}

        {primaryWallet && (
          <div style={{ marginTop: "12px" }}>
            <h2>Wallet details</h2>
            <p>
              <strong>Address:</strong> {primaryWallet.address}
            </p>
            <p>
              <strong>Blockchain:</strong> {primaryWallet.blockchain}
            </p>
            {usdcBalance !== null && (
              <p>
                <strong>USDC balance:</strong> {usdcBalance}
              </p>
            )}
          </div>
        )}

        <pre
          style={{
            whiteSpace: "pre-wrap",
            wordBreak: "break-all",
            lineHeight: "1.8",
            marginTop: "16px",
          }}
        >
          {JSON.stringify(
            {
              deviceId,
              deviceToken,
              deviceEncryptionKey,
              userToken: loginResult?.userToken,
              encryptionKey: loginResult?.encryptionKey,
              challengeId,
              wallets,
              usdcBalance,
            },
            null,
            2,
          )}
        </pre>
      </div>
    </main>
  );
}
```

This page renders the UI and implements all browser-side logic for the Google
social login and wallet creation flow. It initializes the Web SDK, processes the
Google OAuth redirect, manages short-lived state across redirects, and
coordinates the sequence of actions required to create and display the wallet.

## Step 4. Run the app flow

1. Start the dev server:

```shell theme={null}
npm run dev
```

2. Open [http://localhost:3000](http://localhost:3000) in your browser to view the app.

3) Complete the Google authentication and wallet creation flow:
   1. Click **Create device token**: The Web SDK generates a unique `deviceId`,
      which identifies the user's browser. Your backend exchanges the `deviceId`
      for temporary verification tokens (`deviceToken`, `deviceEncryptionKey`)
      used by the Web SDK to allow Google authentication.
   2. Click **Login with Google**: The Web SDK starts the Google OAuth
      authentication process. After the user signs in with Google, the SDK sends
      the OAuth result to Circle. Circle validates the login and returns a
      `userToken` and `encryptionKey`, which together represent an authenticated
      Circle user session.
   3. Click **Initialize user**: Your backend initializes the user using the
      `userToken`. If the user hasn't created a wallet yet, Circle returns a
      `challengeId` to create one. If the user is already initialized, the app
      loads the existing wallet instead.
   4. Click **Create wallet**: The Web SDK executes the challenge using the
      `challengeId`. The user approves the action, and Circle creates the
      wallet.

4) Once the flow completes:
   * The app displays the wallet address, blockchain, and USDC balance.
   * You can verify the user was created in the
     [Circle Dev Console](https://console.circle.com/):\
     **Wallets → User Controlled → Users**.

## Step 5. Fund the wallet

In this step, you fund the new wallet manually using the Circle Faucet and
confirm the updated balance in the app.

1. Copy the wallet address (`0x...`) from the web app UI.
2. Visit the official [Circle Faucet](https://faucet.circle.com/).
3. Select **Arc Testnet** as the blockchain network.
4. Paste the wallet address in the **Send to** field.
5. Click **Send USDC**.
6. Return to the app and walk through the flow again.\
   **Note:** Use the same Google account to show the same wallet.
7. The app will display the updated USDC balance.

<Note>
  In this step, you're acting as the end user to fund your user-controlled
  wallet for testing. In production, app developers don't control user wallets
  or private keys. Instead, users typically fund wallets themselves, but apps
  may also fund using faucets or airdrops without requiring wallet access.
</Note>


# Initiate a Signature Request
Source: https://developers.circle.com/wallets/user-controlled/initiate-a-signature-request

Learn how to initiate a signature request from a user-controlled wallet with social logins or email authentication

This guide outlines initiating a signature request from a previously created
user-controlled wallet with social logins or email authentication. To create a
wallet, see
[Create Your First Wallet with Social Logins](/wallets/user-controlled/create-your-first-wallet-with-social-logins)
or
[Create Your First Wallet with Email](/wallets/user-controlled/create-your-first-wallet-with-email).

<Note>
  If it has been over 14 days or you end the last trial attempt since you first
  ran the sample app, your session is logged out. You must run the sample app
  and acquire a new user token to proceed further. For instructions, see the
  perform login part of [Create Your First Wallet with Social
  Logins](/wallets/user-controlled/create-your-first-wallet-with-social-logins)
  or [Create Your First Wallet with Email
  Authentication](/wallets/user-controlled/create-your-first-wallet-with-email).
</Note>

## Step 1. Initiate a signature request

1. Sign the transaction, EIP-191 message, or EIP-712 typed structure data from a
   specified user-controlled wallet:
   * For a transaction, include `walletId` and `transaction` object or
     `rawTransaction` string in a `POST` request to the `/user/sign/transaction`
     endpoint.
   * For EIP-191, include `walletId` and `message` in a `POST` request to the
     `/user/sign/message` endpoint.
   * For EIP-712, include `walletId` and `data` in a `POST` request to the
     `/user/sign/typedData` endpoint.
2. From the response, copy `challengeId` for the next step.

## Step 2. Perform signing

To perform signing on the sample app's confirmation UI, ensure you have obtained
an active user token and encryption key.

From the Execute Challenge screen, paste the Challenge ID and select
**Execute**.

<Frame>
  <img />
</Frame>

## Step 3. Confirm signature request

The sample app prompts a confirmation UI for the user to view the signing
details and confirm it. You can customize confirmation UIs. For more, see
[Confirmation UIs](/wallets/user-controlled/confirmation-uis) .

<Frame>
  <img />
</Frame>


# iOS Mobile SDK
Source: https://developers.circle.com/wallets/user-controlled/ios-sdk

Set up the client-side iOS SDK for user-controlled wallets in your mobile application.

The Circle iOS SDK enables user-controlled wallets within your mobile
application. Three authentication methods are supported, namely **social
logins**, **email**, or **PIN**, which includes security questions for recovery.
This allows you to authenticate your users in a seamless way and create
user-controlled wallets for them.

By integrating this client-side SDK, your users can securely create wallets and
make transactions using social accounts or email. If you choose the PIN
authentication method, your users can input sensitive data, like PINs or
security answers, in a secure way. Moreover, the SDK encrypts the request body
sent by the application, protecting your users' information.

<Note>
  **Note:**

  The Web and Mobile SDKs preserve the user keyshare with the individual, giving
  them complete control. You must use the SDKs with the user-controlled wallet
  product. Additionally, the Web and Mobile SDKs support only the user-controlled
  wallet product.
</Note>

At Circle, we understand the importance of end-to-end security for your
application and the need to create a tailored and seamless user experience for
your end-users. Hence, Circle's SDK also exposes functionality for you to
customize the description and layout. See the
[iOS SDK UI Customization API](/wallets/user-controlled/ios-sdk-ui-customization-api)
article about customizing the SDK.

## Install the SDKs

The iOS SDK supports:

1. iOS 13.0+

2. macOS 12.5+

3. Xcode 14.1+

\*Earlier versions are not supported.

## CocoaPods (recommended)

CocoaPods is a dependency manager for Cocoa projects. You can install it with
the following command:

```shell Terminal theme={null}
brew install cocoapods
```

<Note>
  How to install Homebrew in MacOS:
  [Link](https://mac.install.guide/homebrew/3.html)
</Note>

To integrate into your Xcode project using CocoaPods, specify it in your
`Podfile`:

```ruby Podfile theme={null}
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/circlefin/w3s-ios-sdk-podspecs.git'

target '<Your Target Name>' do
  pod 'CircleProgrammableWalletSDK'
end
```

Then, run the following command:

```shell Terminal theme={null}
pod install
```

## Manual

You can also manually set up the iOS SDK by downloading it from
[GitHub: circlefin/w3s-ios-sdk](https://github.com/circlefin/w3s-ios-sdk).

## SDK architecture

You must use Web, iOS, or Android SDKs to access the user-controlled
Programmable Wallet product. The SDK secures, manages, and communicates with
your server to ensure your user's keyshare, always stays with them and is not
exposed to your servers.

To learn more, see
[SDK Architecture for User-Controlled Wallets](/wallets/user-controlled/sdk-architecture).

## SDK API references

## WalletSdk

| Public Methods                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| /// Singleton <br /> <br />`public static let shared = WalletSdk()`                                                                                                                                                                                                                                                                                                             |
| /// Set SDK configuration <br />/// - Parameter configuration: Configure the Circle endpoint for SDK to connect and other settings. <br />/// - Throws: An error is thrown while the configuration is invalid. <br /> <br />`public func setConfiguration(_ configuration: Configuration) throws`                                                                               |
| /// Execute the operations by challengeId and call the completion after sending the request to the Circle endpoint. <br /> <br />`public func execute(userToken: String, encryptionKey: String, challengeIds: [String], completion: ExecuteCompletion? = nil)`                                                                                                                  |
| /// Set SDK LayoutProvider <br />/// - Parameter provider: WalletSdkLayoutProvider <br /> <br />`public func setLayoutProvider(_ provider: WalletSdkLayoutProvider)`                                                                                                                                                                                                            |
| /// Set messenger for custom error messages <br />/// - Parameter messenger: ErrorMessager <br /> <br />`public func setErrorMessenger(_ messenger: ErrorMessenger)`                                                                                                                                                                                                            |
| /// Set SDK delegate <br />/// - Parameter delegate: WalletSdkDelegate <br /> <br />`public func setDelegate(_ delegate: WalletSdkDelegate)`                                                                                                                                                                                                                                    |
| /// Set up biometrics to protect PIN code <br />/// - Parameters: <br />/// - userToken: User token <br />/// - encryptionKey: Encryption key <br />/// - completion: The completion handler that will be called when biometrics setup is complete. <br /> <br />`public func setBiometricsPin(userToken: String, encryptionKey: String, completion: ExecuteCompletion? = nil)` |
| /// Get device ID <br />/// - Returns: String ex: 01234567-0123-0123-0123-012345678901 <br /> <br />`public func getDeviceId() -> String`                                                                                                                                                                                                                                       |
| /// Get the SDK version string <br />/// - Returns: String? ex: 1.0.3 (63) <br /> <br />`public func sdkVersion() -> String?`                                                                                                                                                                                                                                                   |
| /// Execute social provider login flow to get userToken, encryptionKey, refreshToken and OAuthInfo object <br /> <br />`public func performLogin(provider: SocialProvider, deviceToken: String, encryptionKey: String, completion: LoginCompletion? = nil)`                                                                                                                     |
| /// Prompt OTP input UI and to verify email OTP and get userToken, encryptionKey, refreshToken <br /> <br />`public func verifyOTP(deviceToken: String, encryptionKey: String, otpToken: String, completion: LoginCompletion? = nil)`                                                                                                                                           |
| /// Clean login data, includes provider's data and userSecret <br /> <br />`public func performLogout(provider: SocialProvider, completion: LogoutCompletion? = nil)`                                                                                                                                                                                                           |

### WalletSdk.Configuration

`public struct Configuration`

| Fields             |                                                                                |
| ------------------ | ------------------------------------------------------------------------------ |
| String             | `endPoint` <br />Init with Circle endpoint. SDK will connect to this endpoint. |
| String             | `appId` <br />AppID from Circle Developer Services Console                     |
| SettingsManagement | `settings` <br /> <br />Configure other settings and features                  |

### SettingsManagement

```swift Swift theme={null}
public struct SettingsManagement {

    /// Enable biometrics to protect PIN code
    let enableBiometricsPin: Bool

    public init(enableBiometricsPin: Bool = false)
}

```

<Note>
  **💡 Notice:**

  **Important**: In any app that uses biometrics, include the
  [NSFaceIDUsageDescription](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW75)
  key in the app's `Info.plist` file. Without this key, the system won't allow
  your app to use biometrics (Face ID).
</Note>

### ExecuteCompletion

```swift Swift theme={null}
public typealias ExecuteCompletion = ((ExecuteCompletionStruct) -> Void)
```

### ExecuteCompletionStruct

```swift Swift theme={null}
public struct ExecuteCompletionStruct {
    public let challenges: [String]
    public let result: Result<ExecuteResult, ApiError>
    public let onErrorController: UINavigationController?
    public let onWarning: ExecuteWarning?
}
```

* When receiving an error or warning, we will not close the current page by
  default.
* You will get the onErrorController in the callback, and then you can decide to
  dismiss/push the page by your error-handling strategy.

### ExecuteResult

```swift Swift theme={null}
public struct ExecuteResult {

  /// The type of the operation that the challenge represents.
  public let resultType: ChallengeType

  /// The execute result
  public let status: ChallengeStatus

  /// The data of the execution. (optional)
  public private(set) var data: ExecuteResultData? = nil
}
```

### ChallengeType

```swift Swift theme={null}
public enum ChallengeType: String, Decodable {
  case SET_PIN
  case CHANGE_PIN
  case RESTORE_PIN
  case SET_SECURITY_QUESTIONS
  case SET_BIOMETRICS_PIN
  case CREATE_WALLET
  case CREATE_TRANSACTION
  case ACCELERATE_TRANSACTION
  case CANCEL_TRANSACTION
  case CONTRACT_EXECUTION
  case SIGN_MESSAGE
  case SIGN_TYPEDDATA
  case SIGN_TRANSACTION
  case INITIALIZE
  case WALLET_UPGRADE
  case UNKNOWN
}
```

### ChallengeStatus

```swift Swift theme={null}
public enum ChallengeStatus: String, Decodable {
  case PENDING
  case IN_PROGRESS
  case COMPLETE
  case FAILED
  case EXPIRED
}
```

### ExecuteResultData

```swift Swift theme={null}
public struct ExecuteResultData: Decodable {

    /// The signature for SIGN_MESSAGE and SIGN_TYPEDDATA
    public let signature: String?

    /// For SIGN_TRANSACTION
    public let signedTransaction: String?

    /// For SIGN_TRANSACTION
    public let txHash: String?

    /// For SIGN_TRANSACTION and only returned for ECDSA chains
    public let v: String?

    /// For SIGN_TRANSACTION and only returned for ECDSA chains
    public let r: String?

    /// For SIGN_TRANSACTION and only returned for ECDSA chains
    public let s: String?

}

```

### ExecuteWarning

```swift Swift theme={null}
public struct ExecuteWarning {

    /// The warning type of the operation (the challenge execution is success)
    public let warningType: WarningType

    /// Description of the warning type
    public var warningString: String
}
```

### WarningType

```swift Swift theme={null}
public enum WarningType: Int {

    // Biometrics

    case deviceNotSupportBiometrics = 155709
    case biometricsKeyPermanentlyInvalidated = 155710   // For Android
    case biometricsUserSkip = 155711
    case biometricsUserDisableForPin = 155712
    case biometricsUserLockout = 155713                 // For Android
    case biometricsUserLockoutPermanent = 155714
    case biometricsUserNotAllowPermission = 155715
    case biometricsInternalError = 155716
}
```

### LoginCompletion

```swift Swift theme={null}
public typealias LoginCompletion = ((LoginCompletionStruct) -> Void)
```

### LoginCompletionStruct

```swift Swift theme={null}
public struct LoginCompletionStruct {
    public let result: Result<LoginResult, ApiError>
    public let onErrorController: UIViewController?
}
```

### LoginResult

```swift Swift theme={null}
public struct LoginResult {
    public let userToken: String
    public let encryptionKey: String
    public let refreshToken: String
    public let oauthInfo: OauthInfo?
}
```

### OauthInfo

`OauthInfo` for Social login

```swift sw theme={null}
public struct OauthInfo: Decodable {
    public let provider: String
    public let scope: [String]?
    public let socialUserUUID: String
    public let socialUserInfo: SocialUserInfo?
}
```

### SocialUserInfo

`SocialUserInfo` for Social login

```swift Swift theme={null}
public struct OauthInfo: Decodable {
    public struct SocialUserInfo: Decodable {
        public let name: String?
        public let email: String?
        public let phone: String?
    }

    public let provider: String
    public let scope: [String]?
    public let socialUserUUID: String
    public let socialUserInfo: SocialUserInfo?
}

```

### LogoutCompletion

```swift Swift theme={null}
public typealias LogoutCompletion = ((Result<Void, Error>) -> Void)
```

### ApiError

`public struct ApiError`

| Fields             |                                                 |
| :----------------- | :---------------------------------------------- |
| ApiError.ErrorCode | `errorCode`                                     |
| String             | `errorString` /// Error string from the SDK     |
| String             | `displayString` /// Error string for UI display |

### ApiError.ErrorCode

`public enum`

```swift Enum Cases theme={null}
case undefined(code: Int) // Error code defined dynamically by server, not in SDK.

case unknown = -1
case success = 0
case apiParameterMissing = 1
case apiParameterInvalid = 2
case forbidden = 3
case unauthorized = 4
case retry = 9
case customerSuspended = 10
case pending = 11
case invalidSession = 12
case invalidPartnerId = 13
case invalidMessage = 14
case invalidPhone = 15
case userAlreadyExisted = 155101
case userNotFound = 155102
case userTokenNotFound = 155103
case userTokenExpired = 155104
case invalidUserToken = 155105
case userWasInitialized = 155106
case userHasSetPin = 155107
case userHasSetSecurityQuestion = 155108
case userWasDisabled = 155109
case userDoesNotSetPinYet = 155110
case userDoesNotSetSecurityQuestionYet = 155111
case incorrectUserPin = 155112
case incorrectDeviceId = 155113
case incorrectAppId = 155114
case incorrectSecurityAnswers = 155115
case invalidChallengeId = 155116
case invalidApproveContent = 155117
case invalidEncryptionKey = 155118
case userPinLocked = 155119
case securityAnswersLocked = 155120
case walletIsFrozen = 155501
case maxWalletLimitReached = 155502
case walletSetIdMutuallyExclusive = 155503
case metadataUnmatched = 155504
case userCanceled = 155701
case launchUiFailed = 155702
case pinCodeNotMatched = 155703
case insecurePinCode = 155704
case hintsMatchAnswers = 155705
case networkError = 155706
case biometricsSettingNotEnabled = 155708
case deviceNotSupportBiometrics = 155709
case biometricsKeyPermanentlyInvalidated = 155710 // For Android
case biometricsUserSkip = 155711
case biometricsUserDisableForPin = 155712
case biometricsUserLockout = 155713 // For Android
case biometricsUserLockoutPermanent = 155714
case biometricsUserNotAllowPermission = 155715
case biometricsInternalError = 155716
case invalidUserTokenFormat = 155718
case userTokenMismatch = 155719
case socialLoginFailed = 155720
case loginInfoMissing = 155721
case walletIdNotFound = 156001
case tokenIdNotFound = 156002
case transactionIdNotFound = 156003
case entityCredentialNotFound = 156004
case walletSetIdNotFound = 156005
```

### SocialProvider

Specify a social provider to operate on. See **WalletSdk.performLogin** and
**WalletSdk.performLogout**.

```swift Swift theme={null}
public enum SocialProvider: String {
    case Google
    case Facebook
    case Apple
}
```

### WalletSdkLayoutProvider

Set **WalletSdkLayoutProvider** for layout customization.

```swift Swift theme={null}
public protocol WalletSdkLayoutProvider: AnyObject {
  /// Set security question list
  ///
  /// - Returns: [SecurityQuestion]
  func securityQuestions() -> [SecurityQuestion]

  /// Set security question required count (default is 2), used in SecurityQuestionsViewController
  ///
  /// - Returns: Int
  func securityQuestionsRequiredCount() -> Int

  /// Set security confirm item list
  ///
  /// - Returns: [SecurityConfirmItem]
  func securityConfirmItems() -> [SecurityConfirmItem]

  /// Set local and remote images
  ///
  /// - Returns: ImageStore
  func imageStore() -> ImageStore

  /// Set theme font programmatically
  ///
  /// - Returns: ThemeFont
  func themeFont() -> ThemeConfig.ThemeFont?

  /// Set the date format for display date strings. (Default is "yyyy-MM-dd")
  /// Reference: https://stackoverflow.com/a/52297497
  ///
  /// - Returns: Date format string
  func displayDateFormat() -> String
}
```

### SecurityQuestion

`public struct SecurityQuestion`

| Fields                     |                                                        |
| -------------------------- | ------------------------------------------------------ |
| String                     | title <br /> <br />The question string                 |
| SecurityQuestion.InputType | inputType <br /> <br />The input type of the question. |

### SecurityQuestion.InputType

`public enum InputType`

```swift Enum Cases theme={null}
text
datePicker
...
```

### SecurityConfirmItem

`public struct SecurityConfirmItem`

| Fields   |                                                                        |
| -------- | ---------------------------------------------------------------------- |
| UIImage? | Image <br /> <br />The drawable resource ID for the introduction item. |
| URL?     | url <br /> <br />The remote image url                                  |
| String   | Text <br /> <br />The Text for the introduction item.                  |

### ImageStore

`public struct ImageStore`

| Fields          |                                            |
| --------------- | ------------------------------------------ |
| \[Img: UIImage] | local <br />The images from local          |
| \[Img: URL]     | remote <br /> <br />The images from remote |

### ImageStore.Img

`public enum Img`

```swift Enum Cases theme={null}

naviClose
naviBack

securityIntroMain
selectCheckMark
dropdownArrow
errorInfo
securityConfirmMain

biometricsAllowMain

showPin
hidePin

transactionTokenIcon
networkFeeTipIcon
showLessDetailArrow
showMoreDetailArrow
requestIcon
```

### WalletSdkDelegate

Methods for managing **CircleProgrammableWalletSDK** process and customizing
controllers.

```swift Swift theme={null}
public protocol WalletSdkDelegate: AnyObject {
  /// Tells the delegate that the SDK is about to be present the controller.
  /// You can customize the layout as you wish dynamically.
  ///
  /// - Parameter controller: The UIViewController to be presented
  func walletSdk(willPresentController controller: UIViewController)

  /// Tells the delegate that the forget PIN button was selected in the controller
  ///
  /// - Parameter controller: Current controller
  /// - Parameter onSelect: Void
  func walletSdk(controller: UIViewController, onForgetPINButtonSelected onSelect: Void)

  /// Tells the delegate that the send again button was selected in the controller
  ///
  /// - Parameter controller: Current controller
  /// - Parameter onSelect: Void
  func walletSdk(controller: UIViewController, onSendAgainButtonSelected onSelect: Void)
}
```

### ErrorMessenger

Define the customized error description. All error codes are listed in
ApiError.ErrorCode.

```swift Swift theme={null}
public protocol ErrorMessenger {
  func getErrorString(_ code: ApiError.ErrorCode) -> String?
}
```

## Static Resources

### Localized String

Provide with a strings file **CirclePWLocalizable.strings**

```swift Swift theme={null}
"circlepw_show_pin" = "Show PIN";
"circlepw_hide_pin" = "Hide PIN";
"circlepw_continue" = "Continue";
"circlepw_next" = "Next";
...

```

### Theme

provide with a JSON file **CirclePWTheme.json**

```swift Swift theme={null}
{
    "font": {
        "regular": "Arial",
        "medium": "",
        "semibold": "",
        "bold": "Arial-BoldMT",
        ...
    },

    "color": {
        "background": "#FFFFFF",
        "divider": "#F0EFEF",
        "success": "#0073C3",
        "error": "#F55538",
        "error_background": "#FDF2F2",
        ...
    }
}

```

### ThemeConfig

`public struct ThemeConfig`

| Fields            |                                                        |
| ----------------- | ------------------------------------------------------ |
| ThemeFontConfig?  | fontConfig <br /> <br />The struct of the theme font   |
| ThemeColorConfig? | colorConfig <br /> <br />The struct of the theme color |

### ThemeFontConfig

`public struct ThemeFontConfig`

| Fields  |                                                                       |
| ------- | --------------------------------------------------------------------- |
| String? | ultraLight <br /> <br />The font name for ultraLight of UIFont.Weight |
| String? | thin <br /> <br />The font name for thin of UIFont.Weight             |
| String? | light <br /> <br />The font name for light of UIFont.Weight           |
| String? | regular <br /> <br />The font name for regular of UIFont.Weight       |
| String? | medium <br /> <br />The font name for medium of UIFont.Weight         |
| ...     | ...                                                                   |

### ThemeColorConfig

`public struct ThemeColorConfig` (see
[Color Reference](/wallets/user-controlled/web-sdk-ui-customizations#colors))

| Fields  |                                                         |
| ------- | ------------------------------------------------------- |
| String? | textMain <br /> <br />The hex format of theme text main |
| String? | error <br /> <br />The hex format of theme error        |
| ...     | ...                                                     |

## Sample Code

### Set endpoint

```swift Swift theme={null}
let configuration = WalletSdk.Configuration(endPoint: endPoint, appId: appId)

do {
    try WalletSdk.shared.setConfiguration(configuration)
} catch {
    // error handling
}

```

### Set endpoint and enable biometrics

```swift Swift theme={null}
let settings: WalletSdk.SettingsManagement = .init(enableBiometricsPin: true)
let configuration = WalletSdk.Configuration(endPoint: endPoint, appId: _appId, settingsManagement: settings)

do {
    try WalletSdk.shared.setConfiguration(configuration)
} catch {
    // error handling
}

```

### Execute

```swift Swift theme={null}
Wallets.shared.execute(userToken: "USERTOKEN",
                       encryptionKey: "ENCRYPTIONKEY",
                       challengeIds: ["challengeId_1", "challengeId_2"])

```

### Set Biometrics Pin

```swift Swift theme={null}
WalletSdk.shared.setBiometricsPin(userToken: "USERTOKEN",
                                  encryptionKey: "ENCRYPTIONKEY")
```

### WalletSdkLayoutProvider

```swift Swift theme={null}
class SomeClass: WalletSdkLayoutProvider {

    func securityQuestions() -> [SecurityQuestion] {
        return [...]
    }

    func securityConfirmItems() -> [SecurityConfirmItem] {
        return [...]
    }

    func imageStore() -> ImageStore {
        let local: [ImageStore.Img: UIImage] =  [...]
        let remote: [ImageStore.Img : URL] = [...]
        return ImageStore(local: local, remote: remote)
    }

    func displayDateFormat() -> String {
        return "dd/MM/yyyy"
    }
}

WalletSdk.shared.setLayoutProvider(SomeClass())

```

### Set Error Messages

```swift Swift theme={null}
class CustomErrorMessenger: ErrorMessenger {

    func getErrorString(_ code: ApiError.ErrorCode) -> String? {
        switch code {
        case .pinCodeNotMatched:
            return "The code you entered is not the same as the first one."

        case .insecurePinCode:
            return "Your PIN can't have repeating or consecutive numbers."

        case .hintsMatchAnswers:
            return "Your hint can't be the same as the answer."

        case .undefined(let code):
            if code == 155134 {
                return "Please check if the OTP value and OTP token match."
            } else {
                return nil
            }

        default:
            return nil
        }
    }
}

WalletSdk.shared.setErrorMessenger(CustomErrorMessenger())

```

### Confirm the delegate for customizing the UI

```swift Swift theme={null}
class SomeClass: WalletSdkDelegate {
func walletSdk(willPresentController controller: UIViewController) {

// You can customize the controller's UI here

        if let vc = controller as? SecurityIntrosViewController {
            vc.introImageView.sd_setImage(with: URL(string: "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"), placeholderImage: UIImage(named: "imangeName"))
            vc.introLink = "https://www.google.com"
            vc.introDescLabel.text = "Test Desc here"
        }
    }
}

```

### PerformLogin Flow

```swift Swift theme={null}
WalletSdk.shared.performLogin(provider: ”SOCIAL_PROVIDER”,
                              deviceToken: “DEVICE_TOKEN”,
                              encryptionKey: “DEVICE_ENCRYPTION_KEY”) { response in
......
}

```

### VerifyOTP flow

```swift Swift theme={null}
WalletSdk.shared.verifyOTP(deviceToken: “DEVICE_TOKEN”,
                           encryptionKey: “DEVICE_ENCRYPTION_KEY”
                           otpToken: ”OTP_TOKEN”) { response in
    ......
}

```

### PerformLogout Flow

```swift Swift theme={null}
WalletSdk.shared.performLogout(provider:  ”SOCIAL_PROVIDER”) { result in
    ......
}

```

See our [sample app guides](/sample-projects).


# iOS SDK UI Customization API
Source: https://developers.circle.com/wallets/user-controlled/ios-sdk-ui-customization-api

iOS SDK UI and key mapping reference for customizations.

This article describes two different ways to customize your iOS application
using the [iOS SDK](/wallets/user-controlled/ios-sdk):

* **Static Resources** customize the UI layout during build time.
* **Programmatic Customization** modifies the layout at run time.

<Note>
  **Note:**

  You can combine static and programmatic approaches for customization.
</Note>

To use the SDK in the most flexible way, combine the reference in this article
with the [iOS SDK](/wallets/user-controlled/ios-sdk).

**Sample Application**: Refer to the
[iOS sample application](https://github.com/circlefin/w3s-ios-sample-app-wallets)
for example code.

## Layouts

## How to Use the Layout Images and Index Tables

This section includes screenshots of layouts for the SDK functionality. As you
review the layouts, you can cross-reference the alphanumeric tags in the images
with the values in the index tables that follow this section:

* [Index Table A](/wallets/user-controlled/ios-sdk-ui-customization-api#index-table-a)
* [Index Table B](/wallets/user-controlled/ios-sdk-ui-customization-api#index-table-b)
* [Index Table C](/wallets/user-controlled/ios-sdk-ui-customization-api#index-table-c)

## New PIN Code

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Confirm PIN Code

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Enter PIN Code

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Security Intro

<Frame>
  <img />
</Frame>

## Security Questions

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Select Question

<Frame>
  <img />
</Frame>

## Security Summary

<Frame>
  <img />
</Frame>

## Security Confirm

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Recover PIN Code

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Biometrics Setup

<Frame>
  <img />
</Frame>

### Touch ID Setup

<Frame>
  <img />
</Frame>

## Confirm Transaction

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Contract Interaction

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Signature Request

<Frame>
  <img />
</Frame>

## Verify Email OTP

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Index Table A

Based on the layouts, table A provides the UI item named in the controller and
the keys in use. You can get the UIViewController from `WalletSdkDelegate` and
customize the UI items in the run time. Also, you can provide the values in
static resources `CirclePWLocalizable.strings` and `CirclePWTheme.json` for
customization layouts in build time.

|           |  **Programmatic Customization**  |                           |                                                         | **Static Resources**                                      |                        |                                                                                                                             |
| --------- | :------------------------------: | :-----------------------: | ------------------------------------------------------- | --------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|           |                                  |                           |                                                         | **CirclePWLocalizable.strings**                           | **CirclePWTheme.json** |                                                                                                                             |
| **#**     |          **Controller**          |          **Item**         | **Note**                                                |                                                           | **font**               | **color**                                                                                                                   |
| **A1**    |     NewPINCodeViewController     |        titleLabel1        | -                                                       | circlepw\_new\_pincode\_headline                          | semibold               | text\_main                                                                                                                  |
| **A2**    |                ''                |        titleLabel2        | -                                                       | circlepw\_new\_pincode\_headline\_2                       | bold                   | title\_gradients                                                                                                            |
| **A3**    |                ''                |       subtitleLabel       | -                                                       | circlepw\_new\_pincode\_subhead                           | regular                | text\_auxiliary                                                                                                             |
| **A4**    |    BasePINInputViewController    |             -             | dots and texts will be generated dynamically            | -                                                         | light                  | pin\_dot\_base / pin\_dot\_base\_border / pin\_dot\_activated / pin\_dot\_focused / pin\_digit\_activated / success / error |
| **A5**    |                ''                |             -             | shows ApiError.displayString                            | -                                                         | regular                | error                                                                                                                       |
| **A8**    |   ConfirmPINCodeViewController   |        titleLabel1        | -                                                       | circlepw\_confirm\_pincode\_headline                      | semibold               | text\_main                                                                                                                  |
| **A9**    |                ''                |        titleLabel2        | -                                                       | circlepw\_confirm\_pincode\_headline\_2                   | bold                   | title\_gradients                                                                                                            |
| **A10**   |                ''                |       subtitleLabel       | -                                                       | circlepw\_confirm\_pincode\_subhead                       | regular                | text\_auxiliary                                                                                                             |
| **A11**   |    EnterPINCodeViewController    |        titleLabel1        | -                                                       | circlepw\_enter\_pincode\_headline                        | semibold               | text\_main                                                                                                                  |
| **A12**   |                ''                |        titleLabel2        | -                                                       | circlepw\_enter\_pincode\_headline\_2                     | bold                   | title\_gradients                                                                                                            |
| **A13**   |                ''                |       subtitleLabel       | -                                                       | circlepw\_enter\_pincode\_subhead                         | regular                | text\_auxiliary                                                                                                             |
| **A14**   |                ''                |      forgotPINButton      | -                                                       | circlepw\_enter\_pincode\_forgot\_pin                     | semibold               | text\_action / text\_action\_pressed                                                                                        |
| **A65**   |                ''                |      biometricsButton     | -                                                       | circlepw\_enter\_pincode\_use\_biometrics                 | semibold               | text\_action / text\_action\_pressed                                                                                        |
| **A15**   |   SecurityIntrosViewController   |        titleLabel1        | -                                                       | circlepw\_security\_intros\_headline                      | semibold               | text\_main                                                                                                                  |
| **A16**   |                ''                |        titleLabel2        | -                                                       | circlepw\_security\_intros\_headline\_2                   | bold                   | title\_gradients                                                                                                            |
| **A17**   |                ''                |       introDescLabel      | -                                                       | circlepw\_security\_intros\_description                   | regular                | text\_auxiliary2                                                                                                            |
| **A18**   |                ''                |      introLinkButton      | -                                                       | circlepw\_security\_intros\_link                          | regular                | text\_action / text\_action\_pressed                                                                                        |
| **A18-1** |                ''                |         introLink         | custom your url string                                  | -                                                         | -                      | -                                                                                                                           |
| **A19**   |                ''                |       continueButton      | text                                                    | circlepw\_continue                                        | semibold               | main\_bt\_text / main\_bt\_text\_pressed / main\_bt\_text\_disabled                                                         |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | main\_bt\_background / main\_bt\_background\_pressed / main\_bt\_background\_disabled                                       |
| **A20**   |  SecurityQuestionsViewController |     baseNaviTitleLabel    | -                                                       | circlepw\_security\_questions\_title                      | medium                 | text\_main                                                                                                                  |
| **A21**   |                ''                |         nextButton        | text                                                    | circlepw\_next                                            | semibold               | main\_bt\_text / main\_bt\_text\_pressed / main\_bt\_text\_disabled                                                         |
|           |                ''                |                           | background                                              | -                                                         | -                      | main\_bt\_background / main\_bt\_background\_pressed / main\_bt\_background\_disabled                                       |
| **A22**   |   SecurityQuestionTableViewCell  |     questionTitleLabel    | -                                                       | circlepw\_security\_questions\_question\_header           | regular                | text\_auxiliary                                                                                                             |
| **A23**   |                ''                |     questionMarkLabel     | -                                                       | circlepw\_security\_questions\_required\_mark             | regular                | error                                                                                                                       |
| **A24**   |                ''                |             -             | placeholder                                             | circlepw\_security\_questions\_question\_placeholder      | regular                | text\_placeholder                                                                                                           |
|           |                ''                |             -             | selected question                                       | -                                                         | regular                | text\_main                                                                                                                  |
| **A25**   |                ''                |      answerTitleLabel     | -                                                       | circlepw\_security\_questions\_answer\_header             | regular                | text\_auxiliary                                                                                                             |
| **A26**   |                ''                |             -             | placeholder                                             | circlepw\_security\_questions\_answer\_placeholder        | regular                | text\_placeholder                                                                                                           |
|           |                ''                |             -             | input text                                              | -                                                         | regular                | text\_main                                                                                                                  |
|           |                ''                |             -             | view                                                    | -                                                         | -                      | input\_background\_disabled / input\_border / input\_border\_focused                                                        |
| **A27**   |                ''                |       hintTitleLabel      | -                                                       | circlepw\_security\_questions\_answer\_hint\_header       | regular                | text\_auxiliary                                                                                                             |
| **A28**   |                ''                |             -             | placeholder                                             | circlepw\_security\_questions\_answer\_hint\_placeholder  | regular                | text\_placeholder                                                                                                           |
|           |                ''                |             -             | input text                                              | -                                                         | regular                | text\_main                                                                                                                  |
|           |                ''                |             -             | view                                                    | -                                                         | -                      | input\_background\_disabled / input\_border / input\_border\_focused                                                        |
| **A29**   |                ''                |      hintWarningLabel     | ApiError(.hintsMatchAnswers)                            | -                                                         | regular                | error                                                                                                                       |
| **A30**   |   SelectQuestionViewController   |     baseNaviTitleLabel    | -                                                       | circlepw\_select\_question\_title                         | medium                 | text\_main                                                                                                                  |
| **A31**   |    SelectQuestionTableViewCell   |         titleLabel        | question list                                           | -                                                         | regular                | text\_main                                                                                                                  |
| **A32**   |   SecuritySummaryViewController  |     baseNaviTitleLabel    | -                                                       | circlepw\_security\_summary\_title                        | medium                 | text\_main                                                                                                                  |
| **A33**   |                ''                |       continueButton      | text                                                    | circlepw\_continue                                        | semibold               | main\_bt\_text / main\_bt\_text\_pressed / main\_bt\_text\_disabled                                                         |
|           |                ''                |                           | background                                              | -                                                         | -                      | main\_bt\_background / main\_bt\_background\_pressed / main\_bt\_background\_disabled                                       |
| **A34**   |   SecuritySummaryTableViewCell   |         titleLabel        | -                                                       | \{ordinal} + circlepw\_question                           | semibold               | text\_main2                                                                                                                 |
| **A35**   |                ''                |     questionTitleLabel    | -                                                       | circlepw\_question + “:”                                  | regular                | text\_auxiliary2                                                                                                            |
| **A36**   |                ''                |             -             | -                                                       | -                                                         | regular                | text\_summary                                                                                                               |
| **A37**   |                ''                |      answerTitleLabel     | -                                                       | circlepw\_answer + “:“                                    | regular                | text\_auxiliary2                                                                                                            |
| **A38**   |                ''                |             -             | -                                                       | -                                                         | semibold               | text\_summary\_highlight                                                                                                    |
| **A39**   |                ''                |       hintTitleLabel      | -                                                       | circlepw\_hint + “:“                                      | regular                | text\_auxiliary2                                                                                                            |
| **A40**   |                ''                |             -             | -                                                       | circlepw\_empty\_placeholder                              | regular                | text\_summary                                                                                                               |
| **A41**   |   SecurityConfirmViewController  |     baseNaviTitleLabel    | -                                                       | circlepw\_security\_confirm\_title                        | medium                 | text\_main                                                                                                                  |
| **A42**   |                ''                |        imageBgView        | -                                                       | -                                                         | -                      | security\_confirm\_main\_bg                                                                                                 |
| **A43**   |                ''                |       tipsTitleLabel      | -                                                       | circlepw\_security\_confirm\_headline                     | medium                 | text\_main                                                                                                                  |
| **A44**   |                ''                |      agreeTitleLabel      | -                                                       | circlepw\_security\_confirm\_input\_headline              | semibold               | text\_main2                                                                                                                 |
| **A45**   |                ''                |       agreeTextField      | placeholder                                             | circlepw\_security\_confirm\_input\_placeholder           | regular                | text\_placeholder                                                                                                           |
|           |                ''                |             ''            | input text                                              | -                                                         | regular                | text\_main2                                                                                                                 |
|           |                ''                |             ''            | view                                                    | -                                                         | -                      | input\_background\_disabled / input\_border / input\_border\_focused                                                        |
| **A46**   |                ''                |       continueButton      | text                                                    | circlepw\_continue                                        | semibold               | main\_bt\_text / main\_bt\_text\_pressed / main\_bt\_text\_disabled                                                         |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | main\_bt\_background / main\_bt\_background\_pressed / main\_bt\_background\_disabled                                       |
| **A47**   |   RecoverPINCodeViewController   |        titleLabel1        | -                                                       | circlepw\_recover\_pincode\_headline                      | semibold               | text\_main                                                                                                                  |
| **A48**   |                ''                |        titleLabel2        | -                                                       | circlepw\_recover\_pincode\_headline\_2                   | bold                   | title\_gradients                                                                                                            |
| **A49**   |                ''                |             -             | shows ApiError.displayString                            | -                                                         | regular                | text\_main                                                                                                                  |
| **A50**   |                ''                |      errorMessageView     | background                                              | -                                                         | -                      | error\_background                                                                                                           |
| **A51**   |                ''                |       confirmButton       | text                                                    | circlepw\_confirm                                         | semibold               | main\_bt\_text / main\_bt\_text\_pressed / main\_bt\_text\_disabled                                                         |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | main\_bt\_background / main\_bt\_background\_pressed / main\_bt\_background\_disabled                                       |
| **A52**   |    RecoverPINCodeTableViewCell   |             -             | -                                                       | -                                                         | regular                | text\_main2                                                                                                                 |
| **A53**   |                ''                |       hintTitleLabel      | text                                                    | circlepw\_hint                                            | regular                | recover\_pin\_hint\_title                                                                                                   |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | recover\_pin\_hint\_title\_bg                                                                                               |
| **A54**   |                ''                |             -             | placeholder                                             | circlepw\_empty\_placeholder                              | regular                | recover\_pin\_hint                                                                                                          |
| **A55**   |                ''                |      answerTitleLabel     | -                                                       | circlepw\_recover\_pincode\_answer\_input\_header         | regular                | text\_auxiliary                                                                                                             |
| **A56**   |                ''                |      answerMarkLabel      | -                                                       | circlepw\_security\_questions\_required\_mark             | regular                | error                                                                                                                       |
| **A57**   |                ''                |             -             | placeholder                                             | circlepw\_recover\_pincode\_answer\_input\_placeholder    | regular                | text\_placeholder                                                                                                           |
|           |                ''                |             -             | input text                                              | -                                                         | regular                | text\_main                                                                                                                  |
|           |                ''                |             -             | view                                                    | -                                                         | -                      | input\_background\_disabled / input\_border / input\_border\_focused                                                        |
| **A58**   |  BiometricsPromptViewController  |      promptTitleLabel     | Set up biometrics first in the process                  | circlepw\_pin\_biometrics\_allow\_title                   | bold                   | text\_prompt                                                                                                                |
| **A60**   |                ''                |             ''            | After first setting up biometrics process               | circlepw\_pin\_biometrics\_failed\_title                  |                        |                                                                                                                             |
| **A62**   |                ''                |             ''            | Update after failure to use biometric PIN               | circlepw\_pin\_biometrics\_update\_title                  |                        |                                                                                                                             |
| **A59**   |                ''                |    promptSubtitleLabel    | Set up biometrics in the process                        | circlepw\_pin\_biometrics\_allow\_subtitle                | regular                | text\_prompt2                                                                                                               |
| **A61**   |                ''                |             ''            | Update after failure to use biometric PIN               | circlepw\_pin\_biometrics\_update\_subtitle               |                        |                                                                                                                             |
| **A63**   |                ''                |         skipButton        | text                                                    | circlepw\_skip                                            | semibold               | second\_bt\_text                                                                                                            |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | second\_bt\_border / second\_bt\_background / second\_bt\_background\_pressed                                               |
| **A64**   |                ''                |       dontAskButton       | text                                                    | circlepw\_pin\_biometrics\_disable                        | semibold               | plain\_bt\_text                                                                                                             |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | plain\_bt\_background / plain\_bt\_background\_pressed                                                                      |
| **A67**   |                 -                |             -             | -                                                       | circlepw\_pin\_touch\_id\_dialog\_subtitle                | -                      | -                                                                                                                           |
| **A68**   |     BaseRequestViewController    |     baseNaviTitleLabel    | -                                                       | circlepw\_transaction\_request\_title                     | medium                 | text\_main                                                                                                                  |
| **A69**   |                ''                |      descriptionLabel     | -                                                       | circlepw\_transaction\_request\_subtitle                  | regular                | text\_auxiliary                                                                                                             |
| **A70**   |                ''                |       confirmButton       | text                                                    | circlepw\_confirm / circlepw\_try\_again                  | semibold               | main\_bt\_text / main\_bt\_text\_pressed / main\_bt\_text\_disabled                                                         |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | main\_bt\_background / main\_bt\_background\_pressed / main\_bt\_background\_disabled                                       |
| **A71**   |                ''                |         errorLabel        | shows ApiError.displayString                            | -                                                         | regular                | error                                                                                                                       |
| **A72**   | TransactionRequestViewController |        amountLabel        | -                                                       | -                                                         | heavy                  | text\_prompt                                                                                                                |
| **A73**   |                ''                |       currencyLabel       | -                                                       | circlepw\_transaction\_request\_main\_currency            | heavy                  | text\_prompt                                                                                                                |
| **A74**   |                ''                |      txFiatValueLabel     | If it has no value, it will be hidden                   | circlepw\_transaction\_request\_exchange\_amount          | semibold               | text\_exchange                                                                                                              |
| **A75**   |                ''                |       fromTitleLabel      | If the fromLabel has no value, it will be hidden        | circlepw\_transaction\_request\_from\_label               | regular                | text\_prompt                                                                                                                |
| **A76**   |                ''                |         fromLabel         | -                                                       | circlepw\_transaction\_request\_from                      | semibold               | text\_prompt                                                                                                                |
| **A77**   |                ''                |        toTitleLabel       | -                                                       | circlepw\_transaction\_request\_to\_label                 | regular                | text\_prompt                                                                                                                |
| **A78**   |                ''                |    toContractNameLabel    | If it has no value, it will be hidden                   | circlepw\_transaction\_request\_to\_contract\_name        | semibold               | text\_prompt                                                                                                                |
| **A79**   |                ''                |     toContractURLLabel    | If it has no value, it will be hidden                   | circlepw\_transaction\_request\_to\_contract\_url         | semibold               | text\_prompt                                                                                                                |
| **A80**   |                ''                |          toLabel          | -                                                       | -                                                         | semibold               | text\_prompt                                                                                                                |
| **A81**   |                ''                |       feeTitleLabel       | If the feeLabel has no value, it will be hidden         | circlepw\_transaction\_request\_network\_fee\_label       | regular                | text\_prompt                                                                                                                |
| **A82**   |                ''                |          feeLabel         | -                                                       | circlepw\_transaction\_request\_network\_fee              | semibold               | text\_prompt                                                                                                                |
| **A83**   |                ''                |     feeFiatValueLabel     | -                                                       | circlepw\_transaction\_request\_exchange\_network\_fee    | regular                | text\_exchange                                                                                                              |
| **A84**   |                ''                |      totalTitleLabel      | If the totalLabel has no value, it will be hidden       | circlepw\_transaction\_request\_total\_label              | regular                | text\_prompt                                                                                                                |
| **A85**   |                ''                |         totalLabel        | -                                                       | -                                                         | semibold               | text\_prompt                                                                                                                |
| **A86**   |                ''                |    totalFiatValueLabel    | If it or the totalLabel has no value, it will be hidden | circlepw\_transaction\_request\_exchange\_total\_value    | regular                | text\_exchange                                                                                                              |
| **A87**   |                ''                |        dividerView1       | -                                                       | -                                                         | -                      | divider                                                                                                                     |
| **A88**   |       FeeTipViewController       |      descriptionLabel     | -                                                       | circlepw\_transaction\_request\_fee\_tip                  | regular                | tip\_text                                                                                                                   |
|           |                ''                |      backgroundColor      | -                                                       | -                                                         | -                      | tip\_background                                                                                                             |
| **A89**   |   ContractRequestViewController  |     baseNaviTitleLabel    | -                                                       | circlepw\_contract\_interaction\_title                    | medium                 | text\_main                                                                                                                  |
| **A90**   |                ''                |      descriptionLabel     | -                                                       | circlepw\_contract\_interaction\_subtitle                 | regular                | text\_auxiliary                                                                                                             |
| **A91**   |                ''                | contractAddressTitleLabel | -                                                       | circlepw\_contract\_interaction\_contract\_address\_label | regular                | text\_prompt                                                                                                                |
| **A92**   |                ''                |    contractAddressLabel   | -                                                       | -                                                         | semibold               | text\_prompt                                                                                                                |
| **A93**   |                ''                |        dividerView2       | -                                                       | -                                                         | -                      | divider                                                                                                                     |
| **A94**   |                ''                |      dataDetailsLabel     | -                                                       | circlepw\_contract\_interaction\_data\_details            | semibold               | text\_prompt                                                                                                                |
| **A95**   |                ''                |   abiFunctionTitleLabel   | -                                                       | circlepw\_contract\_interaction\_abi\_function\_label     | regular                | text\_prompt                                                                                                                |
| **A96**   |                ''                |      abiFunctionLabel     | -                                                       | -                                                         | semibold               | text\_prompt                                                                                                                |
| **A97**   |                ''                |   abiParameterTitleLabel  | -                                                       | circlepw\_contract\_interaction\_abi\_parameter\_label    | regular                | text\_prompt                                                                                                                |
| **A98**   |                ''                |     abiParameterLabel     | text                                                    | -                                                         | regular                | text\_interactive                                                                                                           |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | interactive\_background                                                                                                     |
| **A99**   |                ''                |     callDataTitleLabel    | -                                                       | circlepw\_contract\_interaction\_call\_data\_label        | regular                | text\_prompt                                                                                                                |
| **A100**  |                ''                |       callDataLabel       | text                                                    | -                                                         | regular                | text\_interactive                                                                                                           |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | interactive\_background                                                                                                     |
| **A101**  |  SignatureRequestViewController  |         titleLabel        | -                                                       | circlepw\_signature\_request\_title                       | semibold               | text\_main                                                                                                                  |
| **A102**  |                ''                |     contractNameLabel     | If it has no value, it will be hidden                   | circlepw\_signature\_request\_contract\_name              | semibold               | text\_prompt                                                                                                                |
| **A103**  |                ''                |      contractURLLabel     | If it has no value, it will be hidden                   | circlepw\_signature\_request\_contract\_name              | regular                | text\_sign\_url                                                                                                             |
| **A104**  |                ''                |        dividerView        | -                                                       | -                                                         | -                      | divider                                                                                                                     |
| **A105**  |                ''                |       subtitleLabel       | -                                                       | circlepw\_signature\_request\_subtitle                    | regular                | text\_auxiliary                                                                                                             |
| **A106**  |                ''                |      descriptionLabel     | -                                                       | circlepw\_signature\_request\_description                 | regular                | text\_auxiliary                                                                                                             |
| **A107**  |                ''                |        messageLabel       | -                                                       | -                                                         | regular                | text\_auxiliary                                                                                                             |
| **A108**  |                ''                |         errorLabel        | shows ApiError.displayString                            | -                                                         | regular                | error                                                                                                                       |
| **A109**  |                ''                |       confirmButton       | text                                                    | circlepw\_confirm / circlepw\_try\_again                  | semibold               | main\_bt\_text / main\_bt\_text\_pressed / main\_bt\_text\_disabled                                                         |
|           |                ''                |             ''            | background                                              | -                                                         | -                      | main\_bt\_background / main\_bt\_background\_pressed / main\_bt\_background\_disabled                                       |
| **A110**  |      EmailOTPViewController      |     baseNaviTitleLabel    | -                                                       | circlepw\_email\_otp\_title                               | medium                 | text\_main                                                                                                                  |
| **A111**  |                ''                |      descriptionLabel     | -                                                       | circlepw\_email\_otp\_description                         | regular                | text\_auxiliary                                                                                                             |
| **A112**  |                ''                |                           | -                                                       | circlepw\_email\_otp\_email                               |                        |                                                                                                                             |
| **A113**  |                ''                |        otpHeadLabel       | -                                                       | -                                                         | regular                | text\_prompt                                                                                                                |
| **A114**  |                ''                |        otpDashLabel       | -                                                       | circlepw\_email\_otp\_dash                                | regular                | text\_prompt                                                                                                                |
| **A115**  |                ''                |             -             | texts will be generated dynamically                     | -                                                         | light                  | pin\_dot\_base / pin\_dot\_base\_border / pin\_dot\_focused / pin\_digit\_activated / success / error                       |
| **A116**  |                ''                |     sendAgainHintLabel    | -                                                       | circlepw\_email\_otp\_send\_again\_hint                   | regular                | text\_auxiliary                                                                                                             |
| **A117**  |                ''                |      sendAgainButton      | -                                                       | circlepw\_email\_otp\_send\_again                         | regular                | text\_action / text\_action\_pressed                                                                                        |
| **A118**  |                ''                |     errorMessageLabel     | shows ApiError.displayString                            | -                                                         | regular                | error                                                                                                                       |

## Index Table B

By confirming the `WalletSdkLayoutProvider`, you can custom layout from Table-B
dynamically. See the
[Sample Code](https://circlepay.atlassian.net/wiki/spaces/~62e7eea5da8620d53392126b/pages/767852579/PW+SDK+UI+Customization+-+iOS#WalletSdkLayoutProvider "https://circlepay.atlassian.net/wiki/spaces/~62e7eea5da8620d53392126b/pages/767852579/PW+SDK+UI+Customization+-+iOS#WalletSdkLayoutProvider").

| **#**  | **WalletSdkLayoutProvider**                           | **Note**                                                                                                                                            |
| :----- | :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| **B1** | func securityQuestions() -> \[SecurityQuestion]       | Set security question list                                                                                                                          |
| **B2** | func securityQuestionsRequiredCount() -> Int          | Set security question required count (default is 2)                                                                                                 |
| **B3** | func securityConfirmItems() -> \[SecurityConfirmItem] | Set security confirm item list                                                                                                                      |
| **B4** | func displayDateFormat() -> String                    | Set the date format for display date strings. (Default is "yyyy-MM-dd")                                                                             |
| **-**  | func imageStore() -> ImageStore                       | Set local and remote images (more details in **Table-C**)                                                                                           |
| **-**  | func themeFont() -> ThemeConfig.ThemeFont?            | Set theme font programmatically- Provide the ThemeFont structure by code. - This method will override the font setups in CirclePWTheme.json file. - |

## Index Table C

|         | **Used in WalletSdkLayoutProvider** | **Used in WalletSdkDelegate**                                 |                                |
| ------- | ----------------------------------- | ------------------------------------------------------------- | ------------------------------ |
| **#**   | **ImageStore.Img (Enum)**           | **Controller**                                                | **Item**                       |
| **C1**  | naviClose                           | -                                                             | -                              |
| **C2**  | naviBack                            | -                                                             | -                              |
| **C3**  | securityIntroMain                   | SecurityIntrosViewController                                  | introImageView                 |
| **C4**  | dropdownArrow                       | SecurityQuestionTableViewCell                                 | questionTrailingButton         |
| **C5**  | selectCheckMark                     | SelectQuestionTableViewCell                                   | checkmarkImage                 |
| **C6**  | securityConfirmMain                 | SecurityConfirmViewController                                 | imageView                      |
| **C7**  | errorInfo                           | RecoverPINCodeViewController                                  | errorImageView                 |
| **C8**  | showPin                             | BasePINInputViewController <br />(NewPIN/ConfirmPIN/EnterPIN) | showPINButton (normal state)   |
| **C9**  | hidePin                             | BasePINInputViewController <br />(NewPIN/ConfirmPIN/EnterPIN) | showPINButton (selected state) |
| **C10** | biometricsAllowMain                 | BiometricsPromptViewController                                | imageView                      |
| **C11** | transactionTokenIcon                | TransactionRequestViewController                              | tokenSymbol                    |
| **C12** | networkFeeTipIcon                   | TransactionRequestViewController                              | feeTipIcon                     |
| **C13** | showLessDetailArrow                 | ContractRequestViewController                                 | showLessMoreDetailButton       |
| **C14** | showMoreDetailArrow                 | ContractRequestViewController                                 | showLessMoreDetailButton       |
| **C15** | requestIcon                         | SignatureRequestViewController                                | requestIcon                    |

* Use the `ImageStore.Img (Enum)` column to customize with the
  `WalletSdkLayoutProvider`:

```swift Swift theme={null}
func imageStore() -> ImageStore {
    let local: [ImageStore.Img: UIImage] = [
        .naviBack: UIImage(named: "ic_navi_back")!,
        .naviClose: UIImage(named: "ic_navi_close")!,
        .selectCheckMark: UIImage(named: "ic_checkmark")!,
        .dropdownArrow: UIImage(named: "ic_trailing_down")!,
        .errorInfo: UIImage(named: "ic_warning_alt")!,
        .securityIntroMain: UIImage(named: "img_security_intro")!,
        .securityConfirmMain: UIImage(named: "img_driver_blog")!,
        .biometricsAllowMain: UIImage(named: "ic_biometrics")!,
        .hidePin: UIImage(named: "eye_closed")!,
        .showPin: UIImage(named: "eye_open")!,
        .transactionTokenIcon: UIImage(named: "BTC")!,
        .networkFeeTipIcon: UIImage(named: "BTC")!,
        .showLessDetailArrow: UIImage(named: "chevron-up")!,
        .showMoreDetailArrow: UIImage(named: "chevron-down")!,
        .requestIcon: UIImage(named: "dApp_icon")!,
    ]

    let remote: [ImageStore.Img: URL] = [
        .securityIntroMain: URL(string: "https://www.circle.com/hs-fs/hubfs/Sundaes/810/global-payments-810x810.png")!,
        .securityConfirmMain: URL(string: "https://www.circle.com/hs-fs/hubfs/Sundaes/810/Trust-810x810.png")!,
    ]

    return ImageStore(local: local, remote: remote)
}
```

* If you set both local and remote images, the remote image will present after
  the image loads, and the local image will be set as the placeholder image.
* The remote image formats supported include those from the Apple system (JPEG,
  PNG, TIFF, BMP, etc.), GIF, and APNG animated images.
* The remote image formats unsupported for new image formats include HEIC, BPG,
  AVIF, and vector formats such as PDF and SVG.
* The **Controller** and **Item** column shows where the images are used.\
  Refer to the UI items If you have special customizations with
  `WalletSdkDelegate` (not recommended)

## Static Resources

This section describes how to customize the UI for iOS statically.

<Note>
  **Note:**

  Circle recommends customizing the UI using static files.

  You can copy the icon images from the
  [Sample Project](https://github.com/circlefin/w3s-ios-sample-app-wallets).
</Note>

## Assets

Because the `CircleProgrammableWalletSDK` does not contain any image resources
for the SDK; you must provide the icon images from either local assets or remote
URLs.

<Warning>
  **Important:**

  Setting the `WalletSdkLayoutProvider.imageStore` in `WalletSdkLayoutProvider` is
  required for you to see icons in the layouts.
</Warning>

## CirclePWLocalizable.strings

### Setup

1. Create a file **CirclePWLocalizable.strings** in your main bundle.
2. Provide your strings. Partial override is supported.

<Note>
  **Note:**

  You can provide specific keys and values you want to override and others keys
  will still refer to the default values.
</Note>

<Frame>
  <img />
</Frame>

3. Localization is supported. For more information, see
   [Localization | Apple Developer Documentation](https://developer.apple.com/documentation/Xcode/localization/ "https://developer.apple.com/documentation/Xcode/localization/").

<Frame>
  <img />
</Frame>

## Example CirclePWLocalizable.strings

```swift Swift theme={null}
/*
 * Loco ios export: iOS Localizable.strings
 * Project: strings.xml conversion
 * Release: Working copy
 * Locale: en, English
 * Exported by: Circle
 * Exported at: Tue, 27 Jun 2023 23:35:22 +0800
 */

// [General]
"circlepw_continue" = "Continue";
"circlepw_next" = "Next";
"circlepw_confirm" = "Confirm";
"circlepw_skip" = "Skip";
"circlepw_sign" = "Sign";
"circlepw_try_again" = "Try Again";

"circlepw_question" = "Question";
"circlepw_answer" = "Answer";
"circlepw_hint" = "Hint";
"circlepw_empty_placeholder" = "-";

// [Page] EnterPINCode
"circlepw_enter_pincode_headline" = "Enter your";
"circlepw_enter_pincode_headline_2" = "Web3 PIN";
"circlepw_enter_pincode_subhead" = "Let us know if it's really you.";
"circlepw_enter_pincode_forgot_pin" = "Forgot PIN?";

// [Page] NewPINCode
"circlepw_new_pincode_headline" = "Enter your new";
"circlepw_new_pincode_headline_2" = "Web3 PIN";
"circlepw_new_pincode_subhead" = "Your PIN can't have repeating (e.g. 000000) or consecutive (e.g. 123456) numbers.";

// [Page] ConfirmPINCode
"circlepw_confirm_pincode_headline" = "Re-enter your PIN to confirm";
"circlepw_confirm_pincode_headline_2" = "";
"circlepw_confirm_pincode_subhead" = "";

// [Page] SecurityIntros
"circlepw_security_intros_headline" = "Set up your";
"circlepw_security_intros_headline_2" = "Recovery Method";
"circlepw_security_intros_description" = "This is the only way to recover wallet access if you forget your PIN. Pick 2 security questions and provide answers for access recovery.";
"circlepw_security_intros_link" = "Learn more";

// [Page] SecurityQuestions
"circlepw_security_questions_title" = "Recovery method";
"circlepw_security_questions_question_header" = "Choose your %@ question";
"circlepw_security_questions_question_placeholder" = "Select one question";
"circlepw_security_questions_required_mark" = "*";
"circlepw_security_questions_answer_header" = "Provide an answer";
"circlepw_security_questions_answer_placeholder" = "Type your answer here";
"circlepw_security_questions_answer_hint_header" = "Provide an answer hint (optional)";
"circlepw_security_questions_answer_hint_placeholder" = "Type your hint here";

// [Page] SelectQuestion
"circlepw_select_question_title" = "Select one question";

// [Page] SecuritySummary
"circlepw_security_summary_title" = "Summary";

// [Page] SecurityConfirm
"circlepw_security_confirm_title" = "Confirmation";
"circlepw_security_confirm_headline" = "Keep your questions safe";
"circlepw_security_confirm_input_headline" = "Type “I agree” to proceed:";
"circlepw_security_confirm_input_placeholder" = "Type “I agree” here";
"circlepw_security_confirm_input_match" = "I agree";

// [Page] RecoverPINCode
"circlepw_recover_pincode_headline" = "Recover your";
"circlepw_recover_pincode_headline_2" = "Web3 PIN";
"circlepw_recover_pincode_subhead" = "Please enter the answer of the security questions provided below.";
"circlepw_recover_pincode_answer_input_header" = "Enter your answer here";
"circlepw_recover_pincode_answer_input_placeholder" = "Type your answer here";

// [Page] BiometricsPrompt
"circlepw_pin_biometrics_allow_title" = "Allow Biometrics for Web3 Access";
"circlepw_pin_biometrics_allow_subtitle" = "Elevate Your Experience with Effortless Biometrics";
"circlepw_pin_biometrics_failed_title" = "Failed Biometrics for Web3 Access";
"circlepw_pin_biometrics_update_title" = "Update Biometrics for Web3 Access";
"circlepw_pin_biometrics_update_subtitle" = "Please update your biometrics";
"circlepw_pin_biometrics_disable" = "Don't ask me again";
"circlepw_pin_touch_id_dialog_subtitle" = "Using Touch ID protect PIN";

// [Page] EmailOTP
"circlepw_email_otp_title" = "Enter verification code";
"circlepw_email_otp_description" = "The one-time passcode has been sent to";
"circlepw_email_otp_email" = "your email";
"circlepw_email_otp_dash" = "-";
"circlepw_email_otp_send_again_hint" = "Didn't receive the code?";
"circlepw_email_otp_send_again" = "Send again";

// [Page] SignatureRequest
"circlepw_signature_request_title" = "Signature Request";
"circlepw_signature_request_subtitle" = "Click on sign button to provide a signature for verification";
"circlepw_signature_request_contract_name" = "";
"circlepw_signature_request_contract_url" = "";
"circlepw_signature_request_description" = "You are signing:";

// [Page] TransactionRequest
"circlepw_transaction_request_title" = "Confirm Transaction";
"circlepw_transaction_request_subtitle" = "Please click confirm to proceed the transaction";
"circlepw_transaction_request_main_currency" = "";
"circlepw_transaction_request_exchange_amount" = "";
"circlepw_transaction_request_from_label" = "From";
"circlepw_transaction_request_from" = "";
"circlepw_transaction_request_to_label" = "To";
"circlepw_transaction_request_to_contract_name" = "";
"circlepw_transaction_request_to_contract_url" = "";
"circlepw_transaction_request_network_fee_label" = "Est. Network Fee";
"circlepw_transaction_request_network_fee" = "";
"circlepw_transaction_request_exchange_network_fee" = "";
"circlepw_transaction_request_total_label" = "Total";
"circlepw_transaction_request_exchange_total_value" = "";

// [View] FeeTip
"circlepw_transaction_request_fee_tip" = "Please note this is an estimated fee. Network fees may vary based on network traffic and transaction complexity.";

// [Page] RawTransactionRequest
"circlepw_transaction_request_raw_tx_description" = "Transaction details:";

// [Page] ContractRequest
"circlepw_contract_interaction_title" = "Contract Interaction";
"circlepw_contract_interaction_subtitle" = "Please click confirm to proceed the  contract execution";
"circlepw_contract_interaction_contract_address_label" = "Contract address";
"circlepw_contract_interaction_data_details" = "Data Details";
"circlepw_contract_interaction_abi_function_label" = "ABI Function";
"circlepw_contract_interaction_abi_parameter_label" = "ABI Parameters";
"circlepw_contract_interaction_call_data_label" = "Call Data";
```

## CirclePWTheme.json

### Setup

* Copy the file **CirclePWTheme.json** into your main bundle. You can use
  `Cmd + drag and drop`.

<Frame>
  <img />
</Frame>

* Make sure you have selected the `Target Membership`.

<Frame>
  <img />
</Frame>

* Provide values to set the **font**: To use a custom font, refer to this
  document:
  [Adding a Custom Font to Your App | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app "https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app").

* Set the **color** with a hex string:

### Example: CirclePWTheme.json

```json JSON theme={null}
{
  "font": {
    "ultraLight": "",
    "thin": "",
    "light": "",
    "regular": "CustomFont-Regular",
    "medium": "CustomFont-Medium",
    "semibold": "",
    "bold": "",
    "heavy": "",
    "black": ""
  },
  "color": {
    "background": "#FFFFFF",
    "divider": "#F0EFEF",
    "success": "#0B9C4A",
    "error": "#F55538",
    "error_background": "#FDF2F2",

    "text_main": "#1A1A1A",
    "text_main2": "#1C1C1C",
    "text_auxiliary": "#3D3D3D",
    "text_auxiliary2": "#707070",
    "text_summary": "#0073C3",
    "text_summary_highlight": "#0073C3",
    "text_placeholder": "#A3A3A3",
    "text_action": "#136FD8",
    "text_action_pressed": "#B3136FD8",
    "text_prompt": "#29233B",
    "text_prompt2": "#6B6580",
    "text_exchange": "#979797",
    "text_interactive": "#0073C3",
    "text_sign_url": "#8E8E93",

    "pin_dot_base": "#FFFFFF",
    "pin_dot_base_border": "#707070",
    "pin_dot_activated": "#3D3D3D",
    "pin_dot_focused": "#0073C3",
    "pin_digit_activated": "#3D3D3D",

    "input_border": "#E8E8E8",
    "input_border_focused": "#46B5FF",
    "input_background_disabled": "#F5F5F5",

    "main_bt_text": "#FFFFFF",
    "main_bt_text_pressed": "#80FFFFFF",
    "main_bt_text_disabled": "#BFBFBF",
    "main_bt_background": "#0073C3",
    "main_bt_background_pressed": "#1AA3FF",
    "main_bt_background_disabled": "#F5F5F5",

    "second_bt_text": "#0073C3",
    "second_bt_border": "#0073C3",
    "second_bt_background": "#FFFFFF",
    "second_bt_background_pressed": "#F1F9FE",

    "plain_bt_text": "#0073C3",
    "plain_bt_background": "#FFFFFF",
    "plain_bt_background_pressed": "#F1F9FE",

    "recover_pin_hint_title": "#3D3652",
    "recover_pin_hint_title_bg": "#E1F2FF",
    "recover_pin_hint": "#0073C3",

    "security_confirm_main_bg": "#E9EEFE",

    "tip_text": "#FFFFFF",
    "tip_background": "#29233B",

    "interactive_background": "#F9F9FC",

    "title_gradients": ["#0073C3", "#0073C3"]
  }
}
```

## Programmatic Customization

To programmatically customize the UI refers to the following documents:

* The corresponding rendered layout and the notes on
  [Index Table B](#index-table-b).
* The [Programmable Wallet iOS SDK](/wallets/user-controlled/ios-sdk) .

## Example Code

```swift Swift theme={null}
extension WalletSdkAdapter: WalletSdkLayoutProvider {

    func securityQuestions() -> [SecurityQuestion] {
        return [
            SecurityQuestion(title: "What is your childhood nickname?", inputType: .text),
            SecurityQuestion(title: "What is the middle name of your oldest child?", inputType: .text),
            SecurityQuestion(title: "What is your favorite team?", inputType: .text),
            SecurityQuestion(title: "When was your birthday?", inputType: .datePicker),
            SecurityQuestion(title: "When is your marriage anniversary?", inputType: .datePicker),
        ]
    }

    func securityQuestionsRequiredCount() -> Int {
        return 2
    }

    func securityConfirmItems() -> [SecurityConfirmItem] {
        return [
            SecurityConfirmItem(image: UIImage(named: "img_info"),
                                text: "This is the only way to recover my account access."),
            SecurityConfirmItem(image: UIImage(named: "img_claim_success"),
                                text: "Circle won't store my answers so it's my responsibility to remember them."),
            SecurityConfirmItem(image: UIImage(named: "img_claim_success"),
                                text: "I will lose access to my wallet and my digital assets if I forget my answers."),
        ]
    }

    func displayDateFormat() -> String {
        return "yyyy/MM/dd"
    }

    func imageStore() -> ImageStore {
        let local: [ImageStore.Img: UIImage] = [
            .naviBack: UIImage(named: "ic_navi_back")!,
            .naviClose: UIImage(named: "ic_navi_close")!,
            .selectCheckMark: UIImage(named: "ic_checkmark")!,
            .dropdownArrow: UIImage(named: "ic_trailing_down")!,
            .errorInfo: UIImage(named: "ic_warning_alt")!,
            .securityIntroMain: UIImage(named: "img_security_intro")!,
            .securityConfirmMain: UIImage(named: "img_driver_blog")!
        ]

        let remote: [ImageStore.Img: URL] = [
            .securityIntroMain: URL(string: "https://www.circle.com/hs-fs/hubfs/Sundaes/810/global-payments-810x810.png")!,
            .securityConfirmMain: URL(string: "https://www.circle.com/hs-fs/hubfs/Sundaes/810/Trust-810x810.png")!,
        ]

        return ImageStore(local: local, remote: remote)
    }

    func themeFont() -> ThemeConfig.ThemeFont? {
        return ThemeConfig.ThemeFont(
            ultraLight: nil,
            thin: nil,
            light: "CustomFont-Light",
            regular: "CustomFont-Regular",
            medium: "CustomFont-Medium",
            semibold: "CustomFont-SemiBold",
            bold: "CustomFont-Bold",
            heavy: nil,
            black: nil
        )
    }
}
```

## WalletSdkDelegate

By modifying the `WalletSdkDelegate`, you can get the current view controller
and control the UI parameters in the controller at run time.

```swift Swift theme={null}
public protocol WalletSdkDelegate: AnyObject {

    /// Tells the delegate that the SDK is about to be presented in the controller.
    /// You can customize the layout as you wish dynamically.
    ///
    /// - Parameter controller: The UIViewController to be presented
    func walletSdk(willPresentController controller: UIViewController)

    ...
}
```

### Example Code

```swift Swift theme={null}
extension WalletSdkAdapter: WalletSdkDelegate {

    func walletSdk(willPresentController controller: UIViewController) {
        print("willPresentController: \(controller)")

        if let controller = controller as? NewPINCodeViewController {
            controller.titleLabel1.text = "Hello World"
            controller.titleLabel1.textColor = .blue
            controller.titleLabel1.font = .systemFont(ofSize: 28, weight: .black)

        }

        if let controller = controller as? SecurityConfirmViewController {
            controller.imageBgView.backgroundColor = .blue
            controller.imageView.contentMode = .scaleAspectFill
        }
    }

    ...
}
```

### View Public Interface

Use Jump to Definition (`Cmd + left click`) to see the public interface of the
view controller. Change the UI items as you need.

#### Jump to Definition

<Frame>
  <img />
</Frame>

#### Public Interface

<Frame>
  <img />
</Frame>

## ErrorMessenger

##  `ApiError` Interface

```swift Swift theme={null}
public struct ApiError: Error {

    public let errorCode: ErrorCode

    /// Error string from the SDK
    public let errorString: String

    /// Error string for UI display
    public var displayString: String
}
```

By modifying the `ErrorMessenger`, you can customize the `ApiError` messages.
Your customization replaces the default `ApiError.displayString` for UI usage.
You can also manage the localized error message.

```swift Swift theme={null}
public protocol ErrorMessenger {

    func getErrorString(_ code: ApiError.ErrorCode) -> String?
}

```

### Example Code

```swift Swift theme={null}
import CircleProgrammableWalletSDK

class MyErrorMessenger: ErrorMessenger {

    func getErrorString(_ code: ApiError.ErrorCode) -> String? {
        switch code {
        case .hintsMatchAnswers:
            return "Your custom error message."

        case .networkError:
            return "Your custom error message."

        default:
            return nil
        }
    }
}

// ============ setErrorMessenger ============

WalletSdk.shared.setErrorMessenger(MyErrorMessenger())
```

## ErrorCode and Messages Table

The following table shows the `ApiError.ErrorCode` key names and their default
values:

| ApiError.ErrorCode                          | Default Value                                                                                                                                                                      |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| unknown(-1)                                 | Unknown error                                                                                                                                                                      |
| success(0)                                  | Success                                                                                                                                                                            |
| apiParameterMissing(1)                      | API parameter missing                                                                                                                                                              |
| apiParameterInvalid(2)                      | API parameter invalid                                                                                                                                                              |
| forbidden(3)                                | Forbidden                                                                                                                                                                          |
| unauthorized(4)                             | Unauthorized                                                                                                                                                                       |
| retry(9)                                    | Retry                                                                                                                                                                              |
| customerSuspended(10)                       | Customer suspended                                                                                                                                                                 |
| pending(11)                                 | Pending                                                                                                                                                                            |
| invalidSession(12)                          | Invalid session                                                                                                                                                                    |
| invalidPartnerId(13)                        | Invalid partner ID                                                                                                                                                                 |
| invalidMessage(14)                          | Invalid Message published to a SQS queue.                                                                                                                                          |
| invalidPhone(15)                            | Invalid phone number %@                                                                                                                                                            |
| walletIdNotFound(156001)                    | \<server definition>                                                                                                                                                               |
| tokenIdNotFound(156002)                     | \<server definition>                                                                                                                                                               |
| transactionIdNotFound(156003)               | \<server definition>                                                                                                                                                               |
| entityCredentialNotFound(156004)            | \<server definition>                                                                                                                                                               |
| walletSetIdNotFound(156005)                 | \<server definition>                                                                                                                                                               |
| userAlreadyExisted(155101)                  | user already existed                                                                                                                                                               |
| userNotFound(155102)                        | user not found                                                                                                                                                                     |
| userTokenNotFound(155103)                   | user token not found                                                                                                                                                               |
| userTokenExpired(155104)                    | user token expired                                                                                                                                                                 |
| invalidUserToken(155105)                    | invalid user token                                                                                                                                                                 |
| userWasInitialized(155106)                  | user was initialized                                                                                                                                                               |
| userHasSetPin(155107)                       | user has set pin                                                                                                                                                                   |
| userHasSetSecurityQuestion(155108)          | user has set security question                                                                                                                                                     |
| userWasDisabled(155109)                     | user was disabled                                                                                                                                                                  |
| userDoesNotSetPinYet(155110)                | user does not set pin yet                                                                                                                                                          |
| userDoesNotSetSecurityQuestionYet(155111)   | user does not set security questions yet                                                                                                                                           |
| incorrectUserPin(155112)                    | The PIN you entered is incorrect. You have %@ attempts left.                                                                                                                       |
| incorrectDeviceId(155113)                   | incorrect device id                                                                                                                                                                |
| incorrectAppId(155114)                      | app id not found                                                                                                                                                                   |
| incorrectSecurityAnswers(155115)            | The answers you entered are incorrect. You have %@ attempts left.                                                                                                                  |
| invalidChallengeId(155116)                  | invalid challenge id                                                                                                                                                               |
| invalidApproveContent(155117)               | invalid approve content                                                                                                                                                            |
| invalidEncryptionKey(155118)                | invalid encryption key                                                                                                                                                             |
| userPinLocked(155119)                       | You've used up all PIN attempts. Please wait for %@ mins to retry later.                                                                                                           |
| securityAnswersLocked(155120)               | The answers you entered are incorrect. Please wait for %@ mins to retry again.                                                                                                     |
| walletIsFrozen(155501)                      | Wallet is Frozen                                                                                                                                                                   |
| maxWalletLimitReached(155502)               | Max wallet limit reached                                                                                                                                                           |
| walletSetIdMutuallyExclusive(155503)        | WalletSetId can not be used together with blockchain and address filter                                                                                                            |
| metadataUnmatched(155504)                   | metadata array length does not match wallet count                                                                                                                                  |
| userCanceled(155701)                        | User canceled                                                                                                                                                                      |
| launchUiFailed(155702)                      | \<Launch UI failed reason>                                                                                                                                                         |
| pinCodeNotMatched(155703)                   | The PIN you entered is not the same as the first one.                                                                                                                              |
| insecurePinCode(155704)                     | Your PIN can't have repeating or consecutive numbers.                                                                                                                              |
| hintsMatchAnswers(155705)                   | Your hint can't be the same as the answer.                                                                                                                                         |
| networkError(155706)                        | Network error                                                                                                                                                                      |
| biometricsSettingNotEnabled(155708)         | Biometrics is disabled                                                                                                                                                             |
| deviceNotSupportBiometrics(155709)          | System doesn't support biometrics                                                                                                                                                  |
| biometricsKeyPermanentlyInvalidated(155710) | (Android only) Failed to decrypt biometrics key                                                                                                                                    |
| biometricsUserSkip(155711)                  | The user has not enabled biometrics yet                                                                                                                                            |
| biometricsUserDisableForPin(155712)         | The user refused to enable biometrics                                                                                                                                              |
| biometricsUserLockout(155713)               | (Android only) Too many requests. Try again later.                                                                                                                                 |
| biometricsUserLockoutPermanent(155714)      | Too many requests. The biometrics sensor on the device is locked.                                                                                                                  |
| biometricsUserNotAllowPermission(155715)    | Biometrics is not permitted by the user.                                                                                                                                           |
| biometricsInternalError(155716)             | Unexpected error for biometrics: %@                                                                                                                                                |
| invalidUserSecret(155718)                   | User token format is invalid. Please ensure the format of the user token is correct, then perform login and execute the challenge again.                                           |
| userTokenMismatch(155719)                   | User token and SDK API execute function do not match. Ensure that `executeWithUserSecret` is for users with SSO/Email auth method and `execute` is for users with PIN auth method. |
| socialLoginFailed(155720)                   | Social login is failed. The social provider returns failed during the execution of social login flow. Please refer to the error message for more details.                          |
| loginInfoMissing(155721)                    | Login info is missing. Please perform login and execute the challenge again.                                                                                                       |
| walletIdNotFound(156001)                    | The specified wallet does not exist, or is not visible to the caller. Try the request again with a valid wallet ID.                                                                |
| tokenIdNotFound(156002)                     | The specified token does not exist, or is not visible to the caller. Try the request again with a valid token ID.                                                                  |
| transactionIdNotFound(156003)               | The specified transaction does not exist, or is not visible to the caller. Try the request again with a valid transaction ID.                                                      |
| entityCredentialNotFound(156004)            | Reusing an entity secret ciphertext is not allowed. Please re-encrypt the entity secret to generate a new ciphertext and try again.                                                |
| walletSetIdNotFound(156005)                 | The specified wallet set does not exist, or is not visible to the caller. Try the request again with a valid wallet set.                                                           |


# React Native SDK
Source: https://developers.circle.com/wallets/user-controlled/react-native-sdk

Set up the client-side React Native SDK for user-controlled wallets in your mobile application.

<Note>
  Expo support and dependencies were introduced in V2. This latest release
  applies to V2 and newer versions. For V1 instructions, see [React Native SDK
  V1 (Legacy)](/wallets/user-controlled/react-native-sdk-v1).
</Note>

The Circle React Native SDK enables your mobile application to provide
user-controlled wallets. The SDK supports multiple authentication methods:
social login (Google, Facebook, Apple), email OTP, and PIN with security
questions. Sensitive inputs, such as PINs and security answers, are encrypted by
the SDK and never exposed to your app or backend.

The SDK enforces end-to-end security and supports UX customization for your
end-users. See the
[React Native SDK UI Customization API](/wallets/user-controlled/react-native-sdk-ui-customization-api)
for details.

## SDK architecture

You must use Web, iOS, Android or React Native SDKs to access the
user-controlled Programmable Wallet product. The SDK secures, manages, and
communicates with your server to ensure your user keys are not exposed.

<Info>
  The Web and Mobile SDKs ensure that the user keyshare remains with the
  individual, so the user stays in full control. These SDKs only work with
  user-controlled wallets.
</Info>

To learn more, see
[SDK Architecture for User-Controlled Wallets](/wallets/user-controlled/sdk-architecture).

## Installation and Setup

Follow the
[installation guide](https://github.com/circlefin/w3s-react-native-sdk) on
GitHub to install and configure the React Native SDK for your Expo or React
Native project. The guide also includes migration instructions if you need to
upgrade from a previous version.

## Social Login Configuration

To use social login with the React Native SDK, additional platform-specific
configuration is required. It's not necessary to configure all providers. Follow
only the sections relevant to the providers you plan to support.

<Note>
  For Expo projects, if you haven't generated the native `android` and `ios`
  folders yet, run `npx expo prebuild` first before configuring social login or
  other native settings.
</Note>

### Prerequisites

1. Follow the instructions to obtain IDs from social providers:
   1. **Google**
      1. Visit the [Firebase console](https://console.firebase.google.com/) to
         create a Firebase project. For detailed steps, see
         [View instructions to create a Firebase project](https://firebase.google.com/docs/android/setup#create-firebase-project).
      2. Add an **Android app** to your project:
         1. Go to **Project Settings → Your apps**
         2. Click **Add app → Select Android**
         3. Download the `google-services.json` (required for Google Sign-In on
            Android) For detailed steps, see
            [Register your app with Firebase](https://firebase.google.com/docs/android/setup#register-app).
      3. Add an **iOS app** to your project:
         1. Go to **Project Settings → Your apps**
         2. Click **Add app → Select iOS**
         3. Download the `GoogleService-Info.plist`
         4. Open the file and copy the following values:
            1. `CLIENT_ID`: used in `app.json` (Expo) or `Info.plist` (React
               Native)
            2. `REVERSED_CLIENT_ID`: used in `Info.plist` URL schemes (React
               Native only, auto-generated for Expo)
      4. Enable Google Sign-In:
         1. Under **Product categories**, navigate to\
            **Build → Authentication → Sign-in method** tab
         2. Select **Google**, enable it, and click **Save**.
      5. Get your **Web client ID**:
         1. Open the **Google** provider again
         2. In the **Web SDK configuration** panel, copy the **Web client ID**
   2. **Facebook**
      1. Go to the [Meta for Developers Site](https://developers.facebook.com/)
         and create a new Facebook app.
      2. In the app settings, add both iOS and Android platforms.
      3. Note down the following values:
         1. Facebook App ID
         2. Facebook Client Token (**Settings → Advanced**)
         3. Facebook Display Name
   3. **Apple**
      1. Follow
         [Register a Services ID](https://developer.apple.com/help/account/identifiers/register-a-services-id)
         and note down the **Service ID** for **Sign in with Apple on Android**.

2. Configure
   [Social Logins in Circle Developer Console](https://console.circle.com/wallets/user/configurator/authentication-methods/social-logins)
   with the social provider IDs.

### iOS

<Note>
  Social login can be configured using one of the following approaches:

  * **Expo config plugin (recommended):** Uses config plugins to automatically
    configure iOS native settings during `npx expo prebuild`; requires custom
    AppDelegate modification for Facebook SDK initialization.
  * **Manual native configuration:** You can manually update the native iOS
    project by following the steps in the **React Native** tab. Keep in mind that
    Expo prebuild regenerates native files, so manual changes must be reapplied
    after each run.
</Note>

<Tabs>
  <Tab title="Expo">
    #### Step 1: Configure plugins in app.json

    Add the following configuration to your `app.json` or `app.config.js` file.

    <Note>
      This assumes you have already configured the basic SDK plugins
      (`podfile-modifier`, `withCopyFiles`) during the [Installation and
      Setup](/wallets/user-controlled/react-native-sdk#installation-and-setup)
      section.
    </Note>

    Complete plugins configuration example:

    ```json theme={null}
    {
      "expo": {
        "plugins": [
          "@circle-fin/w3s-pw-react-native-sdk/plugins/podfile-modifier",
          [
            "@circle-fin/w3s-pw-react-native-sdk/plugins/withCopyFiles",
            {
              "sourceDir": "prebuild-sync-src",
              "targetDir": ".",
              "overwrite": true
            }
          ],
          "@circle-fin/w3s-pw-react-native-sdk/plugins/apple-signin-entitlements",
          [
            "@circle-fin/w3s-pw-react-native-sdk/plugins/infoplist-config",
            {
              "facebookAppId": "YOUR_FACEBOOK_APP_ID",
              "facebookClientToken": "YOUR_FACEBOOK_CLIENT_TOKEN",
              "facebookDisplayName": "YOUR_FACEBOOK_DISPLAY_NAME",
              "googleClientId": "YOUR_GOOGLE_IOS_CLIENT_ID"
            }
          ]
        ]
      }
    }
    ```

    What each plugin does:

    * `podfile-modifier`: Configures iOS Podfile (required for SDK, set up during
      installation)
    * `withCopyFiles`: Copies files from `prebuild-sync-src` (required for SDK, set
      up during installation)
    * `apple-signin-entitlements`: Enables Sign in with Apple capability
    * `infoplist-config`: Configures `Info.plist` for social login (Facebook App ID,
      Google Client ID, URL schemes, Face ID description)

    #### Step 2: Modify AppDelegate for Facebook SDK

    After running `npx expo prebuild`, modify the generated
    `ios/YourAppName/AppDelegate.swift` to add Facebook SDK initialization.

    **2.1 Add FBSDKCoreKit import**

    ```swift theme={null}
    import FBSDKCoreKit
    ```

    Your imports section should now look like:

    ```swift theme={null}
    import Expo
    import React
    import ReactAppDependencyProvider
    import FBSDKCoreKit  // Add this line
    ```

    **2.2 Initialize Facebook SDK in didFinishLaunchingWithOptions**

    In the `application(_:didFinishLaunchingWithOptions:)` method, add Facebook SDK
    initialization **before** the existing code:

    ```swift theme={null}
    public override func application(
      _ application: UIApplication,
      didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
      // Add Facebook SDK initialization
      ApplicationDelegate.shared.application(
        application,
        didFinishLaunchingWithOptions: launchOptions
      )

      // ... rest of the existing code (don't modify)
      let delegate = ReactNativeDelegate()
      let factory = ExpoReactNativeFactory(delegate: delegate)
      // ... etc
    ```

    **2.3 Handle Facebook URL schemes**

    Add (or modify if it exists) the URL opening handler to process Facebook
    callbacks:

    ```swift theme={null}
    // Handle URL schemes for social login
    public override func application(
      _ app: UIApplication,
      open url: URL,
      options: [UIApplication.OpenURLOptionsKey: Any] = [:]
    ) -> Bool {
      // Handle Facebook SDK URL
      let facebookHandled = ApplicationDelegate.shared.application(
        app,
        open: url,
        sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String,
        annotation: options[UIApplication.OpenURLOptionsKey.annotation]
      )

      return facebookHandled
        || super.application(app, open: url, options: options)
        || RCTLinkingManager.application(app, open: url, options: options)
    }
    ```

    **2.4 (Optional) Handle Universal Links**

    If your app supports Universal Links, add this method:

    ```swift theme={null}
    // Handle Universal Links
    public override func application(
      _ application: UIApplication,
      continue userActivity: NSUserActivity,
      restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
      let result = RCTLinkingManager.application(application, continue: userActivity, restorationHandler: restorationHandler)
      return super.application(application, continue: userActivity, restorationHandler: restorationHandler) || result
    }
    ```

    #### Step 3: Copy modified AppDelegate to prebuild-sync-src

    Copy the modified `AppDelegate.swift` to `prebuild-sync-src` so it persists
    across future prebuild runs:

    ```bash theme={null}
    mkdir -p prebuild-sync-src/ios/YourAppName
    cp ios/YourAppName/AppDelegate.swift prebuild-sync-src/ios/YourAppName/
    ```

    The withCopyFiles plugin (configured in Step 1) will automatically restore this
    file from `prebuild-sync-src` whenever you run `npx expo prebuild --clean` in
    the future.
  </Tab>

  <Tab title="React Native">
    #### Step 1: Enable Sign in with Apple capability

    Enable the **Sign in with Apple** capability in your Xcode project target. For
    detailed steps, see
    [Enable Sign in with Apple](https://help.apple.com/xcode/mac/current/#/dev50571b902).

    #### Step 2: Configure Info.plist

    Add the following keys to your `ios/YourApp/Info.plist` file:

    ```xml theme={null}
    <!-- Facebook configuration -->
    <key>FacebookAppID</key>
    <string>YOUR_FACEBOOK_APP_ID</string>
    <key>FacebookClientToken</key>
    <string>YOUR_FACEBOOK_CLIENT_TOKEN</string>
    <key>FacebookDisplayName</key>
    <string>YOUR_FACEBOOK_DISPLAY_NAME</string>

    <!-- Google configuration -->
    <key>GIDClientID</key>
    <string>YOUR_GOOGLE_IOS_CLIENT_ID</string>

    <!-- Face ID (required if biometric authentication is used) -->
    <key>NSFaceIDUsageDescription</key>
    <string>Enable Biometrics PIN</string>

    <!-- URL Schemes -->
    <key>CFBundleURLTypes</key>
    <array>
      <!-- Facebook URL Scheme -->
      <dict>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>fbYOUR_FACEBOOK_APP_ID</string>
        </array>
      </dict>
      <!-- Google Reversed Client ID URL Scheme -->
      <dict>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>YOUR_REVERSED_IOS_CLIENT_ID</string>
        </array>
      </dict>
    </array>
    ```

    Where:

    * `YOUR_FACEBOOK_APP_ID` is your Facebook app ID
    * `YOUR_FACEBOOK_CLIENT_TOKEN` is your Facebook client token
    * `YOUR_FACEBOOK_DISPLAY_NAME` is your Facebook app display name
    * `YOUR_GOOGLE_IOS_CLIENT_ID` is the value of the `CLIENT_ID` key from
      `GoogleService-Info.plist`
    * `YOUR_REVERSED_IOS_CLIENT_ID` is the value of the `REVERSED_CLIENT_ID` key
      from `GoogleService-Info.plist`

    #### Step 3: Modify AppDelegate

    Update your AppDelegate.m (or AppDelegate.mm) to initialize Facebook SDK and
    handle URL schemes.

    **3.1 Add required imports**

    ```objectivec theme={null}
    #import "AppDelegate.h"
    #import <FBSDKCoreKit/FBSDKCoreKit.h>  // Add this
    #import <React/RCTLinkingManager.h>    // Add this if not present
    ```

    **3.2 Initialize Facebook SDK in didFinishLaunchingWithOptions**

    In the `application:didFinishLaunchingWithOptions:` method, add Facebook SDK
    initialization at the beginning of the method:

    ```objectivec theme={null}
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
      // Add Facebook SDK initialization
      [[FBSDKApplicationDelegate sharedInstance] application:application
                               didFinishLaunchingWithOptions:launchOptions];

      // ... rest of your existing code (don't modify) ...

      return YES;
    }
    ```

    **3.3 Handle URL schemes**

    Add (or modify if it exists) the URL opening handler:

    ```objectivec theme={null}
    // Handle URL schemes
    - (BOOL)application:(UIApplication *)app
                openURL:(NSURL *)url
                options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
    {
      // Handle Facebook URL
      BOOL facebookHandled = [[FBSDKApplicationDelegate sharedInstance] application:app
                                                                            openURL:url
                                                                  sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
                                                                         annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];

      return facebookHandled
          || [super application:app openURL:url options:options]
          || [RCTLinkingManager application:app openURL:url options:options];
    }
    ```

    **3.4 (Optional) Handle Universal Links**

    If your app supports Universal Links, add this method:

    ```objectivec theme={null}
    // Handle Universal Links
    - (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
     restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
    {
      return [RCTLinkingManager application:application
                       continueUserActivity:userActivity
                         restorationHandler:restorationHandler];
    }
    ```
  </Tab>
</Tabs>

### Android

<Note>
  **For Expo projects:** After making the changes below, place the modified
  files in the `prebuild-sync-src` folder you set up during installation, since
  `npx expo prebuild` regenerates the native files. Otherwise, those manual
  changes must be reapplied after each `npx expo prebuild --clean`.
</Note>

#### Apple

Add `manifestPlaceholders.appAuthRedirectScheme` for Apple Sign-In in your
app-level Gradle file (`android/app/build.gradle` or
`android/app/build.gradle.kts`) under `defaultConfig`.

<CodeGroup>
  ```groovy Groovy (build.gradle) theme={null}
  android {
    defaultConfig {
      manifestPlaceholders = [appAuthRedirectScheme: 'YOUR_APPLE_SERVICE_ID']
    }
  }
  ```

  ```kotlin Kotlin (build.gradle.kts) theme={null}
  android {
    defaultConfig {
      manifestPlaceholders["appAuthRedirectScheme"] = "YOUR_APPLE_SERVICE_ID"
    }
  }
  ```
</CodeGroup>

#### Facebook

Add the following values to `android/app/src/main/res/values/strings.xml`:

```xml theme={null}
<!-- Facebook -->
<string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
<string name="fb_login_protocol_scheme">fbYOUR_FACEBOOK_APP_ID</string>
<string name="facebook_client_token">YOUR_FACEBOOK_CLIENT_TOKEN</string>
```

Where:

* `YOUR_FACEBOOK_APP_ID` is your Facebook app ID
* `YOUR_FACEBOOK_CLIENT_TOKEN` is your Facebook client token

#### Google

1. Add the following values to `android/app/src/main/res/values/strings.xml`:

```xml theme={null}
<!-- Google -->
<string name="google_web_client_id" translatable="false">YOUR_GOOGLE_WEB_CLIENT_ID</string>
```

Where `YOUR_GOOGLE_WEB_CLIENT_ID` is your Google sign-in client ID.

2. Place your `google-services.json` in the `android/app/` directory (or
   `prebuild-sync-src/android/app` for Expo projects).

3. Add
   [Google Services Gradle Plugin](https://developers.google.com/android/guides/google-services-plugin)
   to make the values in your `google-services.json` config file accessible to
   Firebase SDKs:
   1. Ensure the following classpath is added to your project-level Gradle file
      (`android/build.gradle` or `android/build.gradle.kts`):

<CodeGroup>
  ```groovy Groovy (build.gradle) theme={null}
  buildscript {
      dependencies {
          classpath "com.google.gms:google-services:4.4.4"
      }
  }
  ```

  ```kotlin Kotlin (build.gradle.kts) theme={null}
  buildscript {
      dependencies {
          classpath("com.google.gms:google-services:4.4.4")
      }
  }
  ```
</CodeGroup>

4. Add the following to your app-level Gradle file (`android/app/build.gradle`
   or `android/app/build.gradle.kts`):

<CodeGroup>
  ```groovy Groovy (build.gradle) theme={null}
  apply plugin: "com.google.gms.google-services"
  ```

  ```kotlin Kotlin (build.gradle.kts) theme={null}
  plugins {
      id("com.google.gms.google-services")
  }
  ```
</CodeGroup>

## SDK API references

### WalletSdk

implements IWallet

### IWalletSdk

interface IWalletSdk

| Properties                                 |
| ------------------------------------------ |
| `sdkVersion: SdkVersion` <br />SDK version |

| Methods                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init: (configuration: Configuration) => Promise<void>` <br />Configure the Circle endpoint for SDK to connect, reject Promise if the endpoint and appId's format are invalid.                                                                                                                                                                                                                                                                                 |
| `setSecurityQuestions: (securityQuestions: SecurityQuestion[]) => void` <br />Set the security question list, throw Throwable when the SecurityQuestion array is empty or contains any question whose title length is not 2\~512.                                                                                                                                                                                                                              |
| `addListener: (listener: EventListener) => void` <br />Register an EventListener for the app to handle events, e.g. forgot PIN. <br />**Deprecated.**                                                                                                                                                                                                                                                                                                          |
| `removeAllListeners: () => void` <br />Unregister all EventListener. <br />**Deprecated.**                                                                                                                                                                                                                                                                                                                                                                     |
| `execute: ( userToken: string, encryptionKey: string, challengeIds: string[], successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void` <br />Execute the operations by challengeId and trigger the SuccessCallback with SuccessResult after sending the request to Circle endpoint successfully. <br />ErrorCallback will be triggered when parameters are null or invalid.                                                                   |
| `executeWithKeyShare: ( userToken: string, encryptionKey: string, pinCodeDeviceShare: string, challengeIds: string[], successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void` <br />Execute the operations by challengeId and PIN code device share and trigger the SuccessCallback with SuccessResult after sending the request to Circle endpoint successfully. <br />ErrorCallback will be triggered when parameters are null or invalid. |
| `getDeviceId: () => string?` <br />Get device ID                                                                                                                                                                                                                                                                                                                                                                                                               |
| `performLogin: ( provider: SocialProvider, deviceToken: string, deviceEncryptionKey: string, successCallback: LoginSuccessCallback, errorCallback: ErrorCallback) ) => void` <br />Execute social provider login flow to get userToken, encryptionKey, refreshToken and OAuthInfo object. <br />ErrorCallback will be triggered when parameters are null or invalid.                                                                                           |
| `performLogout: ( provider: SocialProvider, successCallback: LoginSuccessCallback, errorCallback: ErrorCallback) ) => void` <br />Clean login data, includes provider's data                                                                                                                                                                                                                                                                                   |
| `setBiometricsPin: ( userToken: string, encryptionKey: string, successCallback: SuccessCallback, errorCallback: ErrorCallback ) => void` <br />Setup BiometricsForPin and trigger the SuccessCallback with SuccessResult after finishing the operation successfully. <br />ErrorCallback will be triggered when parameters are null or invalid.                                                                                                                |
| `setDismissOnCallbackMap: (map: Map<ErrorCode, boolean>) => void` <br />The SDK UI can be dismissed if there's an error or warning during execute() and setBiometricsPin(). App can specify ErrorCode as true in the map to dismiss.                                                                                                                                                                                                                           |
| `moveTaskToFront: () => void` <br />Bring the SDK UI to foreground. After calling moveRnTaskToFront() and finishing the flow on React Native UI, e.g. forgot PIN flow, apps can back to SDK UI by calling moveTaskToFront() and continue the SDK task.                                                                                                                                                                                                         |
| `moveRnTaskToFront: () => void` <br />Bring the React Native Activity / ViewController to front. In some cases, apps may need to go back to React Native UI during execute() or setBiometricsPin, e.g., receive an error, warning or event like forgotPin.                                                                                                                                                                                                     |
| `setTextConfigsMap: (map: Map<TextsKey, TextConfig[]>) => void` <br />Define strings with specific configurations for special text customization. <br />All keys are listed in A Index Table.                                                                                                                                                                                                                                                                  |
| `setIconTextConfigsMap: ( map: Map<IconTextsKey, Array<IconTextConfig>> ) => void` <br />Define icon and string sets with specific configurations for icon text list item customization. <br />All keys are listed in B Index Table.                                                                                                                                                                                                                           |
| `setTextConfigMap: (map: Map<TextKey, TextConfig>) => void` <br />Define strings with specific configurations for general string customization. It will replace values. <br />All keys are listed in C Index Table.                                                                                                                                                                                                                                            |
| `setImageMap: (map: Map<ImageKey, ImageSourcePropType>) => void` <br />Define image resource for image customization. <br />All keys are listed in D Index Table.                                                                                                                                                                                                                                                                                              |
| `setDateFormat: (format: DateFormat) => void` <br />Set display date format, e.g. the answer of a security question in which inputType is datePicker. <br />All supported formats are listed in DateFormat. <br />The default format is “YYYY-MM-DD”.                                                                                                                                                                                                          |
| `setDebugging: (debugging: boolean) => void` <br />Android only. <br />true: default value, check customization map value and print warn level log. <br />false: skip checking and turn off the log.                                                                                                                                                                                                                                                           |
| `setCustomUserAgent: (userAgent: string) => void` <br />Set custom user agent value.                                                                                                                                                                                                                                                                                                                                                                           |
| `setErrorStringMap: (map: Map<ErrorCode, string) => void` <br />Define error message for customization.                                                                                                                                                                                                                                                                                                                                                        |

### SdkVersion

interface SdkVersion

| Properties                                                       |
| ---------------------------------------------------------------- |
| `rn: string` <br />Programmable Wallet React Native SDK version. |
| `native: string` <br />Programmable Wallet Native SDK version.   |

### Configuration

interface Configuration

| Properties                                                                              |
| --------------------------------------------------------------------------------------- |
| `endpoint: string` <br />The endpoint SDK connects.                                     |
| `appId: string` <br />Application ID, retrieved from Circle Developer Services Console. |
| `settingsManagement?: SettingsManagement` <br />Extra settings for SDK                  |

### SettingsManagement

interface SettingsManagement

| Properties                                                                  |
| --------------------------------------------------------------------------- |
| `enableBiometricsPin: boolean` <br />Enable biometrics to protect PIN code. |

### SecurityQuestion

class SecurityQuestion

| Properties                                                                                      |
| ----------------------------------------------------------------------------------------------- |
| `title: string` <br />The question string.                                                      |
| `inputType: InputType` <br />The input type of the question. Support text input and timePicker. |

| Constructor                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------- |
| `constructor(title: string, inputType?: InputType)` <br />Initialize a SecurityQuestion, use InputType.text as default value. |

### SocialProvider

To specify a social provider to operate on. See `WalletSdk.performLogin()`,
`WalletSdk.performLogout()`.

```javascript JavaScript theme={null}
enum InputType {
  Google = 'Google',
  Facebook = 'Facebook',
  Apple = 'Apple',
}
```

### InputType

Enumerates the types of security questions.

```Text JavaScript theme={null}
enum InputType {
  text = 'text',
  datePicker = 'datePicker',
}
```

### LoginResult

Interface LoginResult

| Properties                                               |
| -------------------------------------------------------- |
| `userToken?: string` <br />User token                    |
| `encryptionKey?: string` <br />Encryption key            |
| `refreshToken?: string` <br />Refresh token              |
| `oauthInfo?: OauthInfo` <br />OauthInfo for social login |

### OauthInfo

Interface OauthInfo

| Properties                                                                               |
| ---------------------------------------------------------------------------------------- |
| `provider?: string` <br />Provider                                                       |
| `scope?: string[]` <br />Scope                                                           |
| `socialUserUUID?: string` <br />Social user UUID                                         |
| `socialUserInfo?: SocialUserInfo` <br />SocialUserInfo for Social login for social login |

### SocialUserInfo

Interface SocialUserInfo

| Properties                   |
| ---------------------------- |
| `name?: string` <br />Name   |
| `email?: string` <br />Email |
| `phone?: string` <br />Phone |

### SuccessResult

interface SuccessResult

| Properties                                        |
| ------------------------------------------------- |
| `result: ExecuteResult` <br />Execute result.     |
| `warning?: ExecuteWarning` <br />Execute warning. |

### Error

interface Error

| Properties                             |
| -------------------------------------- |
| `code: string` <br />Error code.       |
| `message: string` <br />Error message. |

### LoginSuccessCallback

type SuccessCallback

| Type declaration                                                                            |
| ------------------------------------------------------------------------------------------- |
| `(result: LoginResult) => void` <br />Callback when the operation is executed successfully. |

### SuccessCallback

type SuccessCallback

| Type declaration                                                                              |
| --------------------------------------------------------------------------------------------- |
| `(result: SuccessResult) => void` <br />Callback when the operation is executed successfully. |

### ErrorCallback

type ErrorCallback

| Type declaration                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------- |
| `(error: Error) => void` <br />The callback is triggered when a failure occurs in operation or is canceled by the user. |

### ExecuteResult

interface ExecuteResult

| Properties                                                                                     |
| ---------------------------------------------------------------------------------------------- |
| `resultType: ExecuteResultType` <br />The type of the operation that the challenge represents. |
| `status: ExecuteResultStatus` <br />The status of the execution.                               |
| `data?: ExecuteResultData` <br />The data of the execution.                                    |

### ExecuteResultData

interface ExecuteResultData

| Properties                                                                      |
| ------------------------------------------------------------------------------- |
| `signature?: string` <br />The signature for SIGN\_MESSAGE and SIGN\_TYPEDDATA. |

### ExecuteResultType

Enumerates the types of challenges supported

```coffeescript JavaScript theme={null}
enum ExecuteResultType {
  UNKNOWN = 'UNKNOWN',
  SET_PIN = 'SET_PIN',
  RESTORE_PIN = 'RESTORE_PIN',
  SET_SECURITY_QUESTIONS = 'SET_SECURITY_QUESTIONS',
  CREATE_WALLET = 'CREATE_WALLET',
  CREATE_TRANSACTION = 'CREATE_TRANSACTION',
  ACCELERATE_TRANSACTION = 'ACCELERATE_TRANSACTION',
  CANCEL_TRANSACTION = 'CANCEL_TRANSACTION',
  CONTRACT_EXECUTION = 'CONTRACT_EXECUTION',
  SIGN_MESSAGE = 'SIGN_MESSAGE',
  SIGN_TYPEDDATA = 'SIGN_TYPEDDATA',
  SET_BIOMETRICS_PIN = 'SET_BIOMETRICS_PIN',
}
```

### ExecuteResultStatus

Enumerates the possible statuses for a challenge

```coffeescript JavaScript theme={null}
enum ExecuteResultStatus {
  UNKNOWN = 'UNKNOWN',
  PENDING = 'PENDING',
  IN_PROGRESS = 'IN_PROGRESS',
  COMPLETE = 'COMPLETE',
  FAILED = 'FAILED',
  EXPIRED = 'EXPIRED',
}
```

### EventListener

type EventListener

| Type declaration                                                                                       |
| ------------------------------------------------------------------------------------------------------ |
| `(event: ExecuteEvent) => void` <br />Event listener for receiving ExecuteEvent. <br />**Deprecated.** |

### CIRCLE\_PW\_ON\_EVENT

Constant event name for use with Expo's `NativeModule.addListener()`. This event
is emitted by the native SDK when certain actions occur, such as "forgot PIN"
and "resend OTP" flow triggered by the user. The event payload conforms to the
CirclePwEventPayload interface, containing a `name` property of type
ExecuteEvent.

```ts theme={null}
const CIRCLE_PW_ON_EVENT = "CirclePwOnEvent";
```

### CirclePwEventPayload

Interface for the payload received when a CIRCLE\_PW\_ON\_EVENT is triggered.

| Properties                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name: ExecuteEvent` <br />The specific event type that was triggered. This value corresponds to one of the defined values in the ExecuteEvent enum. |

### ExecuteEvent

Enumerates the possible event

```coffeescript JavaScript theme={null}
enum ExecuteEvent {
  forgotPin = 'forgotPin',
}
```

### ErrorCode

Enumerates the types of error code

```coffeescript JavaScript theme={null}
enum ErrorCode {
  unknown = '-1',
  success = '0',
  apiParameterMissing = '1',
  apiParameterInvalid = '2',
  forbidden = '3',
  unauthorized = '4',
  retry = '9',
  customerSuspended = '10',
  pending = '11',
  invalidSession = '12',
  invalidPartnerId = '13',
  invalidMessage = '14',
  invalidPhone = '15',
  walletIdNotFound = '156001',
  tokenIdNotFound = '156002',
  transactionIdNotFound = '156003',
  walletSetIdNotFound = '156004',
  notEnoughFounds = '155201',
  notEnoughBalance = '155202',
  exceedWithdrawLimit = '155203',
  minimumFundsRequired = '155204',
  invalidTransactionFee = '155205',
  rejectedOnAmlScreening = '155206',
  tagRequired = '155207',
  gasLimitTooLow = '155208',
  transactionDataNotEncodedProperly = '155209',
  fullNodeReturnedError = '155210',
  walletSetupRequired = '155211',
  lowerThenMinimumAccountBalance = '155212',
  rejectedByBlockchain = '155213',
  droppedAsPartOfReorg = '155214',
  operationNotSupport = '155215',
  amountBelowMinimum = '155216',
  wrongNftTokenIdNumber = '155217',
  invalidDestinationAddress = '155218',
  tokenWalletChainMismatch = '155219',
  wrongAmountsNumber = '155220',
  userAlreadyExisted = '155101',
  userNotFound = '155102',
  userTokenNotFound = '155103',
  userTokenExpired = '155104',
  invalidUserToken = '155105',
  userWasInitialized = '155106',
  userHasSetPin = '155107',
  userHasSetSecurityQuestion = '155108',
  userWasDisabled = '155109',
  userDoesNotSetPinYet = '155110',
  userDoesNotSetSecurityQuestionYet = '155111',
  incorrectUserPin = '155112',
  incorrectDeviceId = '155113',
  incorrectAppId = '155114',
  incorrectSecurityAnswers = '155115',
  invalidChallengeId = '155116',
  invalidApproveContent = '155117',
  invalidEncryptionKey = '155118',
  userPinLocked = '155119',
  securityAnswersLocked = '155120',
  walletIsFrozen = '155501',
  maxWalletLimitReached = '155502',
  walletSetIdMutuallyExclusive = '155503',
  metadataUnmatched = '155504',
  userCanceled = '155701',
  launchUiFailed = '155702',
  pinCodeNotMatched = '155703',
  insecurePinCode = '155704',
  hintsMatchAnswers = '155705',
  networkError = '155706',
  biometricsSettingNotEnabled = '155708',
  deviceNotSupportBiometrics = '155709',
  biometricsKeyPermanentlyInvalidated = '155710',
  biometricsUserSkip = '155711',
  biometricsUserDisableForPin = '155712',
  biometricsUserLockout = '155713',
  biometricsUserLockoutPermanent = '155714',
  biometricsUserNotAllowPermission = '155715',
  biometricsInternalError = '155716',
  userSecretMissing = '155717',
  invalidUserTokenFormat = '155718',
  userTokenMismatch = '155719',
  socialLoginFailed = '155720',
  loginInfoMissing = '155721',
}
```

### TextConfig

Data-only class for text customization.\
class TextConfig

| Properties                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text?: string` <br />Text to display                                                                                                                                                     |
| `gradientColors?: string[]` <br />Array of Gradient text color. Only used by <br />TextsKey.enterPinCodeHeadline, <br />TextsKey.securityIntroHeadline, <br />TextsKey.newPinCodeHeadline |
| `textColor?: string` <br />Text color                                                                                                                                                     |
| `font?: string` <br />Font                                                                                                                                                                |

| Constructor                                                                                  |
| :------------------------------------------------------------------------------------------- |
| `constructor( text?: string, gradientColorsOrTextColor: string[] \| string, font?: string )` |

### TextConfig

Data-only class for icon text list item customization.\
class IconTextConfig

| Properties                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------ |
| [`image:ImageSourcePropType`](https://reactnative.dev/docs/image#source) <br />The image source for customization. |
| `textConfig: TextConfig` <br />Text config for text customization.                                                 |

| Constructor                                                       |
| :---------------------------------------------------------------- |
| `constructor(image: ImageSourcePropType, textConfig: TextConfig)` |

### TextsKey

Enum for setTextConfigsMap().\
See [A Index Table](/wallets/user-controlled/react-native-sdk-ui-customization-api#a-index-table--textskey).

### IconTextsKey

Enum for setIconTextConfigsMap().\
See [B Index Table](/wallets/user-controlled/react-native-sdk-ui-customization-api#b-index-table---icontextskey).

### TextKey

Enum for setTextConfigMap().\
See [C Index Table](/wallets/user-controlled/react-native-sdk-ui-customization-api#c-index-table---resourcekey).

### ImageKey

Enum for setImageMap().\
See [D Index Table](/wallets/user-controlled/react-native-sdk-ui-customization-api#d-index-table).

### DateFormat

Enum for setDateFormat().

```coffeescript JavaScript theme={null}
enum DateFormat {
  YYYYMMDD_HYPHEN = 'yyyy-MM-dd',
  DDMMYYYY_SLASH = 'dd/MM/yyyy',
  MMDDYYYY_SLASH = 'MM/dd/yyyy',
}
```

## SampleCode

```coffeescript JavaScript theme={null}
import * as React from 'react';
import { WalletSdk } from '@circle-fin/w3s-pw-react-native-sdk';

export default function App() {
    const [endpoint, setEndpoint] = React.useState(
    'https://api.circle.com/v1/w3s/'
  );
    const [appId, setAppId] = React.useState('');
    const [enableBiometricsPin, setEnableBiometricsPin] = React.useState(false);
    const [userToken, setUserToken] = React.useState('');
    const [encryptionKey, setEncryptionKey] = React.useState('');
    const [challengeId, setChallengeId] = React.useState('');

    React.useEffect(() => {
        // Regester EventListener
        WalletSdk.addListener((event: any) => {
    if(event == ExecuteEvent.forgotPin){
              WalletSdk.moveRnTaskToFront();
              // forgot PIN flow in React Native UI
           }
        });
  _initSdk();
        _setSecurityQuestions();
        _setDismissOnCallbackMap();
        _setTextConfigsMap();
        _setIconTextConfigsMap();
        _setTextConfigMap();
        _setErrorStringMap();
        _setImageMap();
        _setDateFormat();
        _setDebugging();
        return () => {
           // Removes listeners once unmounted
           WalletSdk.removeAllListeners();
        };
   }, []);
   ...
   return (
       <View>
        <TextInput
          accessibilityLabel={'endpointInput'}
          onChangeText={setEndpoint}
          value={endpoint}
        />
        <TextInput
          accessibilityLabel={'appIdInput'}
          onChangeText={setAppId}
          value={appId}
        />
        <TextInput
          accessibilityLabel={'userTokenInput'}
          onChangeText={setUserToken}
          value={userToken}
        />
        <TextInput
          accessibilityLabel={'encryptionKeyInput'}
          onChangeText={setEncryptionKey}
          value={encryptionKey}
        />
        <TextInput
          onChangeText={setChallengeId}
          value={challengeId}
        />
        <TouchableOpacity
          accessibilityLabel={'executeSdkButton'}
          onPress={() => {
            _executeSdk();
          }}
<Note>

</Note>
          <Text>Execute</Text>
        </TouchableOpacity>
        <TouchableOpacity
          accessibilityLabel={'setBiometricsPinButton'}
          onPress={() => {
            _setBiometricsPin();
          }}
<Note>

</Note>
          <Text>Set Biometrics Pin</Text>
        </TouchableOpacity>
      </View>
   )
}
```

```coffeescript JavaScript theme={null}
 ...
   const _initSdk = async () => {
     try {
            // Set endpoint, app ID and extra settings
   await WalletSdk.init({
     endpoint,
     appId,
     settingsManagement: { enableBiometricsPin: enableBiometricsPin }
    });
     } catch (e: any) {
     toast(e.message);
     return;
     }
   };

  const _setSecurityQuestions = () => {
    WalletSdk.setSecurityQuestions([
      new SecurityQuestion('What was your childhood nickname?', InputType.text),
      new SecurityQuestion('When is your favorite date?', InputType.datePicker),
      new SecurityQuestion('What is the name of your first pet?'),
      new SecurityQuestion('What is your favorite country?'),
    ]);
  };

  const _setDismissOnCallbackMap = () => {
      const map = new Map();
      map.set(ErrorCode.userCanceled, true);
      map.set(ErrorCode.networkError, true);
      WalletSdk.setDismissOnCallbackMap(map);
  };

  const _setTextConfigsMap = () => {
      let gradientColors = ['#05184b', '#21bad5'] as Array<string>;
      const map = new Map();
      map.set(TextsKey.newPinCodeHeadline, [
        new TextConfig('ENTER your new ', '#a6183f'),
        new TextConfig(
          'W3s PIN',
          undefined,
          gradientColors,
          'Roboto'
        ),
      ]);
      map.set(TextsKey.securityIntroLink, [
        new TextConfig('==Learn more=='),
        new TextConfig('https://www.circle.com/en/legal/privacy-policy'),
      ]);
      WalletSdk.setTextConfigsMap(map);
  };

 const _setImageMap = () => {
     const imageMap = new Map();
     imageMap.set(ImageKey.naviBack, require('../../assets/image/ic_back.png'));
     imageMap.set(ImageKey.naviClose, require('../../assets/image/ic_close.png'));
     imageMap.set(
       ImageKey.securityIntroMain,
       require('../../assets/image/grab_confirm_main_icon.png')
     );
     imageMap.set(ImageKey.selectCheckMark, {
       uri: 'https://drive.google.com/uc?id=1UTX1tFnECuj1k3U1bggH0g5YvH_Ens5M',
     });
     imageMap.set(ImageKey.dropdownArrow, {
       uri: 'https://drive.google.com/uc?id=1PR3yYpk4AmsCAlUM8nw6C3y-RAXNjGMv',
     });
     imageMap.set(ImageKey.errorInfo, {
       uri: 'https://drive.google.com/uc?id=1UJjinISU6ZHO0fAoKaZofBMgItaAn9kS',
     });
     imageMap.set(ImageKey.securityConfirmMain, {
       uri: 'https://drive.google.com/uc?id=16OkP3VzEjLICOifNKRQi3FMJntV9F-n-',
     });
     WalletSdk.setImageMap(imageMap);
 };
  const _setIconTextConfigsMap = () => {
      const map = new Map<IconTextsKey, Array<IconTextConfig>>();
      map.set(IconTextsKey.securityConfirmationItems, [
        new IconTextConfig(
          require('../../assets/image/ic_intro_item0_icon.png'),
          new TextConfig('This is the only way to recover my account access. '       )
      ),
        new IconTextConfig(
          require('../../assets/image/ic_intro_item1_icon.png'),
          new TextConfig(
            'Circle won't store my answers so it's my responsibility to remember them.'
          )
      ),
       new IconTextConfig(
         require('../../assets/image/ic_intro_item2_icon.png'),
         new TextConfig(
           'I will lose access to my wallet and my digital assets if I forget my answers. '
         )
       ),
     ]);
     WalletSdk.setIconTextConfigsMap(map);
 };
 const _setTextConfigMap = () => {};
 const _setErrorStringMap = () => {};
 const _setDateFormat = () => {};
 const _setDebugging = () => {};

 // execute
 const _executeSdk = async () => {
     try {
         let { result } = await WalletSdk.execute(userToken, encryptionKey, [
           challengeId,
         ]);
         console.log(`${result.resultType}, ${result.status}, ${result.data?.signature}`);
     } catch (e: any) {
         console.log(e.message);
     }
  };
  // setBiometricsPin
 const _setBiometricsPin = async () => {
    try {
      let { result } = await WalletSdk.setBiometricsPin(
        userToken,
        encryptionKey
      );
      console.log(`${result.resultType}, ${result.status}`);
    } catch (e: any) {
      console.log(e.message);
    }
  };
```


# React Native SDK UI Customization API
Source: https://developers.circle.com/wallets/user-controlled/react-native-sdk-ui-customization-api

React Native SDK UI and key mapping reference for customizations.

This article describes two different ways to customize your React Native
application UI using the
[React Native SDK](/wallets/user-controlled/react-native-sdk)

* **Static Resources** customize the UI layout during build time.
* **Programmatic Customization** modifies the layout at run time.

<Note>
  **Note:**

  You can combine static and programmatic approaches for customization.
</Note>

To use the SDK in the most flexible way, combine the reference in this article
with the [React Native SDK](/wallets/user-controlled/react-native-sdk).

**Sample Application**: Refer to the
[React Native sample application](https://github.com/circlefin/w3s-react-native-sample-app-wallets)
for example code.

## Text, Color, and Font Customization

For text-related customization, there are two types of customization, dynamic
and static:

* For dynamic customization, update the source code's desired string, color, and
  font (as typeface).

```coffeescript JavaScript theme={null}
new TextConfig(text, color, font)
new TextConfig(text, gradientColorArray, font)
```

* For static customization, please refer to Static Resource to add or update
  resource files for Android and iOS respectively. To avoid the static
  customization being overwritten by the dynamic customization, use the
  undefined value for the text argument when initializing with the TextConfig()
  constructor, for example:

```coffeescript JavaScript theme={null}
new TextConfig(undefined, color, font) // text remains static customization
new TextConfig(text, undefined, undefined) // color and font remain static customization
```

Please reference the UI screenshots below with each string's mapping code, then
use the mapping code to find the Key name in the Index Table A, B, C for more
detail of customization support and usage for each text string.

<Note>
  **Note:**

  The detail of supporting scope can be found in the index table and the note
  column. For Android, if the app still customizes those unsupported values, it
  will give a WARN level log printed to logcat, filtered with CustomizeChecker for
  log abstraction.
</Note>

<Frame>
  <img />
</Frame>

## New PIN Code

### A1 / C1\~C5

<Frame>
  <img />
</Frame>

## Confirm PIN Code

### C6\~C7

<Frame>
  <img />
</Frame>

## Enter PIN Code

### A2 / C8\~C9, C5-1, C5-2

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Security Intros

### A3~~A4 / C10~~C11

<Frame>
  <img />
</Frame>

## Security Questions Customization

Please reference the Security Question section in the
[SDK](/wallets/user-controlled/react-native-sdk) for how to customize the
question by using `setSecurityQuestions` method.

### A5 / C12\~C25

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Security Summary

### A6 / C26\~C32

<Frame>
  <img />
</Frame>

## Security Confirm

### C33\~C37 / B1

<Frame>
  <img />
</Frame>

## Recover PIN Code

### A7 / C39\~C47

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Biometrics Prompt

### C46\~C60

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Alert Pop Window

### C61\~C62

<Frame>
  <img />
</Frame>

## Confirm Transaction

### C63\~C90

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Signature Request

### C91\~C98

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Verify OTP

### C99\~C105

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## A Index Table -TextsKey

Put the configs in a map then call WalletSdk.setTextConfigsMap(). For example:

```coffeescript JavaScript theme={null}
  const map = new Map()
  map.set(TextsKey.securityQuestionHeaders, [
    new TextConfig('Choose your 1st question'),
    new TextConfig('Choose your 2nd question')
  ])

  WalletSdk.setTextConfigsMap(map)
```

|        | **Programmatic Customization** |                                      |                     |                          |                     |                               | **Static Resources**      |                    |                            |          | Note🔖                                                                                                                                                        |
| ------ | ------------------------------ | ------------------------------------ | ------------------- | ------------------------ | ------------------- | ----------------------------- | ------------------------- | ------------------ | :------------------------- | :------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|        |                                |                                      |                     |                          |                     |                               | **Android**               |                    | **iOS CirclePWTheme.json** |          |                                                                                                                                                               |
| **#**  | **TextsKey**                   | **TextConfigs length**               | **TextConfig.text** | **TextConfig.textColor** | **TextConfig.font** | **TextConfig.gradientColors** | **colors.xml**            | **styles.xml**     | **color**                  | **font** |                                                                                                                                                               |
| **A1** | newPinCodeHeadline             | \<=2                                 | ✅                   | ✅🔖                      | ✅                   | ✅🔖                           | circlepw\_text\_main      | circlepw\_heading3 | text\_main                 | semibold | textColor will be applied if gradientColors is null.                                                                                                          |
| **A2** | enterPinCodeHeadline           | \<=2                                 | ✅                   | ✅🔖                      | ✅                   | ✅🔖                           | circlepw\_text\_main      | circlepw\_heading3 | text\_main                 | semibold | textColor will be applied if gradientColors is null.                                                                                                          |
| **A3** | securityIntroHeadline          | \<=2                                 | ✅                   | ✅🔖                      | ✅                   | ✅🔖                           | circlepw\_text\_main      | circlepw\_heading4 | text\_main                 | semibold | textColor will be applied if gradientColors is null.                                                                                                          |
| **A4** | securityIntroLink              | 2🔖                                  | ✅                   | ✅🔖                      | ✅🔖                 | ❌                             | circlepw\_text\_action    | circlepw\_body2    | text\_action               | regular  | TextConfigs: \[DisplayText, URL]Only display when the array length is not less then 2 and the URL is not empty.Set color / font according to TextConfig\[0].  |
| **A5** | securityQuestionHeaders        | \<= 5🔖                              | ✅                   | ✅🔖                      | ✅🔖                 | ❌                             | circlepw\_text\_auxiliary | circlepw\_body2    | text\_auxiliary            | regular  | TextConfigs over the length limit will be ignored.                                                                                                            |
| **A6** | securitySummaryQuestionHeaders | Same as securityQuestionHeaders (A5) | ✅                   | ✅                        | ✅                   | ❌                             | circlepw\_text\_main2     | circlepw\_heading5 | text\_main2                | semibold | TextConfigs over the length limit will be ignored.                                                                                                            |
| **A7** | recoverPinCodeHeadline         | Free                                 | ✅                   | ✅🔖                      | ✅                   | ✅🔖                           | circlepw\_text\_main      | circlepw\_heading3 | text\_main                 | semibold | textColor will be applied if gradientColors is null.                                                                                                          |

## B Index Table - IconTextsKey

Use this Index Table to reference the dynamic special Icon, Text, Color, and
Font Customization. Both the icon image and the text fields are dynamically
configured together.\
You can use IconTextConfig() constructor with local image or remote image URL.
For example:

```coffeescript JavaScript theme={null}
new IconTextConfig(
      require('../assets/image/local_icon.png'),
      new TextConfig(text, color, font)
    )

new IconTextConfig(
      {uri: 'https://remote_image'}
      new TextConfig(text, color, font)
    )
```

And put the configs in a map then call WalletSdk.setIconTextConfigsMap():

```coffeescript JavaScript theme={null}
 const map = new Map()
 map.set(IconTextsKey.securityConfirmationItems, [
    new IconTextConfig(
      require('../assets/image/local_icon.png'),
      new TextConfig(text, color, font),
    ),
  ])
  WalletSdk.setIconTextConfigsMap(map)

```

|        | **Programmatic Customization** |                        |                     |                          |                     |                               | **Static Resources** |                 |                            |          | Note🔖                                               |
| ------ | ------------------------------ | ---------------------- | ------------------- | ------------------------ | ------------------- | ----------------------------- | -------------------- | --------------- | :------------------------- | :------- | ---------------------------------------------------- |
|        |                                |                        |                     |                          |                     |                               | **Android**          |                 | **iOS CirclePWTheme.json** |          |                                                      |
| **#**  | **IconTextsKey**               | **TextConfigs length** | **TextConfig.text** | **TextConfig.textColor** | **TextConfig.font** | **TextConfig.gradientColors** | **colors.xml**       | **styles.xml**  | **color**                  | **font** |                                                      |
| **B1** | securityConfirmationItems      | \<=4🔖                 | ✅                   | ✅                        | ✅                   | ❌                             | circlepw\_text\_main | circlepw\_body2 | text\_main                 | regular  | textColor will be applied if gradientColors is null. |

## C Index Table - TextKey

For programmatic customization, put the configs in a map then call
WalletSdk.setTextConfigMap(). For example:

```coffeescript JavaScript theme={null}
   const map = new Map()
  map.set(
    TextKey.circlepw_recover_pincode_answer_input_placeholder,
    new TextConfig(
      'Type your answer here',
      colors.placeholder,
      'Inter-Regular',
    ),
  )
  WalletSdk.setTextConfigMap(map)
```

For static customization, please check
[Static Resource](/wallets/user-controlled/react-native-sdk-ui-customization-api#static-resources).

<Note>
  **Note:**

  The `gradientColors` field is not supported for the Keys in this table. If you
  dynamically set the color as `gradientColor`, the effect will be ignored and the
  `Android WARN` level log will be printed.
</Note>

|       | Programmatic Customization                                 |                |               |          | Static Resources                                          |                                         |                                |                                                           |                                      |          | Note                                                                                                                    |
| ----- | ---------------------------------------------------------- | -------------- | ------------- | -------- | --------------------------------------------------------- | --------------------------------------- | ------------------------------ | --------------------------------------------------------- | ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
|       |                                                            | **TextConfig** |               |          | **Android**                                               |                                         |                                | **iOS CirclePWLocalizable.json**                          | **iOS CirclePWTheme.json**           |          |                                                                                                                         |
| **#** | **TextKey**                                                | **text**       | **textColor** | **font** | **strings.xml**                                           | **colors.xml**                          | **styles.xml**                 | **string**                                                | **color**                            | **font** |                                                                                                                         |
| C1    | circlepw\_new\_pincode\_subhead                            | ✅              | ✅             | ✅        | circlepw\_new\_pincode\_subhead                           | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_new\_pincode\_subhead                           | text\_auxiliary                      | regular  |                                                                                                                         |
| C2    | ❌                                                          | ❌              | ❌             | ❌        | ❌                                                         | circlepw\_text\_main                    | circlepw\_pinDigitText         | ❌                                                         | text\_main                           | light    | Normal                                                                                                                  |
|       |                                                            |                |               |          |                                                           | circlepw\_success                       | circlepw\_pinDigitText         |                                                           | success                              |          | Succeed                                                                                                                 |
|       |                                                            |                |               |          |                                                           | circlepw\_error                         | circlepw\_pinDigitText         |                                                           | error                                |          | Failed                                                                                                                  |
| C3    | circlepw\_enter\_pincode\_use\_biometrics                  | ✅              | ✅             | ✅        | circlepw\_enter\_pincode\_use\_biometrics🔖               | circlepw\_pressed\_assist\_text\_color  | circlepw\_actionText           | circlepw\_enter\_pincode\_use\_biometrics🔖               | text\_action                         | semibold | For Android, the default text is “Use Biometrics”. For iOS, the default text is “Use FACE ID”.                          |
| C5    | circlepw\_pincode\_error\_config                           | ❌🔖            | ✅             | ✅        | ❌🔖                                                       | circlepw\_error                         | circlepw\_body2                | ❌🔖                                                       | error                                | regular  | For text, see Error Message:incorrectUserPin(155112), userPinLocked(155119), pinCodeNotMatched(155703)                  |
| C5-1  | circlepw\_pin\_remain\_attemps\_template                   | ✅🔖            | ❌             | ❌        | circlepw\_pin\_remain\_attemps\_template                  | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | e.g. You have %s attempts left.                                                                                         |
| C5-2  | circlepw\_pin\_lock\_period\_template                      | ✅🔖            | ❌             | ❌        | circlepw\_pin\_lock\_period\_template                     | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | e.g. You've used up all PIN attempts. Please wait for %s mins to retry later..                                          |
| C6    | circlepw\_confirm\_pincode\_headline                       | ✅              | ✅             | ✅        | circlepw\_confirm\_pincode\_headline                      | circlepw\_text\_main                    | circlepw\_heading3             | circlepw\_confirm\_pincode\_headline                      | text\_main                           | semibold |                                                                                                                         |
| C7    | circlepw\_confirm\_pincode\_subhead                        | ✅              | ✅             | ✅        | circlepw\_confirm\_pincode\_subhead                       | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_confirm\_pincode\_subhead                       | text\_auxiliary                      | regular  |                                                                                                                         |
| C8    | circlepw\_enter\_pincode\_subhead                          | ✅              | ✅             | ✅        | circlepw\_enter\_pincode\_subhead                         | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_enter\_pincode\_subhead                         | text\_auxiliary                      | regular  |                                                                                                                         |
| C9    | circlepw\_enter\_pincode\_forgot\_pin                      | ✅              | ✅             | ✅        | circlepw\_enter\_pincode\_forgot\_pin                     | circlepw\_text\_action                  | circlepw\_actionText           | circlepw\_enter\_pincode\_forgot\_pin                     | text\_action / text\_action\_pressed | semibold |                                                                                                                         |
| C10   | circlepw\_security\_intros\_description                    | ✅              | ✅             | ✅        | circlepw\_security\_intros\_description                   | circlepw\_text\_auxiliary2              | circlepw\_body2                | circlepw\_security\_intros\_description                   | text\_auxiliary2                     | regular  |                                                                                                                         |
| C11   | circlepw\_continue                                         | ✅              | ✅             | ✅        | circlepw\_continue                                        | circlepw\_main\_bt\_text                | circlepw\_mainButtonText       | circlepw\_continue                                        | main\_bt\_text                       | semibold | Normal                                                                                                                  |
|       |                                                            |                |               |          |                                                           | circlepw\_main\_bt\_text\_pressed       |                                |                                                           | main\_bt\_text\_pressed              |          | Pressed                                                                                                                 |
|       |                                                            |                |               |          |                                                           | circlepw\_disabled\_main\_bt\_text      |                                |                                                           | main\_bt\_text\_disabled             |          | Disabled                                                                                                                |
| C12   | circlepw\_security\_questions\_title                       | ✅              | ✅             | ✅        | circlepw\_security\_questions\_title                      | circlepw\_text\_main                    | circlepw\_toolbarTitle         | circlepw\_security\_questions\_title                      | text\_main                           | medium   |                                                                                                                         |
| C13   | circlepw\_security\_questions\_required\_mark              | ✅              | ✅             | ✅        | circlepw\_security\_questions\_required\_mark             | circlepw\_error                         | circlepw\_metadata1            | circlepw\_security\_questions\_required\_mark             | error                                | regular  |                                                                                                                         |
| C14   | circlepw\_security\_questions\_question\_input\_config     | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_main                    | circlepw\_body1                | ❌                                                         | text\_main                           | regular  |                                                                                                                         |
| C15   | circlepw\_security\_questions\_question\_placeholder       | ✅🔖            | ✅🔖           | ❌        | circlepw\_security\_questions\_question\_placeholder      | circlepw\_placeholder                   | circlepw\_body1                | circlepw\_security\_questions\_question\_placeholder      | text\_placeholder                    | regular  | Set ​​TextView's textColorHint and hint. Apply circlepw\_security\_questions\_question\_input\_config (C14)'s font.     |
| C16   | circlepw\_security\_questions\_answer\_header              | ✅              | ✅             | ✅        | circlepw\_security\_questions\_answer\_header             | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_security\_questions\_answer\_header             | text\_auxiliary                      | regular  |                                                                                                                         |
| C17   | circlepw\_security\_questions\_answer\_input\_config       | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_main                    | circlepw\_body1                | ❌                                                         | text\_main                           | regular  |                                                                                                                         |
| C18   | circlepw\_security\_questions\_answer\_placeholder         | ✅🔖            | ✅🔖           | ❌🔖      | circlepw\_security\_questions\_answer\_placeholder        | circlepw\_placeholder                   | circlepw\_body1                | circlepw\_security\_questions\_answer\_placeholder        | text\_placeholder                    | regular  | Set ​​TextView's textColorHint and hint. Apply circlepw\_security\_questions\_answer\_input\_config (C17)'s font.       |
| C19   | circlepw\_security\_questions\_answer\_hint\_header        | ✅              | ✅             | ✅        | circlepw\_security\_questions\_answer\_hint\_header       | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_security\_questions\_answer\_hint\_header       | text\_auxiliary                      | regular  |                                                                                                                         |
| C20   | circlepw\_security\_questions\_answer\_hint\_input\_config | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_main                    | circlepw\_body1                | ❌                                                         | text\_main                           | regular  |                                                                                                                         |
| C21   | circlepw\_security\_questions\_answer\_hint\_placeholder   | ✅🔖            | ✅🔖           | ❌🔖      | circlepw\_security\_questions\_answer\_hint\_placeholder  | circlepw\_placeholder                   | circlepw\_body1                | circlepw\_security\_questions\_answer\_hint\_placeholder  | text\_placeholder                    | regular  | Set ​​TextView's textColorHint and hint. Apply circlepw\_security\_questions\_answer\_hint\_input\_config (C20)'s font. |
| C22   | circlepw\_security\_questions\_error\_config               | ❌🔖            | ✅             | ✅        | ❌🔖                                                       | circlepw\_error                         | circlepw\_metadata1            | ❌                                                         | error                                | regular  | For text, see Error Message:hintsMatchAnswers(155705)                                                                   |
| C23   | circlepw\_next                                             | ✅              | ✅             | ✅        | circlepw\_next                                            | circlepw\_main\_bt\_text                | circlepw\_mainButtonText       | circlepw\_next                                            | main\_bt\_text                       | semibold | Normal                                                                                                                  |
|       |                                                            |                |               |          |                                                           | circlepw\_main\_bt\_text\_pressed       |                                |                                                           | main\_bt\_text\_pressed              |          | Pressed                                                                                                                 |
|       |                                                            |                |               |          |                                                           | circlepw\_disabled\_main\_bt\_text      |                                |                                                           | main\_bt\_text\_disabled             |          | Disabled                                                                                                                |
| C24   | circlepw\_select\_question\_title                          | ✅              | ✅             | ✅        | circlepw\_select\_question\_title                         | circlepw\_text\_main                    | circlepw\_toolbarTitle         | circlepw\_select\_question\_title                         | text\_main                           | medium   |                                                                                                                         |
| C25   | circlepw\_select\_question\_item\_config                   | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_main                    | circlepw\_body1                | ❌                                                         | text\_main                           | regular  |                                                                                                                         |
| C26   | circlepw\_security\_summary\_title                         | ✅              | ✅             | ✅        | circlepw\_security\_summary\_title                        | circlepw\_text\_main                    | circlepw\_toolbarTitle         | circlepw\_security\_summary\_title                        | text\_main                           | medium   |                                                                                                                         |
| C27   | circlepw\_question\_label                                  | ✅              | ✅             | ✅        | circlepw\_question\_label                                 | circlepw\_text\_auxiliary2              | circlepw\_body2                | circlepw\_question + “:”                                  | text\_auxiliary2                     | regular  |                                                                                                                         |
| C28   | circlepw\_security\_summary\_question\_value\_config       | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_summary                 | circlepw\_body2                | ❌                                                         | text\_summary                        | regular  |                                                                                                                         |
| C29   | circlepw\_answer\_label                                    | ✅              | ✅             | ✅        | circlepw\_answer\_label                                   | circlepw\_text\_auxiliary2              | circlepw\_body2                | circlepw\_answer + “:“                                    | text\_auxiliary2                     | regular  |                                                                                                                         |
| C30   | circlepw\_security\_summary\_answer\_value\_config         | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_summary                 | circlepw\_caption2             | ❌                                                         | text\_summary\_highlight             | semibold |                                                                                                                         |
| C31   | circlepw\_hint\_label                                      | ✅              | ✅             | ✅        | circlepw\_hint\_label                                     | circlepw\_text\_auxiliary2              | circlepw\_body2                | circlepw\_hint + “:“                                      | text\_auxiliary2                     | regular  |                                                                                                                         |
| C32   | circlepw\_security\_summary\_hint\_value\_config           | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_summary                 | circlepw\_body2                | ❌                                                         | text\_summary                        | regular  |                                                                                                                         |
| C33   | circlepw\_security\_confirm\_title                         | ✅              | ✅             | ✅        | circlepw\_security\_confirm\_title                        | circlepw\_text\_main                    | circlepw\_toolbarTitle         | circlepw\_security\_confirm\_title                        | text\_main                           | medium   |                                                                                                                         |
| C34   | circlepw\_security\_confirm\_headline                      | ✅              | ✅             | ✅        | circlepw\_security\_confirm\_headline                     | circlepw\_text\_main                    | circlepw\_heading4             | circlepw\_security\_confirm\_headline                     | text\_main                           | medium   |                                                                                                                         |
| C35   | circlepw\_security\_confirm\_input\_headline               | ✅              | ✅             | ✅        | circlepw\_security\_confirm\_input\_headline              | circlepw\_text\_main2                   | circlepw\_caption1             | circlepw\_security\_confirm\_input\_headline              | text\_main2                          | semibold |                                                                                                                         |
| C36   | circlepw\_security\_confirm\_input\_placeholder            | ✅🔖            | ✅🔖           | ❌🔖      | circlepw\_security\_confirm\_input\_placeholder           | circlepw\_placeholder                   | circlepw\_body1                | circlepw\_security\_confirm\_input\_placeholder           | text\_placeholder                    | regular  | Set ​​TextView's textColorHint and hint. Apply circlepw\_security\_confirm\_input\_config (C37)'s font.                 |
| C37   | circlepw\_security\_confirm\_input\_config                 | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_main                    | circlepw\_body1                | ❌                                                         | text\_main2                          | regular  |                                                                                                                         |
| C37-1 | circlepw\_security\_confirm\_input\_match                  | ✅              | ❌             | ❌        | circlepw\_security\_confirm\_input\_match                 | ❌                                       | ❌                              | circlepw\_security\_confirm\_input\_match                 | ❌                                    | ❌        | The text is the answer that requires user type. e.g. I agree                                                            |
| C38   | circlepw\_recover\_pincode\_error\_config                  | ❌🔖            | ✅             | ✅        | ❌🔖                                                       | circlepw\_text\_main                    | circlepw\_body2                | ❌                                                         | text\_main                           | regular  | For text, see Error Message:incorrectSecurityAnswers(155115), securityAnswersLocked(155120)                             |
| C38-1 | circlepw\_answer\_remain\_attemps\_template                | ✅🔖            | ❌             | ❌        | circlepw\_answer\_remain\_attemps\_template               | ❌                                       | ❌                              |                                                           |                                      |          | e.g. You have %s attempts left.                                                                                         |
| C38-2 | circlepw\_answer\_lock\_period\_template                   | ✅🔖            | ❌             | ❌        | circlepw\_answer\_lock\_period\_template                  | ❌                                       | ❌                              |                                                           |                                      |          | e.g. Please wait for %s mins to retry later                                                                             |
| C39   | circlepw\_recover\_pincode\_question\_config               | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_main2                   | circlepw\_body1                | ❌                                                         | text\_main2                          | regular  |                                                                                                                         |
| C40   | circlepw\_hint\_tag                                        | ✅              | ✅             | ✅        | circlepw\_hint\_tag                                       | circlepw\_tag\_text                     | circlepw\_metadata2            | circlepw\_hint                                            | recover\_pin\_hint\_title            | regular  |                                                                                                                         |
| C41   | circlepw\_recover\_pincode\_answer\_hint\_config           | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_tag\_following\_text          | circlepw\_metadata1            | ❌                                                         | recover\_pin\_hint                   | regular  |                                                                                                                         |
| C42   | circlepw\_recover\_pincode\_answer\_input\_header          | ✅              | ✅             | ✅        | circlepw\_recover\_pincode\_answer\_input\_header         | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_recover\_pincode\_answer\_input\_header         | text\_auxiliary                      | regular  |                                                                                                                         |
| C43   | circlepw\_recover\_pincode\_answer\_input\_placeholder     | ✅🔖            | ✅🔖           | ❌🔖      | circlepw\_recover\_pincode\_answer\_input\_placeholder    | circlepw\_placeholder                   | circlepw\_body1                | circlepw\_recover\_pincode\_answer\_input\_placeholder    | text\_placeholder                    | regular  | Set ​​TextView's textColorHint and hint. Apply circlepw\_recover\_pincode\_input\_config (C44)'s font.                  |
| C44   | circlepw\_recover\_pincode\_input\_config                  | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_main                    | circlepw\_body1                | ❌                                                         | text\_main                           | regular  |                                                                                                                         |
| C45   | circlepw\_confirm                                          | ✅              | ✅             | ✅        | circlepw\_confirm                                         | circlepw\_main\_bt\_text                | circlepw\_mainButtonText       | circlepw\_confirm                                         | main\_bt\_text                       | semibold |                                                                                                                         |
|       |                                                            |                |               |          |                                                           | circlepw\_main\_bt\_text\_pressed       |                                |                                                           | main\_bt\_text\_pressed              |          |                                                                                                                         |
|       |                                                            |                |               |          |                                                           | circlepw\_disabled\_main\_bt\_text      |                                |                                                           | main\_bt\_text\_disabled             |          |                                                                                                                         |
| C46   | circlepw\_pin\_biometrics\_allow\_title                    | ✅              | ✅             | ✅        | circlepw\_pin\_biometrics\_allow\_title                   | circlepw\_text\_main                    | circlepw\_heading3             | circlepw\_pin\_biometrics\_allow\_title                   | text\_prompt                         | bold     |                                                                                                                         |
| C47   | circlepw\_pin\_biometrics\_allow\_subtitle                 | ✅              | ✅             | ✅        | circlepw\_pin\_biometrics\_allow\_subtitle                | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_pin\_biometrics\_allow\_subtitle                | text\_prompt2                        | regular  |                                                                                                                         |
| C48   | circlepw\_skip                                             | ✅              | ✅             | ✅        | circlepw\_skip                                            | circlepw\_second\_bt\_text              | circlepw\_secondButton         | circlepw\_skip                                            | second\_bt\_text                     | semibold | Normal                                                                                                                  |
|       |                                                            |                |               |          |                                                           | circlepw\_second\_bt\_text              |                                |                                                           |                                      |          | Pressed                                                                                                                 |
|       |                                                            |                |               |          |                                                           | circlepw\_second\_bt\_text\_disabled    |                                |                                                           |                                      |          | Disabled                                                                                                                |
| C49   | circlepw\_pin\_biometrics\_disable                         | ✅              | ✅             | ✅        | circlepw\_pin\_biometrics\_disable                        | circlepw\_plain\_bt\_text               | circlepw\_plainButton          | circlepw\_pin\_biometrics\_disable                        | plain\_bt\_text                      | semibold | Normal                                                                                                                  |
|       |                                                            |                |               |          |                                                           | circlepw\_plain\_bt\_text               |                                |                                                           |                                      |          | Pressed                                                                                                                 |
|       |                                                            |                |               |          |                                                           | circlepw\_plain\_bt\_text\_disabled     |                                |                                                           |                                      |          | Disabled                                                                                                                |
| C50   | circlepw\_pin\_biometrics\_encrypt\_title                  | ✅              | ❌             | ❌        | circlepw\_pin\_biometrics\_encrypt\_title                 | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C51   | circlepw\_pin\_biometrics\_encrypt\_negative\_text         | ✅              | ❌             | ❌        | circlepw\_pin\_biometrics\_encrypt\_negative\_text        | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C52   | circlepw\_pin\_biometrics\_encrypt\_subtitle               | ✅              | ❌             | ❌        | circlepw\_pin\_biometrics\_encrypt\_subtitle              | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C53   | circlepw\_pin\_biometrics\_encrypt\_desc                   | ✅              | ❌             | ❌        | circlepw\_pin\_biometrics\_encrypt\_desc                  | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C54   | circlepw\_pin\_biometrics\_decrypt\_title                  | ✅              | ❌             | ❌        | circlepw\_pin\_biometrics\_decrypt\_title                 | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C55   | circlepw\_pin\_biometrics\_decrypt\_negative\_text         | ✅              | ❌             | ❌        | circlepw\_pin\_biometrics\_decrypt\_negative\_text        | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C56   | circlepw\_pin\_biometrics\_decrypt\_subtitle               | ✅              | ❌             | ❌        | circlepw\_pin\_biometrics\_decrypt\_subtitle              | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C57   | circlepw\_pin\_biometrics\_decrypt\_desc                   | ✅              | ❌             | ❌        | circlepw\_pin\_biometrics\_decrypt\_desc                  | ❌                                       | ❌                              | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C58   | circlepw\_pin\_biometrics\_update\_title                   | ✅🔖            | ✅             | ✅        | circlepw\_pin\_biometrics\_update\_title                  | circlepw\_text\_main                    | circlepw\_heading3             | circlepw\_pin\_biometrics\_update\_title                  | text\_prompt                         | bold     | After the auto-fill PIN verify fails, the following biometrics setting page title will use this.                        |
| C59   | circlepw\_pin\_biometrics\_update\_subtitle                | ✅🔖            | ✅             | ✅        | circlepw\_pin\_biometrics\_update\_subtitle               | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_pin\_biometrics\_update\_subtitle               | text\_prompt2                        | regular  | After the auto-fill PIN verify fails, the following biometrics setting page subtitle will use this.                     |
| C60   | ❌                                                          | ❌              | ❌             | ❌        | ❌                                                         | ❌                                       | ❌                              | circlepw\_pin\_touch\_id\_dialog\_subtitle                | ❌                                    | ❌        | iOS only. info.plist                                                                                                    |
| C61   | circlepw\_alert\_pop\_window\_description\_config          | ❌🔖            | ✅             | ✅        | ❌🔖                                                       | circlepw\_alert\_pop\_description\_text | circlepw\_body2                | ❌                                                         | ❌                                    | ❌        | For text, see Error Message: biometricsKeyPermanentlyInvalidated(155710). Android only.                                 |
| C62   | circlepw\_alert\_pop\_window\_confirm                      | ✅              | ✅             | ✅        | circlepw\_alert\_pop\_window\_confirm                     | circlepw\_alert\_pop\_btn\_text         | circlepw\_actionText           | ❌                                                         | ❌                                    | ❌        | Android only.                                                                                                           |
| C63   | circlepw\_transaction\_request\_title                      | ✅              | ✅             | ✅        | circlepw\_transaction\_request\_title                     | circlepw\_text\_main                    | circlepw\_heading3             | circlepw\_transaction\_request\_title                     | text\_main                           | medium   |                                                                                                                         |
| C64   | circlepw\_transaction\_request\_subtitle                   | ✅              | ✅             | ✅        | circlepw\_transaction\_request\_subtitle                  | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_transaction\_request\_subtitle                  | text\_auxiliary                      | regular  |                                                                                                                         |
| C65   | circlepw\_transaction\_request\_main\_currency             | ✅🔖            | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txAmountMainText     | circlepw\_transaction\_request\_main\_currency            | text\_prompt                         | heavy    |                                                                                                                         |
| C66   | circlepw\_transaction\_request\_exchange\_value            | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_exchange                | circlepw\_txExchangeText       | circlepw\_transaction\_request\_exchange\_value           | text\_exchange                       | semibold |                                                                                                                         |
| C67   | circlepw\_transaction\_request\_from\_label                | ✅              | ✅             | ✅        | circlepw\_transaction\_request\_from\_label               | circlepw\_text\_prompt                  | circlepw\_txInfoText           | circlepw\_transaction\_request\_from\_label               | text\_prompt                         | regular  |                                                                                                                         |
| C68   | circlepw\_transaction\_request\_from                       | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | circlepw\_transaction\_request\_from                      | text\_prompt                         | regular  |                                                                                                                         |
| C69   | circlepw\_transaction\_request\_to\_label                  | ✅              | ✅             | ✅        | circlepw\_transaction\_request\_to\_label                 | circlepw\_text\_prompt                  | circlepw\_txInfoText           | circlepw\_transaction\_request\_to\_label                 | text\_prompt                         | regular  |                                                                                                                         |
| C70   | circlepw\_transaction\_request\_to\_config                 | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | ❌                                                         | text\_prompt                         | semibold |                                                                                                                         |
| C71   | circlepw\_transaction\_request\_to\_contract\_name         | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | circlepw\_transaction\_request\_to\_contract\_name        | text\_prompt                         | semibold |                                                                                                                         |
| C72   | circlepw\_transaction\_request\_to\_contract\_url          | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | circlepw\_transaction\_request\_to\_contract\_url         | text\_prompt                         | semibold |                                                                                                                         |
| C73   | circlepw\_transaction\_request\_network\_fee\_label        | ✅              | ✅             | ✅        | circlepw\_transaction\_request\_network\_fee\_label       | circlepw\_text\_prompt                  | circlepw\_txInfoText           | circlepw\_transaction\_request\_network\_fee\_label       | text\_prompt                         | regular  |                                                                                                                         |
| C74   | circlepw\_transaction\_request\_network\_fee               | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | circlepw\_transaction\_request\_network\_fee              | text\_prompt                         | semibold |                                                                                                                         |
| C75   | circlepw\_transaction\_request\_exchange\_network\_fee     | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_exchange                | circlepw\_txInfoExchangeText   | circlepw\_transaction\_request\_exchange\_network\_fee    | text\_exchange                       | regular  |                                                                                                                         |
| C76   | circlepw\_transaction\_request\_total\_label               | ✅              | ✅             | ✅        | circlepw\_transaction\_request\_total\_label              | circlepw\_text\_prompt                  | circlepw\_txInfoText           | circlepw\_transaction\_request\_total\_label              | text\_prompt                         | regular  |                                                                                                                         |
| C77   | circlepw\_transaction\_request\_total\_config              | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | ❌                                                         | text\_prompt                         | semibold |                                                                                                                         |
| C78   | circlepw\_transaction\_request\_exchange\_total\_value     | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_exchange                | circlepw\_txInfoExchangeText   | circlepw\_transaction\_request\_exchange\_total\_value    | text\_exchange                       | regular  |                                                                                                                         |
| C79   | circlepw\_transaction\_request\_error\_config              | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_error                         | circlepw\_body2                | ❌                                                         | error                                | regular  |                                                                                                                         |
| C80   | circlepw\_transaction\_request\_fee\_tip                   | ✅              | ✅             | ✅        | circlepw\_transaction\_request\_fee\_tip                  | circlepw\_tip\_text                     | circlepw\_feeTipText           | circlepw\_transaction\_request\_fee\_tip                  | tip\_text                            | regular  |                                                                                                                         |
| C81   | circlepw\_contract\_interaction\_contract\_address\_label  | ✅              | ✅             | ✅        | circlepw\_contract\_interaction\_contract\_address\_label | circlepw\_text\_prompt                  | circlepw\_txInfoText           | circlepw\_contract\_interaction\_contract\_address\_label | text\_prompt                         | regular  |                                                                                                                         |
| C82   | circlepw\_contract\_interaction\_contract\_address\_config | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | ❌                                                         | text\_prompt                         | semibold |                                                                                                                         |
| C83   | circlepw\_contract\_interaction\_data\_details             | ✅              | ✅             | ✅        | circlepw\_contract\_interaction\_data\_details            | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | circlepw\_contract\_interaction\_data\_details            | text\_prompt                         | semibold |                                                                                                                         |
| C84   | circlepw\_contract\_interaction\_abi\_function\_label      | ✅              | ✅             | ✅        | circlepw\_contract\_interaction\_abi\_function\_label     | circlepw\_text\_prompt                  | circlepw\_txInfoText           | circlepw\_contract\_interaction\_abi\_function\_label     | text\_prompt                         | regular  |                                                                                                                         |
| C85   | circlepw\_contract\_interaction\_abi\_function\_config     | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_txInfoValueText      | ❌                                                         | text\_prompt                         | semibold |                                                                                                                         |
| C86   | circlepw\_contract\_interaction\_abi\_parameter\_label     | ✅              | ✅             | ✅        | circlepw\_contract\_interaction\_abi\_parameter\_label    | circlepw\_text\_prompt                  | circlepw\_txInfoText           | circlepw\_contract\_interaction\_abi\_parameter\_label    | text\_prompt                         | regular  |                                                                                                                         |
| C87   | circlepw\_contract\_interaction\_call\_data\_label         | ✅              | ✅             | ✅        | circlepw\_contract\_interaction\_call\_data\_label        | circlepw\_text\_prompt                  | circlepw\_txInfoText           | circlepw\_contract\_interaction\_call\_data\_label        | text\_prompt                         | regular  |                                                                                                                         |
| C88   | circlepw\_contract\_interaction\_call\_data\_config        | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_interactive             | circlepw\_contractDataText     | ❌                                                         | text\_interactive                    | regular  |                                                                                                                         |
| C89   | circlepw\_transaction\_request\_raw\_tx\_description       | ✅              | ✅             | ✅        | circlepw\_transaction\_request\_raw\_tx\_description      | circlepw\_text\_auxiliary               | circlepw\_body2                | ❌                                                         | text\_auxiliary                      | regular  |                                                                                                                         |
| C90   | circlepw\_transaction\_request\_raw\_tx\_config            | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_auxiliary               | circlepw\_body2                | ❌                                                         | text\_auxiliary                      | regular  |                                                                                                                         |
| C91   | circlepw\_signature\_request\_title                        | ✅              | ✅             | ✅        | circlepw\_signature\_request\_title                       | circlepw\_text\_main                    | circlepw\_heading3             | circlepw\_signature\_request\_title                       | text\_main                           | semibold |                                                                                                                         |
| C92   | circlepw\_signature\_request\_contract\_name               | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_prompt                  | circlepw\_signNameText         | circlepw\_signature\_request\_contract\_name              | text\_prompt                         | semibold |                                                                                                                         |
| C93   | circlepw\_signature\_request\_contract\_url                | ✅              | ✅             | ✅        | ❌                                                         | circlepw\_text\_sign\_url               | circlepw\_signUrlText          | circlepw\_signature\_request\_contract\_url               | text\_sign\_url                      | regular  |                                                                                                                         |
| C94   | circlepw\_signature\_request\_subtitle                     | ✅              | ✅             | ✅        | circlepw\_signature\_request\_subtitle                    | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_signature\_request\_subtitle                    | text\_auxiliary                      | regular  |                                                                                                                         |
| C95   | circlepw\_signature\_request\_description                  | ✅              | ✅             | ✅        | circlepw\_signature\_request\_description                 | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_signature\_request\_description                 | text\_auxiliary                      | regular  |                                                                                                                         |
| C96   | circlepw\_signature\_request\_msg\_config                  | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_text\_auxiliary               | circlepw\_body2                | ❌                                                         | text\_auxiliary                      | regular  |                                                                                                                         |
| C97   | circlepw\_sign                                             | ✅              | ✅             | ✅        | circlepw\_sign                                            | circlepw\_main\_bt\_text                | circlepw\_mainButtonText       | circlepw\_sign                                            | main\_bt\_text                       | semibold |                                                                                                                         |
|       |                                                            |                |               |          |                                                           | circlepw\_main\_bt\_text\_pressed       |                                |                                                           | main\_bt\_text\_pressed              |          |                                                                                                                         |
|       |                                                            |                |               |          |                                                           | circlepw\_disabled\_main\_bt\_text      |                                |                                                           | main\_bt\_text\_disabled             |          |                                                                                                                         |
| C98   | circlepw\_try\_again                                       | ✅              | ✅             | ✅        | circlepw\_try\_again                                      | circlepw\_main\_bt\_text                | circlepw\_mainButtonText       | circlepw\_try\_again                                      | main\_bt\_text                       | semibold |                                                                                                                         |
|       |                                                            |                |               |          |                                                           | circlepw\_main\_bt\_text\_pressed       |                                |                                                           | main\_bt\_text\_pressed              |          |                                                                                                                         |
|       |                                                            |                |               |          |                                                           | circlepw\_disabled\_main\_bt\_text      |                                |                                                           | main\_bt\_text\_disabled             |          |                                                                                                                         |
| C99   | circlepw\_email\_otp\_title                                | ✅              | ✅             | ✅        | circlepw\_email\_otp\_title                               | circlepw\_text\_main                    | circlepw\_heading3             | circlepw\_email\_otp\_title                               | text\_main                           | medium   |                                                                                                                         |
| C100  | circlepw\_email\_otp\_description                          | ✅              | ✅             | ✅        | circlepw\_email\_otp\_description                         | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_email\_otp\_description                         | text\_auxiliary                      | regular  |                                                                                                                         |
| C101  | circlepw\_email\_otp\_email                                | ✅              | ❌             | ❌        | ❌                                                         | ❌                                       | ❌                              | circlepw\_email\_otp\_email                               | ❌                                    | ❌        |                                                                                                                         |
| C102  | circlepw\_email\_otp\_head\_config                         | ❌              | ✅             | ✅        | ❌                                                         | circlepw\_otp\_head\_text               | circlepw\_otpHeadText          | ❌                                                         | text\_prompt                         | regular  |                                                                                                                         |
| C103  | circlepw\_email\_otp\_dash                                 | ✅              | ✅             | ✅        | circlepw\_email\_otp\_dash                                | circlepw\_otp\_head\_text               | circlepw\_otpHeadText          | circlepw\_email\_otp\_dash                                | text\_prompt                         | regular  |                                                                                                                         |
| C104  | circlepw\_email\_otp\_send\_again\_hint                    | ✅              | ✅             | ✅        | circlepw\_email\_otp\_send\_again\_hint                   | circlepw\_otp\_hint\_text               | circlepw\_otpSendAgainHintText | circlepw\_email\_otp\_send\_again\_hint                   | text\_auxiliary                      | regular  |                                                                                                                         |
| C105  | circlepw\_email\_otp\_send\_again                          | ✅              | ✅             | ✅        | circlepw\_email\_otp\_send\_again                         | circlepw\_otp\_action\_text             | circlepw\_otpSendAgainHintText | circlepw\_email\_otp\_send\_again                         | text\_action                         | regular  |                                                                                                                         |
| C106  | circlepw\_contract\_interaction\_title                     | ✅              | ✅             | ✅        | circlepw\_contract\_interaction\_title                    | circlepw\_text\_main                    | circlepw\_heading3             | circlepw\_contract\_interaction\_title                    | text\_main                           | medium   |                                                                                                                         |
| C107  | circlepw\_contract\_interaction\_subtitle                  | ✅              | ✅             | ✅        | circlepw\_contract\_interaction\_subtitle                 | circlepw\_text\_auxiliary               | circlepw\_body2                | circlepw\_contract\_interaction\_subtitle                 | text\_auxiliary                      | regular  |                                                                                                                         |

## Error Messages

When using this table, reference the **ApiError** heading in the
[WalletSDK section](/wallets/user-controlled/react-native-sdk) of the SDK.

| Possible display location | ApiError.ErrorCode                          | Default Value                                                           | Note                                                      |
| ------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- |
| C5, C38, C79              | unknown(-1)                                 | Unknown error                                                           |                                                           |
|                           | success(0)                                  | Success                                                                 |                                                           |
| C5, C38, C79              | apiParameterMissing(1)                      | API parameter missing                                                   |                                                           |
| C5, C38, C79              | apiParameterInvalid(2)                      | API parameter invalid                                                   |                                                           |
| C5, C38, C79              | forbidden(3)                                | Forbidden                                                               |                                                           |
| C5, C38, C79              | unauthorized(4)                             | Unauthorized                                                            |                                                           |
| C5, C38, C79              | retry(9)                                    | Retry                                                                   |                                                           |
| C5, C38                   | customerSuspended(10)                       | Customer suspended                                                      |                                                           |
| C5, C38                   | pending(11)                                 | Pending                                                                 |                                                           |
| C5, C38                   | invalidSession(12)                          | Invalid session                                                         |                                                           |
| C5, C38                   | invalidPartnerId(13)                        | Invalid partner ID                                                      |                                                           |
| C5, C38                   | invalidMessage(14)                          | Invalid Message published to a SQS queue                                |                                                           |
| C5, C38, C79              | invalidPhone(15)                            | Invalid phone number - should be in E.164 format                        |                                                           |
| C5, C79                   | walletIdNotFound(156001)                    | No such wallet or not accessible to caller                              |                                                           |
| C5, C79                   | tokenIdNotFound(156002)                     | No such token or not accessible to caller                               |                                                           |
| C5, C79                   | transactionIdNotFound(156003)               | No such transaction or not accessible to caller                         |                                                           |
| C5, C79                   | entityCredentialNotFound(156004)            | Reusing entity secret ciphertext not allowed                            |                                                           |
| C5, C79                   | walletSetIdNotFound(156005)                 | No such wallet set or not accessible to caller                          |                                                           |
|                           | userAlreadyExisted(155101)                  | User already existed                                                    |                                                           |
|                           | userNotFound(155102)                        | User not found                                                          |                                                           |
| C5, C38, C79              | userTokenNotFound(155103)                   | User token not found                                                    |                                                           |
| C5, C38, C79              | userTokenExpired(155104)                    | User token expired                                                      |                                                           |
| C5, C38                   | invalidUserToken(155105)                    | Invalid user token                                                      |                                                           |
| C5                        | userWasInitialized(155106)                  | User was initialized                                                    |                                                           |
| C5                        | userHasSetPin(155107)                       | User has set pin                                                        |                                                           |
| C38                       | userHasSetSecurityQuestion(155108)          | User has set security question                                          |                                                           |
| C5, C38                   | userWasDisabled(155109)                     | User was disabled                                                       |                                                           |
| C5                        | userDoesNotSetPinYet(155110)                | User does not set pin yet                                               |                                                           |
| C38                       | userDoesNotSetSecurityQuestionYet(155111)   | User does not set security questions yet                                |                                                           |
| C5                        | incorrectUserPin(155112)                    | PIN entered is incorrect                                                |                                                           |
|                           | incorrectDeviceId(155113)                   | Incorrect device id                                                     |                                                           |
|                           | incorrectAppId(155114)                      | App id not found                                                        |                                                           |
| C38                       | incorrectSecurityAnswers(155115)            | Answers entered are incorrect                                           |                                                           |
|                           | invalidChallengeId(155116)                  | Invalid challenge id                                                    |                                                           |
| C5                        | invalidApproveContent(155117)               | Invalid approve content                                                 |                                                           |
| C5, C38                   | invalidSecretKey(155118)                    | Invalid secret key                                                      |                                                           |
| C5                        | userPinLocked(155119)                       | User PIN input is locked                                                | Just display circlepw\_pin\_lock\_period\_template (C5-2) |
| C38                       | securityAnswersLocked(155120)               | Answers entered are incorrect                                           |                                                           |
| C5                        | walletIsFrozen(155501)                      | Wallet is frozen                                                        |                                                           |
| C5                        | maxWalletLimitReached(155502)               | Max wallet limit reached                                                |                                                           |
| C5                        | walletSetIdMutuallyExclusive(155503)        | WalletSetId can not be used together with blockchain and address filter |                                                           |
| C5                        | metadataUnmatched(155504)                   | Metadata array length does not match wallet count                       |                                                           |
|                           | userCanceled(155701)                        | User canceled                                                           |                                                           |
|                           | launchUiFailed(155702)                      | UI launch failed                                                        | Check error message for exact UI launch failure reason    |
| C5                        | pinCodeNotMatched(155703)                   | PIN entered not the same as first one                                   |                                                           |
| C5                        | insecurePinCode(155704)                     | PIN can't have repeating or consecutive numbers                         |                                                           |
| C22                       | hintsMatchAnswers(155705)                   | Hint can't be the same as the answer                                    |                                                           |
|                           | biometricsSettingNotEnabled(155708)         | "Biometrics instead of PIN" is disabled                                 |                                                           |
|                           | deviceNotSupportBiometrics(155709)          | The device system doesn't support biometrics                            |                                                           |
| C61                       | biometricsKeyPermanentlyInvalidated(155710) | Failed to decrypt biometrics key                                        |                                                           |
|                           | biometricsUserSkip(155711)                  | The user has not enabled biometrics yet                                 |                                                           |
|                           | biometricsUserDisableForPin(155712)         | The user refused to enable biometrics                                   |                                                           |
|                           | biometricsUserLockout(155713)               | Too many requests - try again later                                     |                                                           |
|                           | biometricsUserLockoutPermanent(155714)      | Too many requests - biometrics sensor on the device is locked           |                                                           |
|                           | biometricsUserNotAllowPermission(155715)    | User didn't allow to enable biometrics                                  |                                                           |
|                           | biometricsInternalError(155716)             | Unexpected error for biometrics                                         | Check error message for more information                  |

## Image Customization

The SDK does not contain any image resources for the SDK; you must provide the
icon images from either local assets or remote URLs.\
Each image has its suggested size of width and height shown in the index table's
Image view size column. Follow the suggested size to avoid the possibility of a
broken layout or unexpected display.

## ImageKey

### D1\~D9

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### D Index Table

| #   | ImageKey             | Image View size (dp) |            | Note         |
| --- | -------------------- | -------------------- | ---------- | ------------ |
|     |                      | **width**            | **height** |              |
| D1  | securityIntroMain    | 144                  | 144        |              |
| D2  | selectCheckMark      | 24                   | 24         |              |
| D3  | dropdownArrow        | 40                   | 40         |              |
| D4  | errorInfo            | 21                   | 21         |              |
| D5  | securityConfirmMain  | 144                  | 144        |              |
| D6  | biometricsAllowMain  | 80                   | 80         |              |
| D7  | showPin              | 20                   | 15         |              |
| D8  | hidePin              | 20                   | 15         |              |
| D9  | alertWindowIcon      | 24                   | 24         | Android only |
| D10 | close                | 24                   | 24         |              |
| D11 | back                 | 24                   | 24         |              |
| D12 | transactionTokenIcon | 36                   | 36         |              |
| D13 | networkFeeTipIcon    | 16                   | 16         |              |
| D14 | showLessDetailArrow  | 20                   | 20         |              |
| D15 | showMoreDetailArrow  | 20                   | 20         |              |
| D16 | requestIcon          | 72                   | 72         |              |

## Color Customization

Colors can be customized in a static way as a static string; with the UI
screenshots and Key mapping index table below, the colors of each string can be
defined in the colors.xml.Note that some keys are not specified in the
screenshot but can be referenced from the A and C index table in the colors.xml
(for Android) and color(for iOS) column.\
To avoid dynamic customization, initialize a TextConfig that contains text only
with no color value. For example, use a configuration with new TextConfig(key,
undefined, font).\
For the static resource usage, please check
[Android - colors.xml](/wallets/user-controlled/react-native-sdk-ui-customization-api#android---colorsxml)
and
[iOS - CirclePWTheme.json](/wallets/user-controlled/react-native-sdk-ui-customization-api#ios---circlepwthemejson).

## New, Confirm, and Enter PIN Code

<Frame>
  <img />
</Frame>

## Security Intros

<Frame>
  <img />
</Frame>

## Security Questions

<Frame>
  <img />
</Frame>

## Security Summary

<Frame>
  <img />
</Frame>

## Security Confirm

<Frame>
  <img />
</Frame>

## Recover PIN Code

<Frame>
  <img />
</Frame>

## Biometrics PIN Protection

<Frame>
  <img />
</Frame>

## Contract Interaction

<Frame>
  <img />
</Frame>

## Confirm Transaction

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Signature Request

<Frame>
  <img />
</Frame>

## Verify OTP

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## F Index Table

| #   | colors.xml                                   | iOS CirclePWTheme.json          | Color Code | Note                                  |
| --- | -------------------------------------------- | ------------------------------- | ---------- | ------------------------------------- |
| F1  | circlepw\_text\_main                         | text\_main                      | # 1A1A1A   |                                       |
| F2  | circlepw\_text\_auxiliary                    | text\_auxiliary                 | # 3D3D3D   |                                       |
| F3  | circlepw\_text\_action                       | text\_action                    | # 136FD8   | Normal action text color              |
| F4  | circlepw\_text\_action\_pressed              | text\_action\_pressed           | # B3136FD8 | Pressed action text color             |
| F5  | circlepw\_placeholder                        | text\_placeholder               | # A3A3A3   |                                       |
| F6  | circlepw\_error                              | error                           | # F55538   |                                       |
| F7  | circlepw\_error\_background                  | error\_background               | # FDF2F2   |                                       |
| F8  | circlepw\_text\_main2                        | text\_main2                     | # 1C1C1C   |                                       |
| F9  | circlepw\_text\_auxiliary2                   | text\_auxiliary2                | # 707070   |                                       |
| F10 | circlepw\_text\_summary                      | text\_summary                   | # 0073C3   |                                       |
| F11 | circlepw\_disabled\_main\_bt\_text           | main\_bt\_text\_disabled        | # 80FFFFFF | Disabled button text color            |
| F12 | circlepw\_main\_bt\_text                     | main\_bt\_text                  | # FFFFFF   | Normal button text color              |
| F13 | circlepw\_main\_bt\_text\_pressed            | main\_bt\_text\_pressed         | # FFFFFF   | Pressed button text color             |
| F14 | circlepw\_disabled\_main\_bt\_background     | main\_bt\_background\_disabled  | # 800073C3 | Disabled button background color      |
| F15 | circlepw\_main\_bt\_background               | main\_bt\_background            | # 0073C3   | Normal button background color        |
| F16 | circlepw\_main\_bt\_background\_pressed      | main\_bt\_background\_pressed   | # 1AA3FF   | Pressed button background color       |
| F17 | circlepw\_success                            | success                         | # 0B9C4A   |                                       |
| F18 | circlepw\_input\_boarder                     | input\_border                   | # E8E8E8   | Normal input field border             |
| F19 | circlepw\_input\_boarder\_focused            | input\_border\_focused          | # 46B5FF   | Focused input field border            |
| F20 | circlepw\_tag\_text                          | recover\_pin\_hint\_title       | # 005339   | Tag text color                        |
| F21 | circlepw\_tag\_background                    | recover\_pin\_hint\_title\_bg   | # E1F2FF   | Tag background color                  |
| F22 | circlepw\_tag\_following\_text               | recover\_pin\_hint              | # 0073C3   |                                       |
| F23 | circlepw\_divider                            | divider                         | # F0EFEF   |                                       |
| F24 | circlepw\_pin\_dot\_base                     | pin\_dot\_base                  | # FFFFFF   | PIN dot unfilled color                |
| F25 | circlepw\_pin\_dot\_base\_boarder            | pin\_dot\_base\_boarder         | # 707070   | PIN dot unfilled border color         |
| F26 | circlepw\_pin\_dot\_activated                | pin\_dot\_activated             | # 0073C3   | PIN dot filled color                  |
| F27 | circlepw\_background                         | background                      | # FFFFFF   | General background color              |
| F28 | circlepw\_security\_confirm\_main\_bg        | security\_confirm\_main\_bg     | # E9EEFE   |                                       |
| F29 | circlepw\_disabled\_input\_background        | input\_background\_disabled     | # F5F5F5   | Disabled input field background color |
| F30 | circlepw\_second\_bt\_text                   | second\_bt\_text                | # 0073C3   |                                       |
| F32 | circlepw\_second\_bt\_border                 | second\_bt\_border              | # 0073C3   |                                       |
| F34 | circlepw\_second\_bt\_background             | second\_bt\_background          | # FFFFFF   |                                       |
| F35 | circlepw\_second\_bt\_background\_pressed    | second\_bt\_background\_pressed | # F1F9FE   |                                       |
| F37 | circlepw\_plain\_bt\_text                    | plain\_bt\_text                 | # 0073C3   |                                       |
| F39 | circlepw\_plain\_bt\_background              | plain\_bt\_background           | # FFFFFF   |                                       |
| F40 | circlepw\_plain\_bt\_background\_pressed     | plain\_bt\_background\_pressed  | # F1F9FE   |                                       |
| F42 | circlepw\_text\_prompt                       | text\_prompt                    | # 29233B   |                                       |
| F43 | circlepw\_text\_interactive                  | text\_interactive               | # 0073C3   |                                       |
| F44 | circlepw\_interactive\_bg                    | interactive\_background         | # F9F9FC   |                                       |
| F45 | circlepw\_text\_exchange                     | text\_exchange                  | # F0EFEF   |                                       |
| F46 | circlepw\_tip\_text                          | tip\_text                       | # FFFFFF   |                                       |
| F47 | circlepw\_transaction\_request\_fee\_tip\_bg | tip\_background                 | # 29233B   |                                       |
| F48 | circlepw\_text\_sign\_url                    | text\_sign\_url                 | # 8E8E93   |                                       |
| F49 | circlepw\_otp\_head\_text                    | text\_prompt                    | # 000000   |                                       |
| F50 | circlepw\_otp\_hint\_text                    | text\_auxiliary                 | # 6B6580   |                                       |
| F51 | circlepw\_otp\_action\_text                  | text\_action                    | # 007AFF   |                                       |

## Text Style / Font Customization

Styles can be customized in a Static way as a static style by using the UI
screenshots and Key mapping index table below. The styles of each string can be
defined in the styles.xml file.\
To avoid dynamic customization, initialize a TextConfig that contains text and
color only. For example, use a configuration with new TextConfig(key, color,
undefined).

<Note>
  **Note:**

  Some keys (error message) are not specified in the screenshot but can be
  referenced from the A and C index table at the `styles.xml`file column.
</Note>

For the static resource usage, please check
[Android - styles.xml](/wallets/user-controlled/react-native-sdk-ui-customization-api#android---stylesxml)
and iOS -
[CirclePWTheme.json](/wallets/user-controlled/react-native-sdk-ui-customization-api#ios---circlepwthemejson).

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## G Index Table

| #   | styles.xml                     | iOS CirclePWTheme.json | Note         |
| --- | ------------------------------ | ---------------------- | ------------ |
| G1  | circlepw\_heading3             | semibold               |              |
| G2  | circlepw\_heading4             | semibold               |              |
| G3  | circlepw\_heading5             | semibold               |              |
| G4  | circlepw\_body1                | regular                |              |
| G5  | circlepw\_body2                | regular                |              |
| G6  | circlepw\_caption1             | semibold               |              |
| G7  | circlepw\_caption2             | semibold               |              |
| G8  | circlepw\_metadata1            | regular                |              |
| G9  | circlepw\_metadata2            | regular                |              |
| G10 | circlepw\_actionText           | semibold               |              |
| G11 | circlepw\_pinDigitText         | light                  |              |
| G12 | circlepw\_mainButtonText       | semibold               |              |
| G13 | circlepw\_toolbarTitle         | medium                 |              |
| G14 | circlepw\_datePicker           |                        | Android only |
| G15 | circlepw\_secondButtonText     | semibold               |              |
| G16 | circlepw\_plainButtonText      | semibold               |              |
| G17 | circlepw\_txAmountMainText     | heavy                  |              |
| G18 | circlepw\_txInfoText           | regular                |              |
| G19 | circlepw\_txInfoValueText      | semibold               |              |
| G20 | circlepw\_detailToggleText     | semibold               |              |
| G21 | circlepw\_contractDataText     | regular                |              |
| G22 | circlepw\_txExchangeText       | semibold               |              |
| G23 | circlepw\_txInfoExchangeText   | regular                |              |
| G24 | circlepw\_feeTipText           | regular                |              |
| G25 | circlepw\_otpHeadText          | regular                |              |
| G26 | circlepw\_otpSendAgainHintText | regular                |              |
| G27 | circlepw\_signNameText         | semibold               |              |
| G28 | circlepw\_signUrlText          | regular                |              |

## Static Resources

This section describes how to customize the UI statically.\
Android - strings.xml\
The example values in the strings.xml file below can be used for Static
Customization. The fields also show the default string values in the SDK if you
do not set dynamic customization.\
Please reference this example and add/update any desired text string in your
strings.xml under the res/values folder.

```coffeescript XML theme={null}
<resources>
    <!-- [General] -->
    <string name="circlepw_continue">Continue</string>
    <string name="circlepw_next">Next</string>
    <string name="circlepw_skip">Skip</string>
    <string name="circlepw_question_label">Question:</string>
    <string name="circlepw_answer_label">Answer:</string>
    <string name="circlepw_hint_label">Hint:</string>
    <string name="circlepw_hint_tag">Hint</string>
    <string name="circlepw_empty"></string>
    <string name="circlepw_empty_placeholder">-</string>
    <string name="circlepw_confirm">Confirm</string>
    <string name="circlepw_pin_remain_attemps_template">You have %s attempts left.</string>
    <string name="circlepw_pin_lock_period_template">You've used up all PIN attempts. Please wait for %s mins to retry later.</string>
    <string name="circlepw_answer_remain_attemps_template">You have %s attempts left.</string>
    <string name="circlepw_answer_lock_period_template">Please wait for %s mins to retry later.</string>

    <!-- [Page] EnterPINCode -->
    <string name="circlepw_enter_pincode_subhead">Let us know if it's really you.</string>
    <string name="circlepw_enter_pincode_forgot_pin">Forgot PIN?</string>
    <string name="circlepw_enter_pincode_use_biometrics">Use Biometrics</string>

    <!-- [Page] NewPINCode -->
    <string name="circlepw_new_pincode_subhead">Your PIN can't have repeating (e.g. 000000) or consecutive (e.g. 123456) numbers.</string>
    <!-- [Page] ConfirmPINCode -->
    <string name="circlepw_confirm_pincode_headline">Re-enter your PIN to confirm</string>
    <string name="circlepw_confirm_pincode_subhead"></string>
    <!-- [Page] SecurityIntros -->
    <string name="circlepw_security_intros_description">This is the only way to recover wallet access if you forget your PIN. Pick 2 security questions and provide answers for access recovery.</string>

    <!-- [Page] SecurityQuestions -->
    <string name="circlepw_security_questions_title">Recovery method</string>
    <string name="circlepw_security_questions_required_mark">*</string>
    <string name="circlepw_security_questions_question_placeholder">Select one question</string>
    <string name="circlepw_security_questions_answer_header">Provide an answer</string>
    <string name="circlepw_security_questions_answer_placeholder">Type your answer here</string>
    <string name="circlepw_security_questions_answer_hint_header">Provide an answer hint (optional)</string>
    <string name="circlepw_security_questions_answer_hint_placeholder">Type your hint here</string>

    <!-- [Page] SelectQuestion -->
    <string name="circlepw_select_question_title">Select one question</string>
    <!-- [Page] SecuritySummary -->
    <string name="circlepw_security_summary_title">Summary</string>

    <!-- [Page] SecurityConfirm -->
    <string name="circlepw_security_confirm_title">Confirmation</string>
    <string name="circlepw_security_confirm_headline">Keep your questions safe</string>
    <string name="circlepw_security_confirm_input_headline">Type \"I agree\" to proceed:</string>
    <string name="circlepw_security_confirm_input_placeholder">Type \"I agree\" here</string>
    <string name="circlepw_security_confirm_input_match">I agree</string>

    <!-- [Page] RecoverPINCode -->
    <string name="circlepw_recover_pincode_answer_input_header">Enter your answer here</string>
    <string name="circlepw_recover_pincode_answer_input_placeholder">Type your answer here</string>

    <!-- [Page] BiometricsAllowFragment -->
    <string name="circlepw_pin_biometrics_allow_title">Allow Biometrics for Web3 Access</string>
    <string name="circlepw_pin_biometrics_allow_subtitle">Elevate your experience with effortless biometrics  recognition</string>
    <string name="circlepw_pin_biometrics_disable">Don\'t ask me again</string>
    <string name="circlepw_pin_biometrics_encrypt_title">Verify It\'s Youe</string>
    <string name="circlepw_pin_biometrics_encrypt_negative_text">Cancel</string>
    <string name="circlepw_pin_biometrics_encrypt_subtitle"></string>
    <string name="circlepw_pin_biometrics_encrypt_desc"></string>
    <string name="circlepw_pin_biometrics_decrypt_title">Verify It\'s Youe</string>
    <string name="circlepw_pin_biometrics_decrypt_negative_text">Cancel</string>
    <string name="circlepw_pin_biometrics_decrypt_subtitle"></string>
    <string name="circlepw_pin_biometrics_decrypt_desc"></string>

    <string name="circlepw_pin_biometrics_update_title">Update Biometrics for Web3 Access</string>
    <string name="circlepw_pin_biometrics_update_subtitle">Please update your biometrics</string>
    <string name="circlepw_transaction_request_title">Confirm transaction</string>
    <string name="circlepw_transaction_request_subtitle">Please click confirm to proceed the transaction</string>
    <string name="circlepw_transaction_request_from_label">From</string>
    <string name="circlepw_transaction_request_to_label">To</string>
    <string name="circlepw_transaction_request_network_fee_label">Network fee</string>
    <string name="circlepw_transaction_request_total_label">Total</string>
    <string name="circlepw_transaction_request_fee_tip">Please note this is an estimated fee. Network fees may vary based on network traffic and transaction complexity.</string>
    <string name="circlepw_transaction_request_raw_tx_description">Transaction details:</string>
    <string name="circlepw_signature_request_title">Signature Request</string>
    <string name="circlepw_signature_request_subtitle">Click on sign button to provide a signature for verification.</string>
    <string name="circlepw_signature_request_description">You are signing:</string>

    <string name="circlepw_contract_interaction_title">Contract Interaction</string>
    <string name="circlepw_contract_interaction_subtitle">Please click confirm to proceed the  contract execution.</string>
    <string name="circlepw_contract_interaction_contract_address_label">Contract address</string>
    <string name="circlepw_contract_interaction_data_details">Data Details</string>
    <string name="circlepw_contract_interaction_abi_function_label">ABI Function</string>
    <string name="circlepw_contract_interaction_abi_parameter_label">ABI Parameters</string>
    <string name="circlepw_contract_interaction_call_data_label">Call Data</string>
    <string name="circlepw_email_otp_title">Enter verification code</string>
    <string name="circlepw_email_otp_description">The one-time passcode has been sent to %s</string>
    <string name="circlepw_email_otp_email">your email</string>
    <string name="circlepw_email_otp_dash">-</string>
    <string name="circlepw_email_otp_send_again_hint">Don't receive the code?</string>
    <string name="circlepw_email_otp_send_again">Send again</string>

    <!-- [Social log in] -->
    <string name="google_web_client_id">YOUR_WEB_CLIENT_ID</string>
    <string name="facebook_app_id">YOUR_APP_ID</string>
    <string name="fb_login_protocol_scheme">your_protocol_scheme</string>
    <string name="facebook_client_token">YOUR_CLIENT_TOKEN</string>
</resources>
```

### iOS - CirclePWLocalizable.strings

#### Setup

1. Create a file CirclePWLocalizable.strings in your main bundle.
2. Provide your strings. Partial override is supported.

<Note>
  **Note:**

  You can provide specific keys and values you want to override and others keys
  will still refer to the default values.
</Note>

<Frame>
  <img />
</Frame>

3. Localization is supported. For more information, see Localization | Apple
   Developer Documentation.

<Frame>
  <img />
</Frame>

#### Example CirclePWLocalizable.strings

```coffeescript XML theme={null}
/*
 * Loco ios export: iOS Localizable.strings
 * Project: strings.xml conversion
 * Release: Working copy
 * Locale: en, English
 * Exported by: Circle
 * Exported at: Tue, 27 Jun 2023 23:35:22 +0800
 */


// [General]
"circlepw_show_pin" = "Show PIN";
"circlepw_hide_pin" = "Hide PIN";
"circlepw_continue" = "Continue";
"circlepw_next" = "Next";
"circlepw_confirm" = "Confirm";
"circlepw_skip" = "Skip";


"circlepw_question" = "Question";
"circlepw_answer" = "Answer";
"circlepw_hint" = "Hint";
"circlepw_empty_placeholder" = "-";


// [Page] EnterPINCode
"circlepw_enter_pincode_headline" = "Enter your";
"circlepw_enter_pincode_headline_2" = "PIN";
"circlepw_enter_pincode_subhead" = "Let us know if it's really you.";
"circlepw_enter_pincode_forgot_pin" = "Forgot PIN?";
"circlepw_enter_pincode_use_biometrics" = "Use Biometrics";


// [Page] NewPINCode
"circlepw_new_pincode_headline" = "Enter your";
"circlepw_new_pincode_headline_2" = "New PIN";
"circlepw_new_pincode_subhead" = "Your PIN can't have repeating (e.g. 000000) or consecutive (e.g. 123456) numbers.";


// [Page] ConfirmPINCode
"circlepw_confirm_pincode_headline" = "Re-enter your PIN to confirm";
"circlepw_confirm_pincode_headline_2" = "";
"circlepw_confirm_pincode_subhead" = "";


// [Page] SecurityIntros
"circlepw_security_intros_title" = "Recovery Method";
"circlepw_security_intros_headline" = "Set up your";
"circlepw_security_intros_headline_2" = "Recovery Method";
"circlepw_security_intros_description" = "This is the only way to recover wallet access if you forget your PIN. Pick 2 security questions and provide answers for access recovery.";
"circlepw_security_intros_link" = "Learn more";


// [Page] SecurityQuestions
"circlepw_security_questions_title" = "Recovery method";
"circlepw_security_questions_question_header" = "Choose your %@ question";
"circlepw_security_questions_question_placeholder" = "Select one question";
"circlepw_security_questions_required_mark" = "*";
"circlepw_security_questions_answer_header" = "Provide an answer";
"circlepw_security_questions_answer_placeholder" = "Type your answer here";
"circlepw_security_questions_answer_hint_header" = "Provide an answer hint (optional)";
"circlepw_security_questions_answer_hint_placeholder" = "Type your hint here";


// [Page] SelectQuestion
"circlepw_select_question_title" = "Select one question";


// [Page] SecuritySummary
"circlepw_security_summary_title" = "Summary";


// [Page] SecurityConfirm
"circlepw_security_confirm_title" = "Confirmation";
"circlepw_security_confirm_headline" = "Keep your questions safe";
"circlepw_security_confirm_input_headline" = "Type “I agree” to proceed:";
"circlepw_security_confirm_input_placeholder" = "Type “I agree” here";
"circlepw_security_confirm_input_match" = "I agree";


// [Page] RecoverPINCode
"circlepw_recover_pincode_headline" = "Recover your";
"circlepw_recover_pincode_headline_2" = "Web3 PIN";
"circlepw_recover_pincode_subhead" = "Please enter the answer of the security questions provided below.";
"circlepw_recover_pincode_answer_input_header" = "Enter your answer here";
"circlepw_recover_pincode_answer_input_placeholder" = "Type your answer here";


// [Page] BiometricsPrompt
"circlepw_pin_biometrics_allow_title" = "Allow Biometrics for Web3 Access";
"circlepw_pin_biometrics_allow_subtitle" = "Elevate Your Experience with Effortless Biometrics";
"circlepw_pin_biometrics_failed_title" = "Failed Biometrics for Web3 Access";
"circlepw_pin_biometrics_update_title" = "Update Biometrics for Web3 Access";
"circlepw_pin_biometrics_update_subtitle" = "Please update your biometrics";
"circlepw_pin_biometrics_disable" = "Don't ask me again";
"circlepw_pin_touch_id_dialog_subtitle" = "Using Touch ID protect PIN";

```

### Android - colors.xml

The example values in the colors.xml file can be used for Static Customization.
The fields also show the default string values in the SDK if you do not set
dynamic customization.\
Please reference this example and add/update any desired text color in your
colors.xml under the res/values folder of the App project.

```coffeescript XML theme={null}
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="circlepw_text_main">#1A1A1A</color>
    <color name="circlepw_text_auxiliary">#3D3D3D</color>
    <color name="circlepw_text_action">#136FD8</color>
    <color name="circlepw_text_action_pressed">#B3136FD8</color>
    <color name="circlepw_placeholder">#A3A3A3</color>
    <color name="circlepw_error">#F55538</color>
    <color name="circlepw_error_background">#FDF2F2</color>
    <color name="circlepw_text_main2">#1C1C1C</color>
    <color name="circlepw_text_auxiliary2">#707070</color>
    <color name="circlepw_text_summary">#0073C3</color>
    <color name="circlepw_disabled_main_bt_text">#80FFFFFF</color>
    <color name="circlepw_disabled_main_bt_background">#800073C3</color>
    <color name="circlepw_main_bt_text">#FFFFFF</color>
    <color name="circlepw_main_bt_background">#0073C3</color>
    <color name="circlepw_main_bt_text_pressed">#FFFFFF</color>
    <color name="circlepw_main_bt_background_pressed">#1AA3FF</color>
    <color name="circlepw_second_bt_text">#0073C3</color>
    <color name="circlepw_second_bt_text_disabled">#800073C3</color>
    <color name="circlepw_second_bt_border">#0073C3</color>
    <color name="circlepw_second_bt_border_disabled">#800073C3</color>
    <color name="circlepw_second_bt_background">#FFFFFF</color>
    <color name="circlepw_second_bt_background_pressed">#F1F9FE</color>
    <color name="circlepw_second_bt_background_disabled">#80F1F9FE</color>
    <color name="circlepw_plain_bt_text">#0073C3</color>
    <color name="circlepw_plain_bt_text_disabled">#800073C3</color>
    <color name="circlepw_plain_bt_background">#FFFFFF</color>
    <color name="circlepw_plain_bt_background_pressed">#F1F9FE</color>
    <color name="circlepw_plain_bt_background_disabled">#80F1F9FE</color>
    <color name="circlepw_success">#0B9C4A</color>
    <color name="circlepw_input_boarder">#E8E8E8</color>
    <color name="circlepw_input_boarder_focused">#46B5FF</color>
    <color name="circlepw_input_boarder_focused_shadow">#00B1EABA</color>
    <color name="circlepw_tag_text">#3D3652</color>
    <color name="circlepw_tag_background">#E1F2FF</color>
    <color name="circlepw_tag_following_text">#0073C3</color>
    <color name="circlepw_divider">#F0EFEF</color>
    <color name="circlepw_pin_dot_base">#ffffff</color>
    <color name="circlepw_pin_dot_base_boarder">#707070</color>
    <color name="circlepw_pin_dot_activated">#0073C3</color>
    <color name="circlepw_background">#FFFFFF</color>
    <color name="circlepw_security_confirm_main_bg">#E9EEFE</color>
    <color name="circlepw_ripple_material_light">#08000000</color>
    <color name="circlepw_disabled_input_background">#F5F5F5</color>
    <color name="circlepw_alert_pop_window_background">#B3111827</color>
    <color name="circlepw_alert_pop_title_text">#1D1B20</color>
    <color name="circlepw_alert_pop_description_text">#49454F</color>
    <color name="circlepw_alert_pop_btn_text">#000000</color>
    <color name="circlepw_pin_dot_focused_boarder">#1894E8</color>
    <color name="circlepw_swipe_bt_text">#FFFFFF</color>
    <color name="circlepw_swipe_bt_main_background">#0073C3</color>
    <color name="circlepw_swpie_bt_secondary_background">#F1F9FE</color>
    <color name="circlepw_swpie_bt_confirming_progress_end">#33F1F9FE</color>
    <color name="circlepw_text_prompt">#29233B</color>
    <color name="circlepw_text_exchange">#979797</color>
    <color name="circlepw_text_sign_url">#8E8E93</color>
    <color name="circlepw_transaction_request_fee_tip_bg">#29233B</color>
    <color name="circlepw_tip_text">#FFFFFF</color>
    <color name="circlepw_interactive_bg">#F9F9FC</color>
    <color name="circlepw_text_interactive">#0073C3</color>
    <color name="transparent">#00000000</color>
    <color name="circlepw_otp_head_text">#000000</color>
    <color name="circlepw_otp_hint_text">#6B6580</color>
    <color name="circlepw_otp_action_text">#007AFF</color>
</resources>
```

### Android - styles.xml

The example values in the styles.xml file can be used for Static Customization.
The fields also show the default style values in the SDK if you do not set
dynamic customization.\
Please reference this example and add or update any desired text styles in your
styles.xml file under the res/values folder of the App project.\
The style can be used to define textSize and fontWeight, and it can also be used
in conjunction with the static colors key defined in colors.xml, such as in the
following:

```coffeescript XML theme={null}
<item name="colorControlActivated">@color/circlepw_input_boarder_focused</item>

```

```coffeescript XML theme={null}
<resources>
    <style name="circlepw_heading3">
        <item name="android:textSize">24sp</item>
    </style>
    <style name="circlepw_heading4">
        <item name="android:textSize">20sp</item>
    </style>
    <style name="circlepw_heading5">
        <item name="android:textSize">18sp</item>
    </style>
    <style name="circlepw_body1">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_body2">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_caption1">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_caption2">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_metadata1">
        <item name="android:textSize">12sp</item>
    </style>
    <style name="circlepw_metadata2">
        <item name="android:textSize">10sp</item>
    </style>
    <style name="circlepw_actionText">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_pinDigitText">
        <item name="android:textSize">40sp</item>
    </style>
    <style name="circlepw_mainButtonText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_secondButtonText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_plainButtonText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_toolbarTitle">
        <item name="android:textSize">18sp</item>
    </style>

    <style name="circlepw_datePicker" parent="Theme.AppCompat.Light.Dialog">
        <!-- Top background-->
        <item name="colorAccent">@color/circlepw_main_bt_background</item>
        <!--selected Item color-->
        <item name="colorControlActivated">@color/circlepw_main_bt_background</item>
        <!-- arrow bordercolor(<>)-->
        <item name="android:selectableItemBackgroundBorderless">@color/circlepw_background</item>
        <!--Calender Background color -->
        <item name="android:windowBackground">@color/circlepw_background</item>
        <!-- Ok Cancel Color-->
        <item name="colorOnPrimary">@color/circlepw_main_bt_background</item>
        <!-- Week TextColor-->
        <item name="android:textColorSecondary">@color/circlepw_text_main</item>
        <!-- Calender Number color arrow color (< >) -->
        <item name="android:textColorPrimary">@color/circlepw_text_main</item>
        <!--day , month-->
        <item name="android:textColorPrimaryInverse">@color/circlepw_background</item>
        <!-- year-->
        <item name="android:textColorSecondaryInverse">@color/circlepw_background</item>
    </style>
    <style name="circlepw_txAmountMainText">
        <item name="android:textSize">40sp</item>
    </style>
    <style name="circlepw_txExchangeText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_txInfoText">
        <item name="android:textSize">15sp</item>
    </style>
    <style name="circlepw_detailToggleText">
        <item name="android:textSize">16sp</item>
    </style>
    <style name="circlepw_txInfoValueText">
        <item name="android:textSize">15sp</item>
    </style>
    <style name="circlepw_contractDataText">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_txInfoExchangeText">
        <item name="android:textSize">13sp</item>
    </style>
    <style name="circlepw_feeTipText">
        <item name="android:textSize">14sp</item>
    </style>
    <style name="circlepw_signNameText">
        <item name="android:textSize">17sp</item>
    </style>
    <style name="circlepw_signUrlText">
        <item name="android:textSize">13sp</item>
    </style>
    <style name="circlepw_otpHeadText">
        <item name="android:textSize">24sp</item>
    </style>
    <style name="circlepw_otpSendAgainHintText">
        <item name="android:textSize">15sp</item>
    </style>
</resources>
```

### iOS - CirclePWTheme.json

#### Setup

1. Copy the file CirclePWTheme.json into your main bundle. You can use
   `Cmd + drag and drop`.

<Frame>
  <img />
</Frame>

2. Make sure you have selected the `Target Membership`.

<Frame>
  <img />
</Frame>

3. Provide values to set the font: To use a custom font, refer to this document:
   [Adding a Custom Font to Your App | Apple Developer Documentation.](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app)
4. Set the **color** with a hex string:

#### Example: CirclePWTheme.json

```coffeescript XML theme={null}
{
  "font": {
    "ultraLight": "",
    "thin": "",
    "light": "",
    "regular": "CustomFont-Regular",
    "medium": "CustomFont-Medium",
    "semibold": "",
    "bold": "",
    "heavy": "",
    "black": ""
  },
  "color": {
    "background": "#FFFFFF",
    "divider": "#F0EFEF",
    "success": "#0B9C4A",
    "error": "#F55538",
    "error_background": "#FDF2F2",


    "text_main": "#1A1A1A",
    "text_main2": "#1C1C1C",
    "text_auxiliary": "#3D3D3D",
    "text_auxiliary2": "#707070",
    "text_summary": "#0073C3",
    "text_summary_highlight": "#0073C3",
    "text_placeholder": "#A3A3A3",
    "text_action": "#136FD8",
    "text_action_pressed": "#B3136FD8",
    "text_prompt": "#29233B",
    "text_prompt2": "#6B6580",




    "pin_dot_base": "#FFFFFF",
    "pin_dot_base_border": "#707070",
    "pin_dot_activated": "#3D3D3D",
    "pin_dot_focused": "#0073C3",


    "input_border": "#E8E8E8",
    "input_border_focused": "#46B5FF",
    "input_background_disabled": "#F5F5F5",


    "main_bt_text": "#FFFFFF",
    "main_bt_text_pressed": "#80FFFFFF",
    "main_bt_text_disabled": "#BFBFBF",
    "main_bt_background": "#0073C3",
    "main_bt_background_pressed": "#1AA3FF",
    "main_bt_background_disabled": "#F5F5F5",


    "second_bt_text": "#0073C3",
    "second_bt_border": "#0073C3",
    "second_bt_background": "#FFFFFF",
    "second_bt_background_pressed": "#F1F9FE",


    "plain_bt_text": "#0073C3",
    "plain_bt_background": "#FFFFFF",
    "plain_bt_background_pressed": "#F1F9FE",


    "recover_pin_hint_title": "#3D3652",
    "recover_pin_hint_title_bg": "#E1F2FF",
    "recover_pin_hint": "#0073C3",


    "security_confirm_main_bg": "#E9EEFE",


    "title_gradients": ["#0073C3", "#0073C3"],
  }
}

```


# Recover an Account
Source: https://developers.circle.com/wallets/user-controlled/recover-account

Help users regain access to their accounts when they forget their PIN code.

Circle Wallets provide a comprehensive developer solution to storing, sending,
and spending Web3 digital currencies and NFTs. You or your users can manage
asset infrastructure. Circle provides a one-stop-shop experience with all the
tools and services to handle the complex parts, including security, transaction
monitoring, account recovery flows, and more.

This guide outlines how users can regain access to their account using their
pre-set security questions in the event that they forget their original PIN
code.

Users should be aware that the answers to their security questions are their
responsibility to remember. No additional parties can help users regain access
to a user-controlled wallet if their PIN code is lost and they cannot remember
the answers to their security questions.

<Warning>
  **Caution**: If a user loses both their PIN code and the answers to their
  Security Questions, they will be permanently locked out of their account,
  losing access to all of their wallets and assets.
</Warning>

## 1. Run Sample App

Once you have one of the web, iOS, or Android
[sample applications](/sample-projects) set up locally, you will then:

1. Run the sample app and simulator.
2. Obtain your App ID. This can be done by one of two options
   1. Access the developer console and navigate to the
      [configurator](https://console.circle.com/wallets/user/configurator)
      within user-controlled wallets. From there, copy the App ID.
   2. Make an API request to `GET /config/entity`

      and copy the App ID from the response body.
3. Add the App ID to the sample app.

## 2. Acquire Session Token

Next, you will need to acquire a session token. Make a request to
the[`POST /users/token`](/api-reference/wallets/user-controlled-wallets/get-user-token)
using the previously created `userId` in Step 1. The `userToken` is a 60-minute
session token used to initiate requests requiring a user challenge (PIN code
entry). After 60 minutes, the session expires, and a new `userToken` must be
generated via the same endpoint.

From this response, you will acquire the `encryptionKey` and `userToken` which
you should provide in the respective fields in the sample app. Additionally, you
will use the `userToken` in Step 2.

<CodeGroup>
  ```javascript Node.js SDk theme={null}
  // Import and configure the user-controlled wallet SDK
  const {
    initiateUserControlledWalletsClient,
  } = require("@circle-fin/user-controlled-wallets");
  const circleUserSdk = initiateUserControlledWalletsClient({
    apiKey: "<API_KEY>",
  });

  const response = await circleUserSdk.createUserToken({
    userId: "2f1dcb5e-312a-4b15-8240-abeffc0e3463",
  });
  ```

  ```coffeescript Python SDK theme={null}
  import uuid

  from circle.web3 import user_controlled_wallets
  from circle.web3 import utils

  client = utils.init_user_controlled_wallets_client(api_key="Your API KEY")

  # create an api instance
  api_instance = user_controlled_wallets.UsersAndPinsApi(client)
  # get user token
  try:
      request = user_controlled_wallets.GenerateUserTokenRequest.from_dict({"userId": "<USER_ID>"})
      response = api_instance.get_user_token(request)
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling UsersAndPinsApi->get_user_token: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request POST \
       --url 'https://api.circle.com/v1/w3s/users/token' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --data '
  {
    "userId": "2f1dcb5e-312a-4b15-8240-abeffc0e3463"
  }
  '
  ```
</CodeGroup>

```json Response body theme={null}
{
  "data": {
    "userToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCC9.eyJkZXZlbG9wZXJFbnRpdHlFbnZpcm9ubWVudCI6IlRFU1QiLCJlbnRpdHlJZCI6IjRlMDdhOGM5LTIxOTAtNDVlNC1hNjc0LWQyMGFkNjg4MWI3YyIsImV4cCI6MTY5MDU1MjcwNywiaWF0IjoxNjkwNTQ5MTA3LCJpbnRlcm5hbFVzZXJJZCI6ImQ2ZjkzODliLWQ5MzUtNWFlYy1iOTVhLWNjNTk1NjA2YWM5NiIsImlzcyI6Imh0dHBzOi8vcHJvZ3JhbW1hYmxlLXdhbGxldC5jaXJjbGUuY29tIiwianRpIjoiMmE0YmJlMzAtZTdkZi00YmM2LThiODMtNTk0NGUyMzE2ODlkIiwic3ViIjoiZXh0X3VzZXJfaWRfOSJ9.dhfByhxZFbJx0XWlzxneadT4RQWdnxLu3FSN9ln65hCDOfavaTL1sc4h-jUR8i4zMmfdURw3FFcQIdSbm-BUg6M7FP_fp-cs9xBbNmRZa31gMd1aKdcajJ9SvlVrfUowYfGXM3VcNF8rtTFtW-gk1-KzU4u10U35XXbbMcW1moxE0Rqx_fKotDgk2VdITuuds5d5TiQzAXECqeCOCtNoDKktMkglltbnLxOaRl2ReZjGt-ctD2V0DbYNO4T_ndPSUDI6qD7dXQRed5uDcezJYoha3Qj3tFGBglEnox2Y6DWTbllqjwmfTGrU8Pr0yz4jQz7suGwmiCzHPxcpYxMzYQ",
    "encryptionKey": "Tlcyxz7Ts9ztRLQq5+pic0MIETblYimOo2d7idV/UFM="
  }
}
```

## 3. Initialize Account Recovery and Acquire a Challenge ID

Make a request to
[`POST /user/pin/restore`](/api-reference/wallets/user-controlled-wallets/create-user-pin-restore-challenge)
using the `userToken` returned from Step 1. This call returns a `challengeId`,
which is used with the Circle Programmable Wallet SDK to have the user reset
their PIN code.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  const response = await circleUserSdk.restoreUserPin({
    userToken: "<USER_TOKEN>",
  });
  ```

  ```python Python SDK theme={null}
  # create an api instance
  api_instance = user_controlled_wallets.UsersAndPinsApi(client)
  # get user token
  try:
      request = user_controlled_wallets.RestorePinRequest.from_dict({
          "idempotencyKey": str(uuid.uuid4()),
      })
      response = api_instance.create_user_pin_restore_challenge("<USER_TOKEN>", request)
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling UsersAndPinsApi->create_user_pin_restore_challenge: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request POST \
       --url 'https://api.circle.com/v1/w3s/user/pin/restore' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --header 'X-User-Token: <USER_TOKEN>' \
       --data '
  {
    "idempotencyKey": "bb3d64d9-d421-41c7-aae2-84fc4732be2f"
  }
  '
  ```
</CodeGroup>

```json JSON theme={null}
{
  "data": {
    "challengeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
  }
}
```

## 4. Recover Account in the Sample App

Using the sample application, enter the `userToken` and `secretKey` returned
from Step 1. Enter the `challengeId` returned from Step 2.

At this point, you should be ready to execute the account recovery workflow
through the Circle Programmable Wallet SDK. Once you've entered the required
fields indicated in Step 3, click **Execute** to continue.

<Frame>
  <img />
</Frame>

The sample application takes you through the account recovery process by
answering your Security Questions. If answered correctly, the sample application
prompts you to enter a new PIN code.

<Frame>
  <img />
</Frame>

## 5. Check the Challenge Status

Make a request to
[`GET /user/challenges/{id}`](/api-reference/wallets/user-controlled-wallets/get-user-challenge)
using the `challengeId` received from Step 2 to retrieve the status of the
challenge. Additionally, Circle sends a notification to a
[subscribed endpoint](/wallets/webhook-notifications) once the account recovery
process is complete. For a full list of possible `statuses`, see the
[Asynchronous States and Statuses guide](/wallets/asynchronous-states-and-statuses).

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  const response = await circleUserSdk.getUserChallenge({
    userToken: "<USER_TOKEN>",
    challengeId: "<CHALLENGE_ID>",
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = user_controlled_wallets.UsersAndPinsApi(client)
  # get user token
  try:
      request = user_controlled_wallets.ChangePinRequest.from_dict({
          "idempotencyKey": str(uuid.uuid4()),
      })
      response = api_instance.get_user_challenge("<USER_TOKEN>", "<CHALLENGE_ID>")
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling UsersAndPinsApi->get_user_challenge: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request GET \
       --url 'https://api.circle.com/v1/w3s//user/challenges/{id}' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --header 'X-User-Token: <USER_TOKEN>'
  ```
</CodeGroup>

```json Response Body theme={null}
{
  "data": {
    "challenge": {
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "correlationIds": ["54399e5a-1bf6-4921-9559-10c1115678cd"],
      "status": "COMPLETED",
      "type": "RESTORE_PIN"
    }
  }
}
```


# Reset Account Pin Code
Source: https://developers.circle.com/wallets/user-controlled/reset-account-pin

Walk a user through the steps in resetting a known account PIN code.

This guide outlines how to enable a user to reset their PIN code. Note users
must know their original PIN code to reset it. Otherwise, they must follow the
Account Recovery flow outlined in this
[guide](/wallets/user-controlled/recover-account).

<Warning>
  **Caution**: If a user loses both their PIN code and the answers to their
  Security Questions, they will be permanently locked out of their account,
  losing access to all of their wallets and assets.
</Warning>

## Prerequisites

Before you begin, make sure you have:

* Completed the
  [Create Your First Wallet guide](/wallets/user-controlled/react-native-sdk-ui-customization-api)
  to set up a user and their first wallet.
* Followed the
  [Receive Inbound Transfer guide](/wallets/user-controlled/receive-inbound-transfer)
  or
  [Send Outbound Transfer guide](/wallets/user-controlled/send-outbound-transfer)
  to initialize user activity (optional, but helps validate wallet
  functionality).
* Installed and configured the
  [sample app](/sample-projects#user-account-creation-and-email-login-and-pin-authorization-flow)
  for your platform (web, iOS, or Android).
* Registered a callback to handle the **Reset PIN** flow. This includes:
  1. Sending the reset PIN request
  2. Handling the challenge response
  3. Completing the PIN verification

<Note>
  See the [sample
  app](/sample-projects#user-account-creation-and-email-login-and-pin-authorization-flow)
  for an example implementation.
</Note>

## Steps

Follow these steps to guide a user through resetting their PIN using the
user-controlled wallets SDK:

## 1. Run the Sample App

After you set up one of the web, iOS, or Android
[sample applications](/sample-projects#user-account-creation-and-email-login-and-pin-authorization-flow),
you can:

1. Run the sample app and simulator.
2. Obtain your App ID. To get the App ID, do one of the following:
   1. Access the developer console and navigate to the
      [configurator](https://console.circle.com/wallets/user/configurator)
      within user-controlled wallets. From there, copy the App ID.
   2. Make an API request to
      [GET /config/entity](/api-reference/wallets/programmable-wallets/get-entity-config)
      and copy the App ID from the response body.
3. Add the App ID to the sample app.

## 2. Acquire a Session Token

Next, you need to acquire a session token. To do this, you make a request to
the[`POST /users/token`](/api-reference/wallets/user-controlled-wallets/get-user-token)
using the previously created `userId` in Step 1. The `userToken` is a 60-minute
session token used to initiate requests requiring a user challenge (PIN code
entry). After 60 minutes, the session expires, and a you must generate a new
`userToken` using the same endpoint.

From this response, you can acquire the `encryptionKey` and `userToken` which
you provide in the respective sample app fields. You also use the `userToken` in
the next step.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  // Import and configure the user-controlled wallet SDK
  const {
    initiateUserControlledWalletsClient,
  } = require("@circle-fin/user-controlled-wallets");
  const circleUserSdk = initiateUserControlledWalletsClient({
    apiKey: "<API_KEY>",
  });

  const response = await circleUserSdk.createUserToken({
    userId: "2f1dcb5e-312a-4b15-8240-abeffc0e3463",
  });
  ```

  ```python Python SDK theme={null}
  import uuid

  from circle.web3 import user_controlled_wallets
  from circle.web3 import utils

  client = utils.init_user_controlled_wallets_client(api_key="Your API KEY")

  # create an api instance
  api_instance = user_controlled_wallets.UsersAndPinsApi(client)
  # get user token
  try:
      request = user_controlled_wallets.GenerateUserTokenRequest.from_dict({"userId": "<USER_ID>"})
      response = api_instance.get_user_token(request)
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling UsersAndPinsApi->get_user_token: %s\n" % e)
  ```

  ```shell Curl theme={null}
  curl --request POST \
       --url 'https://api.circle.com/v1/w3s/users/token' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --data '
  {
    "userId": "2f1dcb5e-312a-4b15-8240-abeffc0e3463"
  }
  '
  ```
</CodeGroup>

```json Response body theme={null}
{
  "data": {
    "userToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCC9.eyJkZXZlbG9wZXJFbnRpdHlFbnZpcm9ubWVudCI6IlRFU1QiLCJlbnRpdHlJZCI6IjRlMDdhOGM5LTIxOTAtNDVlNC1hNjc0LWQyMGFkNjg4MWI3YyIsImV4cCI6MTY5MDU1MjcwNywiaWF0IjoxNjkwNTQ5MTA3LCJpbnRlcm5hbFVzZXJJZCI6ImQ2ZjkzODliLWQ5MzUtNWFlYy1iOTVhLWNjNTk1NjA2YWM5NiIsImlzcyI6Imh0dHBzOi8vcHJvZ3JhbW1hYmxlLXdhbGxldC5jaXJjbGUuY29tIiwianRpIjoiMmE0YmJlMzAtZTdkZi00YmM2LThiODMtNTk0NGUyMzE2ODlkIiwic3ViIjoiZXh0X3VzZXJfaWRfOSJ9.dhfByhxZFbJx0XWlzxneadT4RQWdnxLu3FSN9ln65hCDOfavaTL1sc4h-jUR8i4zMmfdURw3FFcQIdSbm-BUg6M7FP_fp-cs9xBbNmRZa31gMd1aKdcajJ9SvlVrfUowYfGXM3VcNF8rtTFtW-gk1-KzU4u10U35XXbbMcW1moxE0Rqx_fKotDgk2VdITuuds5d5TiQzAXECqeCOCtNoDKktMkglltbnLxOaRl2ReZjGt-ctD2V0DbYNO4T_ndPSUDI6qD7dXQRed5uDcezJYoha3Qj3tFGBglEnox2Y6DWTbllqjwmfTGrU8Pr0yz4jQz7suGwmiCzHPxcpYxMzYQ",
    "encryptionKey": "Tlcyxz7Ts9ztRLQq5+pic0MIETblYimOo2d7idV/UFM="
  }
}
```

## 3. Initialize PIN reset and Acquire Challenge ID

Make a request to
[`PUT /user/pin`](/api-reference/wallets/user-controlled-wallets/create-user-pin-challenge)
using the `userToken` returned from Step 1. This call returns a `challengeId`,
which is used with the Circle Programmable Wallet SDK to have the user reset
their PIN code.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  const response = await circleUserSdk.updateUserPin({
    userToken: "<USER_TOKEN>",
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = user_controlled_wallets.UsersAndPinsApi(client)
  # get user token
  try:
      request = user_controlled_wallets.ChangePinRequest.from_dict({
          "idempotencyKey": str(uuid.uuid4()),
      })
      response = api_instance.update_user_pin_challenge("<USER_TOKEN>", request)
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling UsersAndPinsApi->update_user_pin_challenge: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request PUT \
       --url 'https://api.circle.com/v1/w3s/user/pin' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --header 'X-User-Token: <USER_TOKEN>' \
       --data '
  {
    "idempotencyKey": "2532e703-d5a6-4927-b914-adf1c7017984"
  }
  '
  ```
</CodeGroup>

```json JSON theme={null}
{
  "data": {
    "challengeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
  }
}
```

## 4. Reset the PIN in the Sample App

Using the sample application, enter the `userToken` and `secretKey` returned
from Step 1. Enter the `challengeId` returned from Step 2.

<Warning>
  Make sure a callback is registered; otherwise, clicking the **Reset PIN**
  button will have no effect.
</Warning>

You should be ready to execute the reset PIN code workflow via the Circle
Programmable Wallet SDK. Once you've entered the required fields indicated in
Step 3, click **Execute** to continue.

<Frame>
  <img />
</Frame>

The sample application takes you through the authentication and PIN code reset
process, which includes the user entering their PIN code to authorize the reset
and entering a new PIN code.

<Frame>
  <img />
</Frame>

## 5. Check the Challenge Status

Make a request
[`GET /user/challenges/{id}`](/api-reference/wallets/user-controlled-wallets/get-user-challenge)
using the `challengeId` received from Step 2 to retrieve the status of the
challenge. Additionally, Circle sends a notification to a
[subscribed endpoint](/wallets/webhook-notifications) once the PIN code reset is
complete. For a full list of possible `statuses`, see the
[Asynchronous States and Statuses guide](/wallets/asynchronous-states-and-statuses).

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  const response = await circleUserSdk.getUserChallenge({
    userToken: "<USER_TOKEN>",
    challengeId: "<CHALLENGE_ID>",
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = user_controlled_wallets.UsersAndPinsApi(client)
  # get user token
  try:
      request = user_controlled_wallets.ChangePinRequest.from_dict({
          "idempotencyKey": str(uuid.uuid4()),
      })
      response = api_instance.get_user_challenge("<USER_TOKEN>", "<CHALLENGE_ID>")
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling UsersAndPinsApi->get_user_challenge: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request GET \
       --url 'https://api.circle.com/v1/w3s//user/challenges/{id}' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --header 'X-User-Token: <USER_TOKEN>'
  ```
</CodeGroup>

```json Response Body theme={null}
{
  "data": {
    "challenge": {
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "correlationIds": ["54399e5a-1bf6-4921-9559-10c1115678cd"],
      "status": "COMPLETED",
      "type": "CHANGE_PIN"
    }
  }
}
```


# SDK Architecture for User-Controlled Wallets
Source: https://developers.circle.com/wallets/user-controlled/sdk-architecture

Learn the role of SDKs in enabling User-Controlled Wallets

Circle designed the Wallets SDK to guarantee that end-users have complete
control over the private keys of their
[user-controlled wallets](/wallets/user-controlled). For PIN authentication
method, users create their own PIN code and security questions upon account
creation to ensure their access, control, and recovery processes are in place to
use their wallets. Learn more about the available authentication methods.

Go to one of the following guides to set up your local environment and review
the SDK API references:

* [Web SDK](/wallets/user-controlled/web-sdk)
* [iOS SDK](/wallets/user-controlled/ios-sdk)
* [Android SDK](/wallets/user-controlled/android-sdk)
* [React Native SDK](/wallets/user-controlled/react-native-sdk)

## SDK architecture

<Frame>
  <img />
</Frame>

The SDK infrastructure uses the following design flow:

1. A user performs a request in their user-controlled wallet on the developer's
   platform. For example, a user initiates a USDC transfer to an external
   wallet.
2. The developer requests a user's transaction through Circle's Programmable
   Wallets RESTful APIs.
3. Circle's RESTful APIs return a response containing a challenge ID. The
   challenge must be completed to execute the requested transaction.
4. The developer passes the challenge ID to the Wallets SDK, prompting users to
   input their PIN code to complete the challenge.
5. The user completes the challenge by entering their PIN code or click the
   confirm/sign button on the Confirmation UIs, and the encrypted input is
   delivered to Circle's SDK APIs.
6. Circle delivers a callback notification to the developer (or the developer
   queries the corresponding GET endpoint for the given transaction) to receive
   status updates on the requested transaction.
7. Upon completion of the request, the developer notifies the end-user in the
   developer's application.


# User-Controlled Wallets SDKs
Source: https://developers.circle.com/wallets/user-controlled/sdks



Circle's user-controlled wallets SDKs allow for the integration of
user-controlled wallets within your client applications. The SDKs support
various authentications methods to ensure a seamless user experience while using
the wallet.

<Note>
  **Note:** Circle's user-controlled wallets SDKs simplify client-side
  development and are not required for developer-controlled wallets.
</Note>

To build client applications that enable secure, user-controlled wallets, you
must use one of Circle's user-controlled wallets SDKs. Circle supports the
following platforms:

* [Web](/wallets/user-controlled/web-sdk)
* [iOS](/wallets/user-controlled/ios-sdk)
* [Android](/wallets/user-controlled/android-sdk)
* [React Native](/wallets/user-controlled/react-native-sdk)

## Security

The user-controlled wallets SDKs securely manage and communicate with your
server, ensuring that users' keyshares remain exclusively with them and are
never exposed to your server. To maintain security, the SDKs encrypt all request
bodies using an encryption key. This guarantees that users retain full control
over their digital assets in the wallet, with no access to funds by either
Circle or your application.

## Operation

You initialize the SDK by setting the endpoint server. This allows your
application and Circle's API platform to communicate. To simplify the
development of your application, you can use the corresponding server-side
[SDK](/sdks).

Your server retrieves `challengeId` from
[Circle's API platform](/api-reference/wallets/user-controlled-wallets/create-device-token-social-login)
and passes it to the SDK, which then executes relevant operations. Certain
operations may differ based on the authentication method with which you choose
to integrate, for example:

* For social login or email authentication, the SDK can display a confirmation
  UI to your users to preview and confirm the transaction or signature details
* For PIN authentication, the SDK can display a UI that allows your users to
  securely input their PIN and security answers

For more on the SDK design flow including a diagram, see
[SDK Architecture for User-Controlled Wallets](/wallets/user-controlled/sdk-architecture).

## Customizable UI elements

You can customize the styling, layout, and description of your UI modals,
including:

* Title and subtitle - Modify the title and subtitle to reflect your brand
  identity or provide specific instructions.
* Transaction and signature details - Tailor the information displayed on the
  Confirmation UIs to provide context for your users during the signing process.
* Error messages - Customize the error messages displayed to users to provide
  guidance and a personalized experience.
* PIN code input layout - Adjust the layout and styling of the PIN code input
  field to align with your application's design guidelines.
* Question list configuration - Set the list of security questions and allow
  users to choose from a predefined set.

For detailed instructions on customizing UIs for web, iOS, and Android, see the
following docs:

* [Web SDK UI Customizations API](/wallets/user-controlled/web-sdk-ui-customizations)
* [iOS SDK UI Customization API](/wallets/user-controlled/ios-sdk-ui-customization-api)
* [Android SDK UI Customization API](/wallets/user-controlled/android-sdk-ui-customization-api)

## Web SDK

Circle provides the following client-side web SDK to enable integrations with
Circle's prebuilt UI components to create user wallets securely, send
transactions and more.

<div>
  <Card href="/wallets/user-controlled/web-sdk" title="Web SDK">
    <div>
      <div>GET STARTED</div>

      <Icon icon="arrow-right" />
    </div>
  </Card>
</div>

## Mobile SDKs

Circle provides the following client-side mobile device SDKs to help you create
native applications for iOS and Android devices and platforms. Mobile SDKs
support only user-controlled wallets.

<div>
  <Card href="/wallets/user-controlled/ios-sdk" title="iOS SDK">
    <div>
      <div>GET STARTED</div>

      <Icon icon="arrow-right" />
    </div>
  </Card>

  <Card href="/wallets/user-controlled/android-sdk" title="Android SDK">
    <div>
      <div>GET STARTED</div>

      <Icon icon="arrow-right" />
    </div>
  </Card>

  <Card href="/wallets/user-controlled/react-native-sdk" title="React Native SDK">
    <div>
      <div>GET STARTED</div>

      <Icon icon="arrow-right" />
    </div>
  </Card>
</div>

## Postman API Suite

Circle's Postman workspace lets you quickly send requests and learn to use
Developer Services APIs.

<div>
  <Card href="/wallets/postman" title="Postman Collection">
    <div>
      <div>GET STARTED</div>

      <Icon icon="arrow-right" />
    </div>
  </Card>
</div>


# Send an Outbound Transfer or Execute Contract
Source: https://developers.circle.com/wallets/user-controlled/send-an-outbound-transfer-or-execute-contract

Learn how to send USDC or execute a contract from a user-controlled wallet with social logins or email authentication

This guide outlines how to initiate a currency transfer or execute a contract
from a previously created user-controlled wallet with social logins or email
authentication. To create a wallet, see
[Create Your First Wallet with Social Logins](/wallets/user-controlled/create-your-first-wallet-with-social-logins)
or
[Create Your First Wallet with Email](/wallets/user-controlled/create-your-first-wallet-with-email).

<Note>
  If it has been over 14 days or you end the last trial attempt since you first
  ran the sample app, your session is logged out. You must run the sample app
  and acquire a new user token to proceed further. For instructions, see the
  perform login part of [Create Your First Wallet with Social
  Logins](/wallets/user-controlled/create-your-first-wallet-with-social-logins)
  or [Create Your First Wallet with Email
  Authentication](/wallets/user-controlled/create-your-first-wallet-with-email).
</Note>

## Step 1. Check wallet balance and obtain token ID

Before making an outbound transfer, you must have a token ID and token balance
greater than `0`.

1. Include `userToken` copied from the previous step in the header of a `GET`
   request to the `/wallets` endpoint.
2. From the response, copy `id` which is your wallet ID.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  const response = await circleUserSdk.listWallets({
    userToken: "<USER_TOKEN>",
    pageSize: 10,
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = user_controlled_wallets.WalletsApi(client)
  # list wallets
  try:
      response = api_instance.list_wallets("<USER_TOKEN>")
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling WalletsApi->list_wallets: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request GET \
       --url 'https://api.circle.com/v1/w3s/wallets?pageSize=10' \
       --header 'accept: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --header 'X-User-Token: <USER_TOKEN>'
  ```
</CodeGroup>

3. Using `id` which you just copied, send a `GET` request to the
   `/wallet/{id}/balances` endpoint to check your wallet's token balance.\
   From the response, copy and store the `tokenId` that you intend to transfer.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
    const response = await circleUserSdk.getWalletTokenBalance({
    userToken: '<USER_TOKEN>',
    walletId: '<WALLET_ID>'
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = user_controlled_wallets.WalletsApi(client)
  try:
      response = api_instance.list_wallet_balance("<USER_TOKEN>", "<WALLET_ID>")
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling WalletsApi->list_wallet_balance: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request GET \
       --url 'https://api.circle.com/v1/w3s/wallets/{id}/balances' \
       --header 'accept: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --header 'X-User-Token: <USER_TOKEN>'
  ```
</CodeGroup>

## Step 2. Estimate the cost of transaction (optional)

To estimate the fees for the transaction to transfer tokens, send a `POST`
request to the `transactions/transfer/estimateFee` endpoint.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  const response = await circleUserSdk.estimateTransferFee({
    userToken: "<USER_TOKEN>",
    amount: [".01"],
    destinationAddress: "0xEb9614D6d001391e22dDbbEA7571e9823A469c1f",
    tokenId: "36b6931a-873a-56a8-8a27-b706b17104ee",
    walletId: "01899cf2-d415-7052-a207-f9862157e546",
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = user_controlled_wallets.TransactionsApi(client)
  # get user token
  try:
      request = user_controlled_wallets.EstimateTransferTransactionFeeRequest.from_dict({
          "userToken": '<USER_TOKEN>',
          "amounts": ['.01'],
          "destinationAddress": '0xEb9614D6d001391e22dDbbEA7571e9823A469c1f',
          "tokenId": '36b6931a-873a-56a8-8a27-b706b17104ee',
          "walletId": '01899cf2-d415-7052-a207-f9862157e546'
      })
      response = api_instance.create_transfer_estimate_fee("<USER_TOKEN>", request)
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling TransactionsApi->create_transfer_estimate_fee: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request POST \
       --url 'https://api.circle.com/v1/w3s/transactions/transfer/estimateFee' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --header 'X-User-Token: <USER_TOKEN>' \
       --data '
  {
    "amounts": [".01"],
    "destinationAddress": "0xEb9614D6d001391e22dDbbEA7571e9823A469c1f",
    "tokenId": "38f2ad29-a77b-5a44-be05-8d03923878a2",
    "walletId": "01899cf2-d415-7052-a207-f9862157e546"
  }
  ```
</CodeGroup>

```json Response Body theme={null}
{
  "data": {
    "low": {
      "gasLimit": "21000",
      "baseFee": "2.456220277",
      "priorityFee": "1.022783914",
      "maxFee": "5.935224468"
    },
    "medium": {
      "gasLimit": "21000",
      "baseFee": "2.456220277",
      "priorityFee": "2.655282857",
      "maxFee": "7.567723411"
    },
    "high": {
      "gasLimit": "21000",
      "baseFee": "2.456220277",
      "priorityFee": "15.986229693",
      "maxFee": "20.898670247"
    }
  }
}
```

## Step 3. Initiate a blockchain transaction

### Execute an asset transfer

To initiate a blockchain transfer from a specified wallet to a blockchain
address:

1. Include `walletId` and `destinationAddress` in a `POST` request to the
   `/user/transactions/transfer` endpoint.
2. From the response, copy `challengeId` for the next step.

### Execute a contract

To create a transaction that executes a smart contract:

1. Include `walletId` and `contractAddress` in a `POST` request to the
   `/user/transactions/contractExecution` endpoint.
2. From the response, copy `challengeId` and enter it in the sample app.

<Note>
  If you do not have a wallet to use as a destination for the transfer, you can
  create another user-controlled wallet or send funds to any other blockchain
  wallet such as Metamask.
</Note>

## Step 4. Confirm execution

To authorize a transfer on the sample app's confirmation UI, ensure you have
obtained an active user token and encryption key.

* From the Execute Challenge screen in the sample app, paste the Challenge ID
  that you copied from the previous step and select **Execute**.

  <Frame>
    <img />
  </Frame>

  The sample app displays a confirmation UI that contains transaction details
  for the user to confirm. You can customize confirmation UIs. For more, see
  [Confirmation UIs](/wallets/user-controlled/confirmation-uis) .

  <Frame>
    <img />
  </Frame>

<Frame>
  <img />
</Frame>

## Step 5. Check transaction status

As the transfer transaction's `state` changes and ultimately completes, Circle
sends webhook notifications to a
[subscriber endpoint](/wallets/webhook-notifications). For a list of all
possible states, see
[Asynchronous States and Statuses](/wallets/asynchronous-states-and-statuses).

The following code sample shows an example of a webhook notification for a
transfer.

```json JSON theme={null}
{
  "subscriptionId": "d4c07d5f-f05f-4fe4-853d-4dd434806dfb",
  "notificationId": "acab8c14-92ae-481a-8335-6eb5271da014",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "ad3f40ae-9c0e-52cf-816f-91838850572a",
    "blockchain": "MATIC-AMOY",
    "tokenId": "36b6931a-873a-56a8-8a27-b706b17104ee",
    "walletId": "01899cf2-d415-7052-a207-f9862157e546",
    "sourceAddress": "0x7b777eb80e82f73f118378b15509cb48cd2c2ac3",
    "destinationAddress": "0x6e5eaf34c73d1cd0be4e24f923b97cf38e10d1f3",
    "transactionType": "OUTBOUND",
    "custodyType": "ENDUSER",
    "state": "COMPLETE",
    "amounts": ["0.01"],
    "nfts": null,
    "txHash": "0x535ff240984f54e755d67cdc9c79c88768fe5997955f09f3a66b4d1126810900",
    "blockHash": "0xa4c5c79500240f3ae3f4e5c5f641198b7c698d83b7539ac4e8cf2d3f5f49bdfd",
    "blockHeight": 41100000,
    "networkFee": "0.07037500047405219",
    "firstConfirmDate": "2023-10-11T21:08:28Z",
    "operation": "TRANSFER",
    "userId": "c266945c-f440-4537-85cf-a16b6e33b0cc",
    "abiParameters": null,
    "createDate": "2023-10-11T21:08:13Z",
    "updateDate": "2023-10-11T21:08:37Z"
  },
  "timestamp": "2023-10-11T21:08:13Z",
  "version": 2
}
```

You can also include your user's `userId` or `userToken` in a `GET` request to
the `/transactions` endpoint.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  const response = await circleUserSdk.listTransactions({
    userToken: "<USER_TOKEN>",
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = user_controlled_wallets.TransactionsApi(client)
  # get user token
  try:
      response = api_instance.list_transactions("<USER_TOKEN>")
      print(response)
  except user_controlled_wallets.ApiException as e:
      print("Exception when calling TransactionsApi->list_transactions: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request GET \
       --url 'https://api.circle.com/v1/w3s/transactions' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'authorization: Bearer <API_KEY>' \
       --header 'X-User-Token: <USER_TOKEN>'
  ```
</CodeGroup>

The following code sample shows the response.

```json JSON theme={null}
{
  "data": {
    "transactions": [
      {
        "id": "ad3f40ae-9c0e-52cf-816f-91838850572a",
        "blockchain": "MATIC-AMOY",
        "tokenId": "36b6931a-873a-56a8-8a27-b706b17104ee",
        "walletId": "01899cf2-d415-7052-a207-f9862157e546",
        "sourceAddress": "0x7b777eb80e82f73f118378b15509cb48cd2c2ac3",
        "destinationAddress": "0x6e5eaf34c73d1cd0be4e24f923b97cf38e10d1f3",
        "transactionType": "OUTBOUND",
        "custodyType": "ENDUSER",
        "state": "COMPLETE",
        "amounts": ["0.01"],
        "nfts": null,
        "txHash": "0x535ff240984f54e755d67cdc9c79c88768fe5997955f09f3a66b4d1126810900",
        "blockHash": "0xa4c5c79500240f3ae3f4e5c5f641198b7c698d83b7539ac4e8cf2d3f5f49bdfd",
        "blockHeight": 41100000,
        "networkFee": "0.07037500047405219",
        "firstConfirmDate": "2023-10-11T21:08:28Z",
        "operation": "TRANSFER",
        "userId": "c266945c-f440-4537-85cf-a16b6e33b0cc",
        "abiParameters": null,
        "createDate": "2023-10-11T21:08:13Z",
        "updateDate": "2023-10-11T21:08:37Z"
      },
      {
        "id": "81cf790a-ed95-5d41-b7bd-c4e15390eef6",
        "blockchain": "MATIC-AMOY",
        "tokenId": "36b6931a-873a-56a8-8a27-b706b17104ee",
        "walletId": "01899cf2-d415-7052-a207-f9862157e546",
        "sourceAddress": "0x48520ff9b32d8b5bf87abf789ea7b3c394c95ebe",
        "destinationAddress": "0x7b777eb80e82f73f118378b15509cb48cd2c2ac3",
        "transactionType": "INBOUND",
        "custodyType": "ENDUSER",
        "state": "COMPLETE",
        "amounts": ["10"],
        "nfts": null,
        "txHash": "0x5121f9efec29d4d661ffb0b777727d1f5ba7b5bc286ac4891c82f7b1b80a9485",
        "blockHash": "0xba7984dbe7423827b5fd175a636552ae85401c3f2a0c5cdda934a37d6652ac49",
        "blockHeight": 41098635,
        "networkFee": "0.001911870000955935",
        "firstConfirmDate": "2023-10-11T20:13:33Z",
        "operation": "TRANSFER",
        "userId": "c266945c-f440-4537-85cf-a16b6e33b0cc",
        "abiParameters": null,
        "createDate": "2023-10-11T20:13:33Z",
        "updateDate": "2023-10-11T20:13:45Z"
      }
    ]
  }
}
```


# Web SDK
Source: https://developers.circle.com/wallets/user-controlled/web-sdk

Set up the client-side web SDK for user-controlled wallets in your web application.

The Circle Web SDK enables user-controlled wallets within your web application.
Three authentication methods are supported, namely **social logins**, **email**,
or **PIN**, which includes security questions for recovery. This allows you to
authenticate your users in a seamless way and create user-controlled wallets for
them.

By integrating this client-side SDK, your users can securely create wallets and
make transactions using social accounts or email. If you choose the PIN
authentication method, your users can input sensitive data, like PINs or
security answers, in a secure way. Moreover, the SDK encrypts the request body
sent by the application, protecting your users' information.

<Note>
  **Note:**

  The Web and Mobile SDKs preserve the user keyshare with the individual, giving
  them complete control. You must use the SDKs with the user-controlled wallet
  product. Additionally, the Web and Mobile SDKs support only the user-controlled
  wallet product.
</Note>

At Circle, we understand the importance of end-to-end security for your
application and the need to create a tailored and seamless user experience for
your end-users. Hence, Circle's SDK also exposes functionality for you to
customize the description and layout. See the
[Web SDK UI Customization API](/wallets/user-controlled/web-sdk-ui-customizations)
article to customize the SDK.

## Install the SDKs

Install using [npm](https://docs.npmjs.com/about-npm):

```shell Shell theme={null}
npm install @circle-fin/w3s-pw-web-sdk
```

## SDK architecture

You must use Web, iOS, or Android SDKs to access the user-controlled
Programmable Wallet product. The SDK secures, manages, and communicates with
your server to ensure your user's keyshare, always stays with them and is not
exposed to your servers.

To learn more, see
[SDK Architecture for User-Controlled Wallets](/wallets/user-controlled/sdk-architecture).

## SDK API references: enums

The Web SDK supports the API reference enums listed in the following sections.

### ChallengeType

Enumerates the types of challenges supported.

```javascript JavaScript theme={null}
enum ChallengeType {
  INITIALIZE,
  SET_PIN,
  RESTORE_PIN,
  CHANGE_PIN,
  SET_SECURITY_QUESTIONS,
  CREATE_WALLET,
  CREATE_TRANSACTION,
  ACCELERATE_TRANSACTION,
  CANCEL_TRANSACTION,
  CONTRACT_EXECUTION,
  SIGN_MESSAGE,
  SIGN_TYPEDDATA,
  SIGN_TRANSACTION,
  WALLET_UPGRADE,
  UNKNOWN,
}
```

### ChallengeStatus

Enumerates the possible status for a challenge.

```javascript JavaScript theme={null}
enum ChallengeStatus {
  COMPLETE,
  EXPIRED,
  FAILED,
  IN_PROGRESS,
  PENDING,
}
```

### QuestionType

Enumerates the types of security questions.

```javascript JavaScript theme={null}
enum QuestionType {
  DATE,
  TEXT,
}
```

### ErrorCode

Enumerates the types of error code.

```javascript JavaScript theme={null}
enum ErrorCode {
  unknown = -1,
  success = 0,
  apiParameterMissing = 1,
  apiParameterInvalid = 2,
  forbidden = 3,
  unauthorized = 4,
  retry = 9,
  customerSuspended = 10,
  pending = 11,
  invalidSession = 12,
  invalidPartnerId = 13,
  invalidMessage = 14,
  invalidPhone = 15,
  userAlreadyExisted = 155101,
  userNotFound = 155102,
  userTokenNotFound = 155103,
  userTokenExpired = 155104,
  invalidUserToken = 155105,
  userWasInitialized = 155106,
  userHasSetPin = 155107,
  userHasSetSecurityQuestion = 155108,
  userWasDisabled = 155109,
  userDoesNotSetPinYet = 155110,
  userDoesNotSetSecurityQuestionYet = 155111,
  incorrectUserPin = 155112,
  incorrectDeviceId = 155113,
  incorrectAppId = 155114,
  incorrectSecurityAnswers = 155115,
  invalidChallengeId = 155116,
  invalidApproveContent = 155117,
  invalidEncryptionKey = 155118,
  userPinLocked = 155119,
  securityAnswersLocked = 155120,
  notEnoughFunds = 155201,
  notEnoughBalance = 155202,
  exceedWithdrawLimit = 155203,
  minimumFundsRequired = 155204,
  invalidTransactionFee = 155205,
  rejectedOnAmlScreening = 155206,
  tagRequired = 155207,
  gasLimitTooLow = 155208,
  transactionDataNotEncodedProperly = 155209,
  fullNodeReturnedError = 155210,
  walletSetupRequired = 155211,
  lowerThenMinimumAccountBalance = 155212,
  rejectedByBlockchain = 155213,
  droppedAsPartOfReorg = 155214,
  operationNotSupport = 155215,
  amountBelowMinimum = 155216,
  wrongNftTokenIdNumber = 155217,
  invalidDestinationAddress = 155218,
  tokenWalletChainMismatch = 155219,
  wrongAmountsNumber = 155220,
  walletIsFrozen = 155501,
  maxWalletLimitReached = 155502,
  walletSetIdMutuallyExclusive = 155503,
  metadataUnmatched = 155504,
  userCanceled = 155701,
  launchUiFailed = 155702,
  pinCodeNotMatched = 155703,
  insecurePinCode = 155704,
  hintsMatchAnswers = 155705,
  networkError = 155706,
  invalidUserTokenFormat= 155718,
  walletIdNotFound = 156001,
  tokenIdNotFound = 156002,
  transactionIdNotFound = 156003,
  entityCredentialNotFound = 156004,
  walletSetIdNotFound = 156005,
}
```

## SDK API references: interfaces

The Web SDK supports the interfaces listed in the following sections.

### Configs

* `appSettings` [\<AppSettings>](#appsettings) Application settings object
* `authentication` [\<Authentication>](#authentication) Authentication object
* `socialLoginConfig` [\<SocialLoginConfig>](#loginconfigs) Social login
  configuration object

### AppSettings

Holds application settings.

* `appId`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Application ID, retrieved from Circle Developer Services Console

### Authentication

Holds authentication information.

* `userToken`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  User token
* `encryptionKey`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Encryption key

### LoginConfigs

Holds login configuration information.

* `google`
  [\<object> | undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  (optional) Configuration object for Google login.
  * `clientId`
    [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Client ID for Google login
  * `redirectUri`
    [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Redirect URI for Google login
  * `selectAccountPrompt`
    [\<boolean> | undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type)
    Turn on/off the Google prompt for account selection
* `facebook`
  [\<object> | undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  Configuration for Facebook login.
  * `appId`
    [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    App ID for Facebook login
  * `redirectUri`
    [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Redirect URI for Facebook login
* `apple`
  [\<FirebaseOptions> | undefined (optional)](https://firebase.google.com/docs/reference/kotlin/com/google/firebase/FirebaseOptions)
  Configuration for Apple login, using Firebase.
* `deviceToken`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Token used to identify the device
* `deviceEncryptionKey`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Encryption key used for the device
* `otpToken`
  [\<string> | undefined (optional)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  OTP token for verification

#### Definitions

* **google**: Configuration object for Google login.
  * **clientId**: The Client ID for Google login.
  * **redirectUri**: The Redirect URI for Google login.
  * **selectAccountPrompt**: Whether to prompt the user to select an account
    when signing in.
    <Note>
      Learn more about how **prompt** works in the [Google OAuth
      API](https://developers.google.com/identity/protocols/oauth2/javascript-implicit-flow#obtainingaccesstokens)
      documentation (keyword: **prompt**).
    </Note>
* **facebook**: Configuration object for Facebook login.
  * **appId**: The App ID for Facebook login.
  * **redirectUri**: The Redirect URI for Facebook login.
* **apple**: Configuration for Apple login, using Firebase.
* **FirebaseOptions**: The Firebase configuration object.
* **deviceToken**: The token used to identify the device.
* **deviceEncryptionKey**: The encryption key used for the device.
* **otpToken**: The optional OTP token for verification.

### SocialLoginProvider

* `APPLE`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Apple login provider
* `FACEBOOK`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Facebook login provider
* `GOOGLE`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Google login provider

### Challenge

Holds information about a challenge.

* `challengeId`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Challenge Id

### ChallengeResult

Holds the result of a challenge.

* `type` [\<ChallengeType>](#challengetype) Challenge type
* `status` [\<ChallengeStatus>](#challengestatus) Challenge status
* `data` [\<SignMessageResult | undefined>](#signmessageresult) Sign message
  response

### SignMessageResult

Holds the result of a sign message or sign typed-data challenge.

* `signature`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Signature result after signing

### SignTransactionResult

Holds the result of a sign transaction challenge.

* `signature`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Signature result after signing
* `txHash`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Transaction hash
* `signedTransaction`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Signed transaction

### SocialLoginResult

Holds the result of a social login.

* userToken
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  User token
* encryptionKey
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Encryption key
* refreshToken
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Refresh token
* oAuthInfo
  [\<object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  OAuth information

### EmailLoginResult

Holds the result of an email login.

* userToken
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  User token
* encryptionKey
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Encryption key
* refreshToken
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Refresh token

### OauthInfo

Holds the OAuth information.

* provider [\<SocialLoginProvider>](#socialloginprovider) Social login
* scope
  [\<string\[\]>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  OAuth scope
* socialUserUUID
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Social user UUID
* socialUserInfo
  [\<object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  Social user information
  * email
    [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Email
  * name
    [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Name
  * phone
    [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Phone

### Error

Holds error information.

* `code`
  [\<integer | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)
  Internal error code
* `message`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Error message

### SocialLoginCompleteCallback

Callback function for social login completion.

* `error` [\<Error>](#error) Presents if error occurs
* `result` [\<SocialLoginResult>](#socialloginresult) |
  [/\<EmailLoginResult>](#emailloginresult) | undefined > Presents and contains
  the result of the social login when the login is completed

### SecurityQuestion

Holds information about a custom security question.

* `question`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Custom security question
* `type` [\<QuestionType>](#questiontype) Type of the question

### Localizations

Holds localization settings.

* `common` [\<Common | undefined>](#common) The settings for common texts
* `confirmInitPincode` [\<ConfirmPincode | undefined>](#confirmpincode) The
  settings for `ConfirmInitPincode` screen
* `confirmNewPincode` [\<ConfirmPincode | undefined>](#confirmpincode) The
  settings for `ConfirmNewPincode` screen
* `enterPincode` [\<EnterPincode | undefined>](#enterpincode) The settings for
  `EnterPincode` screen
* `initPincode` [\<NewPincode | undefined>](#newpincode) The settings for
  `InitPincode` screen
* `newPincode` [\<NewPincode | undefined>](#newpincode) The settings for
  `NewPincode` screen
* `recoverPincode` [\<RecoverPincode | undefined>](#recoverpincode) The settings
  for `RecoverPincode` screen
* `securityConfirm` [\<SecurityConfirm | undefined>](#securityconfirm) The
  settings for `SecurityConfirm` screen
* `securityIntros` [\<SecurityIntros | undefined>](#securityintros) The settings
  for `SecurityIntros` screen
* `securityQuestions` [\<SecurityQuestions | undefined>](#securityquestions) The
  settings for `SecurityQuestions` screen
* `securitySummary` [\<SecuritySummary | undefined>](#securitysummary) The
  settings for `SecuritySummary` screen
* `socialEmailConfirmationUI`
  [\<SocialEmailConfirmationUI | undefined>](#socialemailconfirmationui) The
  settings for `socialEmailConfirmationUI` screen

### Common

Holds localization settings for common texts.

* `continue`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Continue text
* `showPin`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Show pin text
* `hidePin`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Hide pin text
* `confirm`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Confirm text

### ConfirmPincode

Holds localization settings for `ConfirmInitPincode` or `ConfirmNewPincode`
screen.

* `headline`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text
* `headline2`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text 2
* `subhead`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Subhead text

### EnterPincode

Holds localization settings for `EnterPincode` screen.

* `headline`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text
* `headline2`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text 2
* `subhead`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Subhead text
* `forgotPin`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Forgot pin text

### NewPincode

Holds localization settings for `InitPincode` or `NewPincode` screen.

* `headline`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text
* `headline2`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text 2
* `subhead`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Subhead text

### RecoverPincode

Holds localization settings for `RecoverPincode` screen.

* `headline`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text
* `headline2`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text 2
* `subhead`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Subhead text
* `answerInputHeader`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Answer input header text
* `answerInputPlaceholder`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Answer input placeholder text

### SecurityConfirm

Holds localization settings for `SecurityConfirm` screen.

* `title`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Title text
* `headline`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text
* `inputHeadline`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Input headline text
* `inputPlaceholder`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Input placeholder text
* `inputMatch`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Input match text

### SecurityIntros

Holds localization settings for `SecurityIntros` screen.

* `headline`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text
* `headline2`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text 2
* `description`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Description text
* `link`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Link text

### SecurityQuestions

Holds localization settings for `SecurityQuestions` screen.

* `title`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Title text
* `questionHeader`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Question header text
* `questionPlaceholder`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Question placeholder text
* `requiredMark`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Required mark text
* `answerHeader`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Answer header text
* `answerPlaceholder`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Answer placeholder text
* `answerHintHeader`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Answer hint header text
* `answerHintPlaceholder`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Answer hint placeholder text

### SecuritySummary

Holds localization settings for `SecuritySummary` screen.

* `title`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Title text
* `question`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Question text

### SocialEmailConfirmationUI

Holds localization settings for `SocialEmailConfirmationUI` screen.

* `title`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Title text
* `headline`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Headline text

### TransactionRequest

Holds localization settings for `TransactionRequest` screen.

* `title`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Title text
* `subtitle`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Subtitle text
* `mainCurrency`
  [\<object | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  Main currency details:
  * `amount`
    [\<string | number | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)
    Main currency amount
  * `symbol`
    [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Main currency symbol
* `exchangeValue`
  [\<object | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  Exchange currency details:
  * `amount`
    [\<string | number | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)
    Exchange currency amount
  * `symbol`
    [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Exchange currency symbol
* `fromLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  From label text
* `from`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  From address or label text
* `toLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  To label text
* `to`
  [\<string\[\] | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  To addresses
* `networkFeeLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Network fee label text
* `networkFeeTip`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Network fee tooltip text
* `networkFee`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Network fee amount
* `exchangeNetworkFee`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Exchange network fee amount
* `totalLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Total label text
* `total`
  [\<string\[\] | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Total amounts
* `exchangeTotalValue`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Exchange total value
* `rawTxDescription`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Raw transaction description
* `rawTx`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Raw transaction data

### ContractInteraction

Holds localization settings for a contract interaction screen.

* `title`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Title text
* `subtitle`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Subtitle text
* `mainCurrency`
  [\<object | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  Main currency details:
  * `amount`
    [\<string | number | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)
    Main currency amount
  * `symbol`
    [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Main currency symbol
* `exchangeValue`
  [\<object | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  Exchange value details:
  * `amount`
    [\<string | number | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)
    Exchange value amount
  * `symbol`
    [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Exchange value symbol
* `fromLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  From label text
* `from`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  From address or label text
* `contractAddressLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Contract address label text
* `contractInfo`
  [\<string\[\] | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Contract information
* `networkFeeLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Network fee label text
* `networkFeeTip`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Network fee tooltip text
* `networkFee`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Network fee amount
* `exchangeNetworkFee`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Exchange network fee amount
* `totalLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Total label text
* `total`
  [\<string\[\] | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Total amounts
* `exchangeTotalValue`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Exchange total value
* `dataDetails`
  [\<object | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
  Data details:
  * `dataDetailsLabel`
    [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
    Data details label
  * `callData`
    [\<object | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
    Call data:
    * `callDataLabel`
      [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
      Call data label
    * `data`
      [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
      Call data string
  * `abiInfo`
    [\<object | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects)
    ABI information:
    * `functionNameLabel`
      [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
      Function name label
    * `functionName`
      [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
      Function name string
    * `parametersLabel`
      [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
      Parameters label
    * `parameters`
      [\<string\[\] | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
      Parameters strings

### SignatureRequest

Holds localization settings for a signature request screen.

* `title`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Title text
* `contractName`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Contract name
* `contractUrl`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Contract URL
* `subtitle`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Subtitle text
* `descriptionLabel`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Description label text
* `description`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Description text

### EmailOtp

Holds localization settings for an email OTP (One-Time Password) screen.

* `title`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Title text
* `subtitle`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Subtitle text
* `resendHint`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Resend hint text
* `resend`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Resend button text

### ThemeColor

Holds customization color settings.

* `backdrop`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Backdrop color, e.g. `'#000000'`.
* `backdropOpacity`
  [\<number | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#snumber_type)
  Backdrop opacity, e.g. `0.5`.
* `divider`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Divider color, e.g. `'#808080'` or `'grey'`.
* `bg`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color e.g. `'#FFFFFF'` or `'white'`.
* `success`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Success color, e.g. `'#008000'` or `'green'`.
* `error`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Error color, e.g. `'#FF0000'` or `'red'`.
* `textMain`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Main text color, e.g. `'#000000'` or `'black'`.
* `textMain2`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Main text color 2, e.g. `'#000000'` or `'black'`.
* `textAuxiliary`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Auxiliary text color, e.g. `'#000000'` or `'black'`.
* `textAuxiliary2`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Auxiliary text color 2, e.g. `'#000000'` or `'black'`.
* `textSummary`[\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Summary text color, e.g. `'#000000'` or `'black'`.
* `textSummaryHighlight`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Summary highlight text color, e.g. `'#000000'` or `'black'`.
* `textPlaceholder`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Placeholder text color, e.g. `'#808080'` or `'grey'`.
* `pinDotBase`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Fill color for pincode input dot, e.g. `'#FFFFFF'` or `'white'`.
* `pinDotBaseBorder`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Stroke color for pincode input dot, e.g. `'#000000'` or `'black'`.
* `pinDotActivated`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Fill color for inputted pincode input dot, e.g. `'#0000ff'` or `'blue'`.
* `enteredPinText`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for entered pincode input, e.g. `#000000` or `black`.
* `inputText`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for text input, e.g. `#000000` or `black`.
* `inputBorderFocused`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Outline color for text input on focused, e.g. `'#0000ff'` or `'blue'`.
* `inputBorderFocusedError`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Outline color for text input when error, e.g. `'#FF0000'` or `'red'`.
* `inputBg`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for text input, e.g. `'#FFFFFF'` or `'white'`.
* `inputBgDisabled`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for disabled text input, e.g. `'#FFFFFF'` or `'white'`.
* `dropdownBg`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for dropdown, e.g. `'#FFFFFF'` or `'white'`.
* `dropdownBorderIsOpen`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Outline color for dropdown is open, e.g. `'#0000ff'` or `'blue'`.
* `dropdownBorderError`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Outline color for dropdown when error, e.g. `'#FF0000'` or `'red'`.
* `mainBtnText`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for primary button, e.g. `'#FFFFFF'` or `'white'`.
* `mainBtnTextDisabled`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for disabled primary button, e.g. `'#FFFFFF'` or `'white'`.
* `mainBtnTextOnHover`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for primary button on hover, e.g. `'#FFFFFF'` or `'white'`.
* `mainBtnBg`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for primary button, e.g. `'#000000'` or `'black'`.
* `mainBtnBgOnHover`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for primary button on hover, e.g. `'#000000'` or `'black'`.
* `mainBtnBgDisabled`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for disabled primary button, e.g. `'#000000'` or `'black'`.
* `secondBtnText`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for secondary button, e.g. `'#000000'` or `'black'`.
* `secondBtnTextDisabled`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for disabled secondary button, e.g. `'#000000'` or `'black'`.
* `secondBtnTextOnHover`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for secondary button on hover, e.g. `'#000000'` or `'black'`.
* `secondBtnBorder`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Outline color for secondary button, e.g. `'#000000'` or `'black'`.
* `secondBtnBorderOnHover`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Outline color for secondary button on hover, e.g. `'#000000'` or `'black'`.
* `secondBtnBgOnHover`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for secondary button on hover, e.g. `'#FFFFFF'` or `'white'`.
* `secondBtnBorderDisabled`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Outline color for disabled secondary button, e.g. `'#FFFFFF'` or `'white'`.
* `plainBtnText`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for plain text button, e.g. `'#000000'` or `'black'`.
* `plainBtnTextDisabled`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for disabled plain text button, e.g. `'#000000'` or `'black'`.
* `plainBtnTextOnHover`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for plain text button on hover, e.g. `'#000000'` or `'black'`.
* `plainBtnBg`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for plain text button, e.g. `'#FFFFFF'` or `'white'`.
* `plainBtnBgOnHover`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for plain text button on hover, e.g. `'#FFFFFF'` or
  `'white'`.
* `recoverPinHintTitle`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for recover pincode hint title, e.g. `'#FFFFFF'` or `'white'`.
* `recoverPinHintTitleBg`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for recover pincode hint title, e.g. `'#FFFFFF'` or
  `'white'`.
* `recoverPinHint`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Text color for recover pincode hint, e.g. `'#FFFFFF'` or `'white'`.
* `titleGradients`
  [\<string\[\] | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Background color for linear-gradient text, e.g. `['#B090F5', '#1AA3FF']`.

### Resources

Holds resource urls and properties, such as images or font-family settings.
These resource properties should be hosted on a public server. SDK will load
these resources from the urls provided.

* `naviClose`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Close icon
* `naviBack`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Back icon
* `securityIntroMain`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Security intro main image
* `dropdownArrow`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Dropdown arrow icon
* `selectCheckMark`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Select check mark icon
* `securityConfirmMain`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Security confirm main image
* `errorInfo`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Error info icon
* `fontFamily`
  [\<\{ name?: string, url?: string } | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#object_type)
  Font family settings

### CustomLinks

Holds custom links.

* `learnMoreUrl`
  [\<string | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Learn more link

## Class Definition

The Web SDK supports the class definitions listed in the following sections.

### W3SSdk

#### Constructor

Initializes a new instance of `W3SSdk`.

#### Methods

##### execute

Executes a challenge.

* `challengeId`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Challenge ID

* `onCompleted`
  [\<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
  Callback function
  * `error` [\<Error>](#error) Presents if error occurs
  * `result`[\<ChallengeResult>](#challengeresult) Presents when success

##### setAppSettings

Sets the application settings.

* `appSettings` [\<AppSettings>](#appsettings) Application settings object

##### setAuthentication

Sets the authentication information.

* `auth` [\<Authentication>](#authentication) Authentication object

##### updateConfigs

Updates the configurations.

* `configs`
  [\<Configs>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
  Configurations object
* `onSocialLoginComplete`
  [\<Function | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
  Callback function
  * `error` [\<Error>](#error) Presents if error occurs
  * `result` [\<SocialLoginResult>](#socialloginresult) |
    [\<\EmailLoginResult>](#emailloginresult) | undefined> Presents and
    contains the result of the social login when the social login is completed

##### getDeviceId

Gets the device ID.

##### performLogin

Performs a social login.

* `provider` [\<SocialLoginProvider>](#socialloginprovider) Social login
  provider

##### verifyOtp

Verifies the OTP.

##### execute

Executes a challenge.

* `challengeId`
  [\<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type)
  Challenge ID
* `onCompleted`
  [\<Function | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
  Callback function
  * `error` [\<Error>](#error) Presents if error occurs
  * `result` \<[ChallengeResult](#challengeresult) |
    [SignMessageResult](#signmessageresult) |
    [SignTransactionResult](#signtransactionresult) | undefined> Presents and
    contains the result of the challenge when the challenge is completed

##### setCustomSecurityQuestions

Sets custom security questions.

* `questions` [\<SecurityQuestion\[\] | undefined>](#securityquestion) Array of
  `SecurityQuestion`
* `requiredCount`
  [\<integer | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type)
  Required count of `SecurityQuestion`. The value is 2 by default.
* `securityConfirmItems`
  [\<string\[\] | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#array_type)
  Array of customized disclaimers on `SecurityConfirm` screen. The value is
  `undefined` by default.

##### setLocalizations

Sets custom localizations

* `localizations` [\<Localizations | undefined>](#localizations) Settings of
  `Localizations`

##### setResources

Sets custom resources

* `resources` [\<Resources | undefined>](#resources) Settings of `Resources`

##### setThemeColor

Sets custom theme colors

* `themeColor` [\<ThemeColor | undefined>](#themecolor) Settings of `ThemeColor`

##### setCustomLinks

Sets custom links

* `customLinks` [\<CustomLinks | undefined>](#customlinks) Settings of
  `CustomLinks`

##### setOnForgotPin

Sets callback function for ForgotPin button click event

* `onForgotPin`
  [\<Function | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
  Callback function
* `shouldCloseModalOnForgotPin`
  [\<boolean | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type)
  Should close modal on forgot pin click event

##### setOnResendOtpEmail

Sets callback function for **Resend OTP Email** button click event

* `onResendOtpEmail`
  [\<Function | undefined>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
  Callback function

## Sample code

### React.js

```javascript JavaScript theme={null}
import React, { useCallback, useEffect, useState } from "react";
import { ToastContainer, toast } from "react-toastify";
import TextField from "@mui/material/TextField";
import Button from "@mui/material/Button";
import { W3SSdk } from "@circle-fin/w3s-pw-web-sdk";

let sdk: W3SSdk;

function App() {
  useEffect(() => {
    sdk = new W3SSdk({
      configs: {
        appSettings: { appId: "someAppId" },
        authentication: {
          userToken: "someUserToken",
          encryptionKey: "someEncryptionKey",
        },
        socialLoginConfig: {},
      },
      socialLoginCompleteCallback: (error, result) => {
        if (error) {
          toast.error(`Social Login Error: ${error.message ?? "Error!"}`);
          return;
        }
        toast.success(`Social Login Success: ${result?.userToken}`);
      },
    });
  }, []);

  const [appId, setAppId] = useState(
    localStorage.getItem("appId") || "someAppId"
  );
  const [userToken, setUserToken] = useState(
    localStorage.getItem("userToken") || "someUserToken"
  );
  const [encryptionKey, setEncryptionKey] = useState(
    localStorage.getItem("encryptionKey") || "someEncryptionKey"
  );
  const [challengeId, setChallengeId] = useState(
    localStorage.getItem("challengeId") || "someChallengeId"
  );

  const onChangeHandler = useCallback(
    (setState, key) => (e) => {
      const value = e.target.value;
      setState(value);
      localStorage.setItem(key, value);
    },
    []
  );

  const onSubmit = useCallback(() => {
    sdk.setAppSettings({ appId });
    sdk.setAuthentication({ userToken, encryptionKey });

    sdk.execute(challengeId, (error, result) => {
      if (error) {
        toast.error(`Error: ${error?.message ?? "Error!"}`);
        return;
      }
      toast.success(`Challenge: ${result?.type}, Status: ${result?.status}`);
    });
  }, [appId, userToken, encryptionKey, challengeId]);

  return (
    <div className="p-4">
      <TextField
        label="App Id"
        onChange={onChangeHandler(setAppId, "appId")}
        value={appId}
      />
      <TextField
        label="User Token"
        onChange={onChangeHandler(setUserToken, "userToken")}
        value={userToken}
      />
      <TextField
        label="Encryption Key"
        onChange={onChangeHandler(setEncryptionKey, "encryptionKey")}
        value={encryptionKey}
      />
      <TextField
        label="Challenge Id"
        onChange={onChangeHandler(setChallengeId, "challengeId")}
        value={challengeId}
      />
      <Button variant="contained" color="primary" onClick={onSubmit}>
        Verify Challenge
      </Button>
      <ToastContainer />
    </div>
  );
}
```

### Vanilla JavaScript

```javascript JavaScript theme={null}
// Assume W3SSdk is globally available
let sdk = new W3SSdk({
  configs: {
    appSettings: { appId: 'someAppId' },
    authentication: {
      userToken: 'someUserToken',
      encryptionKey: 'someEncryptionKey'
    },
    socialLoginConfig: {}
  },
  socialLoginCompleteCallback: (error, result) => {
    if (error) {
      console.error(`Social Login Error: ${error.message ?? 'Error!'}`)
      return
    }
    console.log(`Social Login Success: ${result?.userToken}`)
  }
})

// Initialize settings
const initSettings = () => {
  sdk.setAppSettings({
    appId: 'someAppId',
  })
  sdk.setAuthentication({
    userToken: 'someUserToken',
    encryptionKey: 'someEncryptionKey',
  })
}

// Handle form submission
const handleSubmit = () => {
  const challengeId = document.getElementById('challengeId').value

  sdk.execute(challengeId, (error, result) => {
    if (error) {
      console.error(`Error: ${error?.message ?? 'Error!'}`)
      return
    }
    console.log(`Challenge: ${result?.type}, Status: ${result?.status}`)
  })
}

// Initialization
initSettings()

// Listen for button click event
document.getElementById('submitBtn').addEventListener('click', handleSubmit)sdk.execute(challengeId, (error, result) => {
  if (error) {
    toast.error(`Error: ${error?.message ?? 'Error!'}`)
    return
  }
  toast.success(`Challenge: ${result?.type}, Status: ${result?.status}`)
})
```


# Web SDK UI Customizations
Source: https://developers.circle.com/wallets/user-controlled/web-sdk-ui-customizations



This document describes the different customizable sections of the Programmable
Wallet SDK customization API. To get the most flexibility out of the SDK, use
this reference with the [SDK API](/wallets/user-controlled/web-sdk).

## Colors

### setThemeColor(themeColor: ThemeColor)

| #   | ThemeColor property     | Note                                                                        |
| --- | ----------------------- | --------------------------------------------------------------------------- |
| A1  | backdrop                | Modal backdrop color, e.g. '#000000'.                                       |
| A2  | backdropOpacity         | Modal backdrop opacity, e.g. 0.5.                                           |
| A3  | divider                 | Divider border color, e.g. '#808080' or 'grey'.                             |
| A4  | bg                      | Modal background color, e.g. '#FFFFFF' or 'white'.                          |
| A5  | success                 | Success text color, e.g. '#008000' or 'green'.                              |
| A6  | error                   | Error text color, e.g. '#FF0000' or 'red'.                                  |
| A7  | textMain                | Primary color, e.g. '#000000' or 'black'.                                   |
| A8  | textMain2               | Secondary color, e.g. '#000000' or 'black'.                                 |
| A9  | textAuxiliary           | Primary auxiliary color, e.g. '#000000' or 'black'.                         |
| A10 | textAuxiliary2          | Secondary auxiliary color, e.g. '#000000' or 'black'.                       |
| A11 | textSummary             | Summary text color, e.g. '#000000' or 'black'.                              |
| A12 | textSummaryHighlight    | Summary highlight text color, e.g. '#000000' or 'black'.                    |
| A13 | textPlaceholder         | Text input placeholder color, e.g. '#808080' or 'grey'.                     |
| A14 | pinDotBase              | Fill color for pincode input dot, e.g. '#FFFFFF' or 'white'.                |
| A15 | pinDotBaseBorder        | Stroke color for pincode input dot, e.g. '#000000' or 'black'.              |
| A16 | pinDotActivated         | Fill color for inputted pincode input dot, e.g. '#0000ff' or 'blue'.        |
| A17 | inputBorderFocused      | Outline color for text input on focused, e.g. '#0000ff' or 'blue'.          |
| A18 | inputBorderFocusedError | Outline color for text input when error, e.g. '#FF0000' or 'red'.           |
| A19 | inputBg                 | Background color for text input, e.g. '#FFFFFF' or 'white'.                 |
| A20 | inputBgDisabled         | Background color for disabled text input, e.g. '#FFFFFF' or 'white'.        |
| A21 | dropdownBg              | Background color for dropdown, e.g. '#FFFFFF' or 'white'.                   |
| A22 | dropdownBorderIsOpen    | Outline color for dropdown is open, e.g. '#0000ff' or 'blue'.               |
| A23 | dropdownBorderError     | Outline color for dropdown when error, e.g. '#FF0000' or 'red'.             |
| A24 | mainBtnText             | Text color for primary button, e.g. '#FFFFFF' or 'white'.                   |
| A25 | mainBtnTextDisabled     | Text color for disabled primary button, e.g. '#FFFFFF' or 'white'.          |
| A26 | mainBtnTextOnHover      | Text color for primary button on hover, e.g. '#FFFFFF' or 'white'.          |
| A27 | mainBtnBg               | Background color for primary button, e.g. '#000000' or 'black'.             |
| A28 | mainBtnBgOnHover        | Background color for primary button on hover, e.g. '#000000' or 'black'.    |
| A29 | mainBtnBgDisabled       | Background color for disabled primary button, e.g. '#000000' or 'black'.    |
| A30 | secondBtnText           | Text color for secondary button, e.g. '#000000' or 'black'.                 |
| A31 | secondBtnTextDisabled   | Text color for disabled secondary button, e.g. '#000000' or 'black'.        |
| A32 | secondBtnTextOnHover    | Text color for secondary button on hover, e.g. '#000000' or 'black'.        |
| A33 | secondBtnBorder         | Outline color for secondary button, e.g. '#000000' or 'black'.              |
| A34 | secondBtnBorderOnHover  | Outline color for secondary button on hover, e.g. '#000000' or 'black'.     |
| A35 | secondBtnBgOnHover      | Background color for secondary button on hover, e.g. '#FFFFFF' or 'white'.  |
| A36 | secondBtnBorderDisabled | Outline color for disabled secondary button, e.g. '#FFFFFF' or 'white'.     |
| A37 | plainBtnText            | Text color for plain text button, e.g. '#000000' or 'black'.                |
| A38 | plainBtnTextDisabled    | Text color for disabled plain text button, e.g. '#000000' or 'black'.       |
| A39 | plainBtnTextOnHover     | Text color for plain text button on hover, e.g. '#000000' or 'black'.       |
| A40 | plainBtnBg              | Background color for plain text button, e.g. '#FFFFFF' or 'white'.          |
| A41 | plainBtnBgOnHover       | Background color for plain text button on hover, e.g. '#FFFFFF' or 'white'. |
| A42 | recoverPinHintTitle     | Text color for recover pincode hint title, e.g. '#FFFFFF' or 'white'.       |
| A43 | recoverPinHintTitleBg   | Background color for recover pincode hint title, e.g. '#FFFFFF' or 'white'. |
| A44 | recoverPinHint          | ext color for recover pincode hint, e.g. '#FFFFFF' or 'white'.              |
| A45 | titleGradients          | Background color for linear-gradient text, e.g. \['#B090F5', '#1AA3FF'].    |
| A46 | inputText               | Text color for text input, e.g. '#000000' or 'black'.                       |
| A47 | enteredPinText          | Text color for entered pincode input, e.g. `'#000000'` or `'black'`.        |
| A48 | tooltipText             | Text color for tooltip content text, e.g. '#000000' or 'black'.             |
| A49 | tooltipBg               | Background color for tooltip content, e.g. '#FFFFFF' or 'white'.            |
| A50 | textInteractive         | Text color for call data and abi parameters                                 |
| A51 | interactiveBg           | Container background color for call data and abi parameters                 |

### Create your PIN

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<br />

### Re-enter your PIN to Confirm

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<br />

### Set up your Recovery Method

<Frame>
  <img />
</Frame>

<br />

### Security Questions Customization

Please reference the Security Question section in the
[SDK](/wallets/user-controlled/web-sdk#securityquestion) for how to customize
the question by using `setSecurityQuestions` method.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### Security Questions Summary

<Frame>
  <img />
</Frame>

### Security Questions Confirmation

<Frame>
  <img />
</Frame>

<br />

### Enter your PIN

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<br />

### Recover your PIN

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<br />

### Confirm Transaction

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### Contract Interaction

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## Custom security questions

| #  | Function                                                                                                                     | Note                                                                                                      |
| -- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| B1 | setCustomSecurityQuestions(  questions?: SecurityQuestion\[] \| null,  requiredCount = 2,  securityConfirmItems?: string\[]) | Set the array of security questions                                                                       |
| B2 | setCustomSecurityQuestions(  questions?: SecurityQuestion\[] \| null,  requiredCount = 2,  securityConfirmItems?: string\[]) | Set the required count of security questions. The value is 2 by default.                                  |
| B3 | setCustomSecurityQuestions(  questions?: SecurityQuestion\[] \| null,  requiredCount = 2,  securityConfirmItems?: string\[]) | Set the array of customized disclaimers on the SecurityConfirm screen. The value is undefined by default. |
| B4 | setOnForgotPin(onForgotPin: () => void)                                                                                      | Set the callback of onForgotPin                                                                           |

## Resources

### setResource(resources: Resources)

| #   | Resources Property   | Note                                                                                                                                                                      |
| --- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C1  | naviClose            | Close icon url for the navigation bar.                                                                                                                                    |
| C2  | naviBack             | Back icon URL for the navigation bar.                                                                                                                                     |
| C3  | securityIntroMain    | Security intros image URL for the security intros page.                                                                                                                   |
| C4  | dropdownArrow        | Arrow icon URL for the dropdown.                                                                                                                                          |
| C5  | selectCheckMark      | Selected item icon URL for the dropdown.                                                                                                                                  |
| C6  | securityConfirmMain  | Security confirm image URL for the security confirm page.                                                                                                                 |
| C7  | errorInfo            | Error icon for form validation.                                                                                                                                           |
| C8  | fontFamily           | Font-family for customization.E.g. `{ name: 'Edu TAS Beginner', URL: 'https\://fonts.googleapis.com/css2?family=Edu+TAS+Beginner:wght\@400;500;600;700\&display=swap' }`. |
| C9  | transactionTokenIcon | Token icon for the transaction request page.                                                                                                                              |
| C10 | dAppIcon             | DApp icon for customization for the sign message page.                                                                                                                    |
| C11 | tipIcon              | Tooltip icon for customization.                                                                                                                                           |
| C12 | emailIcon            | Email icon for customization.                                                                                                                                             |

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## CustomLinks

### setCustomLinks(customLinks: CustomLinks)

| #  | Custom Links Property | Note                                          |
| -- | --------------------- | --------------------------------------------- |
| D1 | learnMoreUrl          | External link for the learn more button link. |

## Localizations

### setLocalizations(localizations: Localizations)

| #      | Localizations Property | Note                                                      |
| ------ | ---------------------- | --------------------------------------------------------- |
| E1\~E3 | confirmPincode         | Holds localization settings for ConfirmPincode screen.    |
| F1\~F4 | enterPincode           | Holds localization settings for EnterPincode screen.      |
| G1\~G3 | newPincode             | Holds localization settings for NewPincode screen.        |
| H1\~H5 | recoverPincode         | Holds localization settings for RecoverPincode screen.    |
| I1\~I5 | securityConfirm        | Holds localization settings for SecurityConfirm screen.   |
| J1\~J4 | securityIntros         | Holds localization settings for SecurityIntros screen.    |
| K1\~K8 | securityQuestions      | Holds localization settings for SecurityQuestions screen. |
| L1\~L2 | securitySummary        | Holds localization settings for SecuritySummary screen.   |

### confirmPincode

| #  | Property Name | Note                                                                                                         |
| -- | ------------- | ------------------------------------------------------------------------------------------------------------ |
| E1 | headline      | Headline text <br /> <br />Keep the placeholder like this: <br />E.g. \`Re-enter your \{\{pin}} to confirm\` |
| E2 | headline2     | Headline text 2 <br /> <br />The text will replace the \{\{pin}} placeholder in the headline text            |
| E3 | subhead       | Subhead text                                                                                                 |

<Frame>
  <img />
</Frame>

<br />

### enterPincode

| #  | Property Name | Note                                                                                                                 |
| -- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
| F1 | headline      | Headline text <br /> <br />Keep the placeholder like this: <br />E.g. \`Enter your \{\{pin}}\` or \`輸入你的 \{\{pin}}\` |
| F2 | headline2     | Headline text 2 <br /> <br />The text will replace the \{\{pin}} placeholder in the headline text                    |
| F3 | subhead       | Subhead text                                                                                                         |
| F4 | forgotPin     | Forgot pin text                                                                                                      |

<Frame>
  <img />
</Frame>

<br />

### newPincode

| #  | Property Name | Note                                                                                                                 |
| -- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
| G1 | headline      | Headline text <br /> <br />Keep the placeholder like this: <br />E.g. \`Enter your \{\{pin}}\` or \`輸入你的 \{\{pin}}\` |
| G2 | headline2     | Headline text 2 <br /> <br />The text will replace the \{\{pin}} placeholder in the headline text                    |
| G3 | subhead       | Subhead text                                                                                                         |

<Frame>
  <img />
</Frame>

<br />

### recoverPincode

| #  | Property Name          | Note                          |
| -- | ---------------------- | ----------------------------- |
| H1 | headline               | Headline text                 |
| H2 | headline2              | Headline text 2               |
| H3 | subhead                | Subhead text                  |
| H4 | answerInputHeader      | Answer input header text      |
| H5 | answerInputPlaceholder | Answer input placeholder text |

<Frame>
  <img />
</Frame>

### securityConfirm

| #  | Property Name    | Note                   |
| -- | ---------------- | ---------------------- |
| I1 | title            | Title text             |
| I2 | headline         | Headline text          |
| I3 | inputHeadline    | Input headline text    |
| I4 | inputPlaceholder | Input placeholder text |
| I5 | inputMatch       | Input match text       |

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### securityIntros

| #  | Property Name | Note             |
| -- | ------------- | ---------------- |
| J1 | headline      | Headline text    |
| J2 | headline2     | Headline text 2  |
| J3 | description   | Description text |
| J4 | link          | Link text        |

<Frame>
  <img />
</Frame>

### securityQuestions

| #  | Property name         | Note                         |
| -- | --------------------- | ---------------------------- |
| K1 | title                 | Title text                   |
| K2 | questionHeader        | Question header text         |
| K3 | questionPlaceholder   | Question placeholder text    |
| K4 | requiredMark          | Required mark text           |
| K5 | answerHeader          | Answer header text           |
| K6 | answerPlaceholder     | Answer placeholder text      |
| K7 | answerHintHeader      | Answer hint header text      |
| K8 | answerHintPlaceholder | Answer hint placeholder text |

<Frame>
  <img />
</Frame>

### securitySummary

| #  | Property Name | Note                                                                                                                                                                                                                                                                  |
| -- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| L1 | title         | Title text                                                                                                                                                                                                                                                            |
| L2 | question      | Question text <br /> <br />Keep the placeholder like this: <br />E.g. `{{ordinal}} Question` `{{ordinal}} 質問` or `{{ordinal}} вопрос` or `{{ordinal}} คำถาม` <br /> <br />You don't need to place any ordinal value into the placeholder. Web-sdk will do it for you. |

<Frame>
  <img />
</Frame>

### transactionRequest

| #   | Property name      | Note                                                                                                                                                                                                                                                                                                                                                                 |
| --- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| M1  | title              | Main title text                                                                                                                                                                                                                                                                                                                                                      |
| M2  | subtitle           | Subtitle text                                                                                                                                                                                                                                                                                                                                                        |
| M3  | mainCurrency       | Main currency info, including amount and symbol <br /> <br />E.g. \{ mainCurrency: \{ amount: 300, symbol: `ETH` }                                                                                                                                                                                                                                                   |
| M4  | exchangeValue      | Exchanged currency info, including amount and symbol <br /> <br />E.g. \{ exchangeValue: \{ amount: 300, symbol: `USDC` }                                                                                                                                                                                                                                            |
| M5  | fromLabel          | From label                                                                                                                                                                                                                                                                                                                                                           |
| M6  | from               | From value <br />E.g. `0x8De9d7D8503D1DE1566393d7155711B7e4210666` <br /> <br />Sdk will do the shortenHash for you.                                                                                                                                                                                                                                                 |
| M7  | toLabel            | To label                                                                                                                                                                                                                                                                                                                                                             |
| M8  | to                 | To values. <br />This is an array of 3 elements. <br /> <br />E.g. <br />\[`uniswape.org`, `https://uniswape.org`, `0x8De9d7D8503D1DE1566393d7155711B7e4210666`] <br /> <br />If you only need to display the address only and you don't need the dApp name and url displayed, you can input it as follows: <br />`[, , 0x8De9d7D8503D1DE1566393d7155711B7e4210666]` |
| M9  | networkFeeLabel    | Network fee label                                                                                                                                                                                                                                                                                                                                                    |
| M10 | networkFeeTip      | Text for network fee tooltip                                                                                                                                                                                                                                                                                                                                         |
| M11 | networkFee         | Network fee value <br /> <br />E.g. `0.005 ETH`                                                                                                                                                                                                                                                                                                                      |
| M12 | exchangeNetworkFee | Exchanged network fee value <br /> <br />E.g. `10 USD`                                                                                                                                                                                                                                                                                                               |

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### contractInteraction

| #   | Property name      | Note                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| N1  | title              | Main title text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| N2  | subtitle           | Subtitle text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| N3  | mainCurrency       | Main currency info, including amount and symbol <br /> <br />E.g. \{ mainCurrency: \{ amount: 300, symbol: `ETH` }                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| N4  | exchangeValue      | Exchanged currency info, including amount and symbol <br /> <br />E.g. \{ exchangeValue: \{ amount: 300, symbol: `USDC` }                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| N5  | fromLabel          | From label                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| N6  | from               | From value <br /> <br />E.g. `0x8De9d7D8503D1DE1566393d7155711B7e4210666` <br /> <br />Sdk will do the shortenHash for you.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| N7  | toLabel            | To label                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| N8  | to                 | To values. <br /> <br />This is an array of 3 elements. <br /> <br />E.g. <br />`[uniswape.org, https://uniswape.org, 0x8De9d7D8503D1DE1566393d7155711B7e4210666]` <br /> <br />If you only need to display the address only and you don't need the dApp name and url displayed, you can input it as follows: <br />`[, , 0x8De9d7D8503D1DE1566393d7155711B7e4210666]`                                                                                                                                                                                                                                         |
| N9  | networkFeeLabel    | Network fee label                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| N10 | networkFeeTip      | Text for network fee tooltip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| N11 | networkFee         | Network fee value <br /> <br />E.g. `0.005 ETH`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| N12 | exchangeNetworkFee | Exchanged network fee value <br /> <br />E.g. `10 USD`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| N13 | totalLabel         | Total label text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| N14 | total              | Total values. This is an array of 2 elements. <br /> <br />E.g. <br />`[20 USDC, + 0.0002 ETH]` or <br />`[20 USDC + 0.0002 ETH, ]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| N15 | exchangeTotalValue | Exchanged total value text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| N16 | dataDetails        | An object for contract interaction data detail display. <br /> <br />\{ <br /> dataDetails?: \{ <br /> dataDetailsLabel?: string <br /> callData?: \{ <br /> callDataLabel?: string <br /> data?: string <br /> } <br /> abiInfo?: \{ <br /> functionNameLabel?: string <br /> functionName?: string <br /> parametersLabel?: string <br /> parameters?: string\[] <br /> } <br />} <br /> <br />dataDetailsLabel: data details label <br /> <br />callData or abiInfo: The use could choose either one to fill up depending on the transaction can be parsed by abi (choose abiInfo) or not (choose callData) |

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### signatureRequest

| #  | Property name    | Note              |
| -- | ---------------- | ----------------- |
| O1 | title            | Main title text   |
| O2 | subtitle         | Subtitle text     |
| O3 | contractName     | Contract name     |
| O4 | contractUrl      | Contract url      |
| O5 | descriptionLabel | Description label |
| O6 | description      | Description       |

<Frame>
  <img />
</Frame>

### emailOtp

| #  | Property name | Note               |
| -- | ------------- | ------------------ |
| P1 | title         | Main title text    |
| P2 | subtitle      | Subtitle text      |
| P3 | resendHint    | Resend label text  |
| P4 | resend        | Resend button text |

<Frame>
  <img />
</Frame>

### common

| #  | Property name | Note                 |
| -- | ------------- | -------------------- |
| Q1 | continue      | Continue button text |
| Q2 | showPin       | ShowPin button text  |
| Q3 | hidePin       | HidePin button text  |
| Q4 | confirm       | Confirm button text  |
| Q5 | sign          | Sign button text     |
| Q6 | retry         | Retry button text    |

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>


# Wallet Upgrades
Source: https://developers.circle.com/wallets/wallet-upgrades



Smart Contract Account (SCA) and Modular Smart Contract Account (MSCA) wallets
use a contract proxy pattern, a common design pattern that allows Circle to
upgrade the contract's logic without changing the address of the contract. With
a proxy pattern, the proxy contract delegates calls to an implementation
contract. The proxy contract can be configured to use a new implementation
contract, which is commonly referred to as an upgrade. Circle uses the
[ERC-1967](https://docs.openzeppelin.com/contracts/5.x/api/proxy#ERC1967Proxy)
proxy pattern, which is well-established in the crypto industry.

The proxy pattern gives Circle the ability to provide bug fixes and product
improvements to SCAs and MSCAs over time. However, you are in full control of
your wallets, even when Circle performs a contract upgrade. When Circle makes a
new version of a contract available, you must manually initiate an upgrade using
the API.

<Note>
  **Note:** Because modular wallets are proxy contracts, users' wallet addresses
  in block explorers are shown as `ERC1967Proxy` instead of `UpgradeableMSCA`.

  Modular wallets only have a single version of the wallet contract available.
  When an upgrade is available this page provides instructions on the appropriate
  API calls to make to upgrade your wallets.
</Note>

## Smart Contract Account wallets

You can upgrade both developer-controlled and user-controlled SCA wallets to
newer SCA versions using the **Wallet Upgrade API**.

* To upgrade a **developer-controlled wallet**, use
  [`POST /developer/transactions/walletUpgrade`](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-wallet-upgrade).
* To upgrade a **user-controlled wallet**, use
  [`POST /user/transactions/walletUpgrade`](/api-reference/wallets/user-controlled-wallets/create-user-transaction-wallet-upgrade-challenge)
  and follow the standard challenge approval flow.

### Supported migration paths

| Source SCA Version                | Destination SCA Version           | Contract Function Used for Upgrade |
| --------------------------------- | --------------------------------- | ---------------------------------- |
| **circle\_4337\_v1**              | **circle\_6900\_singleowner\_v2** | `upgradeToAndCall(address,bytes)`  |
| **circle\_6900\_singleowner\_v1** | **circle\_6900\_singleowner\_v2** | `upgradeTo(address)`               |

<Note>
  **💡 Tip:** Use the `scaCore` query parameter in the `GET /wallets` endpoint
  to fetch SCA wallets eligible for an upgrade.
</Note>

After calling any **Wallet Upgrade API** endpoint, a transaction appears in the
**Developer Console UI** and transaction APIs, showing the contract execution
call that upgrades the wallet. Once the transaction reaches the `COMPLETE`
state, the SCA version of the wallet is updated in the responses of the
`GET /wallets/{id}` or `GET /wallets` endpoints.

### Special handling for `circle_4337_v1` wallets

Due to onchain specific requirements, `circle_4337_v1` wallets must be **lazy
deployed** before they can be upgraded. To trigger deployment, initiate an
**outbound transfer** or **contract execution** from the SCA wallet you want to
upgrade. See the [account types](/wallets/account-types) page for more details
on SCA lazy deployment.

If you need to upgrade a `circle_4337_v1` wallet on a **testnet**, send native
token funds to the wallet's **owner address**. You can retrieve the owner
address using the
[`POST /contracts/query`](/api-reference/contracts/smart-contract-platform/query-contract)
endpoint.

<CodeGroup>
  ```javascript Node.js SDK theme={null}
  response = await client.queryContract({
    abiFunctionSignature: "owner()",
    address: "<replace-me-with-your-circle_4337_v1-sca-wallet-address>",
    blockchain: "<replace-me-with-your-wallet's-blockchain>",
    abiJson:
      '[{"inputs": [],"name": "owner","outputs": [{"internalType": "address","name": "","type": "address"}],"stateMutability": "view","type": "function"}]',
  });
  ```

  ```coffeescript Python SDK theme={null}
  # create an api instance
  api_instance = smart_contract_platform.InteractApi(scpClient)
  try:
      request = smart_contract_platform.ReadContractStateRequest.from_dict({
          "abiFunctionSignature": "owner()",
          "address": "<replace-me-with-your-circle_4337_v1-sca-wallet-address>",
          "blockchain": "<replace-me-with-your-wallet's-blockchain>",
          "abiJson": "[{\"inputs\": [],\"name\": \"owner\",\"outputs\": [{\"internalType\": \"address\",\"name\": \"\",\"type\": \"address\"}],\"stateMutability\": \"view\",\"type\": \"function\"}]"
      })
      response = api_instance.query_contract(request)
  except smart_contract_platform.ApiException as e:
      print("Exception when calling InteractApi->read_contract: %s\n" % e)
  ```

  ```curl Curl theme={null}
  curl --request POST \
    --url https://api.circle.com/v1/w3s/contracts/query \
    --header "Authorization: Bearer $API_KEY" \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{
        "abiFunctionSignature": "owner()",
        "address": "<replace-me-with-your-circle_4337_v1-sca-wallet-address>",
        "blockchain": "<replace-me-with-your-wallet's-blockchain>",
        "abiJson": "[{\"inputs\": [],\"name\": \"owner\",\"outputs\": [{\"internalType\": \"address\",\"name\": \"\",\"type\": \"address\"}],\"stateMutability\": \"view\",\"type\": \"function\"}]"
      }'
  ```
</CodeGroup>

```json Response Body theme={null}
{
  "data": {
    "outputData": "0x...",
    "outputValues": ["<owner-address>"]
  }
}
```

The first entry in the `outputValues` array contains the **owner address**,
which must receive the native token funds. Circle recommends sending enough
tokens to cover **\~300,000 gas**. Estimated costs:

* **ETH-SEPOLIA**: 300,000 gas \* 30 Gwei (replace with current gas price) =
  `0.009 ETH`
* **MATIC-AMOY**: 300,000 gas \* 150 Gwei (replace with current gas price) =
  `0.045 POL`

<Note>
  **Note:** You can skip the native token funding step for **mainnet**
  `circle_4337_v1` wallets, as they have already received airdropped native
  tokens to cover upgrade transaction fees. These wallets can be upgraded
  immediately after lazy deployment.
</Note>

### How the upgrade works

The wallet upgrade contract execution updates the **logic contract address** of
the [ERC-1967](https://eips.ethereum.org/EIPS/eip-1967) proxy (the SCA wallet)
by calling either:

* `upgradeTo(addresss)`
* `upgradeToAndCall(addresss,bytes)`

Your wallet's address and assets don't change during or after the upgrade. You
can continue to use the wallet normally while the upgrade transaction is in
progress.

## Contract versions

Use the factory and implementation addresses below to verify onchain
deployments. Factory and implementation addresses are the same on mainnet and
testnet.

| Type     | Version                       | Description                                                                                                                                                                    | Factory address                              | Implementation address                       |
| -------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | -------------------------------------------- |
| **SCA**  | circle\_6900\_singleowner\_v3 | Compliant with ERC-6900 v0.7 and ERC-4337 v0.6. Supports a single owner address and batch multiple userOps in one transaction.                                                 | `0xf61023061ed45fa9eAC4D2670649cE1FD37ce536` | `0xD206aC7fEf53d83ED4563E770b28Dba90D0D9eC8` |
| **MSCA** | circle\_6900\_v1              | Compliant with ERC-6900 v0.7 and ERC-4337 v0.7. Supports any ownership type (single owner, multiple owners, passkeys, multisig) and batch multiple userOps in one transaction. | `0x0000000DF7E6c9Dc387cAFc5eCBfa6c3a6179AdD` | `0xA70F1296869DA9D7CB69578123F21888E6dB2B62` |


# Circle Wallets on Solana
Source: https://developers.circle.com/wallets/wallets-on-solana

Overview for developers

## Solana-specific features

* **Account type upon wallet creation**: In Solana, you can only specify the
  Externally Owned Account (EOA) type when creating a wallet. The Smart Contract
  Account (SCA) account type is specifically for ERC-4337 (account abstraction)
  implementation and is not supported in Solana.

* **Transaction acceleration/cancellation**: Solana allows you to specify a
  higher priority fee to attempt to accelerate a transaction. However, you
  cannot replace an existing transaction with a higher transaction fee, which
  means the existing API for accelerating or cancelling transactions is not
  supported in Solana.

* **Signing message and typed data**: Solana only supports signing messages and
  does not support signing typed data.

* **Associated Token Account (ATA)**: When transferring SPLs in Solana, an ATA
  is automatically created for the recipient, which ensures that they can
  receive tokens. Since extra network fees are associated with the first
  transaction of a token, you must have enough fees available in your
  originating wallet.

  <Warning>
    **Arbitrary token accounts are not supported**. Circle Wallets on Solana only
    support Associated Token Accounts (ATAs). Transactions involving non-ATA
    accounts are not parsed, and tokens sent to such accounts may be permanently
    lost and cannot be recovered.
  </Warning>

* **Gas Station**: Gas Station is a feature of Wallets that lets developers
  sponsor network fees on behalf of their end users. Solana natively supports
  the Gas Station feature with `feePayer`, while EVM chains require using SCAs
  to utilize the gas station feature. We've integrated this Solana support into
  our Gas Station so that you can sponsor transaction fees for EOA wallets on
  Solana.

* **Gas specification**: The gas fee mechanism on Solana is similar to EIP-1559:
  you can specify a priority fee to incentivize validators to include your
  transaction in a block. Note that on Solana there is no concept of a “max fee”
  and `gasLimit` is optional. Solana defaults to a gas limit of 200,000
  micro-lamport (10^-15 SOL).

## Migrate from EVM chains to Solana

To transition from EVM chains to Solana, set the `blockchains` parameter value
to `SOL` on mainnet, or `SOL-DEVNET` on testnet.

When creating wallets for end-users, follow these steps to allow them to
transfer assets:

## Step 1. Create Solana wallets

For
[developer-controlled wallets](/api-reference/wallets/developer-controlled-wallets/create-wallet),
use existing wallet sets to generate Solana wallets and change the following
body params:

* **accountType**: Set to `EOA`
* **blockchains**: Set to `SOL` or `SOL-DEVNET`
* **walletSetId**: Set to the existing wallet set ID

For
[user-controlled wallets](/api-reference/wallets/user-controlled-wallets/create-user-wallet),
use the same `X-User-Token` header parameter for the same end-user. If it
expires,
[create a new user token](/api-reference/wallets/user-controlled-wallets/get-user-token).
Change the following body parameters:

* **accountType**: Set to `EOA`
* **blockchains**: Set to `SOL` or `SOL-DEVNET`

Next, for both wallets, specify the wallet metadata associated with an end-user
during or after wallet creation:

* **name**: Set to the wallet name, for example: `User Wallet1`
* **refId**: Set to the unique identifier of the reference, for example: `UUID1`

## Step 2. Request test token

To fund Solana
[testnet](/api-reference/wallets/programmable-wallets/request-testnet-tokens)
wallets, update the following body params:

* **blockchain**: `SOL-DEVNET`
* **address**: Set to the newly created Solana wallet address

## Step 3. Set up the Gas Station policy for Solana

Set up the [Gas Station policy](/wallets/gas-station/policy-management) for
Solana in mainnet. Testnet environments come with pre-set default policies.

## Step 4. Execute transactions

Specify the transaction detail in the following API endpoints:

* [`POST` `/transactions/transfer`](/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-transfer)
* [`POST` `/transactions/transfer/estimateFee`](/api-reference/wallets/developer-controlled-wallets/create-transfer-estimate-fee)

<Warning>
  Ensure the `blockchains` body parameter is set to `SOL` or `SOL-DEVNET`
</Warning>

<Note>
  The response to a `POST` request to the `/transactions/transfer/estimateFee`
  endpoint is the same for each fee level (`high`, `medium`, `low`).
</Note>


# Troubleshoot Webhooks
Source: https://developers.circle.com/wallets/webhook-logs



Utilizing Webhook notification logs, you gain visibility into the comprehensive
history of Webhook events triggered by Circle's systems. In addition, you are
empowered to resend any specific Webhook events, simplifying the process of
troubleshooting any potential issues that may arise.

## Webhook Logs Overview

Within the Circle Developer Console, there is a dedicated tab for **Webhook
Logs**. By accessing this tab, you will be presented with an informative
overview highlighting the most recent Webhook Events, thereby facilitating
efficient monitoring and management of your Webhook integrations.

<Frame>
  <img />
</Frame>

## Detailed Webhook View for Deeper Insight

In addition, you have the ability to access a detailed page for each individual
entry within the Webhook Logs. By clicking on a specific entry, you will be
directed to a dedicated detail page that offers comprehensive information. This
includes nested event object data and an associated table of events, including
their respective Webhook attempts.

This detailed view enables you to gain deeper insights into the specific details
of each Webhook event, aiding in further analysis and troubleshooting. Moreover,
it provides you with the valuable option to resend a Webhook, allowing for
seamless management and control over your Webhook integration flow.

<Frame>
  <img />
</Frame>

**Field Definitions:**

|                     |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Delivery Status** | The delivery status of a webhook notification indicates the outcome of the most recent delivery attempt(s). If any of the recent webhook attempts are marked as failed, it will affect the overall delivery status, resulting in a "failed" status. Monitoring the delivery status helps determine the reliability and success of webhook notifications, allowing for effective troubleshooting and resolution of any delivery issues. |
| **Log ID**          | Unique identifier \[UUID] for the event.                                                                                                                                                                                                                                                                                                                                                                                               |
| **Notification ID** | Unique identifier \[UUID] for the notification.                                                                                                                                                                                                                                                                                                                                                                                        |
| **Event Type**      | The event type and state of the event e.g. Transaction.Initiated.                                                                                                                                                                                                                                                                                                                                                                      |
| **Event**           | The webhook notification payload.                                                                                                                                                                                                                                                                                                                                                                                                      |


# Webhook Events and Payloads
Source: https://developers.circle.com/wallets/webhook-notification-flows



## Common Considerations

All implementations of notification messages have the following attributes:

| Name               | Type   | Description                                                         | Example                                |
| ------------------ | ------ | ------------------------------------------------------------------- | -------------------------------------- |
| `subscriptionId`   | string | ID of the webhook subscription.                                     | `80b9b08f-fd12-4f40-a3a6-51bad45cec51` |
| `notificationId`   | string | ID for each event notification. This value is the same for retries. | `b3f2761f-6ae8-49f8-a730-6216aea08900` |
| `notificationType` | string | The type of notification.                                           | `transactions.inbound`                 |
| `version`          | int    | The version of the notification.                                    | `2`                                    |

## Implementations

This section lists models used by existing flows.

## Transaction Flows

This section introduces the events that may occur with a transaction.

### Inbound Transactions

#### Confirmed

Confirmed transactions have been broadcast on the blockchain but have not yet
reached the number of confirmations needed to be considered complete.

**Confirmed Transaction Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.inbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Transaction Object*.

#### Completed

Completed transactions are settled transactions in which the needed number of
blockchain confirmations has been met. Therefore the funds should be available
in the destination account.

**Completed Transaction Notification Payload:**

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.inbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Transaction Object*.

### Outbound Transactions

#### Queued

Queued transactions have been successfully initiated but have not yet been
processed.

**Queued Transaction Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Transaction Object*.

#### Sent

Sent transactions are processed and sent to the blockchain node but have not yet
been broadcast onchain.

**Sent Transaction Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Transaction Object*.

#### Confirmed

Confirmed transactions have been successfully broadcast on the blockchain but
have not yet reached the number of confirmations needed to be considered
complete.

**Confirmed Transaction Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Transaction Object*.

#### Completed

Completed transactions are settled transactions in which the needed number of
blockchain confirmations has been met. Therefore the funds should be available
in the destination account.

**Completed Transaction Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Transaction Object*.

#### Canceled

The following structure represents notifications for confirmed *cancel*
requests:

**Canceled Transaction Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Transaction Object*.

#### Failed

A transaction might fail due to insufficient balance, failed challenge and so
forth. A notification with the following structure is sent for *failed*
transactions:

**Failed Transaction Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Transaction Object*.

### Challenge Flows

This section introduces the events that may occur with a challenge.

#### Complete

Complete challenges indicate that the operation has been successfully passed by
the end-user. Therefore the associated action should be automatically initiated.

**Complete Challenge Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "challenges.initialize",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Challenge Object*.

#### Failed

Challenges can fail for reasons such as an incorrect pin being entered, the
challenge expiring and so forth. A notification with the following structure is
sent for failed challenges. This indicates that the operation needs to be
re-initiated.

**Failed Challenge Notification Payload**:

```json JSON theme={null}
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "challenges.initialize",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}
```

The payload will contain the information of a *Challenge Object*.


# Set Up Webhooks
Source: https://developers.circle.com/wallets/webhook-notifications



This quickstart guide helps you quickly set up notifications for Circle Wallets.
Follow this to configure a subscriber endpoint that sends a notification every
time the status of resource changes.

This guide focuses on the challenge resource but applies to any resources
available in Programmable Wallet Notifications.

## 1. Expose a Subscriber Endpoint

To receive notifications on changes in resource status, you must expose a
publicly accessible subscriber endpoint on your side. The endpoint must handle
both `HEAD` and **POST** requests over HTTPS.

To quickly expose an endpoint for testing, we will use
[webhook.site](https://webhook.site/) in this guide, which allows you to easily
inspect, test and automate any incoming HTTPS request or e-mail directly in a
web browser.

When visiting [webhook.site](https://webhook.site/) for the first time, you
should see a status message that looks like the following:

<Note>
  Your unique URL (Please copy it from here, not from the address bar!)
  `https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7`
</Note>

<Note>
  **Record the value of the **unique URL**.**

  In the example above, the unique URL
  is:`https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7`. Use the
  public-facing URL you receive as you progress throughout this guide.
</Note>

## 2. Subscribe to Webhook Notifications

Now that you have a publicly accessible endpoint, you need to register your
endpoint as a subscriber to webhook notifications by doing the following:

1. Click **Webhooks** in your Circle Developer account.
2. Click **Add a Webhook** in the upper right corner.
3. Enter your endpoint URL from above. It will be similar to the earlier
   example:`https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7`.
4. Click **Add Webhook**.
5. At this stage, you should receive a Hello World test notification indicating
   you have subscribed to your endpoint successfully:

```json JSON theme={null}
{
  "subscriptionId": "00000000-0000-0000-0000-000000000000",
  "notificationId": "00000000-0000-0000-0000-000000000000",
  "notificationType": "webhooks.test",
  "notification": {
    "hello": "world"
  },
  "timestamp": "2023-07-20T16:18:40.816010685Z",
  "version": 2
}
```

Now you have a sample local environment ready to receive transaction and
challenge status change notifications. Note that in testnet and mainnet there is
a limit of 20 webhook notifications each.

### Customize Webhook Notifications

You can customize your webhook notifications. Customized webhook notifications
allow you to listen to a restricted set of specific events, such as inbound
transactions only, or a specific set of events, such as transaction or
challenges, through a URL endpoint on your receiving application.

To customize your endpoints to only receive certain notifications, toggle on
“Limit to specific events” when creating your webhook.

You are then able to pick the event categories that you want to listen to on
your endpoint. These can be further customized at the event level under each
category. This gives you the flexibility to only listen to events you care about
at each endpoint, rather than overwhelming the endpoint with all notifications.
This reduces the amount of data your server needs to process, making it more
efficient and easier to manage. It also helps in focusing only on the relevant
events, which can improve the performance and reliability of your application.

## 3. Initiate a Challenge Flow to Receive a Notification

To observe a notification message on the status of a challenge, initiate the
creation of a wallet.

Once you successfully initiate a challenge payment, you should see a
notification message on your local server shell that looks like the following:

**Sample Challenge Notification**:

```json JSON theme={null}
{
  "subscriptionId": "a68cd974-d209-46cd-8dbf-b7a081fbd627",
  "notificationId": "eaa4a4fe-24b8-4329-a4c6-6dfd557dbcb2",
  "notificationType": "challenges.initialize",
  "notification": {
    "id": "9c0a1991-735a-5140-8996-7b95720c5e55",
    "userId": "2a054cd1-3124-4aa7-b1f0-86c4a4df995c",
    "type": "INITIALIZE",
    "status": "COMPLETE",
    "correlationIds": ["01890792-a199-77bc-b005-b229f81824fa"],
    "errorCode": 0,
    "errorMessage": ""
  },
  "timestamp": "2023-06-29T14:33:17.785131449Z",
  "version": 2
}
```

## 4. Verify Digital Signature

1. Every webhook notification is digitally signed by an asymmetric key. In the
   headers of each webhook, you can find:
   1. `X-Circle-Signature`: a header containing the digital signature generated
      by Circle
   2. `X-Circle-Key-Id`: a header containing the UUID you need to retrieve the
      relevant public key

```
# Headers
`X-Circle-Key-Id: “879dc113-5ca4-4ff7-a6b7-54652083fcf8”`
`X-Circle-Signature: “MEYCIQCA9EvPbdEJiy7Cw0eY+KQZA/oFi5ZEInPs8CYpyaJexgIhAKtRNnDz9QRQmFKx8QFrvawp+8b9Bs2dQ03xD+XaWVDE”`
```

2. Using the X-Circle-Key-Id value, query the following endpoint to retrieve the
   public key and algorithm used to sign the message:
   [`GET /v2/notifications/publicKey/{keyId)`](/api-reference/wallets/common/get-notification-signature)

```shell Shell theme={null}
# Replace ${YOUR_API_KEY} with your API key
# Replace ${PUBLIC_KEY_ID} with your public key id
curl --request GET \
     --url 'https://api.circle.com/v2/notifications/publicKey/${PUBLIC_KEY_ID)' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ENV_API_KEY:ID:SECRET$' \
```

If successful, you will receive a response with the following shape

```json Response Body theme={null}
{
  "data": {
    "id": "879dc113-5ca4-4ff7-a6b7-54652083fcf8",
    "algorithm": "ECDSA_SHA_256",
    "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAESl76SZPBJemW0mJNN4KTvYkLT8bOT4UGhFhzNk3fJqf6iuPlLQLq533FelXwczJbjg2U1PHTvQTK7qOQnDL2Tg==",
    "createDate": "2023-06-28T21:47:35.107250Z"
  }
}
```

3. Use the public key and algorithm to verify the integrity of the webhook's
   payload against the signature found in `X-Circle-Signature`.

**Note:** Please make sure the webhook notification is properly formatted JSON
string prior to verifying it

```json Response Body theme={null}
{
  "subscriptionId": "890a8cae-46bd-40ad-bd7f-2e49b8dea9da",
  "notificationId": "0bdd3e4b-5070-4530-8ed4-2e2e4c9fd2f0",
  "notificationType": "webhooks.test",
  "notification": {
    "hello": "world"
  },
  "timestamp": "2023-07-12T04: 02: 28.555562821Z",
  "version": 2
}
```

The following code sample demonstrates how to verify the `X-Circle-Signature`:

<CodeGroup>
  ```python Python theme={null}
  import base64

  from cryptography.exceptions import InvalidSignature
  from cryptography.hazmat.primitives import hashes, serialization
  from cryptography.hazmat.primitives.asymmetric import ec

  # Load the public key from the base64 encoded string
  # Note: The public key is static for a given publicKeyId, therefore we recommend you to cache it
  public_key_base64 = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAESl76SZPBJemW0mJNN4KTvYkLT8bOT4UGhFhzNk3fJqf6iuPlLQLq533FelXwczJbjg2U1PHTvQTK7qOQnDL2Tg=="
  public_key_bytes = base64.b64decode(public_key_base64)
  public_key = serialization.load_der_public_key(public_key_bytes)

  # Load the signature you want to verify
  signature_base64 = "MEQCIBlJPX7t0FDOcozsRK6qIQwik5Fq6mhAtCSSgIB/yQO7AiB9U5lVpdufKvPhk3cz4TH2f5MP7ArnmPRBmhPztpsIFQ=="
  signature_bytes = base64.b64decode(signature_base64)

  # Load the message you want to verify
  message = "{\"subscriptionId\":\"00000000-0000-0000-0000-000000000000\",\"notificationId\":\"00000000-0000-0000-0000-000000000000\",\"notificationType\":\"webhooks.test\",\"notification\":{\"hello\":\"world\"},\"timestamp\":\"2024-01-26T18:22:19.779834211Z\",\"version\":2}"
  message_bytes = message.encode(encoding="utf-8")

  # Verify the signature
  try:
      public_key.verify(
          signature_bytes,
          message_bytes,
          ec.ECDSA(hashes.SHA256()),
      )
      print("Signature is valid.")
  except InvalidSignature:
      print("Signature is invalid.")
  ```

  ```javascript Node.js theme={null}
  const crypto = require("crypto");

  // Load the public key from the base64 encoded string
  // Note: The public key is static for a given publicKeyId, therefore we recommend you to cache it
  const publicKeyBase64 =
    "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAESl76SZPBJemW0mJNN4KTvYkLT8bOT4UGhFhzNk3fJqf6iuPlLQLq533FelXwczJbjg2U1PHTvQTK7qOQnDL2Tg==";
  const publicKeyBytes = Buffer.from(publicKeyBase64, "base64");
  const publicKey = crypto.createPublicKey({
    key: publicKeyBytes,
    format: "der",
    type: "spki",
  });

  // Load the signature you want to verify
  const signatureBase64 =
    "MEQCIBlJPX7t0FDOcozsRK6qIQwik5Fq6mhAtCSSgIB/yQO7AiB9U5lVpdufKvPhk3cz4TH2f5MP7ArnmPRBmhPztpsIFQ==";
  const signatureBytes = Buffer.from(signatureBase64, "base64");

  // Load the message you want to verify
  const message =
    '{"subscriptionId":"00000000-0000-0000-0000-000000000000","notificationId":"00000000-0000-0000-0000-000000000000","notificationType":"webhooks.test","notification":{"hello":"world"},"timestamp":"2024-01-26T18:22:19.779834211Z","version":2}';
  const messageBytes = Buffer.from(message);

  // Verify the signature
  const isSignatureValid = crypto.verify(
    "sha256",
    messageBytes,
    publicKey,
    signatureBytes,
  );

  if (isSignatureValid) {
    console.log("Signature is valid.");
  } else {
    console.log("Signature is invalid.");
  }
  ```

  ```java Java theme={null}
  package com.circle.webhook;

  import java.nio.charset.StandardCharsets;
  import java.security.InvalidKeyException;
  import java.security.KeyFactory;
  import java.security.NoSuchAlgorithmException;
  import java.security.PublicKey;
  import java.security.Signature;
  import java.security.SignatureException;
  import java.security.spec.InvalidKeySpecException;
  import java.security.spec.X509EncodedKeySpec;
  import java.util.Base64;

  public class CircleSignature {
      public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeySpecException, InvalidKeyException, SignatureException {
          // Load the public key from the base64 encoded string
          // Note: The public key is static for a given publicKeyId, therefore we recommend you to cache it
          String publicKeyBase64 = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAESl76SZPBJemW0mJNN4KTvYkLT8bOT4UGhFhzNk3fJqf6iuPlLQLq533FelXwczJbjg2U1PHTvQTK7qOQnDL2Tg==";
          byte[] publicKeyBytes = Base64.getDecoder().decode(publicKeyBase64);
          X509EncodedKeySpec keySpec = new X509EncodedKeySpec(publicKeyBytes);
          KeyFactory keyFactory = KeyFactory.getInstance("EC");
          PublicKey publicKey = keyFactory.generatePublic(keySpec);

          // Load the signature you want to verify
          String signatureBase64 = "MEQCIBlJPX7t0FDOcozsRK6qIQwik5Fq6mhAtCSSgIB/yQO7AiB9U5lVpdufKvPhk3cz4TH2f5MP7ArnmPRBmhPztpsIFQ==";
          byte[] signatureBytes = Base64.getDecoder().decode(signatureBase64);

          // Load the message you want to verify
          String message = "{\"subscriptionId\":\"00000000-0000-0000-0000-000000000000\",\"notificationId\":\"00000000-0000-0000-0000-000000000000\",\"notificationType\":\"webhooks.test\",\"notification\":{\"hello\":\"world\"},\"timestamp\":\"2024-01-26T18:22:19.779834211Z\",\"version\":2}";
          byte[] messageBytes = message.getBytes(StandardCharsets.UTF_8);

          // Verify the signature
          Signature signature = Signature.getInstance("SHA256withECDSA");
          signature.initVerify(publicKey);
          signature.update(messageBytes);

          boolean isSignatureValid = signature.verify(signatureBytes);
          if (isSignatureValid) {
              System.out.println("Signature is valid.");
          } else {
              System.out.println("Signature is invalid.");
          }
      }
  }
  ```
</CodeGroup>

## 5. Confirm IP Accesslist

To ensure the security of your integration, only trust Circle webhook
notifications from the following IP addresses.

* `54.243.112.156`
* `100.24.191.35`
* `54.165.52.248`
* `54.87.106.46`

<Note>
  **Webhook notification handling**

  We enforce a 5 second timeout for your endpoint to respond back to our webhook
  notifications. It is highly recommended that you process notifications outside
  of the response loop and respond back promptly.
</Note>


# Webhook Notifications
Source: https://developers.circle.com/wallets/webhook-notifications-for-wallets

Event model for Circle Wallets, asynchronous processing between Circle and blockchains, delivery guarantees, retries, and how state transitions are communicated.

Circle Wallets uses webhooks to notify your application when wallet-related
events occur. Because blockchain state changes asynchronously, Circle does not
block your API calls until finality. Instead, Circle sends event notifications
to an endpoint you provide so you can react to state transitions (for example, a
deposit confirmed, a transaction failed).

This page describes the event model, how delivery and retries work, and how
state is communicated. For setup and debugging, see
[Set Up Webhooks](/wallets/webhook-notifications) and
[Troubleshoot webhooks](/wallets/webhook-logs). For event types and payloads,
see [Webhook events and payloads](/wallets/webhook-notification-flows).

## Event model

Webhook notifications are HTTP POST requests sent to a subscriber endpoint you
configure. Each notification includes:

* **Subscription and notification identifiers**—Use them to correlate events and
  detect duplicates (the same notification can be retried).
* **Event type**—For example, `transactions.inbound`, so you know what kind of
  state change occurred.
* **Payload**—The resource that changed (for example, transaction object with
  status, amounts, addresses).

You subscribe to the events you care about (for example, inbound transactions,
outbound transactions). When the corresponding state change occurs in Circle's
systems (after blockchain confirmation or failure), Circle sends a notification
to your endpoint.

## Asynchronous processing

Transaction lifecycle is asynchronous: you submit a transaction, and later the
blockchain confirms or rejects it. Circle tracks state and sends you
notifications when it changes. Your app can use these events to update balances,
show history, trigger business logic, or alert users. You do not need to poll;
you react to the events Circle delivers.

## Delivery guarantees and retries

Circle attempts to deliver each notification to your endpoint. If your endpoint
does not respond with a success status (for example, 2xx) in a defined time, or
if the request fails, Circle may retry according to its retry policy. The same
notification can be sent more than once (same notification ID); your endpoint
should be idempotent so duplicate deliveries do not cause incorrect state.

For delivery behavior, retry rules, and how to inspect delivery attempts, see
[Troubleshoot webhooks](/wallets/webhook-logs).

## State transitions

Notifications reflect state transitions: for example, a transaction moves from
queued to confirmed, or from pending to failed. Each event type corresponds to a
transition or a final state. The payload includes the current state of the
resource so you can update your systems. For the full list of transaction flow
events and payload shapes, see
[Webhook events and payloads](/wallets/webhook-notification-flows).


# xReserve Overview
Source: https://developers.circle.com/xreserve



xReserve is an interoperability infrastructure that lets blockchain teams deploy
USDC-backed stablecoins on their own chains. It is powered by programmatic
attestations and Circle-deployed smart contracts that hold USDC in reserve on
source chains such as Ethereum. USDC-backed stablecoins deployed through
xReserve are interoperable with each other and with the broader USDC network.

## Key benefits

xReserve offers a range of benefits for blockchains, developers, and end users:

* **Day 1 liquidity**: Tokens created using xReserve are connected to the
  broader USDC network, allowing users to seamlessly move tokens across
  blockchains.
* **Interoperability**: Users can make 1:1 transfers between USDC-backed
  stablecoins and USDC.
* **Deployed by Circle**: xReserve holds USDC in a smart contract deployed by
  Circle.
* **Minimized trust assumptions**: xReserve attesters verify deposits and burns,
  reducing reliance on third-party services to convert USDC.


# How xReserve Works
Source: https://developers.circle.com/xreserve/concepts/how-xreserve-works



xReserve consists of two main services: an onchain smart contract and an
offchain attestation system. Together, these services and related services on
the remote blockchain let users deposit USDC on the source blockchain to receive
USDC-backed stablecoins on the remote blockchain. Subsequently, users can burn
their USDC-backed stablecoins to withdraw the USDC held in xReserve.

The following diagram shows how xReserve handles deposits and withdrawals.

```mermaid theme={null}
sequenceDiagram
    participant U as User app
    participant X as xReserve smart contract
    participant RL as xReserve attestation service
    participant PB as Remote blockchain token contract
    participant PA as Remote blockchain attestation service

    Note over U,PA: Deposit USDC into xReserve and mint USDC-backed stablecoins
    U->>X: Initiates deposit request
    X->>RL: Emits deposit event
    RL-->>RL: Generates signed deposit attestation
    PA->>RL: Fetches deposit attestation
    RL->>PA: Returns deposit attestation
    PA->>PB: Requests to mint USDC-backed stablecoins
    PB-->>PB: Verifies signature and mints USDC-backed stablecoins
    PB->>PA: Emits mint event
    PB->>U: Deposits USDC-backed stablecoins

    Note over U,PA: Withdraw USDC from xReserve and burn USDC-backed stablecoins
    U->>PB: Initiates withdrawal request
    PB-->>PB: Verifies signature and burns USDC-backed stablecoins
    PB->>PA: Emits burn event
    PA-->>PA: Generates and signs burn intent
    PA->>RL: Submits burn intent and signature
    RL-->>RL: Verifies burn and generates withdrawal attestation
    RL->>X: Releases USDC
    X->>U: Releases USDC
```

## xReserve deposits

These steps occur when a user deposits USDC into xReserve:

1. A user deposits USDC from their wallet app into xReserve smart contract on
   the source blockchain.
2. The xReserve contract emits a deposit event and locks the funds, holding them
   in reserve.
3. The xReserve attestation service generates and signs a deposit attestation.
4. The remote blockchain attestation service fetches the signed deposit
   attestation.
5. The remote blockchain mints USDC-backed stablecoins on their blockchain and
   emits a mint event.
6. The remote blockchain token contract deposits the newly minted USDC-backed
   tokens into the user's wallet app on the remote blockchain.

After completing the deposit process, the user receives an equivalent amount of
USDC-backed stablecoins on the remote blockchain.

## xReserve withdrawals

Subsequently, these steps occur when a user withdraws USDC from xReserve:

1. A user requests to burn USDC-backed stablecoins on the remote blockchain and
   withdraw USDC on the destination blockchain.
2. The remote blockchain token contract burns their USDC-backed stablecoins on
   the remote blockchain and emits a burn event.
3. The remote blockchain attestation service generates and signs a burn intent
   offchain.
4. The remote blockchain attestation service passes the burn intent and
   signature to xReserve.
5. xReserve verifies the burn and issues a withdrawal attestation.
6. xReserve releases USDC to the user's wallet on the destination blockchain.

After completing the withdrawal process, the user receives USDC on the source
blockchain.

<Note>
  **Note:** As part of the same withdrawal, xReserve can
  [forward funds](/xreserve/concepts/technical-guide#withdrawal-forwarding) to
  another blockchain. This lets users withdraw funds on a blockchain other than
  the source blockchain without performing an additional crosschain transfer.
</Note>


# xReserve Technical Guide
Source: https://developers.circle.com/xreserve/concepts/technical-guide



This guide provides a detailed reference for partner blockchains and developers
integrating with xReserve. It defines key terms, onchain message formats, and
the attestation flow used to move tokens across blockchains.

## Domains

Domains are Circle-issued numeric identifiers that map to specific blockchains.
They are used in xReserve messages and attestations.

* **Source domains** use small, 0-indexed integers. They represent blockchains
  where the [USDC reserves](#usdc-reserve) are held in xReserve contracts for
  USDC-backed stablecoins.
* **Remote domains** start at 10001 and represent blockchains where USDC-backed
  stablecoins are issued and circulated.

## Blockchain types

### Source chain

The source chain is the blockchain where the xReserve contract exists and USDC
is deposited and held in reserve.

### Remote chain

The remote chain is the xReserve partner blockchain that issues and circulates
USDC-backed stablecoins on their blockchain after an xReserve deposit is made.

### Destination chain

After a remote chain burns USDC-backed stablecoins on its blockchain, xReserve
releases the associated USDC on the source chain. The blockchain where the user
ultimately withdraws these funds is the destination chain.

There are three ways a user can withdraw these funds:

* **Withdraw USDC on a Gateway supported blockchain**: xReserve holds funds in a
  [Circle Gateway](/gateway) wallet. This lets users convert USDC-backed
  stablecoin into USDC on any
  [Gateway supported blockchain](/gateway/references/supported-blockchains),
  including the source chain, without needing to perform an additional
  crosschain transfer.
* **Withdraw USDC on a CCTP-supported blockchain**: If a user requests to
  withdraw USDC on a non-Gateway supported blockchain, xReserve uses Circle's
  [Cross-Chain Transfer Protocol](/cctp) to forward the funds to a
  [CCTP supported blockchain](/cctp/cctp-supported-blockchains). When preparing
  a [burn intent](#burn-intent), this blockchain is the
  `finalDestinationDomain`.
* **Withdraw USDC-backed stablecoins on another remote blockchain**: Redeposits
  let users move USDC-backed stablecoins from one blockchain to another.
  xReserve releases the USDC reserve for the remote blockchain and redeposits it
  for the destination blockchain. When preparing a burn intent, this blockchain
  is the `finalDestinationDomain`. xReserve updates its onchain and offchain
  ledgers to reflect the change in reserve on the remote and destination
  blockchains.

## Contracts

### xReserve contract

Circle deploys and audits the xReserve contract on source blockchains such as
Ethereum. It holds USDC deposited by users in reserve when USDC-backed
stablecoin is minted on a remote chain, and releases USDC when the corresponding
token is burned and withdrawn.

The full EVM-compatible smart contract source code is
[available on GitHub](https://github.com/circlefin/evm-xreserve-contracts).

### Remote blockchain token contract

The remote blockchain is responsible for deploying, operating, and securing the
smart contract that manages its USDC-backed stablecoins. This contract mints and
burns the token and manages token logic. It also defines the infrastructure and
security for how tokens are handled on its blockchain.

## Tokens

### USDC

[USDC](/stablecoins/what-is-usdc) is issued by Circle on supported blockchains
such as Ethereum. It is fully redeemable for fiat with Circle and serves as the
official, native representation of the USDC stablecoin.

### USDC reserve

USDC reserve represents the USDC held in the xReserve smart contract on the
source chain. xReserve uses [Circle Gateway](/gateway) wallets to hold these
balances for USDC-backed stablecoins on the [remote chain](#remote-chains).

### USDC-backed stablecoins

USDC-backed stablecoins are issued on remote blockchains. These tokens are
backed 1:1 by USDC held in xReserve and interoperable with the broader USDC
network. Each remote blockchain defines its own USDC-backed stablecoins.

## Attesters

An attester is a cryptographic identity represented by a single `secp256k1`
keypair.

xReserve and remote blockchains operate independent attesters, creating a
dual-attestation model that ensures both sides must validate before any funds
move. These attesters have distinct responsibilities:

* **xReserve attesters** are operated by Circle. They monitor USDC deposits into
  the xReserve smart contract on the source blockchain and sign deposit
  attestations. Remote blockchains use these attestations to mint USDC-backed
  tokens on their blockchain.
* **Remote blockchain attesters** are managed by the remote blockchain operator.
  They monitor burns of USDC-backed stablecoins on their blockchain and sign
  burn intents. xReserve verifies these burn intents and uses them to release
  the USDC held in the xReserve contract.

## Deposits

### Deposit intent

`DepositIntent` is a structured onchain message created when a user deposits
USDC into the xReserve smart contract on the source blockchain.

The following table shows the message format:

| Field             | Offset (bytes) | Solidity Type | Length (bytes) | Description                                              |
| ----------------- | -------------- | ------------- | -------------- | -------------------------------------------------------- |
| `magic`           | 0              | `uint32*`     | 4              | 4-byte constant (`0x5a2e0acd`, subject to change)        |
| `version`         | 4              | `uint32`      | 4              | Always `1`                                               |
| `amount`          | 8              | `uint256`     | 32             | Token amount to deposit                                  |
| `remoteDomain`    | 40             | `uint32`      | 4              | Destination domain ID                                    |
| `remoteToken`     | 44             | `bytes32`     | 32             | Token address or identifier on the destination chain     |
| `remoteRecipient` | 76             | `bytes32`     | 32             | Recipient address or identifier on the destination chain |
| `localToken`      | 108            | `address`     | 32             | Source chain token address (left-padded to 32 bytes)     |
| `localDepositor`  | 140            | `address`     | 32             | Source chain depositor address (left-padded to 32 bytes) |
| `maxFee`          | 172            | `uint256`     | 32             | Maximum fee amount to pay on the destination chain       |
| `nonce`           | 204            | `bytes32`     | 32             | 32-byte replay protection nonce                          |
| `hookDataLen`     | 236            | `uint32`      | 4              | Length of `hookData` in bytes                            |
| `hookData`        | 240            | `bytes`       | n              | Optional hook payload                                    |

For how a USDC-backed stablecoin contract on the remote blockchain should handle
this message, see the
[USDC-backed Stablecoin Specification](/xreserve/concepts/usdc-backed-stablecoin-specification).

### Deposit attestation

A deposit attestation is an offchain message signed by
[xReserve attesters](#attesters). It can be used by remote blockchains to
independently mint corresponding USDC-backed stablecoins. xReserve constructs a
deposit attestation in response to receiving a deposit intent.

## Withdrawals

Withdrawals let users redeem USDC-backed stablecoins for USDC held in xReserve.
Users can also withdraw USDC-backed stablecoins on another remote blockchain.
All withdrawals are initiated on the remote blockchain.

<Note>
  **Note**: If you're a remote blockchain partner, you can [initiate a
  withdrawal on behalf of your
  users](/xreserve/tutorials/initiate-a-withdrawal-as-a-remote-blockchain).
</Note>

### Burn intent

A `BurnIntent` is a structured message that the remote blockchain creates when a
user requests to burn USDC-backed stablecoins on their blockchain. It includes
the amount of USDC-backed stablecoins burned and the source blockchain on which
the USDC held in xReserve is released.

For how a USDC-backed stablecoin contract on the remote blockchain should
process the burn data, see the
[USDC-backed Stablecoin Specification](/xreserve/concepts/usdc-backed-stablecoin-specification#burn).

### Message hash and burn intent signature

The message hash is a 32-byte hash of the burn intent payload. It is derived
from the transfer specification, fee settings, and forwarding data. The
[`/prepare-withdrawal`](/api-reference/xreserve/all/prepare-withdrawal) endpoint
returns a `messageHashToSign` for each burn intent.
[Remote blockchain attesters](#attesters) sign that hash with their attester
keys, producing the burn intent signature. This signature proves the burn intent
is valid. xReserve validates the burn intent and signature before releasing the
corresponding [USDC reserve](#usdc-reserve).

### Withdrawal attestation

xReserve issues a withdrawal attestation after validating a burn intent
signature and independently validating that the burn occurred on the remote
blockchain. This attestation is used to release the USDC held in the xReserve
smart contract.

### Withdrawal forwarding

xReserve lets users withdraw funds on a blockchain other than the source chain
without performing an additional crosschain transfer. Because xReserve holds
funds in a [Circle Gateway](/gateway) wallet, users can immediately withdraw
USDC on any
[Gateway supported blockchain](/gateway/references/supported-blockchains). If
the [destination chain](#destination-chain) is not supported by Gateway,
xReserve can forward the funds in one of two ways:

* **CCTP forwarding**: xReserve forwards funds to a
  [CCTP supported blockchain](/cctp/cctp-supported-blockchains), which lets
  users withdraw USDC on that blockchain.
* **Redeposits** : xReserve redeposits funds, which lets users withdraw
  USDC-backed stablecoins on another remote blockchain.

## Security audit

The xReserve smart contract has been independently audited by two third-party
security firms:

* [OtterSec (PDF)](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/Public%20Security%20Audit%20Reports/%5BPUBLIC%5D%20%5BOTTERSEC%5D%20circle_xreserve_audit_final.pdf)
* [ChainSecurity (PDF)](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/Public%20Security%20Audit%20Reports/%5BPUBLIC%5D%20%5BCHAINSECURITY%5D%20ChainSecurity_Circle_CircleXReserve_Audit.pdf)


# USDC-backed Stablecoin Reference Specification
Source: https://developers.circle.com/xreserve/concepts/usdc-backed-stablecoin-specification



This reference spec is for blockchain partners looking to develop and deploy a
USDC-backed stablecoin that integrates with xReserve. It describes the
recommended capabilities your smart contract should have, including the state to
track, the callable functions to expose, and the administrative functions
typically restricted to the contract owner.

This spec is a recommended reference implementation, not a mandatory template.
You should adapt the logic in this spec to your blockchain's smart contract
language and environment, and flag any notable deviations to Circle during
integration so both teams understand them.

<Info>
  View a
  [reference contract](https://github.com/circlefin/evm-xreserve-contracts/blob/master/src/examples/USDCx.sol)
  that mints and burns USDC-backed stablecoins in the
  [Circle xReserve Contracts](https://github.com/circlefin/evm-xreserve-contracts)
  GitHub repository.
</Info>

## Deployment requirements

USDC-backed stablecoins are backed 1:1 by an equivalent amount of USDC held in
Circle's xReserve contract. Your contract mints them after verifying a
[deposit attestation](/xreserve/concepts/technical-guide#deposit-attestation),
and users burn them when they want to withdraw USDC or other USDC-backed
stablecoins on a supported blockchain.

When implementing your USDC-backed stablecoin contract, ensure that you:

* Follow the decimal precision of native USDC, which is 6 decimal places. If
  your blockchain token standard uses a different decimal precision, you must
  handle the decimal conversion in the onchain contract so that it still aligns
  with 6-decimal USDC.
* Use `uint256` for balances and amounts by default. If your runtime forces a
  smaller width such as `uint128` or `uint64`, select the equivalent integer
  type and implement overflow and underflow safeguards for that width.

## State and configuration requirements

The following table lists the variables your token contract should track and the
invariants that must remain true after every call that changes state.

| Variable                                     | Description                                                                                                 | Required Invariant                                                                                                                                  |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uint32 domain`                              | Circle-assigned identifier for your blockchain.                                                             | Value must match the domain ID that Circle assigned to your blockchain. It must be immutable after deployment.                                      |
| `mapping(bytes32 => uint256) balances`       | Tracks balances for each USDC-backed stablecoin account.                                                    | Must be non-negative.                                                                                                                               |
| `mapping(bytes32 => bool) usedNonces`        | Tracks consumed deposit intents (for replay protection).                                                    | Must be `false` before mint and set `true` atomically during mint.                                                                                  |
| `mapping(address => bool) xReserveAttesters` | Allowlist of [xReserve attester](/xreserve/concepts/technical-guide#attesters) addresses (in bytes20 form). | Only the owner can configure this list.                                                                                                             |
| `uint256 minBurnSize`                        | Minimum burn amount for withdrawals.                                                                        | The owner must implement and configure this amount.                                                                                                 |
| `uint256 totalSupply` (optional onchain)     | Aggregate minted minus burned balance.                                                                      | Must equal the sum of all account balances. Can be omitted if the complete USDC-backed token supply is indexed and exposed offchain through an API. |

## Core contract functions

Your USDC-backed stablecoin contract should expose these external functions.

### `mint(bytes depositIntent, bytes depositAttestation, uint256 feeAmount)`

Mints USDC-backed stablecoins after verifying a deposit attestation.

For the canonical `DepositIntent` message format, see the
[Technical Guide](/xreserve/concepts/technical-guide#deposit-intent).

**Preconditions**

The following conditions must be met before you move state or the call will
revert:

* `ECDSA.recover(hash(payload), signature)` must resolve to an address whose
  `bytes20` is `true` in the `xReserveAttesters` allowlist.
* `depositIntent.magic` must be `0x5a2e0acd`.
* `depositIntent.version` must be `1`.
* `depositIntent.amount` must be greater than zero.
* `depositIntent.remoteDomain` must match this USDC-backed stablecoin contract's
  `domain`.
* `depositIntent.remoteToken` must match the identifier for this USDC-backed
  stablecoin contract.
* `depositIntent.localToken` and `depositIntent.localDepositor` must not be zero
  addresses.
* `depositIntent.amount` must be at least `depositIntent.maxFee`.
* `depositIntent.maxFee` must be greater than or equal to the `feeAmount` passed
  in.
* `usedNonces[depositIntent.nonce]` must be `false`.

**State transitions**

When all preconditions are met, state must be updated in this order:

1. Set `usedNonces[depositIntent.nonce]` = `true`.
2. Add `depositIntent.amount - feeAmount` to the recipient's balance.
3. Add `feeAmount` to the relayer's balance if a relayer is present.
4. Increase `totalSupply` by `depositIntent.amount`.

**Postconditions**

After the mint completes, make sure:

* `totalSupply` equals exactly the previous supply + `depositIntent.amount`.
* The sum of balances increased by exactly `depositIntent.amount`.
* Your contract emits a mint event:
  `mint(recipient, relayer, amount, feeAmount, remoteDomain, remoteToken)`.

### `burn(uint256 amount, uint32 destinationDomain, bytes32 destinationRecipient)`

Burns USDC-backed stablecoins so xReserve can release USDC on the destination.

<Tip>
  **Recommendation**: Keep this signature where possible. Using the same parameter
  order and types simplifies downstream integrations that expect this interface.
</Tip>

For information on withdrawals, burn intents, and burn intent signatures, see
the [Technical Guide](/xreserve/concepts/technical-guide#withdrawals).

**Preconditions:**

The following conditions must be met before you move state or the call will
revert:

* `amount` must be greater than zero.
* The caller (`msg.sender`) must hold at least `amount`.
* `amount` must meet or exceed `minBurnSize`.

**State transitions:**

When all preconditions are met, state must be updated in this order:

1. Decrement the caller's balance by `amount`.
2. Decrement `totalSupply` by `amount`.

**Postconditions**

After the mint completes, make sure:

* Your contract emits a burn event:
  `burn(depositor, domain, amount, destinationDomain, destinationRecipient)`.

## Administrative functions

Access to these administrative functions should be restricted to the contract
owner or an equivalent privileged role controlled by your blockchain team.

### `setAttester(bytes32 attester, bool enabled)`

Enables or disables an attester address in the allowlist. Set `enabled` to
`true` to approve an
[xReserve attester](/xreserve/concepts/technical-guide#attesters). Configure
more than one approved attester so xReserve can rotate attester keys without
downtime.

### `setMinBurnSize(uint256 minBurnSize)`

Specifies the minimum amount to burn.


# xReserve Withdrawal Fees
Source: https://developers.circle.com/xreserve/references/fees



Circle collects fees from remote blockchains for withdrawing funds from the
xReserve smart contract.

<Note>
  **Note**: Circle doesn't collect a fee for xReserve deposits. However, users
  can still incur gas fees, and the remote blockchain might charge a fee to
  process the deposit and mint the corresponding USDC-backed stablecoins.
</Note>

## Fee types

The following is a list of fees that can occur, depending on the circumstances
of the xReserve withdrawal:

* **xReserve protocol fee**: Applies to every withdrawal unless the funds are
  withdrawn on the source blockchain.
* **Gateway protocol fee**: Applies if the destination is a Gateway supported
  chain other than the source.
* **CCTP protocol fee**: Applies if the destination is a CCTP supported
  blockchain that is not supported by Gateway.
* **Gas fee**: Covers the onchain gas for the withdrawal transaction.
* **xReserve forwarding fee**: Applies if the remote blockchain opts for Circle
  to forward the attestations on the source or destination blockchain.
* **Forwarding gas fee**: Covers the destination chain gas for the forwarding
  transaction if forwarding the withdrawal.

## Table of fees

The following table shows the fees by destination blockchain.

<Tabs>
  <Tab title="Protocol and gas fees">
    | Destination blockchain | xReserve protocol fee (bps) | Gateway protocol fee (bps) | CCTP protocol fee (bps) | Gas fee (USDC) |
    | ---------------------- | --------------------------- | -------------------------- | ----------------------- | -------------- |
    | Arbitrum               | 1                           | 0.5                        | N/A                     | 2              |
    | Avalanche              | 1                           | 0.5                        | N/A                     | 2              |
    | Base                   | 1                           | 0.5                        | N/A                     | 2              |
    | Codex                  | 1                           | N/A                        | 0-1 (by transfer speed) | 2              |
    | Ethereum               | None                        | N/A                        | N/A                     | 1              |
    | HyperEVM               | 1                           | 0.5                        | N/A                     | 2              |
    | Ink                    | 1                           | N/A                        | 0-1 (by transfer speed) | 2              |
    | Linea                  | 1                           | N/A                        | 0-1 (by transfer speed) | 2              |
    | Monad                  | 1                           | N/A                        | 0-1 (by transfer speed) | 2              |
    | OP                     | 1                           | 0.5                        | N/A                     | 2              |
    | Plume                  | 1                           | N/A                        | 0-1 (by transfer speed) | 2              |
    | Polygon PoS            | 1                           | 0.5                        | N/A                     | 2              |
    | Sei                    | 1                           | 0.5                        | N/A                     | 2              |
    | Solana                 | 1                           | N/A                        | 0-1 (by transfer speed) | 2              |
    | Sonic                  | 1                           | 0.5                        | N/A                     | 2              |
    | Unichain               | 1                           | 0.5                        | N/A                     | 2              |
    | World Chain            | 1                           | 0.5                        | N/A                     | 2              |
    | XDC                    | 1                           | N/A                        | 0-1 (by transfer speed) | 2              |
  </Tab>

  <Tab title="Forwarding fees">
    | Destination blockchain | xReserve forwarding fee (USDC) | Forwarding gas fee (USDC) |
    | ---------------------- | ------------------------------ | ------------------------- |
    | Arbitrum               | \$0.20                         | \$0.01                    |
    | Avalanche              | \$0.20                         | \$0.02                    |
    | Base                   | \$0.20                         | \$0.01                    |
    | Codex                  | \$1.45                         | \$0.50 + destination gas  |
    | Ethereum               | \$0.20                         | \$0.80                    |
    | HyperEVM               | \$0.20                         | \$0.05                    |
    | Ink                    | \$1.45                         | \$0.50 + destination gas  |
    | Linea                  | \$1.45                         | \$0.50 + destination gas  |
    | Monad                  | \$1.45                         | \$0.50 + destination gas  |
    | OP                     | \$0.20                         | \$0.0015                  |
    | Plume                  | \$1.45                         | \$0.50 + destination gas  |
    | Polygon PoS            | \$0.20                         | \$0.0015                  |
    | Sei                    | \$0.20                         | \$0.001                   |
    | Solana                 | \$1.45                         | \$0.50 + destination gas  |
    | Sonic                  | \$0.20                         | \$0.01                    |
    | Unichain               | \$0.20                         | \$0.001                   |
    | World Chain            | \$0.20                         | \$0.01                    |
    | XDC                    | \$1.45                         | \$0.50 + destination gas  |
  </Tab>
</Tabs>


# xReserve Supported Blockchains and Domains
Source: https://developers.circle.com/xreserve/references/supported-blockchains-and-domains



## Supported blockchains

xReserve operates across multiple blockchains. Each supported blockchain serves
one or more of the following roles:

* **Source chains** where Circle-deployed xReserve smart contracts hold
  [USDC reserves](/xreserve/concepts/technical-guide#usdc-reserve).
* **Remote chains** where USDC-backed stablecoins are issued.
* **Destination chains** where USDC or USDC-backed stablecoins are ultimately
  withdrawn.

### Source chains

The following tables list the mainnet and testnet blockchains where xReserve
smart contracts have been deployed. Users deposit USDC into these contracts to
receive an equal amount of USDC-backed stablecoins on remote blockchains.

**Mainnet**

| Blockchain | USDC token address                                                                                                    | xReserve contract address                                                                                             |
| ---------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Ethereum   | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48) | [0x8888888199b2Df864bf678259607d6D5EBb4e3Ce](https://etherscan.io/address/0x8888888199b2Df864bf678259607d6D5EBb4e3Ce) |

**Testnet**

| Blockchain       | USDC token address                                                                                                            | xReserve contract address                                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Arc Testnet      | [`0x3600000000000000000000000000000000000000`](https://testnet.arcscan.app/token/0x3600000000000000000000000000000000000000)  | [0x008888878f94C0d87defdf0B07f46B93C1934442](https://testnet.arcscan.app/address/0x008888878f94C0d87defdf0B07f46B93C1934442)  |
| Ethereum Sepolia | [`0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238`](https://sepolia.etherscan.io/token/0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238) | [0x008888878f94C0d87defdf0B07f46B93C1934442](https://sepolia.etherscan.io/address/0x008888878f94C0d87defdf0B07f46B93C1934442) |

### Remote chains

The following tables list the mainnet and testnet xReserve partner blockchains
where USDC-backed stablecoins can be minted.

**Mainnet**

| Blockchain | Token symbol | Token address or identifier                                                                                                                                                                                                                                                                                                                                                           |
| ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Aleo       | USDCx        | [`usdcx_stablecoin.aleo`](https://explorer.provable.com/program/usdcx_stablecoin.aleo)                                                                                                                                                                                                                                                                                                |
| Canton     | USDCx        | `InstrumentId.id`: `USDCx` <br /> `InstrumentId.admin`: [`decentralized-usdc-interchain-rep::12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef`](https://api.utilities.digitalasset.com/api/token-standard/v0/registrars/decentralized-usdc-interchain-rep::12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef/registry/metadata/v1/instruments) |
| Cardano    | USDCx        | [`1f3aec8bfe7ea4fe14c5f121e2a92e301afe414147860d557cac7e345553444378`](https://cardanoscan.io/token/1f3aec8bfe7ea4fe14c5f121e2a92e301afe414147860d557cac7e345553444378)                                                                                                                                                                                                               |
| Movement   | USDCx        | [`0xba11833544a2f99eec743f41a228ca6ffa7f13c3b6b04681d5a79a8b75ff225e`](https://explorer.movementnetwork.xyz/fungible_asset/0xba11833544a2f99eec743f41a228ca6ffa7f13c3b6b04681d5a79a8b75ff225e?network=mainnet)                                                                                                                                                                        |
| Stacks     | USDCx        | [`SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx`](https://explorer.hiro.so/txid/SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx?chain=mainnet)                                                                                                                                                                                                                                      |

**Testnet**

| Blockchain       | Token symbol | Token address or identifier                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Aleo Testnet     | USDCx        | [`test_usdcx_stablecoin.aleo`](https://testnet.explorer.provable.com/program/test_usdcx_stablecoin.aleo)                                                                                                                                                                                                                                                                                      |
| Canton TestNet   | USDCx        | `InstrumentId.id`: `USDCx` <br /> `InstrumentId.admin`: [`decentralized-usdc-interchain-rep::122049e2af8a725bd19759320fc83c638e7718973eac189d8f201309c512d1ffec61`](https://api.utilities.digitalasset-staging.com/api/token-standard/v0/registrars/decentralized-usdc-interchain-rep::122049e2af8a725bd19759320fc83c638e7718973eac189d8f201309c512d1ffec61/registry/metadata/v1/instruments) |
| Cardano Preprod  | USDCx        | [`31dde3db98ad05feb688d4dbb146b3b6054e1246cbcef98c79b0bf665553444378`](https://preprod.cardanoscan.io/token/31dde3db98ad05feb688d4dbb146b3b6054e1246cbcef98c79b0bf665553444378)                                                                                                                                                                                                               |
| Movement Bardock | USDCx        | [`0x63f169ba69623ba6ccf34620857644feb46d0f87e1d7bbcf8c071d30c3d94bd6`](https://explorer.movementnetwork.xyz/fungible_asset/0x63f169ba69623ba6ccf34620857644feb46d0f87e1d7bbcf8c071d30c3d94bd6?network=bardock+testnet)                                                                                                                                                                        |
| Stacks Testnet   | USDCx        | [`ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx`](https://explorer.hiro.so/txid/ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx?chain=testnet)                                                                                                                                                                                                                                              |

### Destination chains

These are the destination blockchains where USDC or USDC-backed stablecoins are
ultimately withdrawn:

* [Gateway supported blockchains](/gateway/references/supported-blockchains):
  Because xReserve holds USDC in Gateway wallets, users can withdraw USDC on any
  Gateway supported blockchain, including the source chain.
* [CCTP supported blockchains](/cctp/cctp-supported-blockchains): If a
  blockchain is not supported by Gateway, xReserve uses CCTP to forward the
  funds to another blockchain. This lets users withdraw USDC on any CCTP
  supported blockchain.
* Another [remote blockchain](#remote-chains): Users can burn USDC-backed
  stablecoins on one remote blockchain to withdraw USDC-backed stablecoins on a
  different remote blockchain.

## Domain identifiers

A domain is a Circle-issued numeric identifier for a blockchain. xReserve uses
domain identifiers in messages and attestations. Domain identifiers don't map to
any existing public chain ID.

xReserve domains fall into two categories:

* **Source domains** are the blockchains on which USDC is held in an xReserve
  contract.
* **Remote domains** are the blockchains on which USDC-backed stablecoins are
  deployed, minted, and circulated.

<Tip>
  Use the [Get domain information](/api-reference/xreserve/all/get-info)
  endpoint to retrieve a list of all source and remote domains.
</Tip>

### Source domains

| Domain | Name        |
| ------ | ----------- |
| 0      | Ethereum    |
| 26     | Arc Testnet |

### Remote domains

| Domain | Name     |
| ------ | -------- |
| 10001  | Canton   |
| 10002  | Aleo     |
| 10003  | Stacks   |
| 10004  | Cardano  |
| 10005  | Movement |


# Quickstart: Deposit USDC into xReserve
Source: https://developers.circle.com/xreserve/tutorials/deposit-usdc-into-xreserve

Learn how to deposit USDC into xReserve on Ethereum Sepolia.

This quickstart is for developers who want to integrate xReserve into their
apps. It helps you write a TypeScript script that deposits USDC into xReserve on
Ethereum Sepolia. Your recipient wallet will receive USDC-backed stablecoins on
the remote blockchain when that network supports automatic settlement.

<Tip>
  Need to transfer USDC from another chain first? Use Arc App Kit's
  [Bridge](https://docs.arc.io/app-kit/bridge) capability to move testnet funds to
  Ethereum Sepolia before making an xReserve deposit.
</Tip>

Select the tab below to view the steps for your blockchain.

<Tabs>
  <Tab title="Aleo">
    <Note>
      This quickstart covers the deposit into xReserve on Ethereum Sepolia. After
      the deposit confirms, Aleo requires you to mint USDCx before it appears in the
      recipient wallet. For details, see the official [Aleo
      documentation](https://developer.aleo.org/guides/introduction/getting_started/)
    </Note>

    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/).

    * Created an Ethereum Sepolia wallet and an Aleo Testnet wallet and funded them
      with testnet tokens.

      <Accordion title="Need a wallet or testnet tokens?">
        * Use a wallet provider such as [MetaMask](https://metamask.io/) for your Ethereum Sepolia wallet.
        * Use [Shield](https://aleo.org/shield/) for your Aleo Testnet wallet.
        * Get Testnet USDC from the [Circle Faucet](https://faucet.circle.com/).
        * Get Testnet ETH from a public [Ethereum Sepolia faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia).
      </Accordion>

    * Installed the required dependencies:
      * `viem` - A TypeScript library that interfaces with Ethereum.
      * `@provablehq/sdk` - Official Aleo SDK for address encoding.

    ## Step 1: Set up your project

    This step shows you how to set up a fresh Node.js workspace, install
    dependencies, configure your environment variables, and prepare your Ethereum
    Sepolia wallet.

    ### 1.1. Set up your development environment

    Create a new directory and install dependencies:

    ```bash Shell theme={null}
    # Set up your directory and initialize the project
    mkdir xreserve-aleo-usdcx
    cd xreserve-aleo-usdcx
    npm init -y

    # Install tools and dependencies
    npm install viem dotenv @provablehq/sdk
    ```

    ### 1.2. Configure environment variables

    Create a `.env` file in the project directory and add your wallet private key
    and the recipient address on Aleo.

    <Info>
      If you use MetaMask, follow their guide for how to [find and export your
      private
      key](https://support.metamask.io/configure/accounts/how-to-export-an-accounts-private-key/).
    </Info>

    ```bash Shell theme={null}
    cat > .env << EOF
    PRIVATE_KEY=<your_ethereum_wallet_private_key>
    ALEO_RECIPIENT=<your_aleo_recipient_testnet_address>
    EOF
    ```

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Set up your script

    This step shows you how to build the script by importing its dependencies and
    defining the configuration constants and ABI fragments that the script uses.

    ### 2.1. Import dependencies

    Create a file called `index.ts` and add the following code to import the
    dependencies:

    ```typescript index.ts theme={null}
    import "dotenv/config";
    import {
      createWalletClient,
      createPublicClient,
      http,
      parseUnits,
      toHex,
      pad,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { sepolia } from "viem/chains";
    import { Address } from "@provablehq/sdk";
    ```

    ### 2.2. Define configuration constants

    Add the following code snippet to your `index.ts` file. It specifies the RPC and
    wallet private key, contract addresses, and Aleo-specific parameters that the
    rest of the script relies on. The `ALEO_RECIPIENT` is loaded from your `.env`
    file.

    <Info>
      You can review the [xReserve EVM
      contracts](https://github.com/circlefin/evm-xreserve-contracts) on GitHub.
    </Info>

    ```typescript index.ts theme={null}
    // ============ Configuration constants ============
    const config = {
      // Public Ethereum Sepolia RPC and your private wallet key
      ETH_RPC_URL: process.env.RPC_URL || "https://ethereum-sepolia.publicnode.com",
      PRIVATE_KEY: process.env.PRIVATE_KEY as `0x${string}`,

      // Contract addresses on Ethereum Sepolia testnet
      X_RESERVE_CONTRACT:
        "0x008888878f94C0d87defdf0B07f46B93C1934442" as `0x${string}`,
      SEPOLIA_USDC_CONTRACT:
        "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as `0x${string}`,

      // Deposit parameters for Aleo
      ALEO_DOMAIN: 10002, // Aleo domain ID
      ALEO_RECIPIENT: process.env.ALEO_RECIPIENT || "", // Shield wallet address to receive USDCx on Aleo
      DEPOSIT_AMOUNT: "5.00",
      MAX_FEE: "0",
    };
    ```

    ### 2.3. Set up contract ABIs

    Add the following code snippet to your `index.ts` file. It adds xReserve and
    ERC-20 ABI fragments which tell `viem` how to format and send the contract calls
    when the script runs.

    <Info>
      For more background on contract ABIs, see QuickNode's guide, [What is an
      ABI?](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi).
    </Info>

    ```typescript index.ts theme={null}
    // ============ Contract ABIs ============
    const X_RESERVE_ABI = [
      {
        name: "depositToRemote",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "value", type: "uint256" },
          { name: "remoteDomain", type: "uint32" },
          { name: "remoteRecipient", type: "bytes32" },
          { name: "localToken", type: "address" },
          { name: "maxFee", type: "uint256" },
          { name: "hookData", type: "bytes" },
        ],
        outputs: [],
      },
    ] as const;

    const ERC20_ABI = [
      {
        name: "approve",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "spender", type: "address" },
          { name: "amount", type: "uint256" },
        ],
        outputs: [{ name: "success", type: "bool" }],
      },
      {
        name: "balanceOf",
        type: "function",
        stateMutability: "view",
        inputs: [{ name: "account", type: "address" }],
        outputs: [{ name: "balance", type: "uint256" }],
      },
    ] as const;
    ```

    ## Step 3: Execute the deposit

    This step shows you how to implement the `main()` function which performs the
    deposit of USDC from your Ethereum Sepolia wallet into the xReserve contract.
    The xReserve contract mints an equivalent amount of USDCx on Aleo Testnet and
    sends it to your recipient wallet.

    ### 3.1. Implement the main function

    Add the following code snippet to your `index.ts` file. It implements the
    `main()` function which uses viem to read balances, approve a USDC spend, call
    the xReserve deposit function, and console.log the transaction results.

    Aleo uses bech32m-encoded addresses and little-endian byte ordering for field
    elements. The script uses the Aleo SDK's `Address.toBytesLe()` method to
    properly convert the address to a 32-byte field element, then uses viem
    `toHex()` and `pad()` utilities to format it as a bytes32 hex string. The
    resulting field element is used for both `remoteRecipient` and `hookData`.

    ```typescript index.ts theme={null}
    // ============ Main function ============
    async function main() {
      if (!config.PRIVATE_KEY) {
        throw new Error("PRIVATE_KEY must be set in your .env file");
      }

      if (!config.ALEO_RECIPIENT) {
        throw new Error("ALEO_RECIPIENT must be set in your .env file");
      }

      // Set up wallet and wallet provider
      const account = privateKeyToAccount(config.PRIVATE_KEY);
      const client = createWalletClient({
        account,
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      const publicClient = createPublicClient({
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      console.log(`Ethereum wallet address: ${account.address}`);

      // Check native ETH balance
      const nativeBalance = await publicClient.getBalance({
        address: account.address,
      });
      console.log(
        `Native balance: ${nativeBalance.toString()} wei (${(
          Number(nativeBalance) / 1e18
        ).toFixed(6)} ETH)`,
      );
      if (nativeBalance === 0n)
        throw new Error("Insufficient native balance for gas fees");

      // Prepare deposit params (USDC has 6 decimals)
      const value = parseUnits(config.DEPOSIT_AMOUNT, 6);
      const maxFee = parseUnits(config.MAX_FEE, 6);

      // Convert Aleo address to bytes using the Aleo SDK
      const aleoAddress = Address.from_string(config.ALEO_RECIPIENT);
      const fieldElementBytes = aleoAddress.toBytesLe();

      if (fieldElementBytes.length !== 32) {
        throw new Error(
          `Invalid Aleo address: expected 32 bytes, got ${fieldElementBytes.length}`,
        );
      }

      // Use field element bytes (little-endian) for both remoteRecipient and hookData
      const remoteRecipientBytes32 = toHex(
        pad(fieldElementBytes, { size: 32 }),
      ) as `0x${string}`;
      const hookData = remoteRecipientBytes32;

      console.log(
        `\nDepositing ${config.DEPOSIT_AMOUNT} USDC to Aleo recipient: ${config.ALEO_RECIPIENT}`,
      );
      console.log(`Aleo field element (little-endian): ${remoteRecipientBytes32}`);

      // Check token balance
      const usdcBalance = await publicClient.readContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "balanceOf",
        args: [account.address],
      });
      console.log(
        `USDC balance: ${usdcBalance.toString()} (${(
          Number(usdcBalance) / 1e6
        ).toFixed(6)} USDC)`,
      );
      if (usdcBalance < value) {
        throw new Error(
          `Insufficient USDC balance. Required: ${(Number(value) / 1e6).toFixed(
            6,
          )} USDC`,
        );
      }

      // Approve xReserve to spend USDC
      const approveTxHash = await client.writeContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "approve",
        args: [config.X_RESERVE_CONTRACT, value],
      });
      console.log("Approval tx hash:", approveTxHash);
      console.log("Waiting for approval confirmation...");

      await publicClient.waitForTransactionReceipt({ hash: approveTxHash });
      console.log("✅ Approval confirmed");

      // Deposit transaction
      const depositTxHash = await client.writeContract({
        address: config.X_RESERVE_CONTRACT,
        abi: X_RESERVE_ABI,
        functionName: "depositToRemote",
        args: [
          value,
          config.ALEO_DOMAIN,
          remoteRecipientBytes32,
          config.SEPOLIA_USDC_CONTRACT,
          maxFee,
          hookData,
        ],
      });

      console.log("Deposit tx hash:", depositTxHash);
      console.log(
        "✅ Transaction submitted. You can track this on Sepolia Etherscan.",
      );
    }

    // ============ Call the main function ============
    main().catch((error) => {
      console.error("❌ Error:", error);
      process.exit(1);
    });
    ```

    This step finalizes the transfer, depositing USDC into xReserve on Ethereum
    Sepolia to make USDCx available on Aleo Testnet.

    ### 3.2. Run the script

    Execute the script in your terminal:

    ```bash Shell theme={null}
    npx tsx index.ts
    ```

    ### 3.3. Verify the deposit

    After the script finishes, find the `Deposit tx hash` in the terminal output and
    paste it into [Sepolia Etherscan](https://sepolia.etherscan.io) to confirm your
    deposit transaction was successful.

    After the deposit confirms, Aleo requires you to mint USDCx before it appears in
    the recipient wallet. For details, see the official
    [Aleo documentation](https://developer.aleo.org/guides/introduction/getting_started/).
  </Tab>

  <Tab title="Canton">
    <Note>
      Canton requires additional setup before USDCx can be minted to the recipient
      wallet. For details, see the official
      [Canton documentation](https://docs.digitalasset.com/usdc/xreserve/index.html).
    </Note>

    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/).

    * Created an Ethereum Sepolia wallet and a Canton TestNet wallet and funded them
      with testnet tokens.

      <Accordion title="Need a wallet or testnet tokens?">
        * Use a wallet provider such as [MetaMask](https://metamask.io/) for your Ethereum Sepolia wallet.
        * Use [Console Wallet](https://consolewallet.io/) or [Bron](https://www.canton.network/ecosystem/bron) for your Canton TestNet wallet.
        * Get Testnet USDC from the [Circle Faucet](https://faucet.circle.com/).
        * Get Testnet ETH from a public [Ethereum Sepolia faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia).
      </Accordion>

    * Installed the required dependencies:
      * `viem` - A TypeScript library that interfaces with Ethereum.

    ## Step 1: Set up your project

    This step shows you how to set up a fresh Node.js workspace, install
    dependencies, configure your environment variables, and prepare your Ethereum
    Sepolia wallet.

    ### 1.1. Set up your development environment

    Create a new directory and install dependencies:

    ```bash Shell theme={null}
    # Set up your directory and initialize the project
    mkdir xreserve-canton-usdcx
    cd xreserve-canton-usdcx
    npm init -y

    # Install tools and dependencies
    npm install viem dotenv
    ```

    ### 1.2. Configure environment variables

    Create a `.env` file in the project directory and add your wallet private key
    and the recipient address on Canton.

    <Info>
      If you use MetaMask, follow their guide for how to [find and export your
      private
      key](https://support.metamask.io/configure/accounts/how-to-export-an-accounts-private-key/).
    </Info>

    ```bash Shell theme={null}
    cat > .env << EOF
    PRIVATE_KEY=<your_ethereum_wallet_private_key>
    CANTON_RECIPIENT=<your_canton_recipient_testnet_address>
    EOF
    ```

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Set up your script

    This step shows you how to build the script by importing its dependencies and
    defining the configuration constants and ABI fragments that the script uses.

    ### 2.1. Import dependencies

    Create a file called `index.ts` and add the following code to import the
    dependencies:

    ```typescript index.ts theme={null}
    import "dotenv/config";
    import {
      createWalletClient,
      createPublicClient,
      http,
      parseUnits,
      keccak256,
    } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { sepolia } from "viem/chains";
    ```

    ### 2.2. Define configuration constants

    Add the following code snippet to your `index.ts` file. It specifies the RPC and
    wallet private key, contract addresses, and Canton-specific parameters that the
    rest of the script relies on. The `CANTON_RECIPIENT` is loaded from your `.env`
    file.

    <Info>
      You can review the [xReserve EVM
      contracts](https://github.com/circlefin/evm-xreserve-contracts) on GitHub.
    </Info>

    ```typescript index.ts theme={null}
    // ============ Configuration constants ============
    const config = {
      // Public Ethereum Sepolia RPC and your private wallet key
      ETH_RPC_URL: process.env.RPC_URL || "https://ethereum-sepolia.publicnode.com",
      PRIVATE_KEY: process.env.PRIVATE_KEY as `0x${string}`,

      // Contract addresses on Ethereum Sepolia testnet
      X_RESERVE_CONTRACT:
        "0x008888878f94C0d87defdf0B07f46B93C1934442" as `0x${string}`,
      SEPOLIA_USDC_CONTRACT:
        "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as `0x${string}`,

      // Deposit parameters for Canton
      CANTON_DOMAIN: 10001, // Canton domain ID
      CANTON_RECIPIENT: process.env.CANTON_RECIPIENT || "", // Address to receive USDCx on Canton
      DEPOSIT_AMOUNT: "5.00",
      MAX_FEE: "0",
    };
    ```

    ### 2.3. Set up contract ABIs

    Add the following code snippet to your `index.ts` file. It adds xReserve and
    ERC-20 ABI fragments which tell `viem` how to format and send the contract calls
    when the script runs.

    <Info>
      For more background on contract ABIs, see QuickNode's guide, [What is an
      ABI?](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi).
    </Info>

    ```typescript index.ts theme={null}
    // ============ Contract ABIs ============
    const X_RESERVE_ABI = [
      {
        name: "depositToRemote",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "value", type: "uint256" },
          { name: "remoteDomain", type: "uint32" },
          { name: "remoteRecipient", type: "bytes32" },
          { name: "localToken", type: "address" },
          { name: "maxFee", type: "uint256" },
          { name: "hookData", type: "bytes" },
        ],
        outputs: [],
      },
    ] as const;

    const ERC20_ABI = [
      {
        name: "approve",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "spender", type: "address" },
          { name: "amount", type: "uint256" },
        ],
        outputs: [{ name: "success", type: "bool" }],
      },
      {
        name: "balanceOf",
        type: "function",
        stateMutability: "view",
        inputs: [{ name: "account", type: "address" }],
        outputs: [{ name: "balance", type: "uint256" }],
      },
    ] as const;
    ```

    ## Step 3: Execute the xReserve deposit

    This step shows you how to implement the main logic that checks balances,
    approves USDC, and calls xReserve on Ethereum Sepolia so Canton TestNet can mint
    the corresponding USDCx.

    ### 3.1. Add the main function

    Add the following code snippet to your `index.ts` file. This code flows through
    the following actions:

    * Verifies that `PRIVATE_KEY` is present before continuing.
    * Creates an Ethereum Sepolia wallet client and logs the originating address.
    * Checks native ETH balance to ensure there is enough gas for transactions.
    * Computes the deposit value, maximum fee, and recipient payload (USDC uses 6
      decimals).
    * Confirms that the wallet's USDC balance covers the configured deposit amount.
    * Approves the xReserve smart contract to spend USDC on the wallet's behalf.
    * Calls `depositToRemote` to submit the deposit and tell Canton to mint USDCx
      for the wallet specified as the `CANTON_RECIPIENT`.

    Canton uses a keccak256 hash of the recipient address for the `remoteRecipient`
    parameter. The original address is encoded as hex for `hookData`.

    ```typescript index.ts theme={null}
    // ============ Main function ============
    async function main() {
      if (!config.PRIVATE_KEY) {
        throw new Error("PRIVATE_KEY must be set in your .env file");
      }

      if (!config.CANTON_RECIPIENT) {
        throw new Error("CANTON_RECIPIENT must be set in your .env file");
      }

      // Set up wallet and wallet provider
      const account = privateKeyToAccount(config.PRIVATE_KEY);
      const client = createWalletClient({
        account,
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      const publicClient = createPublicClient({
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      console.log(`Ethereum wallet address: ${account.address}`);

      // Check native ETH balance
      const nativeBalance = await publicClient.getBalance({
        address: account.address,
      });
      console.log(
        `Native balance: ${nativeBalance.toString()} wei (${(
          Number(nativeBalance) / 1e18
        ).toFixed(6)} ETH)`,
      );
      if (nativeBalance === 0n)
        throw new Error("Insufficient native balance for gas fees");

      // Prepare deposit params (USDC has 6 decimals)
      const value = parseUnits(config.DEPOSIT_AMOUNT, 6);
      const maxFee = parseUnits(config.MAX_FEE, 6);
      const encoder = new TextEncoder();
      const recipientBytes = encoder.encode(config.CANTON_RECIPIENT);
      const remoteRecipientBytes32 = keccak256(recipientBytes);
      const hookData = ("0x" +
        Buffer.from(recipientBytes).toString("hex")) as `0x${string}`;

      console.log(
        `\nDepositing ${config.DEPOSIT_AMOUNT} USDC to Canton recipient: ${config.CANTON_RECIPIENT}`,
      );

      // Check token balance
      const usdcBalance = await publicClient.readContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "balanceOf",
        args: [account.address],
      });
      console.log(
        `USDC balance: ${usdcBalance.toString()} (${(
          Number(usdcBalance) / 1e6
        ).toFixed(6)} USDC)`,
      );
      if (usdcBalance < value) {
        throw new Error(
          `Insufficient USDC balance. Required: ${(Number(value) / 1e6).toFixed(
            6,
          )} USDC`,
        );
      }

      // Approve xReserve to spend USDC
      const approveTxHash = await client.writeContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "approve",
        args: [config.X_RESERVE_CONTRACT, value],
      });
      console.log("Approval tx hash:", approveTxHash);
      console.log("Waiting for approval confirmation...");

      await publicClient.waitForTransactionReceipt({ hash: approveTxHash });
      console.log("✅ Approval confirmed");

      // Deposit transaction
      const depositTxHash = await client.writeContract({
        address: config.X_RESERVE_CONTRACT,
        abi: X_RESERVE_ABI,
        functionName: "depositToRemote",
        args: [
          value,
          config.CANTON_DOMAIN,
          remoteRecipientBytes32,
          config.SEPOLIA_USDC_CONTRACT,
          maxFee,
          hookData,
        ],
      });

      console.log("Deposit tx hash:", depositTxHash);
      console.log(
        "✅ Transaction submitted. You can track this on Sepolia Etherscan.",
      );
    }

    // ============ Call the main function ============
    main().catch((error) => {
      console.error("❌ Error:", error);
      process.exit(1);
    });
    ```

    This step finalizes the transfer, depositing USDC into xReserve on Ethereum
    Sepolia to make USDCx available on Canton TestNet.

    ### 3.2. Run the script

    Execute the script in your terminal:

    ```bash Terminal theme={null}
    npx tsx index.ts
    ```

    ### 3.3. Verify the deposit

    After the script finishes, find the `Deposit tx hash` in the terminal output and
    paste it into [Sepolia Etherscan](https://sepolia.etherscan.io) to confirm your
    deposit transaction was successful.

    If you've completed the required Canton setup, the recipient wallet will receive
    the minted testnet USDCx . For details, see the official
    [Canton documentation](https://docs.digitalasset.com/usdc/xreserve/index.html).
  </Tab>

  <Tab title="Cardano">
    ## Prerequisites

    Before you begin, ensure you've:

    * Installed [Node.js v22+](https://nodejs.org/).

    * Created an Ethereum Sepolia wallet and a Cardano Preprod wallet and funded
      them with testnet tokens.

      <Accordion title="Need a wallet or testnet tokens?">
        * Use a wallet provider such as [MetaMask](https://metamask.io/) for your Ethereum Sepolia wallet.
        * Use [Eternl](https://eternl.io/) or [Lace](https://www.lace.io/) for your Cardano Preprod wallet.
        * Get Testnet USDC from the [Circle Faucet](https://faucet.circle.com/).
        * Get Testnet ETH from a public [Ethereum Sepolia faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia).
      </Accordion>

    * Installed the required dependencies:
      * `viem` - A TypeScript library that interfaces with Ethereum.
      * `@scure/base` - For bech32 decoding of Cardano addresses.

    ## Step 1: Set up your project

    This step shows you how to set up a fresh Node.js workspace, install
    dependencies, configure your environment variables, and prepare your Ethereum
    Sepolia wallet.

    ### 1.1. Set up your development environment

    Create a new directory and install dependencies:

    ```bash Shell theme={null}
    # Set up your directory and initialize the project
    mkdir xreserve-cardano-usdcx
    cd xreserve-cardano-usdcx
    npm init -y

    # Install tools and dependencies
    npm install viem dotenv @scure/base
    ```

    ### 1.2. Configure environment variables

    Create a `.env` file in the project directory and add your wallet private key
    and the recipient address on Cardano Preprod. Use a valid Cardano bech32
    address.

    <Info>
      If you use MetaMask, follow their guide for how to [find and export your
      private
      key](https://support.metamask.io/configure/accounts/how-to-export-an-accounts-private-key/).
    </Info>

    ```bash Shell theme={null}
    cat > .env << EOF
    PRIVATE_KEY=<your_ethereum_wallet_private_key>
    CARDANO_RECIPIENT=<your_cardano_preprod_recipient_address>
    EOF
    ```

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Set up your script

    This step shows you how to build the script by importing its dependencies and
    defining the configuration constants and ABI fragments that the script uses.

    ### 2.1. Import dependencies

    Create a file called `index.ts` and add the following code to import the
    dependencies:

    ```typescript index.ts theme={null}
    import "dotenv/config";
    import { createWalletClient, createPublicClient, http, parseUnits } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { sepolia } from "viem/chains";
    import { bech32 } from "@scure/base";
    ```

    ### 2.2. Define configuration constants

    Add the following code snippet to your `index.ts` file. It specifies the RPC and
    wallet private key, contract addresses, and Cardano-specific parameters that the
    rest of the script relies on. The `CARDANO_RECIPIENT` is loaded from your `.env`
    file.

    <Info>
      You can review the [xReserve EVM
      contracts](https://github.com/circlefin/evm-xreserve-contracts) on GitHub.
    </Info>

    ```typescript index.ts theme={null}
    // ============ Configuration constants ============
    const config = {
      // Public Ethereum Sepolia RPC and your private wallet key
      ETH_RPC_URL: process.env.RPC_URL || "https://ethereum-sepolia.publicnode.com",
      PRIVATE_KEY: process.env.PRIVATE_KEY as `0x${string}`,

      // Contract addresses on Ethereum Sepolia testnet
      X_RESERVE_CONTRACT:
        "0x008888878f94C0d87defdf0B07f46B93C1934442" as `0x${string}`,
      SEPOLIA_USDC_CONTRACT:
        "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as `0x${string}`,

      // Deposit parameters for Cardano Preprod (works on testnet and mainnet)
      CARDANO_DOMAIN: 10004, // Cardano domain ID
      CARDANO_RECIPIENT: process.env.CARDANO_RECIPIENT || "", // Address to receive USDCx on Cardano Preprod
      DEPOSIT_AMOUNT: "20.00",
      MAX_FEE: "10.00",
    };
    ```

    ### 2.3. Set up contract ABIs

    Add the following code snippet to your `index.ts` file. It adds xReserve and
    ERC-20 ABI fragments which tell `viem` how to format and send the contract calls
    when the script runs.

    <Info>
      For more background on contract ABIs, see QuickNode's guide, [What is an
      ABI?](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi).
    </Info>

    ```typescript index.ts theme={null}
    // ============ Contract ABIs ============
    const X_RESERVE_ABI = [
      {
        name: "depositToRemote",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "value", type: "uint256" },
          { name: "remoteDomain", type: "uint32" },
          { name: "remoteRecipient", type: "bytes32" },
          { name: "localToken", type: "address" },
          { name: "maxFee", type: "uint256" },
          { name: "hookData", type: "bytes" },
        ],
        outputs: [],
      },
    ] as const;

    const ERC20_ABI = [
      {
        name: "approve",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "spender", type: "address" },
          { name: "amount", type: "uint256" },
        ],
        outputs: [{ name: "success", type: "bool" }],
      },
      {
        name: "balanceOf",
        type: "function",
        stateMutability: "view",
        inputs: [{ name: "account", type: "address" }],
        outputs: [{ name: "balance", type: "uint256" }],
      },
    ] as const;
    ```

    ## Step 3: Execute the xReserve deposit

    This step shows you how to implement the main logic that checks balances,
    approves USDC, and calls xReserve on Ethereum Sepolia so Cardano Preprod can
    mint the corresponding USDCx.

    ### 3.1. Add the main function

    Add the following code snippet to your `index.ts` file. This code:

    * Verifies that `PRIVATE_KEY` and `CARDANO_RECIPIENT` are set.
    * Creates an Ethereum Sepolia wallet client and logs the originating address.
    * Checks native ETH balance for gas.
    * Computes the deposit value, maximum fee, and recipient payload (USDC uses 6
      decimals).
    * Confirms the wallet's USDC balance covers the deposit amount.
    * Approves the xReserve contract to spend USDC.
    * Calls `depositToRemote` to submit the deposit so Cardano Preprod mints USDCx
      for the `CARDANO_RECIPIENT` address.

    The `parseCardanoAddress` helper validates the address type and builds
    `remoteRecipient` and `hookData` for `depositToRemote`. Base addresses use the
    staking credential in `hookData` so USDCx arrives at the exact wallet address.
    Enterprise addresses use empty `hookData`.

    ```typescript index.ts theme={null}
    // ============ Parse Cardano address (remoteRecipient + hookData) ============
    const CREDENTIAL_TAG = {
      KEY_HASH: "0x00000001",
      SCRIPT_HASH: "0x00000002",
    } as const;

    const SUPPORTED_ADDRESS_TYPES = {
      BASE: [0, 1, 2, 3], // Base addresses: payment + staking credentials
      ENTERPRISE: [6, 7], // Enterprise addresses: payment credential only
    };

    function parseCardanoAddress(cardanoAddress: string): {
      remoteRecipient: `0x${string}`;
      hookData: `0x${string}`;
    } {
      const decoded = bech32.decode(cardanoAddress, 1000);
      const bytes = bech32.fromWords(decoded.words);
      const headerByte = bytes[0];
      const addressType = headerByte >> 4;

      const allSupported = [
        ...SUPPORTED_ADDRESS_TYPES.BASE,
        ...SUPPORTED_ADDRESS_TYPES.ENTERPRISE,
      ];
      if (!allSupported.includes(addressType)) {
        throw new Error(
          `Unsupported Cardano address type ${addressType}. ` +
            `Use a Base (addr1q...) or Enterprise (addr1v...) address.`,
        );
      }

      // remoteRecipient: [4-byte tag][28-byte payment credential]
      const isScriptPayment = (addressType & 1) === 1;
      const tag = isScriptPayment
        ? CREDENTIAL_TAG.SCRIPT_HASH
        : CREDENTIAL_TAG.KEY_HASH;
      const paymentCredential = bytes.slice(1, 29);
      const credentialHex = Array.from(paymentCredential)
        .map((b) => b.toString(16).padStart(2, "0"))
        .join("");
      const remoteRecipient = `${tag}${credentialHex}` as `0x${string}`;

      // hookData: empty for Enterprise, 95 bytes for Base
      if (SUPPORTED_ADDRESS_TYPES.ENTERPRISE.includes(addressType)) {
        return { remoteRecipient, hookData: "0x" as `0x${string}` };
      }

      // Base address: extract staking credential
      if (bytes.length < 57) {
        throw new Error("Malformed Base address: expected 57 bytes");
      }

      const stakingCredential = bytes.slice(29, 57);
      const isStakingScript = (addressType & 2) === 2;
      const stakingTag = isStakingScript ? "02" : "01";

      // hookData layout (95 bytes):
      // txHash(32) + txIdx(1) + datumTag(1) + datum(32) + stakingTag(1) + stakingCred(28)
      const stakingHex = Array.from(stakingCredential)
        .map((b) => b.toString(16).padStart(2, "0"))
        .join("");
      const hookData =
        `0x${"00".repeat(66)}${stakingTag}${stakingHex}` as `0x${string}`;

      return { remoteRecipient, hookData };
    }

    // ============ Main function ============
    async function main() {
      if (!config.PRIVATE_KEY) {
        throw new Error("PRIVATE_KEY must be set in your .env file");
      }

      if (!config.CARDANO_RECIPIENT) {
        throw new Error("CARDANO_RECIPIENT must be set in your .env file");
      }

      const account = privateKeyToAccount(config.PRIVATE_KEY);
      const client = createWalletClient({
        account,
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      const publicClient = createPublicClient({
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      console.log(`Ethereum wallet address: ${account.address}`);

      const nativeBalance = await publicClient.getBalance({
        address: account.address,
      });
      console.log(
        `Native balance: ${nativeBalance.toString()} wei (${(
          Number(nativeBalance) / 1e18
        ).toFixed(6)} ETH)`,
      );
      if (nativeBalance === 0n)
        throw new Error("Insufficient native balance for gas fees");

      const value = parseUnits(config.DEPOSIT_AMOUNT, 6);
      const maxFee = parseUnits(config.MAX_FEE, 6);
      const { remoteRecipient, hookData } = parseCardanoAddress(
        config.CARDANO_RECIPIENT,
      );

      console.log(
        `\nDepositing ${config.DEPOSIT_AMOUNT} USDC to Cardano recipient: ${config.CARDANO_RECIPIENT}`,
      );

      const usdcBalance = await publicClient.readContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "balanceOf",
        args: [account.address],
      });
      console.log(
        `USDC balance: ${usdcBalance.toString()} (${(
          Number(usdcBalance) / 1e6
        ).toFixed(6)} USDC)`,
      );
      if (usdcBalance < value) {
        throw new Error(
          `Insufficient USDC balance. Required: ${(Number(value) / 1e6).toFixed(
            6,
          )} USDC`,
        );
      }

      const approveTxHash = await client.writeContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "approve",
        args: [config.X_RESERVE_CONTRACT, value],
      });
      console.log("Approval tx hash:", approveTxHash);
      console.log("Waiting for approval confirmation...");

      await publicClient.waitForTransactionReceipt({ hash: approveTxHash });
      console.log("✅ Approval confirmed");

      const depositTxHash = await client.writeContract({
        address: config.X_RESERVE_CONTRACT,
        abi: X_RESERVE_ABI,
        functionName: "depositToRemote",
        args: [
          value,
          config.CARDANO_DOMAIN,
          remoteRecipient,
          config.SEPOLIA_USDC_CONTRACT,
          maxFee,
          hookData,
        ],
      });

      console.log("Deposit tx hash:", depositTxHash);
      console.log(
        "✅ Transaction submitted. You can track this on Sepolia Etherscan.",
      );
    }

    main().catch((error) => {
      console.error("❌ Error:", error);
      process.exit(1);
    });
    ```

    ### 3.2. Run the script

    Execute the script in your terminal:

    ```bash Terminal theme={null}
    npx tsx index.ts
    ```

    ### 3.3. Verify the deposit

    After the script finishes, find the `Deposit tx hash` in the terminal output and
    paste it into [Sepolia Etherscan](https://sepolia.etherscan.io) to confirm your
    deposit transaction. The recipient wallet on Cardano Preprod will receive the
    minted USDCx. You can verify the token on
    [Preprod CardanoScan](https://preprod.cardanoscan.io/).
  </Tab>

  <Tab title="Movement">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/).

    * Created an Ethereum Sepolia wallet and a Movement Bardock wallet and funded
      them with testnet tokens.

      <Accordion title="Need a wallet or testnet tokens?">
        * Use a wallet provider such as [MetaMask](https://metamask.io/) for your Ethereum Sepolia wallet.
        * Use a wallet provider such as [Nightly](https://nightly.app/) for your Movement Bardock wallet.
        * Get Testnet USDC from the [Circle Faucet](https://faucet.circle.com/).
        * Get Testnet ETH from a public [Ethereum Sepolia faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia).
      </Accordion>

    * Installed the required dependencies:
      * `viem` - A TypeScript library that interfaces with Ethereum.

    ## Step 1: Set up your project

    This step shows you how to set up a fresh Node.js workspace, install
    dependencies, configure your environment variables, and prepare your Ethereum
    Sepolia wallet.

    ### 1.1. Set up your development environment

    Create a new directory and install dependencies:

    ```bash Shell theme={null}
    # Set up your directory and initialize the project
    mkdir xreserve-movement-usdcx
    cd xreserve-movement-usdcx
    npm init -y

    # Install tools and dependencies
    npm install viem dotenv
    ```

    ### 1.2. Configure environment variables

    Create a `.env` file in the project directory and add your wallet private key
    and the recipient account address on Movement Bardock.

    <Info>
      If you use MetaMask, follow their guide for how to [find and export your
      private
      key](https://support.metamask.io/configure/accounts/how-to-export-an-accounts-private-key/).
    </Info>

    ```bash Shell theme={null}
    cat > .env << EOF
    PRIVATE_KEY=<your_ethereum_wallet_private_key>
    MOVEMENT_RECIPIENT=<your_movement_testnet_account_address>
    EOF
    ```

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Set up your script

    This step shows you how to build the script by importing its dependencies and
    defining the configuration constants and ABI fragments that the script uses.

    ### 2.1. Import dependencies

    Create a file called `index.ts` and add the following code to import the
    dependencies:

    ```typescript index.ts theme={null}
    import "dotenv/config";
    import { createWalletClient, createPublicClient, http, parseUnits } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { sepolia } from "viem/chains";
    ```

    ### 2.2. Define configuration constants

    Add the following code snippet to your `index.ts` file. It specifies the RPC and
    wallet private key, contract addresses, and Movement-specific values. The
    `MOVEMENT_RECIPIENT` is loaded from your `.env` file.

    <Info>
      You can review the [xReserve EVM
      contracts](https://github.com/circlefin/evm-xreserve-contracts) on GitHub.
    </Info>

    ```typescript index.ts theme={null}
    // ============ Configuration constants ============
    const config = {
      // Public Ethereum Sepolia RPC and your private wallet key
      ETH_RPC_URL: process.env.RPC_URL || "https://ethereum-sepolia.publicnode.com",
      PRIVATE_KEY: process.env.PRIVATE_KEY as `0x${string}`,

      // Contract addresses on Ethereum Sepolia testnet
      X_RESERVE_CONTRACT:
        "0x008888878f94C0d87defdf0B07f46B93C1934442" as `0x${string}`,
      SEPOLIA_USDC_CONTRACT:
        "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as `0x${string}`,

      // Deposit parameters for Movement
      MOVEMENT_DOMAIN: 10005, // Movement domain ID
      MOVEMENT_RECIPIENT: process.env.MOVEMENT_RECIPIENT || "", // Account to receive USDCx on Movement
      DEPOSIT_AMOUNT: "5.00",
      MAX_FEE: "0",
    };
    ```

    ### 2.3. Set up contract ABIs

    Add the following code snippet to your `index.ts` file. It adds xReserve and
    ERC-20 ABI fragments which tell `viem` how to format and send the contract calls
    when the script runs.

    <Info>
      For more background on contract ABIs, see QuickNode's guide, [What is an
      ABI?](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi).
    </Info>

    ```typescript index.ts theme={null}
    // ============ Contract ABIs ============
    const X_RESERVE_ABI = [
      {
        name: "depositToRemote",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "value", type: "uint256" },
          { name: "remoteDomain", type: "uint32" },
          { name: "remoteRecipient", type: "bytes32" },
          { name: "localToken", type: "address" },
          { name: "maxFee", type: "uint256" },
          { name: "hookData", type: "bytes" },
        ],
        outputs: [],
      },
    ] as const;

    const ERC20_ABI = [
      {
        name: "approve",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "spender", type: "address" },
          { name: "amount", type: "uint256" },
        ],
        outputs: [{ name: "success", type: "bool" }],
      },
      {
        name: "balanceOf",
        type: "function",
        stateMutability: "view",
        inputs: [{ name: "account", type: "address" }],
        outputs: [{ name: "balance", type: "uint256" }],
      },
    ] as const;
    ```

    ## Step 3: Execute the xReserve deposit

    This step shows you how to implement the main logic that checks balances,
    approves USDC, and calls xReserve on Ethereum Sepolia so Movement Bardock can
    mint the corresponding USDCx.

    ### 3.1. Add the main function

    Add the following code to your `index.ts` file. It defines the `main` function,
    which does the following:

    * Validates `PRIVATE_KEY` and `MOVEMENT_RECIPIENT`.
    * Verifies you have enough Sepolia ETH (gas) and USDC for the deposit.
    * Approves the xReserve contract, then calls `depositToRemote` with your
      Movement account.

    ```typescript index.ts theme={null}
    // ============ Main function ============
    async function main() {
      // Require Ethereum private key and Movement recipient (32-byte hex account)
      if (!config.PRIVATE_KEY) {
        throw new Error("PRIVATE_KEY must be set in your .env file");
      }

      if (!config.MOVEMENT_RECIPIENT) {
        throw new Error("MOVEMENT_RECIPIENT must be set in your .env file");
      }

      // Movement accounts are already bytes32-sized hex; only normalize optional 0x prefix
      const remoteRecipient = (
        config.MOVEMENT_RECIPIENT.startsWith("0x")
          ? config.MOVEMENT_RECIPIENT
          : `0x${config.MOVEMENT_RECIPIENT}`
      ) as `0x${string}`;
      // Pass empty bytes (hookData is not used for Movement)
      const hookData = "0x" as `0x${string}`;

      // Set up wallet and wallet provider
      const account = privateKeyToAccount(config.PRIVATE_KEY);
      const client = createWalletClient({
        account,
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      const publicClient = createPublicClient({
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      console.log(`Ethereum wallet address: ${account.address}`);

      // Check native ETH balance
      const nativeBalance = await publicClient.getBalance({
        address: account.address,
      });
      console.log(
        `Native balance: ${nativeBalance.toString()} wei (${(
          Number(nativeBalance) / 1e18
        ).toFixed(6)} ETH)`,
      );
      if (nativeBalance === 0n)
        throw new Error("Insufficient native balance for gas fees");

      const value = parseUnits(config.DEPOSIT_AMOUNT, 6);
      const maxFee = parseUnits(config.MAX_FEE, 6);

      console.log(
        `\nDepositing ${config.DEPOSIT_AMOUNT} USDC to Movement recipient: ${config.MOVEMENT_RECIPIENT}`,
      );

      const usdcBalance = await publicClient.readContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "balanceOf",
        args: [account.address],
      });
      console.log(
        `USDC balance: ${usdcBalance.toString()} (${(
          Number(usdcBalance) / 1e6
        ).toFixed(6)} USDC)`,
      );
      if (usdcBalance < value) {
        throw new Error(
          `Insufficient USDC balance. Required: ${(Number(value) / 1e6).toFixed(
            6,
          )} USDC`,
        );
      }

      const approveTxHash = await client.writeContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "approve",
        args: [config.X_RESERVE_CONTRACT, value],
      });
      console.log("Approval tx hash:", approveTxHash);
      console.log("Waiting for approval confirmation...");

      await publicClient.waitForTransactionReceipt({ hash: approveTxHash });
      console.log("✅ Approval confirmed");

      const depositTxHash = await client.writeContract({
        address: config.X_RESERVE_CONTRACT,
        abi: X_RESERVE_ABI,
        functionName: "depositToRemote",
        args: [
          value,
          config.MOVEMENT_DOMAIN,
          remoteRecipient,
          config.SEPOLIA_USDC_CONTRACT,
          maxFee,
          hookData,
        ],
      });

      console.log("Deposit tx hash:", depositTxHash);
      console.log(
        "✅ Transaction submitted. You can track this on Sepolia Etherscan.",
      );
    }

    // ============ Call the main function ============
    main().catch((error) => {
      console.error("❌ Error:", error);
      process.exit(1);
    });
    ```

    This step finalizes the transfer, depositing USDC into xReserve on Ethereum
    Sepolia to make USDCx available on Movement Bardock.

    ### 3.2. Run the script

    Execute the script in your terminal:

    ```bash Shell theme={null}
    npx tsx index.ts
    ```

    ### 3.3. Verify the deposit

    After the script finishes, find the `Deposit tx hash` in the terminal output and
    paste it into [Sepolia Etherscan](https://sepolia.etherscan.io) to confirm your
    deposit transaction was successful. On Movement Bardock, the recipient account
    will receive the minted testnet USDCx.
  </Tab>

  <Tab title="Stacks">
    ## Prerequisites

    Before you begin, ensure that you've:

    * Installed [Node.js v22+](https://nodejs.org/).

    * Created an Ethereum Sepolia wallet and a Stacks Testnet wallet and funded them
      with testnet tokens.

      <Accordion title="Need a wallet or testnet tokens?">
        * Use a wallet provider such as [MetaMask](https://metamask.io/) for your Ethereum Sepolia wallet.
        * Use [Leather Wallet](https://leather.io/) or [Xverse](https://www.xverse.app/) for your Stacks Testnet wallet.
        * Get Testnet USDC from the [Circle Faucet](https://faucet.circle.com/).
        * Get Testnet ETH from a public [Ethereum Sepolia faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia).
      </Accordion>

    * Installed the required dependencies:
      * `viem` - A TypeScript library that interfaces with Ethereum.
      * `@stacks/transactions` - A JavaScript library for Stacks address creation
        and transaction handling.
      * `micro-packed` - A library for encoding Stacks addresses to bytes32 format.

    ## Step 1: Set up your project

    This step shows you how to set up a fresh Node.js workspace, install
    dependencies, configure your environment variables, and prepare your Ethereum
    Sepolia wallet.

    ### 1.1. Set up your development environment

    Create a new directory and install dependencies:

    ```bash Shell theme={null}
    # Set up your directory and initialize the project
    mkdir xreserve-stacks-usdcx
    cd xreserve-stacks-usdcx
    npm init -y

    # Install tools and dependencies
    npm install viem dotenv @stacks/transactions micro-packed @scure/base
    ```

    ### 1.2. Configure environment variables

    Create a `.env` file in the project directory and add your wallet private key
    and the recipient address on Stacks.

    <Info>
      If you use MetaMask, follow their guide for how to [find and export your
      private
      key](https://support.metamask.io/configure/accounts/how-to-export-an-accounts-private-key/).
    </Info>

    ```bash Shell theme={null}
    cat > .env << EOF
    PRIVATE_KEY=<your_ethereum_wallet_private_key>
    STACKS_RECIPIENT=<your_stacks_recipient_testnet_address>
    EOF
    ```

    <Warning>
      This example uses one or more private keys for local testing. In production,
      use a secure key management solution and never expose or share private keys.
    </Warning>

    ## Step 2: Set up your script

    This step shows you how to build the script by importing its dependencies and
    defining the configuration constants and ABI fragments that the script uses.

    ### 2.1. Create helpers

    Create a `helpers.ts` file and add the following code to it. This code encodes
    Stacks addresses into the bytes32 format required by xReserve:

    ```typescript helpers.ts theme={null}
    import * as P from "micro-packed";
    import {
      createAddress,
      addressToString,
      AddressVersion,
      StacksWireType,
    } from "@stacks/transactions";
    import { hex } from "@scure/base";
    import { type Hex, pad, toHex } from "viem";

    export const remoteRecipientCoder = P.wrap<string>({
      encodeStream(w, value: string) {
        const address = createAddress(value);
        // Left pad with 11 zero bytes
        P.bytes(11).encodeStream(w, new Uint8Array(11).fill(0));
        // 1 version byte
        P.U8.encodeStream(w, address.version);
        // 20 hash bytes
        P.bytes(20).encodeStream(w, hex.decode(address.hash160));
      },
      decodeStream(r) {
        // Left pad (11 bytes)
        P.bytes(11).decodeStream(r);
        // 1 version byte
        const version = P.U8.decodeStream(r);
        // 20 hash bytes
        const hash = P.bytes(20).decodeStream(r);
        return addressToString({
          hash160: hex.encode(hash),
          version: version as AddressVersion,
          type: StacksWireType.Address,
        });
      },
    });

    export function bytes32FromBytes(bytes: Uint8Array): Hex {
      return toHex(pad(bytes, { size: 32 }));
    }
    ```

    ### 2.2. Import dependencies

    Create a file called `index.ts` and add the following code to import the
    dependencies:

    ```typescript index.ts theme={null}
    import "dotenv/config";
    import { createWalletClient, createPublicClient, http, parseUnits } from "viem";
    import { privateKeyToAccount } from "viem/accounts";
    import { sepolia } from "viem/chains";
    import { bytes32FromBytes, remoteRecipientCoder } from "./helpers";
    ```

    ### 2.3. Define configuration constants

    Add the following code snippet to your `index.ts` file. It specifies the RPC and
    wallet private key, contract addresses, and Stacks-specific parameters that the
    rest of the script relies on. The `STACKS_RECIPIENT` is loaded from your `.env`
    file.

    <Info>
      You can review the [xReserve EVM
      contracts](https://github.com/circlefin/evm-xreserve-contracts) on GitHub.
    </Info>

    ```typescript index.ts theme={null}
    // ============ Configuration constants ============
    const config = {
      // Public Ethereum Sepolia RPC and your private wallet key
      ETH_RPC_URL: process.env.RPC_URL || "https://ethereum-sepolia.publicnode.com",
      PRIVATE_KEY: process.env.PRIVATE_KEY as `0x${string}`,

      // Contract addresses on Ethereum Sepolia testnet
      X_RESERVE_CONTRACT:
        "0x008888878f94C0d87defdf0B07f46B93C1934442" as `0x${string}`,
      SEPOLIA_USDC_CONTRACT:
        "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as `0x${string}`,

      // Deposit parameters for Stacks
      STACKS_DOMAIN: 10003, // Stacks domain ID
      STACKS_RECIPIENT: process.env.STACKS_RECIPIENT || "", // Address to receive USDCx on Stacks
      DEPOSIT_AMOUNT: "5.00",
      MAX_FEE: "0",
    };
    ```

    ### 2.4. Set up contract ABIs

    Add the following code snippet to your `index.ts` file. It adds xReserve and
    ERC-20 ABI fragments which tell `viem` how to format and send the contract calls
    when the script runs.

    <Info>
      For more background on contract ABIs, see QuickNode's guide, [What is an
      ABI?](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi).
    </Info>

    ```typescript index.ts theme={null}
    // ============ Contract ABIs ============
    const X_RESERVE_ABI = [
      {
        name: "depositToRemote",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "value", type: "uint256" },
          { name: "remoteDomain", type: "uint32" },
          { name: "remoteRecipient", type: "bytes32" },
          { name: "localToken", type: "address" },
          { name: "maxFee", type: "uint256" },
          { name: "hookData", type: "bytes" },
        ],
        outputs: [],
      },
    ] as const;

    const ERC20_ABI = [
      {
        name: "approve",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "spender", type: "address" },
          { name: "amount", type: "uint256" },
        ],
        outputs: [{ name: "success", type: "bool" }],
      },
      {
        name: "balanceOf",
        type: "function",
        stateMutability: "view",
        inputs: [{ name: "account", type: "address" }],
        outputs: [{ name: "balance", type: "uint256" }],
      },
    ] as const;
    ```

    ## Step 3: Execute the xReserve deposit

    This step shows you how to implement the main logic that checks balances,
    approves USDC, and calls xReserve on Ethereum Sepolia so Stacks can mint the
    corresponding USDCx.

    ### 3.1. Add the main function

    Add the following code snippet to your `index.ts` file. This code flows through
    the following actions:

    * Verifies that `PRIVATE_KEY` is present before continuing.
    * Creates an Ethereum Sepolia wallet client and logs the originating address.
    * Checks native ETH balance to ensure there is enough gas for transactions.
    * Computes the deposit value, maximum fee, and recipient payload (USDC uses 6
      decimals).
    * Confirms that the wallet's USDC balance covers the configured deposit amount.
    * Approves the xReserve smart contract to spend USDC on the wallet's behalf.
    * Calls `depositToRemote` to submit the deposit and tell Stacks to mint USDCx
      for the wallet specified as the `STACKS_RECIPIENT`.

    Stacks uses the micro-packed library to encode the Stacks address into bytes32
    format for the `remoteRecipient` parameter. The original address is encoded as
    hex for `hookData`.

    ```typescript index.ts theme={null}
    // ============ Main function ============
    async function main() {
      if (!config.PRIVATE_KEY) {
        throw new Error("PRIVATE_KEY must be set in your .env file");
      }

      if (!config.STACKS_RECIPIENT) {
        throw new Error("STACKS_RECIPIENT must be set in your .env file");
      }

      // Set up wallet and wallet provider
      const account = privateKeyToAccount(config.PRIVATE_KEY);
      const client = createWalletClient({
        account,
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      const publicClient = createPublicClient({
        chain: sepolia,
        transport: http(config.ETH_RPC_URL),
      });

      console.log(`Ethereum wallet address: ${account.address}`);

      // Check native ETH balance
      const nativeBalance = await publicClient.getBalance({
        address: account.address,
      });
      console.log(
        `Native balance: ${nativeBalance.toString()} wei (${(
          Number(nativeBalance) / 1e18
        ).toFixed(6)} ETH)`,
      );
      if (nativeBalance === 0n)
        throw new Error("Insufficient native balance for gas fees");

      // Prepare deposit params (USDC has 6 decimals)
      const value = parseUnits(config.DEPOSIT_AMOUNT, 6);
      const maxFee = parseUnits(config.MAX_FEE, 6);
      const encoder = new TextEncoder();
      const recipientBytes = encoder.encode(config.STACKS_RECIPIENT);
      const remoteRecipient = bytes32FromBytes(
        remoteRecipientCoder.encode(config.STACKS_RECIPIENT),
      );
      const hookData = ("0x" +
        Buffer.from(recipientBytes).toString("hex")) as `0x${string}`;

      console.log(
        `\nDepositing ${config.DEPOSIT_AMOUNT} USDC to Stacks recipient: ${config.STACKS_RECIPIENT}`,
      );

      // Check token balance
      const usdcBalance = await publicClient.readContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "balanceOf",
        args: [account.address],
      });
      console.log(
        `USDC balance: ${usdcBalance.toString()} (${(
          Number(usdcBalance) / 1e6
        ).toFixed(6)} USDC)`,
      );
      if (usdcBalance < value) {
        throw new Error(
          `Insufficient USDC balance. Required: ${(Number(value) / 1e6).toFixed(
            6,
          )} USDC`,
        );
      }

      // Approve xReserve to spend USDC
      const approveTxHash = await client.writeContract({
        address: config.SEPOLIA_USDC_CONTRACT,
        abi: ERC20_ABI,
        functionName: "approve",
        args: [config.X_RESERVE_CONTRACT, value],
      });
      console.log("Approval tx hash:", approveTxHash);
      console.log("Waiting for approval confirmation...");

      await publicClient.waitForTransactionReceipt({ hash: approveTxHash });
      console.log("✅ Approval confirmed");

      // Deposit transaction
      const depositTxHash = await client.writeContract({
        address: config.X_RESERVE_CONTRACT,
        abi: X_RESERVE_ABI,
        functionName: "depositToRemote",
        args: [
          value,
          config.STACKS_DOMAIN,
          remoteRecipient,
          config.SEPOLIA_USDC_CONTRACT,
          maxFee,
          hookData,
        ],
      });

      console.log("Deposit tx hash:", depositTxHash);
      console.log(
        "✅ Transaction submitted. You can track this on Sepolia Etherscan.",
      );
    }

    // ============ Call the main function ============
    main().catch((error) => {
      console.error("❌ Error:", error);
      process.exit(1);
    });
    ```

    This step finalizes the transfer, depositing USDC into xReserve on Ethereum
    Sepolia to make USDCx available on Stacks Testnet.

    ### 3.2. Run the script

    Execute the script in your terminal:

    ```bash Shell theme={null}
    npx tsx index.ts
    ```

    ### 3.3. Verify the deposit

    After the script finishes, find the `Deposit tx hash` in the terminal output and
    paste it into [Sepolia Etherscan](https://sepolia.etherscan.io) to confirm your
    deposit transaction was successful. On Stacks Testnet, the recipient wallet will
    receive the minted testnet USDCx.
  </Tab>
</Tabs>


# Initiate a Withdrawal from xReserve as a Remote Blockchain
Source: https://developers.circle.com/xreserve/tutorials/initiate-a-withdrawal-as-a-remote-blockchain



If you're a remote blockchain partner, you can submit to withdraw from xReserve
after a user burns tokens on your chain. This tutorial walks through the process
using Canton TestNet as the example remote blockchain and Ethereum Sepolia as
both the example source and destination blockchain.

<Note>
  **Note**: This tutorial is intended for remote blockchain partners. If you're
  a developer or user, visit the remote blockchain website or contact them for
  instructions on how to withdraw funds from xReserve.
</Note>

## Step 1. Monitor burn events

Listen for burn events on your blockchain. Each event should include at least:

* The recipient wallet address on the destination chain.
* The
  [remote domain](/xreserve/references/supported-blockchains-and-domains#remote-domains)
  ID.

## Step 2. Prepare the withdrawal

Send the burn intent data to the
[`/prepare-withdrawal`](/api-reference/xreserve/all/prepare-withdrawal)
endpoint. The following example request contains data to withdraw 2500 USDC on
Ethereum:

```json json theme={null}
{
  "batches": [
    {
      "token": "USDC",
      "valueExcludingFees": "2500.00",
      "remoteDomain": 10001,
      "remoteDepositor": "0x000000000000000000000000c0ffee254729296a45a3885639ac7e10f9d54979",
      "finalDestinationDomain": 0,
      "finalDestinationRecipient": "0x000000000000000000000000aabbee11223344556677889900aabbccddeeff00",
      "finalDestinationCaller": "0x00000000000000000000000000112233445566778899aabbccddeeff00112233",
      "useCircleForwarding": true,
      "salt": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    }
  ]
}
```

**Response**

The API returns a fully encoded
[burn intent](/xreserve/concepts/technical-guide#burn-intent) and the canonical
[message hash](/xreserve/concepts/technical-guide#message-hash-and-burn-intent-signature)
for you to sign, for example:

```json json theme={null}
{
  "batches": [
    {
      "burnIntents": [
        {
          "maxBlockHeight": "18976543",
          "maxFee": "750000",
          "spec": {
            "version": 1,
            "sourceDomain": 0,
            "destinationDomain": 0,
            "sourceContract": "0x0000000000000000000000000077777d7eba4688bdef3e311b846f25870a19b9",
            "destinationContract": "0x0000000000000000000000000022222abe238cc2c7bb1f21003f0a260052475b",
            "sourceToken": "0x74ed63088c070c8fd5d8ad71f2a1cef868c63d00e0ac6dc2a6722d171691a422",
            "destinationToken": "0x0000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c7238",
            "sourceDepositor": "0x000000000000000000000000c0ffee254729296a45a3885639ac7e10f9d54979",
            "destinationRecipient": "0x000000000000000000000000aabbee11223344556677889900aabbccddeeff00",
            "sourceSigner": "0x0000000000000000000000005555555555555555555555555555555555555555",
            "destinationCaller": "0x00000000000000000000000000112233445566778899aabbccddeeff00112233",
            "value": "2500000000",
            "salt": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
            "hookData": {
              "remoteDomain": 10001,
              "remoteDepositor": "0xc0ffee254729296a45a3885639ac7e10f9d54979",
              "remoteToken": "0x74ed63088c070c8fd5d8ad71f2a1cef868c63d00e0ac6dc2a6722d171691a422",
              "forwardingContractAddress": "0x0000000000000000000000000000000000000000",
              "forwardingCalldata": "0x"
            }
          }
        }
      ],
      "encoded": "0x8ddf3a...f9a2",
      "messageHashToSign": "0x4f5c6d7e8f90123456789abcdeffedcba9876543210fedcba9876543210abcd"
    }
  ]
}
```

## Step 3. Sign the message hash

Use your [attester](/xreserve/concepts/technical-guide#attesters) keys to sign
the `messageHashToSign` returned in the previous step. This produces the burn
intent signatures.

## Step 4. Submit the withdrawal

Send the encoded burn intent payload, the array of burn signatures, and the burn
transaction hash to the
[`/withdraw`](/api-reference/xreserve/all/submit-withdrawal) endpoint. Set
`useCircleForwarding` to `true` if you want Circle to submit the withdrawal on
behalf of your user.

<Note>
  **Note**: If you don't use Circle
  [forwarding](/xreserve/concepts/technical-guide#withdrawal-forwarding), you'll
  need to perform an additional crosschain transfer to withdraw funds from
  xReserve.
</Note>

The following is an example request:

```json json theme={null}
{
  "batches": [
    {
      "burnIntents": {
        "maxBlockHeight": "18976543",
        "maxFee": "750000",
        "spec": {
          "version": 1,
          "sourceDomain": 0,
          "destinationDomain": 0,
          "sourceContract": "0x0000000000000000000000000077777d7eba4688bdef3e311b846f25870a19b9",
          "destinationContract": "0x0000000000000000000000000022222abe238cc2c7bb1f21003f0a260052475b",
          "sourceToken": "0x74ed63088c070c8fd5d8ad71f2a1cef868c63d00e0ac6dc2a6722d171691a422",
          "destinationToken": "0x0000000000000000000000001c7d4b196cb0c7b01d743fbc6116a902379c7238",
          "sourceDepositor": "0x000000000000000000000000c0ffee254729296a45a3885639ac7e10f9d54979",
          "destinationRecipient": "0x000000000000000000000000aabbee11223344556677889900aabbccddeeff00",
          "sourceSigner": "0x0000000000000000000000005555555555555555555555555555555555555555",
          "destinationCaller": "0x00000000000000000000000000112233445566778899aabbccddeeff00112233",
          "value": "2500000000",
          "salt": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
          "hookData": {
            "remoteDomain": 10001,
            "remoteDepositor": "0xc0ffee254729296a45a3885639ac7e10f9d54979",
            "remoteToken": "0x74ed63088c070c8fd5d8ad71f2a1cef868c63d00e0ac6dc2a6722d171691a422",
            "forwardingContractAddress": "0x0000000000000000000000000000000000000000",
            "forwardingCalldata": "0x"
          }
        }
      },
      "burnSignatures": [
        "0x9c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff0011223344556677",
        "0x7f6e5d4c3b2a19080706050403020100ffeeddccbbaa99887766554433221100"
      ],
      "burnTxId": "0x5a7b3c1d4e6f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70819",
      "useCircleForwarding": true
    }
  ]
}
```

**Response**

The API returns `withdrawalId`, a unique identifier for each withdrawal batch.
For example:

```json json theme={null}
[
  {
    "withdrawalId": "6149dc3d-71bf-4d57-8cc1-5e2d4c0a8e70",
    "transferSpecHashes": [
      "0x23f8c66d5a8bb5b712f2f4bc1c0a5a51d7c2b4f93d587f1449bcf3da6d8e1f20"
    ],
    "verificationStatus": "unverified",
    "attestation": null,
    "requireCircleRelay": true
  }
]
```

## Step 5. Monitor withdrawal status

Check the status of your withdrawal by calling
[`GET /withdrawals/{withdrawalId}`](/api-reference/xreserve/all/get-withdrawal-status).
xReserve releases funds once the `status` is `finalized`. If the status remains
`created`, `verified`, or `unverified`, keep polling. If the status changes to
`failed`, resolve the issue and resubmit the withdrawal.