LinkePay 商户文档

主题

02 · API 参考 ​

  • Base URL（生产/主网）：https://linkepay-api.bestxx.com
  • 路径前缀：/api/v1/client/project/{project_uid}
  • 下文示例中的 Ab3xY9Kq7Z 为示例 project_uid，请替换为平台分配给你的值。
  • 所有请求的 Content-Type 均为 application/json。

0. 通用响应结构 ​

所有接口返回统一信封：

json
{
  "code": 200,
  "status": "success",
  "message": "",
  "data": { },
  "error": "",
  "sig": "8e3a8db3...c69ef00"
}
字段说明
code200 表示成功；失败时为 HTTP 状态码或业务错误码（见 06-附录）
statussuccess / error
message人类可读的说明；失败时是失败原因
data业务数据
error失败时的错误标识
sig平台对本次响应体的签名（部分接口有）。十六进制、无 0x 前缀。验签方法见 04-签名规范

判定成功：以 HTTP 状态码 200 且 code == 200 为准。

1. 公共接口（免鉴权） ​

这几个接口不需要签名、API Key，也不受 IP 白名单限制，可用于健康检查和配置自检。

1.1 健康检查 ​

bash
curl -s "https://linkepay-api.bestxx.com/api/v1/admin/health/"
json
{"code":200,"status":"success","message":"server is healthy","data":null}

1.2 获取支持的网络 ​

bash
curl -s "https://linkepay-api.bestxx.com/api/v1/public/networks"
json
{
  "code": 200,
  "status": "success",
  "message": "",
  "data": [
    { "name": "All",              "id": 0 },
    { "name": "Ethereum Mainnet", "id": 1 },
    { "name": "Sepolia",          "id": 11155111 },
    { "name": "BSC Mainnet",      "id": 56 },
    { "name": "BSC Testnet",      "id": 97 },
    { "name": "TRX",              "id": 4 },
    { "name": "TRX Shasta",       "id": 5 }
  ]
}

这里返回的是平台代码层面支持的全部网络。生产环境实际开通并运行索引器的网络只有 1（Ethereum Mainnet）、4（TRON）、56（BSC Mainnet），请勿在生产上使用测试网 ID。

1.3 获取支持的币种 ​

bash
curl -s "https://linkepay-api.bestxx.com/api/v1/public/assets"

返回每条网络上每种币的合约地址、图标、显示名。生产主网关键条目：

network_id网络asset_id币种合约地址
1Ethereum Mainnet1USDC0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
1Ethereum Mainnet2USDT0xdac17f958d2ee523a2206206994597c13d831ec7
56BSC Mainnet1USDC0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d
56BSC Mainnet2USDT0x55d398326f99059fF775485246999027B3197955
4TRON2USDTTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

商户侧通常不需要关心精度：提现传可读金额字符串，回调里直接用 float_amount。 若需自行换算，精度见 06-附录 第 3 节「金额精度」。

1.4 获取平台公钥 ​

bash
curl -s "https://linkepay-api.bestxx.com/api/v1/public/platform-public-key"
json
{
  "code": 200,
  "status": "success",
  "message": "",
  "data": "0xc0b2388188f35c087400575393c124e9c459550f1dfcf848214f47637b599ee08a6b64876c4687e869d070d892b97071fd4c90b0a3491814823b4e97f8e7d50f"
}

1.5 其它枚举接口 ​

bash
curl -s "https://linkepay-api.bestxx.com/api/v1/public/tx-statuses"
curl -s "https://linkepay-api.bestxx.com/api/v1/public/withdraw-statuses"
curl -s "https://linkepay-api.bestxx.com/api/v1/public/collect-task-statuses"
curl -s "https://linkepay-api.bestxx.com/api/v1/public/call-back-statuses"

2. 生成充值地址（按用户 UID） ​

推荐用法：一个终端用户一个地址。

方法POST
路径/api/v1/client/project/{project_uid}/user/generate-deposit-address-by-user-uid
鉴权X-Signature（请求签名）

请求体 ​

字段类型必填说明
uidstring是必须是 {project_uid}-{你的用户ID}。例如 Ab3xY9Kq7Z-100286。全局唯一，不可复用
network_idnumber是网络 ID，生产可用 1 / 4 / 56

示例 ​

bash
BASE=https://linkepay-api.bestxx.com
PUID=Ab3xY9Kq7Z
PATH_=/api/v1/client/project/$PUID/user/generate-deposit-address-by-user-uid
BODY='{"network_id":4,"uid":"Ab3xY9Kq7Z-100286"}'

# SIG = sign(sha256(PATH_ + sortedJSON(BODY)))，见 04-签名规范.md
curl -s -X POST "$BASE$PATH_" \
  -H "Content-Type: application/json" \
  -H "X-Signature: 0x<签名>" \
  -d "$BODY"

响应 ​

json
{
  "code": 200,
  "status": "success",
  "message": "",
  "data": {
    "address": {
      "id": 812394,
      "created_at": "2026-08-10T03:21:44.512Z",
      "updated_at": "2026-08-10T03:21:44.512Z",
      "uid": "Ab3xY9Kq7Z-100286",
      "address": "TNf6U6U4JtLGBYLvPF7mWQimb8UsagJ22u",
      "network_id": 4,
      "network_name": "TRX",
      "project_uid": "Ab3xY9Kq7Z",
      "nonce": 0
    },
    "count": 1
  },
  "error": "",
  "sig": "0c96ca4e...cb3d01"
}

商户只需要取 data.address.address 和 data.address.uid。

常见错误 ​

场景HTTPmessage
uid 未加 {project_uid}- 前缀500invalid uid
uid 已被占用400uid already used for this network，error 字段为 uid already used
network_id 非法或未开通500invalid network id
商户公钥未登记400Project public key not found
签名不匹配401invalid signature
来源 IP 未白名单403IP address not whitelisted or not approved

地址池耗尽：若返回 failed to generate address，通常是平台侧该网络的预生成地址池告罄，请联系平台。

3. 批量生成充值地址 ​

方法POST
路径/api/v1/client/project/{project_uid}/user/generate-deposit-address
鉴权X-Signature

请求体 ​

字段类型必填说明
countnumber是生成数量，1 ~ 100
network_idnumber是网络 ID

平台会为每个地址生成一个 6 位随机 uid，商户需要自行维护「地址 ↔ 用户」映射。

示例 ​

bash
BASE=https://linkepay-api.bestxx.com
PUID=Ab3xY9Kq7Z
PATH_=/api/v1/client/project/$PUID/user/generate-deposit-address
BODY='{"count":3,"network_id":56}'

curl -s -X POST "$BASE$PATH_" \
  -H "Content-Type: application/json" \
  -H "X-Signature: 0x<签名>" \
  -d "$BODY"

响应 ​

json
{
  "code": 200,
  "status": "success",
  "data": {
    "addresses": [
      { "uid": "aZ7Ivq", "address": "0x8e6462f65c9d596246c1618c81c1284d4bb459b7", "network_id": 56, "network_name": "BSC Mainnet", "project_uid": "Ab3xY9Kq7Z" },
      { "uid": "jOzBFn", "address": "0x2b31f4a1c0c7dd3e11c9c5a08b7f7f1a0b6f4d21", "network_id": 56, "network_name": "BSC Mainnet", "project_uid": "Ab3xY9Kq7Z" },
      { "uid": "kQ1mPz", "address": "0x93c18812f4955b713304abc3f90652d8b93cddde", "network_id": 56, "network_name": "BSC Mainnet", "project_uid": "Ab3xY9Kq7Z" }
    ],
    "count": 3
  },
  "sig": "..."
}

只返回你请求的那条网络的记录。EVM 系网络（Ethereum / BSC）下这批地址在其它已开通 EVM 网络上同样受监控， 但不要把它们当成独立地址重复分配给不同用户。

4. 查询用户充值地址 ​

方法GET
路径/api/v1/client/project/{project_uid}/user/{user_uid}/deposit-address/{network_id}
鉴权X-API-Key

{user_uid} 就是创建时传的 uid（含 {project_uid}- 前缀）。

bash
curl -s "https://linkepay-api.bestxx.com/api/v1/client/project/Ab3xY9Kq7Z/user/Ab3xY9Kq7Z-100286/deposit-address/4" \
  -H "X-API-Key: <API_KEY>"
json
{
  "code": 200,
  "status": "success",
  "message": "",
  "data": { "address": "TNf6U6U4JtLGBYLvPF7mWQimb8UsagJ22u" },
  "error": "",
  "sig": "..."
}

地址不存在时返回 HTTP 500，code 为 1027（user address not found）。

5. 发起提现 ​

方法POST
路径/api/v1/client/project/{project_uid}/withdraw
鉴权X-Signature

请求体 ​

字段类型必填说明
uidstring是提现单号，全局唯一，同时是幂等键。建议用 UUID
asset_idnumber是币种 ID：1=USDC，2=USDT，3=原生币
network_idnumber是网络 ID
amountstring是可读金额字符串，如 "100.5"。必须 > 0
to_addressstring是收款地址。EVM 网络需为合法 0x 地址，TRON 需为合法 T 开头地址
notestring否备注，会记录在提现单上

示例 ​

bash
BASE=https://linkepay-api.bestxx.com
PUID=Ab3xY9Kq7Z
PATH_=/api/v1/client/project/$PUID/withdraw
BODY='{"amount":"100.5","asset_id":2,"network_id":56,"to_address":"0x4b2048ede5ca5d962795fec5edf8b41a860e2d4d","uid":"5f9a1c8e-3d2b-4a71-9d0e-6c1f2ab34567"}'

curl -s -X POST "$BASE$PATH_" \
  -H "Content-Type: application/json" \
  -H "X-Signature: 0x<签名>" \
  -d "$BODY"

响应 ​

json
{
  "code": 200,
  "status": "success",
  "message": "",
  "data": {
    "request_uid": "5f9a1c8e-3d2b-4a71-9d0e-6c1f2ab34567",
    "status": "pending"
  }
}
data.status含义
pending已受理，进入出金队列
under_review金额达到项目免审阈值，等待平台侧审核

校验顺序与常见错误 ​

平台按以下顺序校验，任一失败立即返回：

  1. 参数合法性（asset_id / network_id / 地址格式 / 金额 > 0）→ 1002 invalid request
  2. 项目在该网络是否有归集地址 → 500 failed to get consolidation address
  3. 链上归集地址余额是否充足 → 1028 insufficient balance: requested X, available Y
  4. 数据库归集余额是否充足（行锁，防并发超额）→ 1028 insufficient consolidation balance
  5. uid 是否已使用 → 1029 uid already used
  6. 单日提现笔数上限 → 1030 daily withdraw times limit reached
  7. 单日提现金额上限 → 1031 daily withdraw amount limit reached

同步返回 ≠ 出金成功。提现最终状态请以回调为准，或在控制台查询。

6. 查询归集余额 ​

方法GET
路径/api/v1/client/project/{project_uid}/consolidation/balances
鉴权X-API-Key（且 API Key 必须属于该项目）

查询参数 ​

参数必填说明
network_id否按网络过滤
token_id否按币种过滤
bash
curl -s "https://linkepay-api.bestxx.com/api/v1/client/project/Ab3xY9Kq7Z/consolidation/balances?network_id=56&token_id=2" \
  -H "X-API-Key: <API_KEY>"
json
{
  "code": 200,
  "status": "success",
  "message": "",
  "data": [
    {
      "address": "0x9eE4C914A0c6E41E5F7c4c9febff9FEC846835eF",
      "network_id": 56,
      "network_name": "BSC Mainnet",
      "token_id": 2,
      "token_name": "usdt",
      "balance": "125000000000000000000",
      "balance_float": "125.0000",
      "decimal": 18
    }
  ],
  "error": "",
  "sig": ""
}

用途：发起提现前预检余额，避免频繁触发 1028。

错误HTTP
API Key 无效401 invalid api key
API Key 不属于该项目403 api key does not belong to this project

7. 查询充值 / 提现记录 ​

方法GET
路径/api/v1/client/project/{project_uid}/user/deposits
/api/v1/client/project/{project_uid}/user/withdrawals
鉴权X-API-Key
参数page（默认 1）、page_size（默认 10）
bash
curl -s "https://linkepay-api.bestxx.com/api/v1/client/project/Ab3xY9Kq7Z/user/deposits?page=1&page_size=10" \
  -H "X-API-Key: <API_KEY>"

除分页外，还支持这些过滤参数：

参数说明
tx_hash按交易哈希精确查询
network_id / asset_id按网络 / 币种过滤
tx_status（充值）/ withdraw_status（提现）按状态过滤
address_uid按充值地址绑定的用户 uid 过滤
uid按业务单号过滤（提现单号）
from_address / to_address按地址过滤（大小写不敏感）
confirmedtrue / false
start_time / end_time / date毫秒时间戳，按创建时间过滤
order_bycreated_at（升序）或 -created_at（降序）

对账建议：实时入账仍应以回调为准（见 03-回调通知.md）， 本接口用于对账、补单和历史查询。

响应结构：

json
{
  "code": 200,
  "status": "success",
  "data": {
    "data": {
      "deposits": [
        {
          "id": 12,
          "uid": "...",
          "created_at": "2026-08-10T02:57:35.625Z",
          "project_uid": "Ab3xY9Kq7Z",
          "tx_hash": "0x60a7904f...965bcaf",
          "from_address": "0x93C18812f4955B713304aBC3F90652d8B93cDDDe",
          "to_address": "0xF9c66B4c44943345881aDe7Bad4E096F6550b7E9",
          "address_uid": "Ab3xY9Kq7Z-100286",
          "amount": "1000000",
          "float_amount": "1.0000",
          "network_id": 1,
          "network_name": "Ethereum Mainnet",
          "asset_id": 2,
          "asset_name": "usdt",
          "tx_status": "confirmed",
          "confirmed": true,
          "confirmed_at": "2026-08-10T03:00:40.086Z"
        }
      ],
      "summary": [
        { "asset_id": 2, "asset_name": "usdt", "network_id": 1, "network_name": "Ethereum Mainnet", "amount": "1.0000" }
      ]
    },
    "page": 1,
    "page_size": 10,
    "total": 1
  },
  "sig": "..."
}

8. 接口一览表 ​

接口方法鉴权幂等
/user/generate-deposit-address-by-user-uidPOST签名是（同 uid 报错）
/user/generate-deposit-addressPOST签名否（每次都新建）
/user/{user_uid}/deposit-address/{network_id}GETAPI Key—
/withdrawPOST签名是（同 uid 报错）
/consolidation/balancesGETAPI Key—
/user/depositsGETAPI Key—
/user/withdrawalsGETAPI Key—

本文档描述 LinkePay 生产环境（主网）接口。接口如有变更以本文档为准。

LinkePay