.png?fit=max&auto=format&n=ML35RDblT1Ol-zJb&q=85&s=062e79ad9c4540929eec204aff020178)
.png?fit=max&auto=format&n=ML35RDblT1Ol-zJb&q=85&s=f6328956931c9664a2a070c2edb6e9b3)
Event Type
Each notification flow corresponds to a specific lifecycle event within the Wallet Infrastructure platform:wallets:deposit.pending: Triggered when an incoming deposit is detected on-chain but awaiting required network block confirmations.wallets:deposit.success: Triggered when a deposit reaches required confirmations and funds are successfully credited.wallets:withdraw.pending: Triggered when a withdrawal request is initiated and queued for execution.wallets:withdraw.success: Triggered when an outbound withdrawal transaction is successfully confirmed on-chain.wallets:swap.success: Triggered when a token swap order finishes execution across target chains and assets.
Event Schema
Root Payload Fields
| Field | Description | Type |
|---|---|---|
requestId | Unique tracking identifier for the webhook delivery request. | string |
method | Event type identifier (e.g., wallets:deposit.success, wallets:swap.success). | string |
params | Object containing event-specific transaction and resource details. | object |
Transaction (Deposit | Withdraw)
Transaction (Deposit | Withdraw)
| Field | Description | Type |
|---|---|---|
params.id | Unique ID of the transaction record. | string |
params.refId | External or internal system reference ID. | string |
params.idempotencyKey | Key used for idempotency protection on state-changing requests. | string |
params.tokenName | Display name of the cryptocurrency asset (e.g., USD Coin). | string |
params.tokenSymbol | Asset ticker symbol (e.g., USDC). | string |
params.tokenTicker | Platform asset identifier (e.g., USDC_BASE). | string |
params.tokenAddress | On-chain contract address of the transferred token. | string |
params.decimals | Decimal precision defined by the asset’s contract. | number |
params.isNative | Indicates if the asset is the native network currency. | boolean |
params.amount.value | Human-readable transaction amount string. | string |
params.amount.rawValue | Atomic unit representation of the transaction amount. | string |
params.chainDecimals | Decimal precision of the underlying blockchain network. | number |
params.blockchain | Target blockchain protocol identifier (e.g., BASE). | string |
params.protocol | Network virtual machine/architecture type (e.g., EVM). | string |
params.environment | Network mode (testnet / live). | string |
params.network | Specific blockchain network name (e.g., base-sepolia). | string |
params.txType | Primary direction of transaction (incoming or outgoing). | string |
params.status | Current transaction execution status (pending, success). | string |
params.fromAddress | Blockchain address originating the transfer. | string |
params.toAddress | Destination blockchain address. | string |
params.txHash | Blockchain transaction hash. | string |
params.note | Optional internal note attached to the transaction. | string | null |
params.triggerOrigin | Trigger source (blockchain for detected deposits, api for programmatic requests). | string |
params.confirmation | Current block confirmation count. | string |
params.confirmed | Indicates whether network confirmation requirements have been satisfied. | boolean |
params.confirmedAt | ISO 8601 timestamp when block confirmation was achieved. | string |
params.userId | Unique ID of the associated User entity. | string |
params.walletId | Unique ID of the associated Wallet endpoint. | string |
params.accountId | Unique ID of the governing Account container. | string |
params.workspaceId | Unique ID of the organization workspace. | string |
params.createdAt | Creation timestamp of the transaction. | string |
params.updatedAt | Last update timestamp of the transaction. | string |
params.wallet.id | ID of the target wallet. | string |
params.wallet.address | Primary blockchain address assigned to the wallet. | string |
params.wallet.type | Infrastructure wallet type (e.g., deposit, settlement). | string |
params.wallet.protocol | Virtual machine protocol standard (e.g., EVM). | string |
params.wallet.isEvmCompatible | Indicates EVM execution capability. | boolean |
params.wallet.name | Label or display name assigned to the wallet. | string |
params.wallet.userId | User ID attached to the wallet. | string |
params.wallet.refId | External mapping reference for the wallet. | string |
params.wallet.custodyType | Custody model framework (DEVELOPER). | string |
params.wallet.token.balance | Real-time updated wallet balance post-transaction. | object |
Swap
Swap
| Field | Description | Type |
|---|---|---|
params.id | Unique ID of the swap order. | string |
params.idempotencyKey | Unique key sent during order creation to ensure single execution. | string |
params.refId | System reference identifier for the swap operation. | string |
params.from.token | Source token ticker symbol (e.g., USDC). | string |
params.from.chain | Source blockchain network (e.g., ETHEREUM). | string |
params.from.contractAddress | Smart contract address of the source token. | string |
params.from.amount | Amount of source token submitted for swap. | string |
params.to.token | Destination token ticker symbol (e.g., USDC). | string |
params.to.chain | Destination blockchain network (e.g., ARBITRUM). | string |
params.to.contractAddress | Smart contract address of the target token. | string |
params.to.amount | Estimated or final output amount on the target network. | string |
params.amountType | Swap pricing calculation mode (exactInput or exactOutput). | string |
params.slippage | Slippage tolerance threshold applied during execution (e.g., auto). | string |
params.environment | Network environment mode (sandbox or live). | string |
params.status | Final execution status of the order (success, pending). | string |
params.txHash | Inbound/source blockchain transaction hash. | string |
params.hashOut | Outbound/destination transaction hash (populated once cross-chain delivery settles). | string | null |
params.fee.token | Token used to pay platform/execution fees. | string |
params.fee.chain | Network chain where the execution fee was deducted. | string |
params.fee.decimal | Decimal precision of the fee token contract. | string |
params.fee.contractAddress | Smart contract address of the fee token. | string |
params.fee.amount | Platform fee amount deducted for the swap. | string |
params.fee.amountInUsd | USD valuation equivalent of the platform fee. | string |
params.bridgeFee.token | Token used to pay cross-chain liquidity bridge fees. | string |
params.bridgeFee.chain | Network chain where the bridge fee was processed. | string |
params.bridgeFee.contractAddress | Smart contract address of the bridge fee token. | string |
params.bridgeFee.amount | Cross-chain bridge provider fee amount. | string |
params.bridgeFee.amountInUsd | USD valuation equivalent of the bridge fee. | string |
params.triggerOrigin | Execution trigger source (api or console). | string |
params.transactionGroupId | Shared tracking ID linking multi-leg or cross-chain swap executions. | string |
params.createdAt | Creation timestamp of the swap order. | string (ISO 8601) |
params.updatedAt | Timestamp when the swap order was last updated. | string (ISO 8601) |
params.walletId | ID of the Wallet entity executing the swap. | string |
params.accountId | ID of the Account container associated with the wallet. | string |
params.workspaceId | ID of the organization workspace. | string |
Event Examples
Incoming Deposit (pending) example
Incoming Deposit (pending) example
{
"requestId": "04afc1dd8ffae1f6f8c66f96eed0f5",
"method": "wallets:withdraw.pending",
"params": {
"id": "6a382b941e117b9527366499",
"refId": "2a1ee011-e5b5-419e-a967-bb0a8f0626c3",
"idempotencyKey": "0e620f37-0f8a-4cee-b0e7-72235b697449",
"tokenName": "USD Coin",
"tokenSymbol": "USDC",
"tokenTicker": "USDC_BASE",
"tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
"decimals": 6,
"isNative": false,
"amount": {
"value": "5",
"rawValue": "5000000"
},
"totalAmount": {
"value": "5.028011",
"rawValue": "5028011"
},
"chainDecimals": 18,
"blockchain": "BASE",
"protocol": "EVM",
"environment": "testnet",
"network": "base-sepolia",
"txType": "outgoing",
"status": "pending",
"fromAddress": "0xda0348137a73899a156944e31c81f05f646d168c",
"toAddress": "0x226917bdc6d659672050e48ca6ce73dbd3a1d318",
"txHash": "0xee30898cdfaee9c810996756337044fd98b4b0406583dd2d5706288b97f472e5",
"totalFee": {
"value": "0.000001224105803529",
"rawValue": "1224105803529"
},
"feeLevel": "fast",
"feeToken": "ETH",
"isBatch": false,
"destinations": [
{
"address": "0x226917bdc6d659672050e48ca6ce73dbd3a1d318",
"value": "5",
"rawValue": "5000000"
},
{
"address": "0x7a750d8d6e12cce09a7c15482077a8a4d4c37de4",
"value": "0.028011",
"rawValue": "28011"
}
],
"note": null,
"triggerOrigin": "blockchain",
"confirmation": null,
"confirmed": false,
"confirmedAt": null,
"userId": "69f60c8561a6152a39f39005",
"walletId": "69f60c8561a6152a39f39005",
"accountId": "69eba97c3f7e15428aef8811",
"workspaceId": "67e723ed4b44a4f73dd2e8a2",
"createdAt": "2026-06-21T18:21:08.349Z",
"updatedAt": "2026-06-21T18:21:08.349Z",
"wallet": {
"id": "69f60c8561a6152a39f39005",
"address": "0xDA0348137A73899A156944e31C81f05F646d168c",
"type": "deposit",
"protocol": "EVM",
"isEvmCompatible": true,
"name": "user_0_Zee",
"userId": "69f60c8561a6152a39f39005",
"refId": "f3f14dcf-a233-4128-8044-5c8f03feb230",
"custodyType": "DEVELOPER",
"token": {
"name": "USD Coin",
"symbol": "USDC",
"blockchain": "BASE",
"tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
"isNative": false,
"decimals": 6,
"standard": "ERC20",
"balance": {
"value": "12.471989",
"rawValue": "12471989"
}
}
}
}
}
}
Incoming Deposit (success) example
Incoming Deposit (success) example
{
"requestId": "04afc1dd8ffae1f6f8c66f96eed0f5",
"method": "wallets:deposit.success",
"params": {
"id": "6a382b951e117b952736649a",
"refId": "9395d9b3-b58a-4856-8a3e-886c687f8d6f",
"idempotencyKey": "d1526226-27c2-440f-8d57-a2e3bc980e89",
"tokenName": "USD Coin",
"tokenSymbol": "USDC",
"tokenTicker": "USDC_BASE",
"tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
"decimals": 6,
"isNative": false,
"amount": {
"value": "5",
"rawValue": "5000000"
},
"chainDecimals": 18,
"blockchain": "BASE",
"protocol": "EVM",
"environment": "testnet",
"network": "base-sepolia",
"txType": "incoming",
"status": "success",
"fromAddress": "0xda0348137a73899a156944e31c81f05f646d168c",
"toAddress": "0x226917bdc6d659672050e48ca6ce73dbd3a1d318",
"txHash": "0xee30898cdfaee9c810996756337044fd98b4b0406583dd2d5706288b97f472e5",
"note": null,
"triggerOrigin": "blockchain",
"confirmation": "1",
"confirmed": true,
"confirmedAt": "2026-06-21T18:24:28.849Z",
"userId": "69f60c8561a6152a39f39005",
"walletId": "6a38259e7b6635a105154d11",
"accountId": "69eba97c3f7e15428aef8811",
"workspaceId": "67e723ed4b44a4f73dd2e8a2",
"createdAt": "2026-06-21T18:21:08.955Z",
"updatedAt": "2026-06-21T18:24:29.478Z",
"wallet": {
"id": "6a38259e7b6635a105154d11",
"address": "0x226917Bdc6d659672050E48ca6CE73dbd3A1D318",
"type": "deposit",
"protocol": "EVM",
"isEvmCompatible": true,
"name": "dev-user-4",
"userId": "69f60c8561a6152a39f39005",
"refId": "2198ddd0-4738-4ef6-b703-d1bfa79531d0",
"custodyType": "DEVELOPER",
"token": {
"name": "USD Coin",
"symbol": "USDC",
"blockchain": "BASE",
"tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
"isNative": false,
"decimals": 6,
"standard": "ERC20",
"balance": {
"value": "5",
"rawValue": "5000000"
}
}
}
}
}
}
Outgoing Transfer (pending) example
Outgoing Transfer (pending) example
{
"requestId": "04afc1dd8ffae1f6f8c66f96eed0f5",
"method": "wallets:withdraw.pending",
"params": {
"id": "6a382b941e117b9527366499",
"refId": "2a1ee011-e5b5-419e-a967-bb0a8f0626c3",
"idempotencyKey": "0e620f37-0f8a-4cee-b0e7-72235b697449",
"tokenName": "USD Coin",
"tokenSymbol": "USDC",
"tokenTicker": "USDC_BASE",
"tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
"decimals": 6,
"isNative": false,
"amount": {
"value": "5",
"rawValue": "5000000"
},
"totalAmount": {
"value": "5.028011",
"rawValue": "5028011"
},
"chainDecimals": 18,
"blockchain": "BASE",
"protocol": "EVM",
"environment": "testnet",
"network": "base-sepolia",
"txType": "outgoing",
"status": "pending",
"fromAddress": "0xda0348137a73899a156944e31c81f05f646d168c",
"toAddress": "0x226917bdc6d659672050e48ca6ce73dbd3a1d318",
"txHash": "0xee30898cdfaee9c810996756337044fd98b4b0406583dd2d5706288b97f472e5",
"totalFee": {
"value": "0.000001224105803529",
"rawValue": "1224105803529"
},
"feeLevel": "fast",
"feeToken": "ETH",
"isBatch": false,
"destinations": [
{
"address": "0x226917bdc6d659672050e48ca6ce73dbd3a1d318",
"value": "5",
"rawValue": "5000000"
},
{
"address": "0x7a750d8d6e12cce09a7c15482077a8a4d4c37de4",
"value": "0.028011",
"rawValue": "28011"
}
],
"note": null,
"triggerOrigin": "blockchain",
"confirmation": null,
"confirmed": false,
"confirmedAt": null,
"userId": "69f60c8561a6152a39f39005",
"walletId": "69f60c8561a6152a39f39005",
"accountId": "69eba97c3f7e15428aef8811",
"workspaceId": "67e723ed4b44a4f73dd2e8a2",
"createdAt": "2026-06-21T18:21:08.349Z",
"updatedAt": "2026-06-21T18:21:08.349Z",
"wallet": {
"id": "69f60c8561a6152a39f39005",
"address": "0xDA0348137A73899A156944e31C81f05F646d168c",
"type": "deposit",
"protocol": "EVM",
"isEvmCompatible": true,
"name": "user_0_Zee",
"userId": "69f60c8561a6152a39f39005",
"refId": "f3f14dcf-a233-4128-8044-5c8f03feb230",
"custodyType": "DEVELOPER",
"token": {
"name": "USD Coin",
"symbol": "USDC",
"blockchain": "BASE",
"tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
"isNative": false,
"decimals": 6,
"standard": "ERC20",
"balance": {
"value": "12.471989",
"rawValue": "12471989"
}
}
}
}
}
}
Outgoing Transfer (success) example
Outgoing Transfer (success) example
{
"requestId": "04afc1dd8ffae1f6f8c66f96eed0f5",
"method": "wallets:withdraw.success",
"params": {
"id": "6a382b941e117b9527366499",
"refId": "2a1ee011-e5b5-419e-a967-bb0a8f0626c3",
"idempotencyKey": "0e620f37-0f8a-4cee-b0e7-72235b697449",
"tokenName": "USD Coin",
"tokenSymbol": "USDC",
"tokenTicker": "USDC_BASE",
"tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
"decimals": 6,
"isNative": false,
"amount": {
"value": "5",
"rawValue": "5000000"
},
"totalAmount": {
"value": "5.028011",
"rawValue": "5028011"
},
"chainDecimals": 18,
"blockchain": "BASE",
"protocol": "EVM",
"environment": "testnet",
"network": "base-sepolia",
"txType": "outgoing",
"status": "success",
"fromAddress": "0xda0348137a73899a156944e31c81f05f646d168c",
"toAddress": "0x226917bdc6d659672050e48ca6ce73dbd3a1d318",
"txHash": "0xee30898cdfaee9c810996756337044fd98b4b0406583dd2d5706288b97f472e5",
"totalFee": {
"value": "0.000001224105803529",
"rawValue": "1224105803529"
},
"feeLevel": "fast",
"feeToken": "ETH",
"isBatch": false,
"destinations": [
{
"address": "0x226917bdc6d659672050e48ca6ce73dbd3a1d318",
"value": "5",
"rawValue": "5000000"
},
{
"address": "0x7a750d8d6e12cce09a7c15482077a8a4d4c37de4",
"value": "0.028011",
"rawValue": "28011"
}
],
"note": null,
"triggerOrigin": "blockchain",
"confirmation": "1",
"confirmed": true,
"confirmedAt": "2026-06-21T18:24:28.849Z",
"userId": "69f60c8561a6152a39f39005",
"walletId": "69f60c8561a6152a39f39005",
"accountId": "69eba97c3f7e15428aef8811",
"workspaceId": "67e723ed4b44a4f73dd2e8a2",
"createdAt": "2026-06-21T18:21:08.349Z",
"updatedAt": "2026-06-21T18:24:28.940Z",
"wallet": {
"id": "69f60c8561a6152a39f39005",
"address": "0xDA0348137A73899A156944e31C81f05F646d168c",
"type": "deposit",
"protocol": "EVM",
"isEvmCompatible": true,
"name": "user_0_Zee",
"userId": "69f60c8561a6152a39f39005",
"refId": "f3f14dcf-a233-4128-8044-5c8f03feb230",
"custodyType": "DEVELOPER",
"token": {
"name": "USD Coin",
"symbol": "USDC",
"blockchain": "BASE",
"tokenAddress": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
"isNative": false,
"decimals": 6,
"standard": "ERC20",
"balance": {
"value": "12.471989",
"rawValue": "12471989"
}
}
}
}
}
}
Swap (success) example
Swap (success) example
{
"requestId": "04afc1dd8ffae1f6f8c66f96eed0f5",
"method": "wallets:swap.success",
"params": {
"id": "6a68cfce4ee8fda4940bfad0",
"idempotencyKey": "360316a4-c6d8-4efa-a2ea-2ef5847be96e",
"refId": "whprn-1785252137197-bb3749136904",
"from": {
"token": "USDC",
"chain": "ETHEREUM",
"contractAddress": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
"amount": "6"
},
"to": {
"token": "USDC",
"chain": "ARBITRUM",
"contractAddress": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
"amount": "5.913586"
},
"amountType": "exactInput",
"slippage": "auto",
"environment": "testnet",
"status": "success",
"txHash": "0xc825ef19cefb6085aefe39a453e5f97893755f2ca0b0c1c4b061ebead711421d",
"hashOut": null,
"fee": {
"token": "USDC",
"chain": "ETHEREUM",
"decimal": "6",
"contractAddress": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
"amount": "0.031403",
"amountInUsd": "0.031399999999999997"
},
"bridgeFee": {
"token": "USDC",
"chain": "ARBITRUM",
"contractAddress": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
"amount": "0.016571",
"amountInUsd": "0.016569094334999999"
},
"triggerOrigin": "api",
"transactionGroupId": "568a808e-e0a7-4d54-ae93-4859b2e1d725",
"createdAt": "2026-07-28T15:50:37.763Z",
"updatedAt": "2026-07-28T16:05:08.167Z",
"walletId": "6a68b709637b8f5046f9e431",
"accountId": "6a4e5f0257cd222d532fd201",
"workspaceId": "68448233bdb9b58d5c9ef9e8"
}
}
Best Practices
- Idempotent Processing: Ensure your webhook handlers are idempotent to avoid duplicate processing.
- Final Events Only: Update balances only on final events, Refer to the full list of
supported eventsto identify valid final event types. - Acknowledgment: Always respond with a 2xx HTTP status code within 1 minutes to acknowledge receipt.
- Security: Verify webhook payload signatures to ensure authenticity.