API 使用说明

1. 鉴权方式

TronSan 支持两种凭据：

• API Key：程序化调用首选，在 用户中心 → "API Key 管理" 创建。最多 10 个，创建时仅显示一次完整明文。
• JWT Token：网页登录获取，7 天有效期，适合前端直接调用。

未带凭据的请求按 IP 每日 10 次匿名额度处理。

2. HTTP 查询接口

Base URL: https://your-domain/api/v1

响应格式

// 成功
{ "code": "success", "data": { ... } }

// 失败
{ "code": "error", "msg": "具体错误(English.)" }

curl 示例：查询地址概览

curl "https://your-domain/api/v1/address/TXYZaaB...bbb" \
  -H "x-api-key: sk_live_abc123..."

Node.js 示例

const res = await fetch("https://your-domain/api/v1/address/" + addr, {
  headers: { "x-api-key": "sk_live_..." }
});
const { code, data, msg } = await res.json();
if (code !== "success") throw new Error(msg);
console.log(data.balance);

常用接口

3. WSS 实时推送

WebSocket 连接用于接收已订阅的频道事件（余额变动、授权变动、大额转账等）。 必须带 API Key 鉴权，支持 Header 或 Query 两种方式。

连接示例（浏览器 / Node.js）

// 方式 A：Query 带 key（浏览器 WebSocket 不支持自定义 header）
const ws = new WebSocket("wss://your-domain/ws?api_key=sk_live_...");

// 方式 B：Node.js 用 header（更安全，key 不会出现在日志 URL）
import WebSocket from "ws";
const ws = new WebSocket("wss://your-domain/ws", {
  headers: { "x-api-key": "sk_live_..." }
});

订阅频道

频道必须在 用户中心 → 订阅管理 先创建，WS 层只能订阅已存在的频道。

ws.onopen = () => {
  ws.send(JSON.stringify({
    action: "subscribe",
    channel: "address_balance:TXYZ...bbb"
  }));
};

ws.onmessage = (ev) => {
  const msg = JSON.parse(ev.data);
  if (msg.type === "event") {
    console.log("事件", msg.channel, msg.data);
  }
};

断开与重连

• 积分不足时服务端主动关闭，关闭码 4402
• API Key 无效或缺失：关闭码 4401
• 客户端应带指数退避重连（1s → 2s → 5s → 30s 封顶）

4. 频道与消息格式

频道名格式

<type>:<address> （全网类频道 address 填 *）

消息格式

// 订阅确认
{ "type": "subscribed", "channel": "address_balance:TXYZ..." }

// 事件推送
{
  "type": "event",
  "channel": "address_balance:TXYZ...",
  "ts": 1736123456789,
  "data": {
    "tx_hash": "abc...",
    "from": "T...",
    "to": "T...",
    "amount": "1234.56",
    "token": "USDT"
  }
}

// 错误（key 失效、积分不足、频道未订阅）
{ "type": "error", "msg": "积分不足(Not enough credits.)" }

5. 限流与计费

超过秒级速率返回 HTTP 429 RATE_LIMITED；积分耗尽返回 402。

6. 常见错误码