API Reference

The XthonPay REST API lets you create invoices, check balances, process withdrawals, and receive real-time webhook notifications. All requests use HMAC-SHA256 authentication.

Authentication

All API requests must include your API key in the X-API-Key header. You can generate API keys from the Telegram bot.

For write operations, you must also include a timestamp and HMAC signature:

Headers

X-API-Key: xpk_live_xxxxxxxxxxxxxxxx
X-Timestamp: 1711324800
X-Signature: hmac_sha256(timestamp, your_secret)
        

API keys have configurable permissions and optional IP whitelisting for production security.

Base URL

All API requests should be made to:

Production

https://xthonpay.com/api/v1

Balance

GET /v1/balance

Returns the current on-chain balance of your wallet.

Response

200 OK

{
  "status": "success",
  "data": {
    "currency": "USDT",
    "balance": 14500.50,
    "address": "0x7a3B...f42d"
  }
}
          

Deposit Address

GET /v1/deposit-address

Returns your unique HD wallet deposit address on BSC.

Response

200 OK

{
  "status": "success",
  "data": {
    "address": "0x7a3B4c2d9E1f...8a6F42d",
    "network": "BSC",
    "currency": "USDT (BEP-20)"
  }
}
          

Create Invoice

POST /v1/invoices

Create a payment invoice. Once paid, your webhook will be notified.

Parameters

Name	Type	Description
amountrequired	string	Payment amount in USDT
external_idrequired	string	Your unique reference ID
callback_url	string	URL for webhook notifications
expires_in	integer	Expiry in seconds (default: 3600)

Request

POST /v1/invoices

{
  "amount": "100.00",
  "external_id": "ORDER-9921",
  "callback_url": "https://yourapp.com/webhooks/pay",
  "expires_in": 3600
}
          

Response

201 Created

{
  "status": "success",
  "data": {
    "invoice_id": "inv_8f2a3b",
    "deposit_address": "0x7a3B...f42d",
    "amount": "100.00",
    "status": "pending",
    "expires_at": "2026-03-25T15:00:00Z"
  }
}
          

Withdrawal

POST /v1/withdraw

Send USDT from your wallet to an external BSC address. Fee: FREE.

Parameters

Name	Type	Description
amountrequired	string	Amount to withdraw
to_addressrequired	string	BSC recipient address

Response

200 OK

{
  "status": "success",
  "data": {
    "withdrawal_id": "wd_4c2d1e",
    "amount": "500.00",
    "fee": "0.00",
    "to_address": "0x71C7...62b",
    "status": "processing"
  }
}
          

Webhooks

XthonPay sends webhook notifications when events occur in your account. All webhook payloads are signed with HMAC-SHA256 using your webhook secret.

Supported Events

invoice.paid — Invoice has been fully paid
deposit.confirmed — Deposit reached required confirmations
withdrawal.completed — Withdrawal tx confirmed on-chain
invoice.expired — Invoice expired without payment

Always verify the X-Xthon-Signature header before processing webhook payloads.

Payload Example

Webhook POST

{
  "id": "evt_7x291",
  "event": "invoice.paid",
  "created_at": "2026-03-25T10:00:00Z",
  "data": {
    "invoice_id": "inv_9982",
    "amount_received": 100.00,
    "tx_hash": "0xdfa...821"
  }
}
        

Error Handling

XthonPay uses standard HTTP status codes to indicate success or failure.

Code	Meaning	Description
200	Success	Request completed successfully
201	Created	Resource created successfully
401	Unauthorized	Invalid or missing API key
422	Validation Error	Invalid parameters (e.g., insufficient balance)
429	Rate Limited	Too many requests, slow down
500	Server Error	Internal error, retry with backoff