CryptoGift API 文档

版本 v1.0 · 最后更新 2026-09-03

简介

CryptoGift API 允许开发者通过编程方式购买礼品卡、话费充值，查询订单状态和实时汇率。所有请求使用 HTTPS，数据格式为 JSON。

基础URL: https://api.cryptogift.com/v1

认证方式

所有API请求需要在Header中携带API Key：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

在会员中心申请API Key。每个Key有独立的调用限额和白名单配置。

错误处理

状态码	说明
200	请求成功
400	参数错误
401	未授权/API Key无效
402	余额不足
404	资源不存在
429	请求频率超限
500	服务器内部错误

{
  "success": false,
  "error": "Insufficient balance",
  "code": "INSUFFICIENT_BALANCE"
}

商品接口

获取商品列表

GET /products

查询参数：category 分类, country 国家, search 搜索关键词

curl -H "Authorization: Bearer KEY" https://api.cryptogift.com/v1/products?category=gaming

获取商品详情

GET /products/:id

订单接口

创建订单

POST /orders

{
  "productId": "amazon-us",
  "denomination": 50,
  "quantity": 1,
  "email": "user@example.com",
  "cryptoCurrency": "USDT",
  "callbackUrl": "https://your-site.com/webhook"
}

查询订单

GET /orders/:orderId

{
  "success": true,
  "data": {
    "orderId": "ord_xxx",
    "status": "delivered",
    "giftCardCode": "XXXX-XXXX-XXXX-XXXX",
    "giftCardPin": "1234",
    "giftCardExpiry": "2027-09-03"
  }
}

支付接口

获取支付地址

POST /payment

查询支付状态

GET /payment/:paymentId

汇率接口

GET /rates

返回所有支持币种对USD的实时汇率，每10秒更新。

GET /rates/convert?amount=100&from=USDT&to=BTC

话费充值

GET /airtime/countries

GET /airtime/operators?country=US

POST /airtime/topup

Webhook

订单状态变更时，系统会向您配置的 callbackUrl 发送POST通知：

{
  "event": "order.delivered",
  "orderId": "ord_xxx",
  "status": "delivered",
  "giftCardCode": "XXXX-XXXX-XXXX-XXXX",
  "timestamp": 1756848000000,
  "signature": "hmac_sha256_signature"
}

请使用HMAC-SHA256验证签名，密钥为您的API Secret。

官方SDK

语言	安装	状态
Node.js	`npm install @cryptogift/sdk`	✅ 已发布
Python	`pip install cryptogift`	✅ 已发布
PHP	`composer require cryptogift/sdk`	🔄 开发中
Go	`go get github.com/cryptogift/sdk-go`	🔄 开发中

入门

API接口

SDK