Integration Guide

Quick Start

Getting started with XthonPay takes under 5 minutes. Here's the complete flow:

Create Your Account

Open @XthonPayBot on Telegram and press Start. Your unique HD wallet address is generated automatically.

Generate API Keys

Navigate to the API Keys section in the bot menu. Create a key pair with the permissions you need (read, write, webhooks).

Create an Invoice

Use the API to create a payment invoice. The response includes a deposit address your customer should pay to.

Handle Webhooks

Authentication Setup

All API requests require HMAC-SHA256 authentication. Here's how to sign your requests:

Python - Request Signing

import hmac, hashlib, time, requests

API_KEY = "xpk_live_your_key_id"
SECRET  = "xps_live_your_secret"
BASE    = "https://xthonpay.com/api/v1"

def make_request(method, path, body=None):
    ts = str(int(time.time()))
    sig = hmac.new(
        SECRET.encode(),
        ts.encode(),
        hashlib.sha256
    ).hexdigest()

    headers = {
        "X-API-Key": API_KEY,
        "X-Timestamp": ts,
        "X-Signature": sig,
    }

    if method == "GET":
        return requests.get(BASE + path, headers=headers)
    return requests.post(BASE + path, json=body, headers=headers)
      

Creating an Invoice

To accept a payment, create an invoice with the amount and an optional callback URL:

Python - Create Invoice

# Create a $50 USDT invoice
resp = make_request("POST", "/invoices", {
    "amount": "50.00",
    "external_id": "order_12345",
    "callback_url": "https://yourapp.com/webhooks/pay"
})

data = resp.json()
deposit_address = data["data"]["deposit_address"]
print(f"Customer should send to: {deposit_address}")
      

Show the deposit_address to your customer. Once they send the USDT, our scanner detects it within 15 seconds.

Handling Webhooks

When a payment is confirmed, XthonPay sends a POST request to your callback_url. Always verify the signature before processing.

Python - Webhook Handler (Flask)

from flask import Flask, request
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret"

@app.route("/webhooks/pay", methods=["POST"])
def handle_webhook():
    # Verify signature
    signature = request.headers.get("X-Xthon-Signature")
    payload = request.get_data()
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload, hashlib.sha256
    ).hexdigest()

    if signature != expected:
        return "Invalid signature", 401

    # Process the event
    event = request.json
    if event["event"] == "invoice.paid":
        order_id = event["data"]["external_id"]
        # Mark order as paid in your database
        fulfill_order(order_id)

    return "OK", 200
      

Always verify the HMAC signature before trusting webhook payloads. Never process unverified requests.

Checking Balance

Query your on-chain wallet balance at any time:

Python

resp = make_request("GET", "/balance")
balance = resp.json()["data"]["balance"]
print(f"Current balance: {balance} USDT")
      

Requesting a Withdrawal

Send USDT from your wallet to any BSC address. Withdrawals are free (only standard gas applies).

Python

resp = make_request("POST", "/withdraw", {
    "amount": "100.00",
    "to_address": "0x71C765...62b"
})

wd = resp.json()["data"]
print(f"Withdrawal {wd['withdrawal_id']}: {wd['status']}")
      

Best Practices

Always verify webhooks — Check the HMAC-SHA256 signature on every incoming webhook request.
Use idempotency keys — Include unique keys in your requests to prevent duplicate transactions.
Store API keys securely — Use environment variables, never commit keys to source code.
Enable IP whitelisting — Restrict your API keys to specific server IPs for production.
Handle retries gracefully — Webhooks may be delivered more than once. Make your handler idempotent.

For the full API reference including all parameters, response formats, and error codes, see the API Documentation.

Start accepting payments