GasTank
文档目录
← 返回文档列表

API 接入指南

在控制台充值并创建 API Key，再调用 /openapi/v1/rentals/。API 与网页租赁共用账户余额及结算流程，实际可用性以部署网络和租赁状态为准。

1. 确认网络

Nile 测试 TRX 与主网 TRX 不通用。账户、充值地址、API Key 和服务必须属于同一网络。不要向测试地址支付主网资金；服务地址决定使用的网络，API Key 必须与该部署匹配，无需传网络请求头。

2. 注册并充值

控制台提供专属 TRX 充值地址和二维码。按页面显示的网络充值，链上确认并记入账户后才可消费。实收金额全额入账；物理钱包归集不改变虚拟账户余额。

3. 创建密钥

只查询时选择只读权限；需要报价及下单时选择读取与租赁。有效期可选默认期限或永不过期，两者都可手动撤销。完整密钥仅在创建时显示一次，只保存在服务端，禁止写入网页、URL、日志或版本控制。轮换时先创建并验证新密钥，再撤销旧密钥。

使用 Authorization: Bearer YOUR_API_KEY 认证。所有金额使用整数 SUN 字符串，"5000000" 表示 5 TRX。可用余额为总余额减冻结金额。

4. 报价及下单

按接收地址、能量数量与租期请求报价。接收地址是使用能量的钱包，实际能耗取决于操作，转账笔数只是参考。核对租赁费、激活费及报价有效期后，提交报价编号、最高费用和事先持久化的 Idempotency-Key。

202 表示已受理，不是交付成功。超时或 500 后先按原幂等键查询，不要直接生成新键。接口字段和错误码见接口参考。

5. 查询交付及扣费

结果账户处理
下单受理冻结租赁费及适用激活费，总余额不变
平台激活确认成功激活费只扣一次
第三方先激活释放激活冻结，不收激活费
能量确认交付扣除租赁费
租赁明确失败释放未消费租赁冻结，已经成功的激活费保留
链上结果不明保持相应冻结并核验原交易

账户流水记录充值、实际扣费及人工余额调整。冻结及释放在订单费用明细查看；正常租期结束不退还租赁费。撤销密钥不取消已经受理的订单。

本批没有自动提现或即时退款接口。充值、流水及密钥管理使用控制台。

curl 调用示例（Bash）

替换全部大写占位值。除本机测试外，使用实际 HTTPS 服务地址。

# 真实密钥通过密钥管理工具注入，不要提交或粘贴到命令历史。
export OPENAPI_BASE_URL="YOUR_OPENAPI_BASE_URL"
export GASTANK_API_KEY="YOUR_API_KEY"

curl --fail-with-body "${OPENAPI_BASE_URL}balance/" \
  -H "Authorization: Bearer $GASTANK_API_KEY"

curl --fail-with-body "${OPENAPI_BASE_URL}quotes/" \
  -H "Authorization: Bearer $GASTANK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"receiver_address":"YOUR_TRON_ADDRESS","energy_amount":65000,"duration_seconds":600}'

# 读取报价并授权金额，持久化请求编号后再执行这个 POST。
curl --fail-with-body "${OPENAPI_BASE_URL}orders/" \
  -H "Authorization: Bearer $GASTANK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_PERSISTED_REQUEST_ID" \
  -d '{"quote_id":"QUOTE_UUID","max_total_sun":"AUTHORIZED_TOTAL_IN_SUN"}'

curl --fail-with-body "${OPENAPI_BASE_URL}orders/?idempotency_key=YOUR_PERSISTED_REQUEST_ID" \
  -H "Authorization: Bearer $GASTANK_API_KEY"

使用 orders/ORDER_UUID/ 轮询交付。429 后等待 Retry-After；下单结果不明时先按原幂等键查询，再决定是否重试。示例不自动循环提交订单。

可选带宽

租赁表单默认只租能量。需要带宽时开启“同时租赁带宽”，填写明确数量；API 使用 bandwidth_amount。带宽单独报价，与能量共用租期，各自确认交付和扣费。部分交付只收成功部分费用，余额付款释放失败部分冻结；匿名付款差额由客服人工处理。结果不明时继续核验，不能视为失败或成功。

仅通过 API 租带宽时传 energy_amount: 0 和正数 bandwidth_amount，不能同时为零。网页仍要求租赁能量。单租带宽沿用带宽价格；能量费用为零且不适用，交付以 deliveries 中的 BANDWIDTH 为准。