> ## 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.

# 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 Console](https://console.circle.com) account and API key. You do not
need billing or a credit card.

To set up an endpoint and subscribe, see
[Set up a webhook endpoint](/api-reference/webhook-endpoints). For the event
model, delivery behavior, and signature verification, see the
[Webhooks](/api-reference/webhooks) group in the API reference.

## Authentication

While Gateway itself is permissionless and does not require authentication,
webhook subscriptions require a Circle Console account and API key. Manage
subscriptions through the `POST /v2/notifications/subscriptions/permissionless`
endpoint. Create a free account at the
[Circle 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>