闪租 API 接入文档

接入流程

1. 登录会员中心生成 API 密钥完整密钥只展示一次。可选填最多 5 个服务器 IP 作为白名单。
2. 提交唯一业务订单号和两个地址系统分析本次转账所需能量，并查询转出钱包当前可用能量。
3. 够用免租，不够才闪租现有能量足够时不调用租用服务、不扣余额；不足时按当前开放的 1 小时套餐租用。
4. 按业务订单号查询结果区分现有能量可用、租用发放成功与发放中；API 不替您执行 USDT 转账。

身份验证与接口地址

在每个请求头中加入 Authorization: Bearer YOUR_API_KEY。密钥应由您的服务器持有，不要放进浏览器、App、公开代码或 URL。

若设置了 IP 白名单，接口只接受名单中服务器的真实来源 IP（按服务器接收到的 IP 判断）；不支持 CIDR 网段、域名或代理请求头指定的 IP。密钥失效或白名单不匹配时，请在会员中心检查设置。

创建闪租订单

POST ?action=rent，请求体为 JSON。无需填写时长或能量数量：系统根据转出钱包和实际收款方分析 required_energy（本次所需能量），同时查询钱包当前可用能量。可用能量达到所需数量时，直接返回“成功、可转账”：不调用租用服务、不创建扣费流水，即使会员余额为 0 也无需充值。此时 billing_units=0、energy_amount=0。

若现有能量不足，实际租用数量 energy_amount=max(61000, required_energy)，即单次租用最少 61,000 能量。required_energy 不超过 65,000 时按 1 笔计价，超过 65,000 时按 2 笔计价；billing_units 返回实际计价笔数。65K / 130K 只是价格档，不代表固定发放的能量数量。

现有能量不足时才按会员余额闪租。当前 5 分钟套餐已关闭，API 会按开放的 1 小时套餐下单并计价；无需在请求中指定时长，实际租期以订单响应为准。若今后重新开放 5 分钟，系统可优先尝试该套餐；仅在确认未发放并完成原扣款退款后，才安全切换到 1 小时。正常情况下 API 会等待租用的最终发放结果；若上游超时或结果尚未确认，则返回 delivering，不要换业务单号重复下单，应继续查询原单。当前售价请通过 ?action=prices 获取。

curl -X POST 'https://shantrx.com/api.php?action=rent' -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' --data '{"client_order_id":"order_20260927_001","energy_address":"T...转出钱包地址","recipient_address":"T...实际收款地址"}'

查询订单

GET ?action=order&client_order_id=...。发放中可按同一 client_order_id 每 3–5 秒查询一次，直到得到最终状态；会员每分钟最多 60 次 API 请求，来源 IP 每分钟最多 120 次预认证请求。返回数据会包含中英文状态、结果类型、是否执行租用、实际时长与尝试记录（如租用过）、所需与可用能量、扣费与退款、余额及链上交易哈希等。

如果原提交已保存，但此前在能量分析等建单前步骤失败、尚未创建租用订单，查询原单号会继续处理这笔请求；符合下单条件后按正常售价扣款。已创建的订单不会因重复查询再次创建或重复扣款。不存在或已终止的请求不会因此新建订单。

curl -G 'https://shantrx.com/api.php' -H 'Authorization: Bearer YOUR_API_KEY' --data-urlencode 'action=order' --data-urlencode 'client_order_id=order_20260927_001'

ok: true 仅表示接口请求已处理。整笔业务以顶层 data.status 判断；不要把 attempts 中单次尝试的结果当作整笔业务结果。租用结果不明、退款待恢复或链上哈希暂未取得等异常可能返回 delivering，商户必须查询原业务单号。现有能量够用与真实租用成功都会返回 status: success、status_text: 成功；请用 result_type、rental_performed 和 message 区分。existing_energy 是免租免扣费、没有租用 TXID；rental 是真实租用，必须有有效链上交易哈希才会标为成功。simulated 只是本地测试。

如果租用已被接受但尚无交易哈希，请至少等待 1 分钟后用原业务单号查询。系统会定时只读核验发放中状态，不会额外付费重试；上游超时且缺少可核验订单号时可能仍需人工核查，不可换单号重下。

{
    "ok": true,
    "data": {
        "status": "success",
        "status_text": "成功",
        "result_type": "existing_energy",
        "nocharge": true,
        "rental_performed": false,
        "rental_success": null,
        "available_energy": 140000,
        "required_energy": 58000,
        "billing_units": 0,
        "energy_amount": 0,
        "charged_trx": "0",
        "txid": null,
        "message": "能量充足，未产生费用，可直接转账"
    }
}

{
    "ok": true,
    "data": {
        "status": "success",
        "status_text": "成功",
        "result_type": "rental",
        "nocharge": false,
        "rental_performed": true,
        "rental_success": true,
        "duration": "1h",
        "required_energy": 58000,
        "billing_units": 1,
        "energy_amount": 61000,
        "txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
}

{
    "ok": true,
    "data": {
        "status": "delivering",
        "status_text": "发放中",
        "rental_success": null,
        "result_confirmed": false,
        "required_energy": 98000,
        "billing_units": 2,
        "energy_amount": 98000,
        "txid": null
    }
}

查询余额与价格

curl -G 'https://shantrx.com/api.php' -H 'Authorization: Bearer YOUR_API_KEY' --data-urlencode 'action=balance'

curl -G 'https://shantrx.com/api.php' -H 'Authorization: Bearer YOUR_API_KEY' --data-urlencode 'action=prices'

状态、幂等与安全重试

正常响应为 {"ok":true,"data":{...}}；请求验证失败为 {"ok":false,"error":{"code":"...","message":"..."}}。ok 不是发放结果；要连同 result_type 和 rental_performed 判断：

网络超时后，请先用原 client_order_id 查询，再以完全相同参数重试。同编号且参数相同会返回原请求结果；同编号更改参数会被拒绝。每一次新的实际 USDT 转账必须使用新的业务单号，不能永久复用旧单的“成功”结果。曾提交的付费租用订单不会因为钱包后来出现足够能量就被改写成“免租成功”。若相同转出钱包已有另一客户单号的发放中订单，新单将返回 HTTP 409 / ADDRESS_BUSY，不扣款、不再调用租用服务；不能换编号绕过。