主题
06 · 附录：枚举、精度与错误码
1. 网络 ID
network_id | 名称 | 类型 | 生产环境 |
|---|---|---|---|
1 | Ethereum Mainnet | EVM | ✅ 已开通 |
56 | BSC Mainnet | EVM | ✅ 已开通 |
4 | TRX（TRON 主网） | TRON | ✅ 已开通 |
11155111 | Sepolia | EVM | ❌ 测试网，生产未启用 |
97 | BSC Testnet | EVM | ❌ 测试网，生产未启用 |
5 | TRX Shasta | TRON | ❌ 测试网，生产未启用 |
0 | All（仅用于查询过滤） | — | — |
实时确认：
curl https://linkepay-api.bestxx.com/api/v1/public/networks⚠️ 早期文档中出现过 BSC Mainnet =
66、BSC Testnet =67的写法，那是旧版 SDK 常量， 服务端实际使用的是56/97，请以本表为准。
确认数
| 网络 | 确认区块数 |
|---|---|
| Ethereum Mainnet | 6 |
| BSC Mainnet | 6 |
| TRON | 6 |
2. 币种 ID
asset_id | asset_name | 说明 |
|---|---|---|
1 | usdc | USDC |
2 | usdt | USDT |
3 | native | 原生币（ETH / BNB / TRX） |
0 | All | 仅用于查询过滤 |
生产环境合约地址
| 网络 | 币种 | 合约地址 |
|---|---|---|
| Ethereum Mainnet | USDC | 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 |
| Ethereum Mainnet | USDT | 0xdac17f958d2ee523a2206206994597c13d831ec7 |
| BSC Mainnet | USDC | 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d |
| BSC Mainnet | USDT | 0x55d398326f99059fF775485246999027B3197955 |
| TRON | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
TRON 主网目前只支持 USDT。
3. 金额精度（decimals）
结算时平台使用下表精度把可读金额换算成最小单位：
| 网络 | USDC | USDT | 原生币 |
|---|---|---|---|
| Ethereum Mainnet | 6 | 6 | 18 |
| BSC Mainnet | 18 | 18 | 18 |
| TRON | 6 | 6 | 6 |
注意 同一种 USDT，在 Ethereum 上是 6 位精度、在 BSC 上是 18 位精度（BEP-20 版本确实是 18 位）。
商户一般不需要自己做精度换算：
- 提现请求传可读金额字符串（
"100.5"），平台自行换算；- 回调和查询返回里同时给出
amount（最小单位）和float_amount（可读金额）与decimal， 入账直接用float_amount即可。若需要自行换算，请用大整数运算，切勿用浮点数。
4. 状态枚举
4.1 充值交易状态 tx_status
| 值 | 说明 |
|---|---|
pending | 已在链上发现，尚未达到确认数 |
confirmed | 已确认，可安全入账 |
timeout | 长时间（约 1 小时）未确认 |
4.2 提现状态 withdraw_status
| 值 | 说明 | 是否推送回调 |
|---|---|---|
under_review | 金额达到免审阈值，等待平台审核 | 否 |
rejected | 审核拒绝 | 否 |
pending | 审核通过 / 免审，排队等待出金 | 否 |
processing | 正在构造/广播交易 | 否 |
success | 交易已广播 | 是 |
confirmed | 交易已确认 | 是 |
error | 出错（可重试） | 否 |
failed | 最终失败 | 否 |
只有
success/confirmed会触发回调。失败/拒绝类状态需要通过控制台或人工对账处理。
4.3 回调状态 call_back_status（平台内部，控制台可见）
| 值 | 说明 |
|---|---|
pending | 待推送 |
processing | 推送中 |
success | 商户已返回 201 |
error | 上次推送未成功，等待重试 |
failed | 商户返回 4xx，或已达 50 次上限 |
skipped | 内部流水（如归集转账），不推送 |
4.4 归集策略 collect_policy（控制台配置）
| 值 | 说明 |
|---|---|
after_every_deposit | 每笔充值后立即归集 |
every_fixed_duration | 固定周期归集（5 分钟 ~ 1 个月） |
at_fixed_time | 每天固定时间归集 |
threshold | 累计金额达到阈值时归集 |
manually | 仅手动归集 |
5. 错误码
响应体里的 code 字段。200 为成功；4xx/5xx 为 HTTP 层错误；1xxx 为业务错误码。
5.1 商户常见业务错误码
code | error | 含义与处理 |
|---|---|---|
1002 | invalid param | 参数非法（币种/网络/地址格式/金额）。检查请求体 |
1007 | project public key not set | 商户公钥未登记，去控制台登记 |
1009 | missing param | 缺少必填参数（如缺 X-Signature） |
1010 | project not found | project_uid 不存在 |
1011 | invalid signature | 签名不匹配，见 04-签名规范 第 4 节 |
1012 | invalid public key | 已登记的公钥格式非法，联系平台 |
1018 | too many requests | 触发限流，退避后重试 |
1025 | invalid network id | 网络 ID 非法或未开通 |
1026 | address already exists | 地址已存在 |
1027 | user address not found | 该用户在该网络上还没有充值地址，先调创建接口 |
1028 | insufficient balance to withdraw | 归集地址余额不足。先查 consolidation/balances |
1029 | withdraw uid already used | 提现单号重复。按已提交处理，不要换 uid 重发 |
1030 | withdraw daily times limit reached | 触发单日提现笔数上限 |
1031 | withdraw daily amount limit reached | 触发单日提现金额上限 |
5.2 HTTP 层错误
| HTTP | 场景 |
|---|---|
400 | 参数/签名格式错误、公钥未登记、uid 已占用 |
401 | 签名验证失败；API Key 缺失或无效 |
403 | 来源 IP 未在白名单或未审核通过；API Key 不属于该项目 |
429 | 触发限流（约 125 req/s per IP） |
500 | 服务端错误，或部分业务错误（如 1029）以 500 承载 |
502 | 网关到后端的转发失败，可重试 |
平台部分业务错误使用 HTTP 500 承载（如提现 uid 重复）。 判定逻辑请以响应体的
code/error字段为准，不要只看 HTTP 状态码。
6. 快速自检命令
bash
BASE=https://linkepay-api.bestxx.com
PUID=<PROJECT_UID>
KEY=<API_KEY>
# 1. 服务是否健康
curl -s "$BASE/api/v1/admin/health/"
# 2. 平台公钥（用于回调验签）
curl -s "$BASE/api/v1/public/platform-public-key"
# 3. 支持的网络与币种
curl -s "$BASE/api/v1/public/networks"
curl -s "$BASE/api/v1/public/assets"
# 4. 我的出口 IP（对照白名单）
curl -s https://api.ipify.org; echo
# 5. API Key + IP 白名单是否通
curl -s "$BASE/api/v1/client/project/$PUID/consolidation/balances" -H "X-API-Key: $KEY"第 5 步：
- 返回
200+ 余额列表 → API Key 与 IP 白名单均正常 - 返回
401→ API Key 无效 - 返回
403 IP address not whitelisted→ 出口 IP 未审核通过