Skip to main content

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.

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

​
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, the relay is confirmed → gateway.mint.forwarded
  3. The deposit is attested and tokens are minted on the destination blockchain → gateway.mint.finalized

​
Limits

ResourceLimit
Subscriptions per developer account20
Registered addresses per developer account50

​
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 account.

​
Get started

Webhook events reference

View schemas and examples for each event type