> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Withdrawal webhook events

> Withdrawal event types and the payload fields each one carries.

Learn how to listen for stablecoin events that happen on your account.

A webhook is a URL on your server where we send payloads for transaction events. For example, if you implement webhooks, we will immediately notify your server with a `deposit.success` event once a stablecoin deposit is confirmed on-chain. Whenever you receive a webhook notification from us, return a `200 OK` to avoid resending the same event again from our server.

> [!NOTE]
>
> Signature verification, retries, source IPs, and local testing work the same way for every Bitnob Business API webhook. They're covered once, on [Webhooks](https://www.bitnob.dev/api-reference/webhooks.md).

### Webhook

Stablecoin webhooks are fired when a customer sends or receives stablecoin.

### Deposit stablecoin success

This webhook is fired when a stablecoin deposit is successfully confirmed on the blockchain.

**event\_id** `string`

A unique identifier for this webhook event. Use it to de-duplicate deliveries, since the same event may be sent more than once.

**event** `string`

The webhook event type indicating a successful stablecoin deposit. In this case, it is always 'deposit.success'.

**address** `string`

The receiving wallet address where the deposit was sent. This belongs to the user or your system.

**amount** `string`

The deposit amount represented as a string in the smallest unit of the currency (e.g., '9000000' for 9 USDT).

**chain** `string`

The blockchain network where the deposit occurred (e.g., 'tron', 'bsc', 'ethereum').

**currency** `string`

The currency received in the deposit, such as 'USDT', 'USDC', etc.

**fee** `string`

The fee amount associated with the deposit, typically '0' for incoming payments.

**from\_address** `string`

The sender's wallet address that the deposit came from.

**hash** `string`

The blockchain transaction hash that uniquely identifies the deposit. Can be used to verify the transaction on a blockchain explorer.

**reference** `string`

A unique reference generated for the deposit transaction. Useful for reconciling deposits and tracking them across logs or your system.

**transaction\_id** `string`

The unique identifier of the transaction in Bitnob. Use it to look up or reconcile the deposit through the API.

**timestamp** `string`

The ISO 8601 timestamp of when the deposit was recorded, indicating when the transaction was detected on the blockchain.

```json theme={null}
{
  "event_id": "0b7d6c1e-4f3a-4b8e-9a52-1c2d3e4f5a6b",
  "event": "deposit.success",
  "data": {
    "address": "TJZCwdcH2GZRLjt8aAphrhCZtEbJLqEAfC",
    "amount": "9000000",
    "chain": "tron",
    "currency": "USDT",
    "fee": "0",
    "from_address": "TRMPscTMrXg21YuDFuvpXRUkwEbipHEZXN",
    "hash": "2426850248470ae3c24ff8ae62a5efbde325ea0c496475befb63947a65f5c122",
    "reference": "RCV_SBLNC_cc309ba8c361",
    "timestamp": "2025-12-12T20:38:23Z",
    "transaction_id": "8c3d1332-bd52-40f4-972f-768a2c4106f3"
  }
}
```

### Transfer stablecoin success

This webhook is fired when a stablecoin transfer is successfully completed on the blockchain.

> [!NOTE]
>
> The response shares the same payload structure as **Deposit Stablecoin Success**, without `from_address`. Refer to the **Deposit Stablecoin Success** section for field explanations.

```json theme={null}
{
  "event_id": "1c9e4a77-3d21-4f6b-8e10-7a2b4c6d8e90",
  "event": "transfer.success",
  "data": {
    "address": "TRMPscTMrXg21YuDFuvpXRUkwEbipHEZXN",
    "amount": "2000000",
    "chain": "tron",
    "currency": "USDT",
    "fee": "1000000",
    "hash": "4ae4308579587370accbd31dbfaebf3a97c8cfc7f68e2128ddec840349cafc60",
    "reference": "SND_SBLNC_80c7895d89e9",
    "timestamp": "2025-12-12T20:30:18Z",
    "transaction_id": "5d1f2c7a-93b4-4e0e-8a61-2b7c9e4f1a30"
  }
}
```

### Transfer stablecoin failed

This webhook is fired when a stablecoin transfer is rejected, reverted, or times out. Held funds return to your balance.

> [!NOTE]
>
> The response shares the same payload structure as **Deposit Stablecoin Success**, without `from_address`. Refer to the **Deposit Stablecoin Success** section for field explanations.

```json theme={null}
{
  "event_id": "6f3b2d18-9a47-4c55-b2e1-0d4e6f8a1b23",
  "event": "transfer.failed",
  "data": {
    "address": "TRMPscTMrXg21YuDFuvpXRUkwEbipHEZXN",
    "amount": "2000000",
    "chain": "tron",
    "currency": "USDT",
    "fee": "1000000",
    "hash": "",
    "reference": "your-transfer-reference",
    "timestamp": "2025-12-12T20:30:00Z"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.