Coin Webhooks

⚠️ Beta Feature: Webhooks are currently in beta. While fully functional, some features are still being refined.

Monitor token balance changes for a specific Sui address.

Overview

Coin webhooks notify you when a specific address's token balance changes. This is perfect for payment systems, treasury monitoring, and real-time balance tracking.

Configuration

Field	Required	Description
Address	Yes	The address to monitor for balance changes
Coin Type	No	Specific coin type to filter (e.g., 0x2::sui::SUI). Leave empty for all coins
Webhook URL	Yes	Your HTTPS endpoint

Example Payload

{
  "payloadVersion": 1,
  "payload": {
    "activityType": "balance_change",
    "address": "0x1234abcd",
    "coinType": "0x2::sui::SUI",
    "amount": "-1000000000",
    "txDigest": "Qr9Mn3wxyz",
    "checkpoint": 12345682,
    "timestamp": 1703097700000
  }
}

Payload Fields

Field	Type	Description
activityType	string	Always balance_change
address	string	The monitored address
coinType	string	The coin type (e.g., 0x2::sui::SUI)
amount	string	Balance change amount (string for precision, can be negative)
txDigest	string	Transaction digest
checkpoint	number	Checkpoint sequence number
timestamp	number	Unix timestamp in milliseconds

Understanding Amount Values

The amount field is a string representation of the balance change:

• Positive values: Tokens received (e.g., "1000000000")
• Negative values: Tokens sent (e.g., "-1000000000")
• String format: Preserves precision for large values

💡 Token Decimals: Most tokens use 9 decimals. "1000000000" = 1 SUI. Always verify the decimal places for the specific token type.

Filtering by Coin Type

You can optionally filter for a specific coin type:

• No filter: Receive webhooks for all token balance changes
• With filter: Only receive webhooks for the specified coin type

Example coin types:

• 0x2::sui::SUI - Native SUI token

Use Cases

Payment Systems

• Confirm payment receipts in real-time
• Update order status when tokens arrive
• Trigger fulfillment on payment confirmation

Treasury Monitoring

• Track incoming and outgoing funds
• Alert on large balance changes
• Monitor multiple token types

Wallet Applications

• Show real-time balance updates
• Push notifications for incoming tokens
• Track all token movements

Token Distribution

• Monitor airdrop distributions
• Track staking reward payments
• Verify token vesting schedules

Best Practices

1. Use coin type filters when you only care about specific tokens
2. Handle negative amounts - outgoing transfers have negative amounts
3. Parse as BigInt - use BigInt for amount calculations to avoid precision loss
4. Monitor specific wallets - don't monitor high-activity addresses unless necessary

Next Steps

• Webhook Setup Guide - Endpoint requirements and signature verification
• Event Webhooks - Monitor smart contract events
• Address Webhooks - Monitor wallet activity
• Object Webhooks - Watch object mutations