WhatPay API Reference

Multi-chain custody & payment API for ETH, BSC, BASE, POLYGON, TRX, and SOL

Overview

The WhatPay API allows you to integrate multi-chain cryptocurrency deposits and withdrawals into your application. All API responses use JSON and follow a consistent structure:

{
  "code": 0,        // 0 = success, non-zero = error
  "data": { ... }   // response payload
}

Each merchant project has a unique slug (e.g. acme). All API requests are scoped to your project via the base URL:

https://console.whatpay.com/{your-slug}/api/v1/...

Replace {your-slug} with the slug assigned to your project. You can find it in your console workspace URL.

Supported chains:

ETH BSC BASE POLYGON TRX SOL

API Credentials

API credentials are created in your project console under Settings → API Keys. Each key has a permission level that controls what it can do:

When a key is created, you receive three credentials — store them securely, they are shown only once:

Authentication

WhatPay supports two authentication modes. Choose at API key creation time in the console:

Both modes share the same sign-string format and replay-prevention rules. The only difference is the signature algorithm and encoding. Existing HMAC keys keep working — RSA is opt-in per key.

HMAC Mode

HMAC-SHA256 request signing. Include these headers with every request:

Signature Calculation

Build the sign string and compute HMAC-SHA256 using your api_secret:

sign_string = timestamp + "\n" + METHOD + "\n" + path_with_query + "\n" + md5(body)

signature = HMAC-SHA256(sign_string, api_secret)

Example (Node.js)

const crypto = require('crypto');

// API_SECRET is a 64-char hex string — pass it as-is, do NOT Buffer.from(secret, 'hex')
function sign(method, path, body, apiSecret) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce     = crypto.randomBytes(8).toString('hex');
  const bodyStr   = body || '';                                         // '' for GET
  const bodyMd5   = crypto.createHash('md5').update(bodyStr).digest('hex');
  const signStr   = `${timestamp}\n${method.toUpperCase()}\n${path}\n${bodyMd5}`;
  const signature = crypto.createHmac('sha256', apiSecret).update(signStr).digest('hex');
  return { 'x-app-id': APP_ID, 'x-timestamp': timestamp, 'x-nonce': nonce, 'x-signature': signature };
}

// POST example
const postBody = JSON.stringify({ user_id: 'u001' });
const headers  = sign('POST', '/v1/subaccount/create', postBody, API_SECRET);
const res = await fetch('https://console.whatpay.com/{slug}/api/v1/subaccount/create', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: postBody,
});

// GET example — pass empty string for body
const getHeaders = sign('GET', '/v1/subaccount/list?page=1&size=20', '', API_SECRET);
const res2 = await fetch('https://console.whatpay.com/{slug}/api/v1/subaccount/list?page=1&size=20', {
  method: 'GET',
  headers: getHeaders,
});

Example (Python)

import hmac as hmac_lib, hashlib, time, secrets, json

# api_secret is a 64-char hex string — encode to bytes as UTF-8, do NOT bytes.fromhex()
def sign(method, path, body, api_secret):
    ts       = str(int(time.time()))
    nonce    = secrets.token_hex(8)
    body_str = body or ''                                         # '' for GET
    body_md5 = hashlib.md5(body_str.encode()).hexdigest()
    sign_str = f"{ts}\n{method.upper()}\n{path}\n{body_md5}"
    sig      = hmac_lib.new(api_secret.encode('utf-8'), sign_str.encode('utf-8'), hashlib.sha256).hexdigest()
    return {'x-app-id': APP_ID, 'x-timestamp': ts, 'x-nonce': nonce, 'x-signature': sig}

# POST example
post_body = json.dumps({'user_id': 'u001'})
headers   = sign('POST', '/v1/subaccount/create', post_body, API_SECRET)
headers['Content-Type'] = 'application/json'

# GET example — pass empty string for body
get_headers = sign('GET', '/v1/subaccount/list?page=1&size=20', '', API_SECRET)

RSA Mode (Recommended)

RSA-SHA256 request signing. The server only stores your public key; the private key is generated and held entirely by you. Even if our database is compromised, your signing capability cannot be forged.

1. Prepare a key pair

Two options:

• In-browser (recommended): when creating the key in the console, click "Generate key pair in browser (2048)". The browser uses WebCrypto to generate the pair locally; the private key is downloaded as whatpay_private_key.pem and never leaves your machine. The public key is auto-filled in the form.
• OpenSSL on your server:

  openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out whatpay_private_key.pem
  openssl rsa -in whatpay_private_key.pem -pubout -out whatpay_public_key.pem
  # Paste the contents of whatpay_public_key.pem into the console.

2. Headers

Same four headers as HMAC mode. Only the encoding of x-signature differs.

3. Signature calculation

The sign-string is identical to HMAC mode. Only the signing primitive changes:

sign_string = timestamp + "\n" + METHOD + "\n" + path_with_query + "\n" + md5(body)

signature = base64( RSA-SHA256-sign( private_key, sign_string ) )
# RSA padding: PKCS#1 v1.5  (NOT PSS)
# Hash:        SHA-256
# Encoding:    standard base64 (with "=" padding)

4. Example (Node.js)

const crypto = require('node:crypto');
const fs     = require('node:fs');

const PRIVATE_KEY = fs.readFileSync('./whatpay_private_key.pem', 'utf8');

function sign(method, path, body) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce     = crypto.randomBytes(8).toString('hex');
  const bodyStr   = body || '';
  const bodyMd5   = crypto.createHash('md5').update(bodyStr).digest('hex');
  const signStr   = `${timestamp}\n${method.toUpperCase()}\n${path}\n${bodyMd5}`;
  const signature = crypto.sign('sha256', Buffer.from(signStr), {
    key:     PRIVATE_KEY,
    padding: crypto.constants.RSA_PKCS1_PADDING,
  }).toString('base64');
  return { 'x-app-id': APP_ID, 'x-timestamp': timestamp, 'x-nonce': nonce, 'x-signature': signature };
}

const postBody = JSON.stringify({ user_id: 'u001' });
const headers  = sign('POST', '/v1/subaccount/create', postBody);
const res = await fetch('https://console.whatpay.com/{slug}/api/v1/subaccount/create', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: postBody,
});

5. Example (Python)

Uses the cryptography library (pip install cryptography). Avoids legacy PyCrypto.

import hashlib, time, secrets, base64, json
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

with open('whatpay_private_key.pem', 'rb') as f:
    PRIVATE_KEY = serialization.load_pem_private_key(f.read(), password=None)

def sign(method, path, body):
    ts        = str(int(time.time()))
    nonce     = secrets.token_hex(8)
    body_str  = body or ''
    body_md5  = hashlib.md5(body_str.encode()).hexdigest()
    sign_str  = f"{ts}\n{method.upper()}\n{path}\n{body_md5}".encode()
    sig_bytes = PRIVATE_KEY.sign(sign_str, padding.PKCS1v15(), hashes.SHA256())
    sig       = base64.b64encode(sig_bytes).decode()
    return {'x-app-id': APP_ID, 'x-timestamp': ts, 'x-nonce': nonce, 'x-signature': sig}

post_body = json.dumps({'user_id': 'u001'})
headers   = sign('POST', '/v1/subaccount/create', post_body)
headers['Content-Type'] = 'application/json'

6. Example (Go)

package main

import (
    "crypto"
    "crypto/md5"
    "crypto/rand"
    "crypto/rsa"
    "crypto/x509"
    "encoding/base64"
    "encoding/hex"
    "encoding/pem"
    "fmt"
    "os"
    "strconv"
    "time"
)

var priv *rsa.PrivateKey

func init() {
    data, _ := os.ReadFile("whatpay_private_key.pem")
    block, _ := pem.Decode(data)
    k, _ := x509.ParsePKCS8PrivateKey(block.Bytes)
    priv = k.(*rsa.PrivateKey)
}

func sign(method, path, body string) map[string]string {
    ts := strconv.FormatInt(time.Now().Unix(), 10)
    nonce := make([]byte, 8); rand.Read(nonce)
    bodyMd5 := fmt.Sprintf("%x", md5.Sum([]byte(body)))
    signStr := ts + "\n" + method + "\n" + path + "\n" + bodyMd5
    h := crypto.SHA256.New(); h.Write([]byte(signStr))
    sigBytes, _ := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA256, h.Sum(nil))
    return map[string]string{
        "x-app-id": APP_ID, "x-timestamp": ts,
        "x-nonce": hex.EncodeToString(nonce),
        "x-signature": base64.StdEncoding.EncodeToString(sigBytes),
    }
}

7. Verifying your setup

If the server returns 40101 RSA signature verification failed, check in this order:

• Is the algorithm SHA256WithRSA with PKCS#1 v1.5 padding? PSS will not be accepted.
• Is the signature base64-encoded (with = padding)? Hex will not be accepted in RSA mode.
• Is the sign-string built with \n (LF) line breaks, not \r\n?
• Is the path exactly the server-side route (e.g. /v1/withdraw/list), without the slug prefix or query-string re-ordering?
• Has your local clock drifted more than ±300s from server time? Run ntpdate / check OS time sync.

You can dump both signature strings (client and server) for a side-by-side byte-level diff if mismatch persists — contact support with the request ID.

Error Codes

Deposit Status Flow

Every deposit goes through the following lifecycle. The status field in all deposit responses reflects the current stage.

Confirmation Thresholds by Chain

Webhooks

Configure your webhook URL when creating API credentials. WhatPay pushes deposit.credited once a deposit reaches its chain-specific confirmation threshold (see the table above). Failed deliveries are retried automatically — see Retry & idempotency.

Verify Signature (Node.js)

const crypto = require('crypto');

function verifyWebhook(req, webhookSecret) {
  const ts  = req.headers['x-timestamp'];
  const sig = req.headers['x-signature'];
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(ts + JSON.stringify(req.body))   // timestamp + raw body string
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Event: deposit.credited

Fired when the deposit reaches the chain-specific confirmation threshold (see the timing table above). This is the authoritative event — credit the user balance only when this arrives.

{
  "event": "deposit.credited",
  "data": {
    "deposit_no": "DEP-20260523-001",
    "user_id": "user_001",
    "chain": "ETH",
    "address": "0xAbC...",
    "token": "USDT",
    "amount": "100.000000000000000000",
    "tx_hash": "0x1234...",
    "block_number": "22000000",
    "confirmations": 12,
    "status": 2,
    "credited_at": 1748000180
  },
  "timestamp": 1748000180
}

Retry & Idempotency

Any non-2xx response (or connection failure) is queued for retry with exponential backoff:

After 6 failures the delivery is marked abandoned. A 30-second background sweep also rescues any deliveries that were missed (e.g. queue downtime). Use POST /v1/deposit/replay_webhook to manually replay any individual deposit.

Withdrawal Webhook Events

WhatPay sends up to five events during a withdrawal lifecycle. All events share the same signature scheme as deposit webhooks.

Event: withdraw.approved

Fired when an admin approves the withdrawal and it enters the signing queue.

{
  "event": "withdraw.approved",
  "data": {
    "withdraw_no": "WD20260525A1B2",
    "biz_order_id": "order_001",
    "chain": "ETH",
    "token": "USDT",
    "amount": "500.00",
    "to_address": "0xRecipient...",
    "tx_hash": null,
    "status": 1,
    "fail_reason": null,
    "created_at": 1748000000,
    "confirmed_at": null
  },
  "timestamp": 1748000060
}

Event: withdraw.broadcast

Fired when the signed transaction has been broadcast to the network. tx_hash is now set.

{
  "event": "withdraw.broadcast",
  "data": {
    "withdraw_no": "WD20260525A1B2",
    "biz_order_id": "order_001",
    "chain": "ETH",
    "token": "USDT",
    "amount": "500.00",
    "to_address": "0xRecipient...",
    "tx_hash": "0xabc123def456...",
    "status": 3,
    "fail_reason": null,
    "created_at": 1748000000,
    "confirmed_at": null
  },
  "timestamp": 1748000120
}

Event: withdraw.confirmed

The authoritative success event. The on-chain transaction has been confirmed. Safe to credit the recipient.

{
  "event": "withdraw.confirmed",
  "data": {
    "withdraw_no": "WD20260525A1B2",
    "biz_order_id": "order_001",
    "chain": "ETH",
    "token": "USDT",
    "amount": "500.00",
    "to_address": "0xRecipient...",
    "tx_hash": "0xabc123def456...",
    "status": 4,
    "fail_reason": null,
    "created_at": 1748000000,
    "confirmed_at": 1748000300
  },
  "timestamp": 1748000300
}

Event: withdraw.failed

Fired when signing or broadcast fails. Check fail_reason for details. Contact support if this is unexpected.

{
  "event": "withdraw.failed",
  "data": {
    "withdraw_no": "WD20260525A1B2",
    "biz_order_id": "order_001",
    "chain": "ETH",
    "token": "USDT",
    "amount": "500.00",
    "to_address": "0xRecipient...",
    "tx_hash": null,
    "status": 5,
    "fail_reason": "insufficient funds for gas",
    "created_at": 1748000000,
    "confirmed_at": null
  },
  "timestamp": 1748000130
}

Event: withdraw.rejected

Fired when an admin rejects the withdrawal request. The funds are never moved.

{
  "event": "withdraw.rejected",
  "data": {
    "withdraw_no": "WD20260525A1B2",
    "biz_order_id": "order_001",
    "chain": "ETH",
    "token": "USDT",
    "amount": "500.00",
    "to_address": "0xRecipient...",
    "tx_hash": null,
    "status": 6,
    "fail_reason": "Rejected: suspicious address",
    "created_at": 1748000000,
    "confirmed_at": null
  },
  "timestamp": 1748000090
}

Client Wallet Webhook Events

For every Client Wallet operation that reaches a final state, WhatPay pushes one webhook to your configured webhook_url. Signature scheme is the same as the deposit/withdraw webhooks (X-Signature + X-Timestamp, HMAC-SHA256 of timestamp + rawBody with webhook_secret).

Example: client.sign-message.confirmed

The only way to retrieve the raw signature asynchronously — there is no synchronous REST endpoint that returns it during signing. GET /v1/client/operations also exposes signature once the op reaches status=3, so polling is a viable fallback.

{
  "event": "client.sign-message.confirmed",
  "timestamp": 1748100000,
  "data": {
    "op_no": "op_baf50fb89523fa64234e4b7e5cec",
    "op_type": "sign-message",
    "project_id": "algowhirl",
    "wallet_id": 7,
    "from_address": "0x2531BA2fC2876f8dd712FC2Eef4e2fDA81673Eb6",
    "chain": "BASE",
    "token": null,
    "to_address": null,
    "amount": null,
    "status": 3,
    "decided_by": "auto",
    "tx_hash": null,
    "signature": "0xb00cbb8048a0c4f1e8...1b",
    "fail_reason": null,
    "created_at": 1779983462,
    "sent_at":    null,
    "confirmed_at": 1779983463
  }
}

Example: client.transfer.confirmed

{
  "event": "client.transfer.confirmed",
  "timestamp": 1748100120,
  "data": {
    "op_no": "op_d5430c5081c4e99a6868540b3ee8",
    "op_type": "transfer",
    "project_id": "algowhirl",
    "wallet_id": 7,
    "from_address": "0x2531BA2fC2876f8dd712FC2Eef4e2fDA81673Eb6",
    "chain": "BASE",
    "token": "USDC",
    "to_address": "0xRecipient...",
    "amount": "12.500000",
    "status": 3,
    "decided_by": "session_key",
    "tx_hash": "0xabc123def456...",
    "signature": null,
    "fail_reason": null,
    "created_at": 1779983460,
    "sent_at":    1779983464,
    "confirmed_at": 1779983478
  }
}

Example: client.send-tx.failed

{
  "event": "client.send-tx.failed",
  "timestamp": 1748100200,
  "data": {
    "op_no": "op_1cafaf1ca1319f03797befa92d44",
    "op_type": "send-tx",
    "project_id": "algowhirl",
    "wallet_id": 7,
    "from_address": "0x2531BA2fC2876f8dd712FC2Eef4e2fDA81673Eb6",
    "chain": "BASE",
    "token": null,
    "to_address": "0xContract...",
    "amount": null,
    "status": 4,
    "decided_by": "auto",
    "tx_hash": null,
    "signature": null,
    "fail_reason": "insufficient funds for gas",
    "created_at": 1779983470,
    "sent_at":    null,
    "confirmed_at": null
  }
}

System Endpoints

{ "code": 0, "data": { "status": "ok", "time": "2026-05-23T10:00:00.000Z" } }

{
  "code": 0,
  "data": [
    { "chain": "ETH",  "chain_id": 1,    "native_token": "ETH",  "confirmations": 12, "block_time": 12 },
    { "chain": "BSC",  "chain_id": 56,   "native_token": "BNB",  "confirmations": 15, "block_time": 3  },
    { "chain": "BASE", "chain_id": 8453, "native_token": "ETH",  "confirmations": 15, "block_time": 2  },
    { "chain": "POLYGON","chain_id": 137,"native_token": "MATIC","confirmations": 30, "block_time": 2  },
    { "chain": "TRX",  "chain_id": null, "native_token": "TRX",  "confirmations": 20, "block_time": 3  },
    { "chain": "SOL",  "chain_id": null, "native_token": "SOL",  "confirmations": 32, "block_time": 1  }
  ]
}

{
  "code": 0,
  "data": [
    { "chain": "ETH", "token": "USDT", "token_address": "0xdAC17F...", "decimals": 6, "is_native": 0, "min_deposit": "1.000000" },
    { "chain": "ETH", "token": "ETH",  "token_address": null,          "decimals": 18,"is_native": 1, "min_deposit": "0.001000" }
  ]
}

Sub-account Endpoints

POST /v1/subaccount/create
Content-Type: application/json

{ "user_id": "user_001", "label": "Alice" }

{
  "code": 0,
  "data": {
    "account_no": "WP-BE0A-7C3D-R2",
    "sub_account_id": 15,
    "user_id": "user_001",
    "addresses": {
      "EVM": "0xbE0A19E174aAdC6f06952F2299A082B04ac17C3d",
      "TRX": "TXkxBEEQqKFrQL3m2LCsoVDvuRDGLyK7MY",
      "SOL": "4SkUmubQKFPaauHTAoZ9G3iqMphQyVWX2aJvMtpPaDhA"
    }
  }
}

{
  "code": 0,
  "data": {
    "account_no": "WP-BE0A-7C3D-R2",
    "sub_account_id": 15,
    "user_id": "user_001",
    "addresses": {
      "EVM": "0xbE0A19E174aAdC6f06952F2299A082B04ac17C3d",
      "TRX": "TXkxBEEQqKFrQL3m2LCsoVDvuRDGLyK7MY",
      "SOL": "4SkUmubQKFPaauHTAoZ9G3iqMphQyVWX2aJvMtpPaDhA"
    }
  }
}

{
  "code": 0,
  "data": {
    "total": 2,
    "page": 1,
    "size": 20,
    "list": [
      {
        "id": 15,
        "sub_index": 1,
        "account_no": "WP-BE0A-7C3D-R2",
        "user_ref": "user_001",
        "label": "Alice",
        "addresses": {
          "EVM": "0xbE0A19E174aAdC6f06952F2299A082B04ac17C3d",
          "TRX": "TXkxBEEQqKFrQL3m2LCsoVDvuRDGLyK7MY",
          "SOL": "4SkUmubQKFPaauHTAoZ9G3iqMphQyVWX2aJvMtpPaDhA"
        }
      }
    ]
  }
}

Address Endpoints

{
  "code": 0,
  "data": { "chain": "ETH", "address": "0xAbc...", "token": "USDT", "balance": "1250.50" }
}

Deposit Endpoints

{
  "code": 0,
  "data": {
    "total": 1,
    "list": [
      {
        "deposit_no": "DEP-20260523-001",
        "user_id": "user_001",
        "chain": "ETH",
        "address": "0xAbc...",
        "token": "USDT",
        "amount": "100.00",
        "tx_hash": "0x1234...",
        "block_number": "22000000",
        "confirmations": 12,
        "status": 2,
        "created_at": 1747994400,
        "credited_at": 1747994520
      }
    ]
  }
}

{
  "code": 0,
  "data": {
    "deposit_no": "DEP-20260523-001",
    "user_id": "user_001",
    "chain": "ETH",
    "address": "0xAbc...",
    "token": "USDT",
    "amount": "100.00",
    "tx_hash": "0x1234...",
    "block_number": "22000000",
    "confirmations": 12,
    "status": 2,
    "created_at": 1747994400,
    "credited_at": 1747994520
  }
}

POST /v1/deposit/replay_webhook
Content-Type: application/json

{ "deposit_no": "DEP-20260523-001" }

{ "code": 0, "message": "Queued" }

Withdrawal Flow

Every withdrawal request goes through a risk-tiered approval workflow before the transaction is signed and broadcast.

Approval Levels

Withdrawal Endpoints

HTTP 409
{
  "code": 40902,
  "message": "Withdraw bizOrderId already used by failed record (withdrawNo=WD..., lastFailReason=...). Please retry with a new bizOrderId."
}

POST /v1/withdraw/apply
Content-Type: application/json

{
  "biz_order_id": "order_20260523_001",
  "chain": "ETH",
  "token": "USDT",
  "to_address": "0xRecipientAddress...",
  "amount": "100.00"
}

{
  "code": 0,
  "data": {
    "withdraw_no": "WD-20260523-001",
    "status": 0,
    "level": 1,
    "created_at": 1748000000
  }
}

{
  "code": 0,
  "data": {
    "withdraw_no": "WD-20260523-001",
    "biz_order_id": "order_20260523_001",
    "chain": "ETH",
    "token": "USDT",
    "to_address": "0xRecipientAddress...",
    "amount": "100.00",
    "amount_usd": 100.00,
    "status": 4,
    "level": 1,
    "tx_hash": "0xabc123...",
    "memo": null,
    "created_at": 1748000000,
    "confirmed_at": 1748000500
  }
}

POST /v1/withdraw/cancel
Content-Type: application/json

{ "biz_order_id": "order_20260523_001" }

{ "code": 0, "message": "Cancelled" }

{
  "code": 0,
  "data": {
    "total": 2,
    "list": [
      {
        "withdraw_no": "WD-20260523-001",
        "biz_order_id": "order_20260523_001",
        "chain": "ETH",
        "token": "USDT",
        "to_address": "0xRecipient...",
        "amount": "100.00",
        "status": 4,
        "level": 1,
        "tx_hash": "0xabc123...",
        "created_at": 1747994400,
        "confirmed_at": 1747994700
      }
    ]
  }
}

Swap & Bridge API

Give your end-users in-app token swap directly from their WhatPay sub-account wallets. Internally we aggregate quotes from KyberSwap (same-chain EVM swap) and route the trade end-to-end: report quote → execute on-chain → confirm → push swap.* webhook events.

Flow

┌────────────┐    quote     ┌────────────┐    execute   ┌────────────┐
│  Customer  │ ────────────▶│  WhatPay   │ ────────────▶│  WhatPay   │
│  business  │              │   Quote    │              │  Executor  │
│   system   │ ◀────────────│  (5 min)   │              │ (broadcast)│
└────────────┘   route_id   └────────────┘              └────────────┘
                                                              │
                                                              │ swap.broadcast / confirmed / failed
                                                              ▼
                                                       Your webhook URL

Status machine

{
  "code": 0,
  "data": {
    "chain": "BSC",
    "tokens": [
      {"symbol":"BNB","address":"0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE","decimals":18,"isNative":true},
      {"symbol":"USDT","address":"0x55d398326f99059fF775485246999027B3197955","decimals":18},
      {"symbol":"USDC","address":"0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d","decimals":18}
    ]
  }
}

curl -X POST https://api.whatpay.com/v1/swap/quote \
  -H "X-App-Id: app_xxx" -H "X-Timestamp: ..." -H "X-Nonce: ..." -H "X-Signature: ..." \
  -H "X-Project-Slug: algowhirl" -H "Content-Type: application/json" \
  -d '{
    "from_chain":"BSC","from_token":"USDT",
    "to_chain":"BSC","to_token":"USDC",
    "amount_in":"1","from_address":"0x52...","slippage_bps":50
  }'

# Response
{
  "code": 0,
  "data": {
    "route_id": "rt_c7dd9179f7dac5e4e1923078",
    "provider": "KyberSwap",
    "from_chain": "BSC", "from_token": "USDT", "from_token_address": "0x55d...",
    "to_chain": "BSC",   "to_token": "USDC",   "to_token_address": "0x8AC...",
    "amount_in": "1", "amount_in_raw": "1000000000000000000",
    "amount_out_expected": "0.998884",
    "amount_out_min": "0.988895",
    "amount_in_usd": 1.0011, "amount_out_usd": 1.0011, "gas_usd": 0.098,
    "slippage_bps": 50,
    "router_address": "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5",
    "expires_at": 1780499620
  }
}

{
  "code": 0,
  "data": {
    "swap_no": "SWMPY7BO7LF65B0CD4",
    "biz_order_id": "swap_2026060401",
    "status": 0,
    "provider": "KyberSwap",
    "from_chain": "BSC", "from_token": "USDT", "to_token": "USDC",
    "amount_in": "1",
    "amount_out_expected": "0.998884",
    "amount_out_min": "0.988895",
    "slippage_bps": 50,
    "created_at": 1780499320
  }
}

{
  "code": 0,
  "data": {
    "swap_no": "SWMPY7BO7LF65B0CD4",
    "biz_order_id": "swap_2026060401",
    "from_chain": "BSC", "from_token": "USDT",
    "to_chain": "BSC", "to_token": "USDC",
    "from_address": "0x52...", "to_address": "0x52...",
    "amount_in": "1", "amount_out_expected": "0.998884",
    "amount_out_min": "0.988895", "amount_out_actual": "0.998910",
    "slippage_bps": 50,
    "provider": "KyberSwap", "status": 3,
    "src_tx_hash": "0xab12...",
    "dest_tx_hash": null,
    "gas_cost_usd": "0.082",
    "created_at": 1780499320, "signed_at": 1780499322,
    "sent_at": 1780499325, "confirmed_at": 1780499335
  }
}

{ "code": 0, "data": { "total": 42, "list": [ ... ], "page": 1, "size": 20 } }

Swap Webhooks

Three events are pushed to your webhook_url as a swap progresses. Same HMAC signature scheme as deposit/withdraw webhooks (X-Signature = HMAC-SHA256(timestamp + rawBody, webhook_secret)).

Example payload (swap.confirmed)

{
  "event": "swap.confirmed",
  "timestamp": 1780499336,
  "data": {
    "swap_no": "SWMPY7BO7LF65B0CD4",
    "biz_order_id": "swap_2026060401",
    "provider": "KyberSwap",
    "from_chain": "BSC", "from_token": "USDT", "amount_in": "1",
    "to_chain": "BSC", "to_token": "USDC", "amount_out_actual": "0.998910",
    "src_tx_hash": "0xab12...",
    "status": 3,
    "confirmed_at": 1780499335
  }
}

Error Codes (Swap-specific)

Client Wallet API

The Client API lets your application drive the wallet directly: send transfers, sign messages / EIP-712 typed data, and call arbitrary contracts. Useful when you want to embed wallet operations into your own product without going through the withdrawal approval flow.

All endpoints under /v1/client/* require the same HMAC authentication as the rest of the API. Operations are tied to the wallet bound to your API credential (wallet_id).

Operation status

Session Key

A session key is a pre-authorized signing right. The user (admin with approve permission) creates a key bound to a scope — chains, contract addresses, function selectors, native-token transfer policy, per-tx and daily USD caps. Any operation that fits the scope is signed without manual approval.

Scope fields

risk_reason values (when an operation lands as pending)

Wallet Endpoints

{
  "code": 0,
  "data": {
    "project_id": "proj_default",
    "wallet_id": 2,
    "addresses": [
      { "chain": "EVM", "address": "0x2531BA2fC2876f8dd712FC2Eef4e2fDA81673Eb6", "addr_index": 0 },
      { "chain": "TRX", "address": "TVYnQWsmDiM2AtxYooreYgYgtgRdEN3Kfu", "addr_index": 0 },
      { "chain": "SOL", "address": "7RaqwuvBzmEqWbfqGZiEUYdxfuMefXPHp4k1jaAzmdrR", "addr_index": 0 }
    ]
  }
}

{ "code": 0, "data": {
  "op_no": "op_871391ae831bdd3dfe03bcaf2535",
  "status": "queued",
  "decided_by": "session_key",
  "amount_usd": 12.5
} }

{ "code": 0, "data": {
  "op_no": "op_xxxx",
  "status": "pending",
  "decided_by": "pending",
  "risk_reason": "no_session_key",
  "expires_at": 1779964456
} }

POST /v1/client/send-tx
{
  "chain": "BASE",
  "to": "0xUniswapV3Router...",
  "value": "0x0",
  "data": "0xa9059cbb000000000000000000000000..."
}

{
  "op_no": "op_871391ae...",
  "op_type": "sign-message",
  "status": 3,
  "signature": "0xb00cbb8048b8a9efd7f7e5d297d887dab4c0bf66c69dbef9aa1fbd814f..."
}

POST /v1/client/sign-typed-data
{
  "chain": "BASE",
  "domain": { "name":"USD Coin", "version":"2", "chainId":8453,
              "verifyingContract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
  "types": {
    "Permit": [
      {"name":"owner","type":"address"},
      {"name":"spender","type":"address"},
      {"name":"value","type":"uint256"},
      {"name":"nonce","type":"uint256"},
      {"name":"deadline","type":"uint256"}
    ]
  },
  "primaryType": "Permit",
  "message": {
    "owner": "0x2531BA2fC2876f8dd712FC2Eef4e2fDA81673Eb6",
    "spender": "0xRouter...",
    "value": "1000000",
    "nonce": "0",
    "deadline": "1799999999"
  }
}

{ "code": 0, "data": { "list": [
  {
    "op_no": "op_xxx", "op_type": "transfer",
    "chain": "BASE", "token": "USDC",
    "to_address": "0x...", "amount": "12.5", "amount_usd": "12.5000",
    "decided_by": "session_key",
    "status": 3,
    "tx_hash": "0xabc...",
    "signature": "0xb00cbb...",
    "fail_reason": null,
    "created_at": 1779931489,
    "sent_at":    1779931493,
    "confirmed_at": 1779931499
  }
] } }

Session Key Endpoints

POST /v1/client/session-keys
{
  "name": "OpenSea listings",
  "scope": {
    "chains": ["BASE"],
    "allow_contracts": ["0x0000000000000068f116a894984e2db1123eb395"],
    "allow_selectors": ["0xa9059cbb"],
    "deny_native": 1
  },
  "max_per_tx_usd": 100,
  "daily_cap_usd": 500,
  "ttl_days": 30
}

{ "code": 0, "data": {
  "sk_id": "sk_033a4e2f1919aef3425a6d2d36234d3a3f9b",
  "expires_at": "2026-06-25T12:24:16.325Z"
} }

{ "code": 0 }

TRX Energy Service

Platform-managed TRX energy rental for all your TRC20 outbound transactions (sweep / withdraw / client-tx). After subscribing, you receive a project-specific TRX deposit address; any TRX you send there is automatically forwarded to the platform's GasStation account and credited to your internal balance. The platform then pays for energy on every TRC20 transfer you do, saving ~87% vs burning TRX. Subscribe once via POST /v1/energy/subscribe; the rest are read-only.

POST /v1/energy/subscribe
{
  "low_balance_threshold": "50",       // optional, TRX, default 50
  "notify_webhook_url": "https://..."  // optional, for future low-balance alerts
}

{
  "code": 0,
  "data": {
    "project_id":      "proj_xxxxxxxx",
    "deposit_address": "TEdFXUbhAEkVmYo8e9FjENvTpJeMcq3TT2",
    "enabled":         true,
    "balance_trx":     "0"
  }
}

{
  "code": 0,
  "data": {
    "project_id":             "proj_xxxxxxxx",
    "enabled":                1,
    "deposit_address":        "TEdFXUbhAE...",
    "balance_trx":            "85.342500",
    "total_topup_trx":        "200.000000",
    "total_consumed_trx":     "114.657500",
    "low_balance_threshold":  "50.000000",
    "notify_webhook_url":     null,
    "created_at":             "2026-05-28 17:25:00"
  }
}

{
  "code": 0,
  "data": {
    "balance_trx":  "85.342500",
    "low_balance":  false,
    "enabled":      true
  }
}

{
  "code": 0,
  "data": {
    "list": [
      {
        "id":              1,
        "amount_trx":      "50.000000",
        "tx_hash":         "abc...",
        "settled_tx_hash": "def...",
        "status":          1,
        "block_time":      "2026-05-28 18:00:00",
        "created_at":      "2026-05-28 18:00:05"
      }
    ],
    "total": 1, "page": 1, "limit": 20
  }
}

{
  "code": 0,
  "data": {
    "list": [
      {
        "id":               42,
        "business_type":    "withdraw",
        "business_ref":     "wd_12345",
        "receive_address":  "THqUhi...",
        "energy_amount":    64400,
        "duration_code":    "10010",
        "cost_trx":         "1.752000",
        "status":           1,
        "gas_trade_no":     "GAS09442733",
        "created_at":       "2026-05-28 20:20:30"
      }
    ],
    "total": 142, "page": 1, "limit": 20
  }
}

{
  "code": 0,
  "data": [
    {
      "id":                    1,
      "wallet_id":             7,
      "enabled":               1,
      "dest_sub_account_id":   35,
      "dest_address":          "THqUhi...",
      "min_usd":               "5.00",
      "duration_code":         "10010",
      "fallback_burn_enabled": 0,
      "fallback_burn_trx":     "30"
    }
  ]
}

{ "code": 0, "data": { "ok": true } }

How Energy Costs Are Calculated

• Recipient already holds the TRC20 token (warm): 64,400 energy ≈ 1.75 TRX (10-min rental)
• Recipient never held it (cold): 130,400 energy ≈ 3.50 TRX (10-min rental)
• Sender already has staked energy: 0 cost — no rental placed
• Same sender within 10 minutes of a successful rental: 0 cost — energy is still delegated

Compared with burning TRX (~13.5 TRX warm, ~27 TRX cold), this saves ~87% on every TRC20 outbound.

WhatPay API v1  ·  Need help? Contact your account manager.