Crypto Pay API 完整对接指南

Crypto Pay 是一套轻量级加密货币支付解决方案，依托 Crypto Bot 生态运行，仅需一次集成即可同时支持收款与转账功能。本文用简明中文流程带你快速跑通 Crypto Pay API，涵盖创建应用、调试接口、订阅 Webhook 等核心环节，帮助开发者与商家 30 分钟上线数字资产收付服务。

Quick Start：三步开启加密收款

创建应用： 在 Telegram 搜索 @CryptoBot，点击 Crypto Pay → 创建应用 获得专属 API Token。
开发测试： 指向沙盒环境 @CryptoTestnetBot，随时验证签名、查余额。
部署生产： 将请求域名切换至主网 https://pay.crypt.bot/api/，实时收款。

👉 用不到 10 行代码接入系统，现在就跑通你的第一笔 USDT 付款 →

API 最新变更速览

v1.5.1（2025-06-16）
fix：大额转账手续费异常；增强 transfer 方法回调稳定性。
v1.5（2024-09-11）
新增 getStats 获取流水与分析数据；支持按时间维度查询收入曲线。
v1.4（2024-06-21）
引入 Webhook 签名校验字段 crypto-pay-api-signature，提升安全性。
v1.3（2024-03-15）
新增法币汇率表，方便一键显示 CNY、EUR 等本地金额。

授权与安全：Token 与签名

要点	说明
传输协议	仅限 HTTPS，POST/GET 均可
请求头	`Crypto-Pay-API-Token: your_token_here`
签名验证	Webhook 需对 `crypto-pay-api-signature` 做 HMAC-SHA-256，密钥为 API Token 的 SHA256 哈希
测试网	域名 `https://testnet-pay.crypt.bot/api/`，Token 前缀 `TEST_`

示例 curl：

curl -X POST https://pay.crypt.bot/api/getMe \
  -H 'Crypto-Pay-API-Token: 12345:ABC'

核心接口全景图

1. 基础信息

getMe：验证 Token 并获得应用 ID、名称。
getBalance：即时查询 App 各币余额，实时掌握现金流。

2. 收款端

createInvoice：秒速创建包含 UTXO、ERC20、TRC20 地址的收款订单。
getInvoices：批量拉取订单列表，支持 status & date 过滤。
deleteInvoice：手动关闭未支付订单，释放地址池。

3. 付款端

transfer：从应用余额直接打币至用户地址，安全二次验证。
getTransfers：回溯所有转账记录，精准对账。

使用场景：在社群发红包、购物返现、佣金结算。

👉 查看完整转账操作示例与代码片段 →

4. 营销工具

createCheck：生成固定金额 礼金券，用户点击即可领取。
deleteCheck：当活动结束时可批量回收未用券码。

5. 行情与统计

getExchangeRates：自动抓取链上行情，输出 实时汇率。
getStats：汇总收入、订单量、热门资产，方便做 BI 报表。

Webhook：实时拿订单状态

在 My Apps → Webhooks 中填入 HTTPS URL。
Crypto Pay 将把 payload POST 到你配置的地址；包含订单ID、金额、状态。
强烈建议先校验签名并比对 request_date，防止重放攻击。

接收格式示例：

{
  "ok": true,
  "update": {
    "update_id": 111,
    "invoice": {
      "invoice_id": 444,
      "status": "paid",
      "amount": "150000",
      "asset": "USDT"
    }
  }
}

常见问题 (FAQ)

Q1：API Token 泄露怎么办？
A1：立即在机器人生成新 Token，旧 Token 30 分钟内失效。

Q2：哪种网络费率最低？
A2：截止今日，TRC20 USDT 单笔成本 < $0.8，速度约 1 分钟。

Q3：为什么 transfer 报 403？
A3：未在 Security → Transfers 中开启权限；开通后即可正常调用。

Q4：Webhook 可部署在 HTTP 站点吗？
A4：不可以，系统强制要求 HTTPS，且需可访问外部 443 端口。

Q5：一笔交易最多支持多少币种？
A5：getCurrencies 接口会列出全部 20+ 资产，包括 BTC、ETH、TON 等，随版本增加。

Q6：需要手续费吗？
A6：收款 0 手续费，转账时链上矿工费由 App 余额 自动扣除。

SDK 与社区库

为方便不同技术栈集成，社区已提供主流 SDK：

Node.js：@crypto-pay/sdk（Promise / TypeScript 支持）
Python：cryptopay-python（同步 & asyncio 双模式）
PHP：cryptopay-php（Laravel 封装）
Go：cryptopay-go（可内嵌 Gin 框架）
.NET：CryptoPayNet（支持 .NET 6）

提示：遇到 Bug 请直接向各仓库提 Issue，官方不直接维护第三方库。

一页速查表

创建应用 → 获取 API Token → 发送首个 getMe
生产域名：https://pay.crypt.bot/api/
所有金额单位为“最小精度整数”，如 1 USDT = 1000000
永远先做沙盒测试，确认无误再上主网

Crypto Pay 的魅力在于极小的学习成本和一笔即可上线的体验。
用 加密货币 连接全球用户，把收款变成一次三秒钟的优雅动作。