TronBid Quick Rent API

用于自动租用 TRON Energy 的 B2B REST API。以编程方式为 USDT TRC-20 转账购买能量——支持 on-chain 或使用 TronBid 余额。

本页目录

概览：这是什么，适合谁

Quick Rent API 是一种自动租用 TRON Energy 的方式，无需手动操作。有了 Energy，USDT（TRC-20）转账及其他智能合约调用会比燃烧 TRX 更便宜。

简单来说：您的程序（网站、机器人或服务）会在需要时自动购买 Energy——例如在每位客户发起 USDT 转账之前。

把它想象成自动售货机：查看价格、投入钱、拿到商品。API 就是这些按钮，只不过由您的程序来按。

1
查询价格
程序向 API 询问所需 Energy 套餐当前的价格。
2
创建订单并支付
程序创建订单并支付——向指定地址转账 TRX，或从 TronBid 余额扣款。
3
获得 Energy
几秒后 Energy 出现在目标钱包上，即可更便宜地发送 USDT。

重要：API 是面向开发者的工具。要使用它，需要有人编写发送请求的代码。

如果没有人写代码——请使用网站上的现成购买（Quick Rent）或 Telegram 机器人 @tronbid。结果相同，只是手动操作。

术语表

本文档中出现的词语的简短解释。

Energy（能量）: TRON 网络智能合约操作的“燃料”。不足时网络会改为燃烧 TRX，成本更高。租用 Energy 可以省钱。
TRX: TRON 网络的原生代币。用于支付 Energy 租用和网络手续费。
USDT TRC-20: TRON 上的稳定币（美元）。发送它是一次需要 Energy 的智能合约调用。
API 密钥: 访问 API 的秘密口令。每个请求都要携带。仅保存在服务器端。
Endpoint（端点）: API 的具体地址“按钮”，程序向其发送请求（例如 /quote——查询价格）。
GET / POST: 请求类型。GET 表示“查询/读取数据”，POST 表示“执行动作”（创建订单、计算价格）。
Bearer 令牌: 传递 API 密钥的方式：请求头写 Authorization: Bearer 您的密钥。
on-chain 支付: 通过普通 TRX 转账到指定地址来支付订单——立即可用，无需开通。
余额支付: 从您的 TronBid 账户余额扣款支付。更快，但需先为密钥开通。
委托（Delegation）: 在租期内（例如 15 或 60 分钟）将租来的 Energy 临时转给目标钱包。
轮询（Polling）: 每隔几秒重复查询订单状态，直到变为 delegated 或以错误结束。
idempotency_key: 您自己的唯一订单编号。若请求发送两次，API 返回同一订单而不新建——防止重复支付。

开始之前

发出第一个请求前需要准备的东西。

1
获取 API 密钥
在 Telegram 联系 @tronbid——将获得与您的 TronBid 账户绑定的密钥。没有它请求无法通过。
2
准备目标 TRON 钱包
确定需要 Energy 的地址（target_address）。通常是您客户发送 USDT 的钱包。
3
从目录中选择套餐
Energy 按套餐出售（通常为 65000 或 131000 能量，15 或 60 分钟）。可从目录端点获取最新列表，无需授权。
4
准备支付
on-chain 需要一个含 TRX 的钱包用于支付；余额支付需要已充值的 TronBid 账户并开通 balance 模式。

简介

Quick Rent API 让您的服务自动租用 TRON Energy，使 USDT TRC-20 转账及其他智能合约调用的成本低于直接燃烧 TRX。

所有端点共用一个 base URL。

Base URL（生产）

http

https://tronbid.com/api/v2/quick-rent

鉴权

每个请求都必须在 Authorization 头中以 Bearer 令牌形式携带您的 API 密钥。

密钥仅保存在服务端（后端、CI 机密）。切勿放入前端代码或公开仓库。密钥绑定到单一 TronBid 账户（开通时指定的钱包）；余额支付只能从该账户扣款。

超过速率限制时，API 返回 HTTP 429。

http

Authorization: Bearer <API_KEY>

支付模式

订单有两种支付方式。on-chain 为默认方式，无需设置。余额支付为可选项，需为您的密钥单独开通。

未开通时，带 payment_mode: balance 的请求会返回 403 BALANCE_PAYMENT_NOT_ENABLED。如需开通，请联系 TronBid 客服。

模式	如何启用	支付
`on-chain`	默认——不传 payment_mode（或 "onchain"）	从 payer_address 向 pay_address 转账 TRX
`balance`	payment_mode: balance + 已为您的密钥开通	从 TronBid 账户 TRX 余额扣款

套餐目录

energy_amount 和 duration_minutes 必须匹配有效的 Quick Rent 套餐——通常为 65000 或 131000 能量，15 或 60 分钟。

可随时获取当前套餐目录（无需鉴权）：

获取有效套餐目录（无需鉴权）

bash

curl -sS https://tronbid.com/api/public/quick-rent/skus

快速上手：从零到 Energy

在最简单的场景（on-chain）上的完整端到端示例。四步即可让 Energy 到达钱包。

下面是每一步发生了什么以及 API 返回什么。请填入您的 API 密钥、地址和订单 ID。

1
第 1 步。查询价格 — POST /quote
发送 Energy 数量和时长。返回 price_trx 以及价格锁定的秒数。
2
第 2 步。创建订单 — POST /orders
发送套餐、您的 idempotency_key 和 payer_address。返回 pay_address（付款地址）、amount_trx（金额）和 expires_at（截止时间）。
3
第 3 步。付款
从您的 payer_address 向 pay_address 精确转账 amount_trx TRX。这是一次普通的 TRON 转账。
4
第 4 步。等待 Energy — GET /orders/:id
每隔几秒轮询状态，直到变为 delegated。这表示 Energy 已委托到钱包——完成。

响应

json

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

响应（on-chain）

json

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

cURL

bash

# poll every 3s until the order is done
while true; do
  STATUS=$(curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
    -H "Authorization: Bearer $API_KEY" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    delegated|failed|expired|cancelled) break ;;
  esac
  sleep 3
done

响应

json

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

On-chain 流程

第 1 步 — POST /quote 查询价格。第 2 步 — POST /orders 创建订单并获取 pay_address、amount_trx 与 expires_at。第 3 步 — 从您的 payer_address 向 pay_address 精确转账 amount_trx TRX。第 4 步 — 轮询 GET /orders/:id 直到状态变为 delegated（或 failed / expired / cancelled）。

target_address 为可选项——若不传，能量将委托至 payer_address。

同一 payer_address 同时只允许一个未关闭的 on-chain 订单（pending_payment），否则返回 409 PENDING_PAYMENT_INTENT_EXISTS。多付/少付时最终能量可能不同——请查看 GET /orders/:id 中的 effective_energy_amount。

请求体

json

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-001",
  "payer_address": "TPayerWalletXXXXXXXXXXXXXXXXXXXXXX",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

响应

json

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

余额流程

第 1 步 — GET /balance 查看 TRX 余额。第 2 步 — POST /quote 查询价格。第 3 步 — POST /orders 携带 payment_mode: balance，扣款并开始委托。第 4 步 — 轮询 GET /orders/:id 直到 delegated（若委托失败则变为 failed，TRX 退回余额）。

无需 payer_address——由绑定到您 API 密钥的账户付款。响应中的 energy_amount 可能高于所下 SKU（价格矩阵赠送）。

请求体

json

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-balance-001",
  "payment_mode": "balance",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

响应

json

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

订单状态

每个订单都会经历以下状态。通过 GET /orders/:id 进行跟踪。

状态	含义
`pending_payment`	等待 on-chain 付款
`delegating`	已收款或已扣余额，委托进行中
`delegated`	能量已委托
`cancelled`	付款前已取消（on-chain）
`expired`	on-chain 付款时限已过
`failed`	出错（余额模式下 TRX 退回）

幂等性

idempotency_key（8–128 个字符）是您这一侧的唯一订单 ID。用相同密钥（同一 API 客户端）重复 POST /orders 会返回同一订单并带 "duplicate": true。

不要在不同支付模式（onchain 与 balance）间复用同一 idempotency_key，否则返回 409 IDEMPOTENCY_PAYMENT_MODE_MISMATCH。

计算器

估算某地址完成转账所需的能量。传入收款钱包，并说明其是否已持有 USDT。

POST/api/v2/quick-rent/calculator

参数

参数	类型	说明	示例
`wallet_address`	string	要分析的 TRON 地址	`TXXXXXXXX...XXXX`
`has_usdt`	boolean \| null	收款方是否已持有 USDT（影响能量）。true、false 或不传。	`true`

请求体

json

{
  "wallet_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "has_usdt": true
}

cURL

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/calculator" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","has_usdt":true}'

获取报价

返回套餐的当前价格：price_trx、是否可用、save_percent 以及报价有效期（expires_in_sec）。

POST/api/v2/quick-rent/quote

参数

参数	类型	说明	示例
`energy_amount`	int	来自有效目录的能量数量	`131000`
`duration_minutes`	int	来自目录的租用时长	`15`

响应

json

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

cURL

bash

export BASE_URL="https://tronbid.com"
export API_KEY="your_api_key"

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"energy_amount":131000,"duration_minutes":15}'

创建订单

创建租用订单。on-chain 模式：传入 payer_address，并将返回的 amount_trx 支付到 pay_address。余额模式：加上 payment_mode: balance，绑定账户会立即扣款。

target_address 可选（默认为 payer_address）。注意 409 规则：每个 payer 仅允许一个未关闭的 on-chain 订单，且 target 上不能已有有效的 Quick Rent 委托（ACTIVE_DELEGATION_EXISTS）。

POST/api/v2/quick-rent/orders

参数

参数	类型	说明	示例
`energy_amount`	int	来自目录的能量数量	`131000`
`duration_minutes`	int	来自目录的租用时长	`15`
`idempotency_key`	string	您这侧的唯一订单 ID（8–128 个字符）	`partner-onchain-001`
`payment_mode`	string	可选。"onchain"（默认）或 "balance"。	`balance`
`payer_address`	string	on-chain：发送 TRX 的钱包。余额模式不需要。	`TPayer...`
`target_address`	string	可选。接收能量的钱包（默认为 payer_address）。	`TTarget...`

响应（on-chain）

json

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

响应（余额）

json

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

cURL（on-chain）

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-onchain-001",
    "payer_address": "TPayer...",
    "target_address": "TTarget..."
  }'

cURL（余额）

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-balance-001",
    "payment_mode": "balance",
    "target_address": "TTarget..."
  }'

查询订单状态

返回当前状态、payment_mode、金额、地址，以及失败时的 error_code / error_message。effective_energy_amount 反映在多付/少付后实际委托的能量。

GET/api/v2/quick-rent/orders/:id

参数

参数	类型	说明	示例
`id`	string	订单 ID（路径参数）	`uuid`

响应

json

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

cURL

bash

curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
  -H "Authorization: Bearer $API_KEY"

取消订单

取消仍处于 pending_payment 状态的订单（仅 on-chain）。能量一旦已委托，订单便无法再取消。

POST/api/v2/quick-rent/orders/:id/cancel

参数

参数	类型	说明	示例
`id`	string	订单 ID（路径参数）	`uuid`

cURL

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

更换付款方

为处于 pending_payment 的 on-chain 订单更换付款钱包——当客户在转账前决定改用其他钱包付款时很有用。

POST/api/v2/quick-rent/orders/:id/set-payer

参数

参数	类型	说明	示例
`id`	string	订单 ID（路径参数）	`uuid`
`payer_address`	string	新的付款钱包	`TNewPayer...`

cURL

bash

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/set-payer" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer_address":"TNewPayer..."}'

查询余额

返回绑定到您 API 密钥的 TronBid 账户的 TRX 余额（应用内余额，非链上钱包）。需要 Authorization 头。

GET/api/v2/quick-rent/balance

响应

json

{ "balance_trx": "150.500000" }

cURL

bash

curl -sS "$BASE_URL/api/v2/quick-rent/balance" \
  -H "Authorization: Bearer $API_KEY"

错误码

错误会返回 HTTP 状态码和 error 字段。以下是您可能遇到的错误。

HTTP	error	触发条件
400	`Invalid body`	JSON 或字段无效
400	`INVALID_SKU / SKU_INACTIVE`	套餐不可用
400	`INVALID_PAYER_ADDRESS / INVALID_TARGET_ADDRESS`	TRON 地址格式错误
400	`TARGET_ACCOUNT_NOT_ACTIVATED`	能量接收钱包在 TRON 上未激活（尚未收到 TRX）
503	`TRON_ACCOUNT_CHECK_FAILED`	无法验证 TRON 账户状态 — 请稍后重试
400	`INSUFFICIENT_BALANCE`	余额 TRX 不足（余额模式）
401	`Unauthorized`	缺少或无效的 API 密钥
403	`BALANCE_PAYMENT_NOT_ENABLED`	未为您的密钥开通余额支付
409	`PENDING_PAYMENT_INTENT_EXISTS`	该 payer 已存在未关闭的 on-chain 订单
409	`ACTIVE_DELEGATION_EXISTS`	target 上已有有效的 Quick Rent 委托
409	`POOL_ENERGY_INSUFFICIENT`	当前池内暂无空闲能量
409	`IDEMPOTENCY_PAYMENT_MODE_MISMATCH`	相同 idempotency_key 使用了不同 payment_mode
429	`Too Many Requests`	速率限制
503	`—`	服务暂时不可用，请稍后重试

如果出现问题

常见情况以及用简单话说明该怎么办。

已付款但订单卡在 pending_payment

请确认转账金额与 amount_trx 完全相等，且资金从指定的 payer_address 发往 pay_address。转账须在 expires_at 之前到账。状态通常在网络确认后一分钟内更新——请继续轮询 GET /orders/:id。

状态变成 failed 是什么意思？

委托未成功。余额支付时 TRX 会自动退回余额。原因见 GET /orders/:id 的 error_code 和 error_message。可创建新订单。

错误 409 PENDING_PAYMENT_INTENT_EXISTS

该 payer_address 已有一个未支付的 on-chain 订单。请先支付、等待其过期（expires_at）或通过 /orders/:id/cancel 取消，然后再创建新订单。

错误 403 BALANCE_PAYMENT_NOT_ENABLED

您的密钥未开通余额支付。请联系 TronBid 支持开通，或使用 on-chain（默认）。

错误 429 Too Many Requests

短时间内请求过多。请降低轮询频率（例如每 3 秒一次）并稍后重试。

收到的 Energy 比下单的少

on-chain 少付/多付时最终数量会变化。请查看 GET /orders/:id 中的 effective_energy_amount——这是实际委托的 Energy。

支持

需要 API 接入、更高限额或开通余额支付？联系我们，我们将提供帮助。

API 接入与余额支付Telegram @tronbid

邮箱support@tronbid.com