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.
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.
{
"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
{
"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.mint.forwarded
Fires when a forwarded mint relay is confirmed. This event only occurs for
transfers that use the
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) |
| 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
{
"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.
{
"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
}
