商家接入 · 快速开始

前往 商家免费接入，邮箱注册并输入 6 位邮箱验证码完成验证，再添加你的网站域名并完成所有权验证（在站点根目录放置指定 HTML 文件）。

登录后在 商家中心 → 开发者：

• API Key：请求头 X-API-Key 携带。
• API Secret：仅创建时展示一次，作为 X-API-Signature = HMAC-SHA256(secret, rawBody)。
• 回调地址：CoinHub 完成打款后会 POST 到这里，事件为 payout.sent / payout.failed， 请求头 X-Webhook-Signature 用同一 secret 校验。

Secret 丢失只能轮换。不要写入前端或公开仓库。

用户在你的网站点击「用 100 硬币打赏作者」时，你的后端调用一次：

POST https://easy-coin-mart.lovable.app/api/public/merchant/charge
Content-Type: application/json
X-API-Key: ck_xxx
X-API-Signature: <hex(hmac_sha256(secret, rawBody))>

{
  "user_email": "spender@example.com",   // 在你站内消费硬币的用户
  "coins": 100,                          // 本次消费的硬币数
  "reference": "tip-2026-0001",          // 幂等键：同一值重复请求不会重复处理
  "description": "打赏文章 #1234 作者 alice@example.com"
}

成功返回 200 { ok: true, charge_id, fee_coins, net_coins, balance }。 CoinHub 会按 description 中你登记的「收款用户」把对应 USDT 直接打到对方钱包，对方无需在 CoinHub 注册。如需指定收款人，扩展字段 payee：

{
  "user_email": "spender@example.com",
  "coins": 100,
  "reference": "tip-2026-0001",
  "payee": {
    "chain": "TRC20",
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ref": "creator:alice@example.com"
  }
}

// Node.js
import crypto from "crypto";
const body = JSON.stringify({
  user_email: "spender@example.com",
  coins: 100,
  reference: "tip-2026-0001",
  payee: { chain: "TRC20", address: "TXxxx...", ref: "creator:alice" },
});
const sig = crypto.createHmac("sha256", process.env.COINHUB_SECRET)
  .update(body).digest("hex");
await fetch("https://easy-coin-mart.lovable.app/api/public/merchant/charge", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.COINHUB_KEY,
    "X-API-Signature": sig,
  },
  body,
});

# curl
BODY='{"user_email":"spender@example.com","coins":100,"reference":"tip-2026-0001"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$COINHUB_SECRET" | awk '{print $2}')
curl -X POST https://easy-coin-mart.lovable.app/api/public/merchant/charge \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $COINHUB_KEY" \
  -H "X-API-Signature: $SIG" \
  -d "$BODY"

CoinHub 完成对目标用户打款后会推送：

{
  "event": "payout.sent",
  "reference": "tip-2026-0001",
  "payee_ref": "creator:alice@example.com",
  "chain": "TRC20",
  "address": "TXxxx...",
  "amount_usdt": "13.47",
  "txid": "0xabc...",
  "fee_coins": 3,           // 你站点设置的手续费（将按月结算给你）
  "at": "2026-06-07T10:00:00Z"
}

请求头 X-Webhook-Signature = hex(hmac_sha256(callback_secret, rawBody))，X-Webhook-Event 为事件名。务必先验签再处理，否则任何人都可以伪造打款回调。

// Node.js (Express) 验签示例
import crypto from "crypto";
app.post("/coinhub/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-Webhook-Signature") ?? "";
  const expected = crypto.createHmac("sha256", process.env.COINHUB_CB_SECRET)
    .update(req.body).digest("hex");
  const ok = sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.status(401).end("bad signature");
  const evt = JSON.parse(req.body.toString("utf8"));
  // evt.event === "payout.sent" | "payout.failed"
  res.json({ ok: true });
});

打款进度也可以在 商家中心 · 打款记录 按批次查看、重试或转人工。

每一行的 code 都可点击跳转到 接入日志，按该错误码筛选你最近的真实请求。