← Back to Home

API Documentation

CryptoGate 加密支付网关 RESTful API。支持 BSC 和 Polygon 链的 USDT/USDC 收付款。

Base URL: https://your-domain.com
认证: 在请求头中传入 X-API-Key: your_api_key（如未配置 API_KEYS 环境变量则免认证）

认证

所有写操作和敏感读接口需要 API Key 认证。在请求头中传入：

X-API-Key: your_api_key
// 或
Authorization: Bearer your_api_key

以下接口无需认证：GET /api/health、GET /api/chains

快速开始

3 步完成支付接入：

# 1. 创建发票
curl -X POST https://your-domain.com/api/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"chainId":"bsc","tokenSymbol":"USDT","amount":100}'

# 2. 返回支付地址和精确金额，引导用户转账
# response.data.deposit_address → 收款地址
# response.data.payment_amount   → 用户需支付的精确金额（含随机后缀）
# response.checkoutUrl           → 托管收银台页面

# 3. 系统自动检测到账，回调通知你的服务器

接口列表

GET/api/health

服务健康检查，无需认证。

响应示例：

{
  "status": "ok",
  "service": "CryptoGate",
  "version": "2.1.0",
  "chains": ["bsc", "polygon"],
  "tokens": ["USDT", "USDC"],
  "database": "connected",
  "wallet": "0xE2eb...",
  "auth": "enabled",
  "timestamp": "2026-05-31T12:00:00.000Z"
}
GET/api/chains

获取支持的链和代币信息，无需认证。

{
  "data": [
    {
      "id": "bsc",
      "name": "BNB Smart Chain",
      "chainId": 56,
      "nativeSymbol": "BNB",
      "tokens": [
        { "symbol": "USDT", "address": "0x55d3...", "decimals": 18 },
        { "symbol": "USDC", "address": "0x8AC7...", "decimals": 18 }
      ]
    },
    {
      "id": "polygon",
      "name": "Polygon PoS",
      "chainId": 137,
      "nativeSymbol": "MATIC",
      "tokens": [
        { "symbol": "USDT", "address": "0xc213...", "decimals": 6 },
        { "symbol": "USDC", "address": "0x2791...", "decimals": 6 }
      ]
    }
  ]
}
POST/api/invoices

创建支付发票。系统会在金额末尾附加随机小数（6位）作为订单标识，用户需按精确金额转账。

请求参数

参数类型必填说明
chainIdstring必填链 ID：bsc 或 polygon
tokenSymbolstring必填代币：USDT 或 USDC
amountnumber必填收款金额（整数部分），如 100
externalIdstring可选你的业务订单号
callbackUrlstring可选支付确认后的回调地址

请求示例

curl -X POST https://your-domain.com/api/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "chainId": "bsc",
    "tokenSymbol": "USDT",
    "amount": 100,
    "externalId": "ORDER-12345",
    "callbackUrl": "https://your-site.com/callback"
  }'

响应示例

{
  "data": {
    "id": "inv_mptt1ata_yj033g",
    "external_id": "ORDER-12345",
    "chain_id": "bsc",
    "token_symbol": "USDT",
    "amount": "100.00000000",
    "payment_amount": "100.00075231",
    "received_amount": "0.00000000",
    "deposit_address": "0xE2ebdf2c5f2cb2A6bC440643E52d6f6f1fdd9DE2",
    "status": "pending",
    "tx_hash": null,
    "callback_url": "https://your-site.com/callback",
    "created_at": "2026-05-31T12:00:00.000Z",
    "expires_at": "2026-05-31T13:00:00.000Z"
  },
  "checkoutUrl": "/checkout.html?id=inv_mptt1ata_yj033g"
}
关键字段说明：
deposit_address — 用户转账的目标地址
payment_amount — 用户必须支付的精确金额（含随机后缀，用于标识订单）
checkoutUrl — 可直接引导用户打开的托管收银台页面
发票有效期 60 分钟，超时自动标记为 expired
GET/api/invoices/:id

查询单个发票详情。

响应状态说明

状态说明
pending等待支付
confirmed已确认到账
expired超时未支付（60分钟）
GET/api/invoices?limit=20&offset=0

查询发票列表。

参数类型默认说明
limitnumber20每页条数，最大 100
offsetnumber0偏移量
POST/api/payouts

发起代币提现，从主钱包向指定地址转账。

请求参数

参数类型必填说明
chainIdstring必填链 ID
tokenSymbolstring必填代币符号
addressstring必填接收地址（0x 开头）
amountnumber必填提现金额
callbackUrlstring可选回调地址
curl -X POST https://your-domain.com/api/payouts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "chainId": "bsc",
    "tokenSymbol": "USDT",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "amount": 50
  }'
GET/api/payouts?limit=20&offset=0

查询提现列表。

GET/api/transactions?limit=20&offset=0

查询所有交易记录（充值 + 提现）。

GET/api/balances

查询主钱包在各链上的代币余额和 Gas 余额。

{
  "data": [
    {
      "chainId": "bsc",
      "chainName": "BNB Smart Chain",
      "tokenSymbol": "USDT",
      "tokenBalance": 10.98,
      "nativeBalance": "0.016037",
      "nativeSymbol": "BNB",
      "address": "0xE2eb..."
    }
  ]
}
GET/api/stats

查询统计概览。

回调通知

创建发票时如果传了 callbackUrl，系统在确认到账后会向该地址发送 POST 请求：

POST https://your-site.com/callback
Content-Type: application/json

{
  "event": "invoice.confirmed",
  "data": {
    "id": "inv_mptt1ata_yj033g",
    "externalId": "ORDER-12345",
    "chainId": "bsc",
    "tokenSymbol": "USDT",
    "amount": 100,
    "paymentAmount": 100.00075231,
    "receivedAmount": 100.00075231,
    "txHash": "0xabc123...",
    "status": "confirmed",
    "createdAt": "2026-05-31T12:00:00.000Z",
    "confirmedAt": "2026-05-31T12:05:00.000Z"
  }
}
回调说明：系统会尝试发送回调，不保证 100% 送达。建议同时使用 GET /api/invoices/:id 主动轮询确认状态。

支付流程图

商户系统                    CryptoGate                    用户
   │                           │                           │
   │  POST /api/invoices       │                           │
   │ ─────────────────────────>│                           │
   │  返回 deposit_address     │                           │
   │  和 payment_amount        │                           │
   │ <─────────────────────────│                           │
   │                           │                           │
   │  展示支付地址和金额       │                           │
   │ ─────────────────────────────────────────────────────>│
   │                           │         转账 payment_amount│
   │                           │<──────────────────────────│
   │                           │                           │
   │                           │  检测到账（15s轮询）      │
   │                           │  匹配金额 → 确认          │
   │                           │                           │
   │  回调通知 invoice.confirmed│                           │
   │ <─────────────────────────│                           │
   │                           │                           │
   │  GET /api/invoices/:id    │                           │
   │ ─────────────────────────>│                           │
   │  status = confirmed       │                           │
   │ <─────────────────────────│                           │
   │                           │                           │
   │  发货/完成订单            │                           │
   │                           │                           │

错误码

HTTP 状态码说明
400参数错误（缺少必填字段、不支持的链/代币、金额无效等）
401未认证或 API Key 无效
404资源不存在
500服务器内部错误

SDK 示例

Node.js

const BASE = 'https://your-domain.com';
const API_KEY = 'your_api_key';

async function createInvoice(chainId, tokenSymbol, amount, externalId) {
  const res = await fetch(`${BASE}/api/invoices`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({ chainId, tokenSymbol, amount, externalId }),
  });
  return res.json();
}

async function getInvoice(id) {
  const res = await fetch(`${BASE}/api/invoices/${id}`, {
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

// 使用
const { data } = await createInvoice('bsc', 'USDT', 100, 'ORDER-001');
console.log('支付地址:', data.deposit_address);
console.log('精确金额:', data.payment_amount);
console.log('收银台:', `${BASE}${checkoutUrl}`);

Python

import requests

BASE = 'https://your-domain.com'
API_KEY = 'your_api_key'
HEADERS = {'X-API-Key': API_KEY, 'Content-Type': 'application/json'}

def create_invoice(chain_id, token_symbol, amount, external_id=None):
    body = {'chainId': chain_id, 'tokenSymbol': token_symbol, 'amount': amount}
    if external_id:
        body['externalId'] = external_id
    return requests.post(f'{BASE}/api/invoices', json=body, headers=HEADERS).json()

def get_invoice(invoice_id):
    return requests.get(f'{BASE}/api/invoices/{invoice_id}', headers=HEADERS).json()

# 使用
result = create_invoice('bsc', 'USDT', 100, 'ORDER-001')
print('支付地址:', result['data']['deposit_address'])
print('精确金额:', result['data']['payment_amount'])