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

> ## Agent Instructions
> Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}.
> Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts.
> Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md.
> Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md.
> Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers.
> Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews.
> Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming.
> Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md.
> Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors.
> API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product.
> Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes.
> When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records.
> Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md.

# Solana programs and interfaces for Gateway

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,
  use its Associated Token Account (ATA), not the recipient wallet address
  itself.
</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`.