HTTP API 接口文档

支持 GET/POST 请求，采用请求级 HMAC-SHA256 鉴权并提供防重放与幂等保护

返回首页
开发者下载
下载 OpenAPI JSON
认证方式

签名算法

所有需要认证的接口必须携带以下请求头：

请求头 说明 示例
x-api-key API Key，在首页 → 个人资料 → 开放API Key 模块创建 ak_xxxxxxxxxxxxxxxx
x-timestamp 10位 Unix 时间戳（秒），允许与服务端相差 ±5 分钟 1704614400
x-nonce 每个请求唯一随机串，仅允许字母、数字、_、-，长度 16-128 req_20250324_abcd1234
x-signature 对 stringToSign 做 HMAC-SHA256 后得到的小写 hex a1b2c3d4e5f6...

签名生成

stringToSign = METHOD + "\n" + rawPath + "\n" + rawQuery + "\n" + sha256(rawBody)
             + "\n" + x-timestamp + "\n" + x-nonce + "\n" + x-api-key
             + "\n" + (x-idempotency-key || "")

signature = HMAC-SHA256(stringToSign, api_secret).toLowerCase()

Python 示例

import hmac
import hashlib
import json
import time
import uuid
from urllib.parse import urlsplit

api_key = "your_api_key"
api_secret = "your_api_secret"
method = "POST"
url = "https://trxhh.com/api/v1/buy_energy"
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
idempotency_key = "order_20250324_001"
body = {
    "count": 65000,
    "period": "1h",
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

raw_body = json.dumps(body, separators=(",", ":")).encode("utf-8")
parsed = urlsplit(url)
raw_query = parsed.query
body_hash = hashlib.sha256(raw_body).hexdigest()

string_to_sign = "\n".join([
    method,
    parsed.path,
    raw_query,
    body_hash,
    timestamp,
    nonce,
    api_key,
    idempotency_key
])

signature = hmac.new(
    api_secret.encode('utf-8'),
    string_to_sign.encode('utf-8'),
    hashlib.sha256
).hexdigest().lower()

headers = {
    "x-api-key": api_key,
    "x-timestamp": timestamp,
    "x-nonce": nonce,
    "x-signature": signature,
    "x-idempotency-key": idempotency_key,
    "Content-Type": "application/json"
}

JavaScript 示例

const crypto = require('crypto');

const apiKey = "your_api_key";
const apiSecret = "your_api_secret";
const method = "POST";
const url = new URL("https://trxhh.com/api/v1/buy_energy");
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(16).toString('hex');
const idempotencyKey = "order_20250324_001";
const body = {
  count: 65000,
  period: "1h",
  address: "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
};

const rawBody = JSON.stringify(body);
const bodyHash = crypto.createHash('sha256').update(rawBody, 'utf8').digest('hex');
const stringToSign = [
    method,
    url.pathname,
    url.search ? url.search.slice(1) : '',
    bodyHash,
    timestamp,
    nonce,
    apiKey,
    idempotencyKey
].join('\n');

const signature = crypto
    .createHmac('sha256', apiSecret)
    .update(stringToSign)
    .digest('hex')
    .toLowerCase();

const headers = {
    "x-api-key": apiKey,
    "x-timestamp": timestamp,
    "x-nonce": nonce,
    "x-signature": signature,
    "x-idempotency-key": idempotencyKey,
    "Content-Type": "application/json"
};
注意事项
  • 时间戳必须是10位的 Unix 秒级时间戳，不支持毫秒
  • 签名有效期为 ±5 分钟，请确保服务器时间同步
  • 每个请求都必须使用新的 x-nonce；重复使用会返回 HTTP 409
  • 被限流（HTTP 429）不会消耗 x-nonce，但请按 Retry-After 退避后重试
  • 签名必须基于实际发送的请求：Method、Path、Query、Body 字节内容都要一致
  • buy_energy、delegate_energy_smart 必须携带 x-idempotency-key
  • 重试复用同一个 x-idempotency-key，但仍要换新的 x-nonce、x-timestamp 和签名；同一幂等键的重复请求会返回同一结果，不会重复扣费
  • 下单接口为异步受理，通常在数百毫秒内返回订单号（status=processing），实际委托在后台执行；若因网络异常未收到响应，请用同一 x-idempotency-key 重试或查询 query_result，不会重复扣费
  • 认证失败时响应头可能带有 x-server-time，可用于排查本机时间偏差
响应格式

所有接口统一返回以下 JSON 格式：

{
    "code": 1,           // 1=成功, 0=失败
    "msg": "success",    // 响应消息
    "time": "1704614400",// 服务器时间戳
    "data": { ... }      // 业务数据（可为null）
}
字段 类型 说明
code number 状态码：1 表示成功，0 表示失败
msg string 响应消息，失败时包含错误原因
time string 服务器当前 Unix 时间戳（秒）
data object|null 业务数据，失败时通常为 null
接口列表
GET /api/v1/ping 探活接口（无需认证） ▼

描述

用于检测 API 服务是否正常运行，此接口无需认证。

响应示例

{
    "code": 1,
    "msg": "pong",
    "time": "1704614400",
    "data": null
}
GET /api/v1/user_info 获取用户信息 ▼

描述

获取当前 API Key 关联用户的账户信息，包括余额等。

请求头

需要携带认证请求头（x-api-key、x-timestamp、x-nonce、x-signature）

响应示例

{
    "code": 1,
    "msg": "success",
    "time": "1704614400",
    "data": {
        "balance_trx": "1000.50",
        "balance_usdt": "500.25"
    }
}

响应字段说明

字段 类型 说明
balance_trx string TRX 余额
balance_usdt string USDT 余额
GET /api/v1/query_price 查询价格 ▼

描述

查询指定资源类型、数量和周期的价格。

请求参数

参数 类型 必填 说明
type string 是 资源类型：energy（能量）
count number 是 资源数量，如 65000
period string 是 租赁周期，见下方周期参数说明

周期参数说明

参数值 说明
15minutes15分钟
1h1小时
1day1天
3day3天
7day7天
30day30天

请求示例

GET https://trxhh.com/api/v1/query_price?type=energy&count=65000&period=1h

响应示例

{
    "code": 1,
    "msg": "success",
    "time": "1704614400",
    "data": {
        "price": 16000000,
        "amount": "10.4000",
        "fee": "0.0000",
        "remark": "65000 能量 x 1h",
        "price_trx": "10.4000",
        "price_usdt": "3.2000"
    }
}
POST /api/v1/buy_energy 购买能量 ▼

描述

购买能量并委托到指定地址。此接口会扣除账户余额。

异步受理 接口在完成校验、扣款后立即返回订单号（status=processing），实际委托在后台执行。请使用返回的 order_sn 轮询 query_result 获取最终结果（completed / failed / refund_pending）。收到 completed 后再发送链上交易。
幂等性保护 此接口要求携带 x-idempotency-key 请求头，用于业务幂等。业务重试时可复用同一个幂等键，但每次 HTTP 请求仍必须使用新的 x-nonce 并重新签名。

请求头

请求头 必填 说明
x-api-key 是 API Key
x-timestamp 是 Unix 时间戳（秒）
x-nonce 是 每个请求唯一随机串，重复使用会被拦截
x-signature 是 请求级 HMAC-SHA256 签名；buy_energy 时要把 x-idempotency-key 一起算进签名
x-idempotency-key 是 业务幂等键，仅允许字母、数字、连字符和下划线，最长128字符；重试时复用同一个值
Content-Type 是 application/json 或 application/x-www-form-urlencoded

请求参数（JSON 或 Form）

参数 类型 必填 说明
count number 是 能量数量，如 65000
period string 是 租赁周期，如 1h
address string 是 接收能量的 TRON 地址

请求示例

POST https://trxhh.com/api/v1/buy_energy
Content-Type: application/json
x-api-key: ak_xxxxxxxx
x-timestamp: 1704614400
x-nonce: req_20250324_abcd1234
x-signature: a1b2c3d4...
x-idempotency-key: order_20250107_001

{
    "count": 65000,
    "period": "1h",
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

响应示例

{
    "code": 1,
    "msg": "订单已受理，处理中，请使用 query_result 查询最终结果",
    "time": "1704614400",
    "data": {
        "order_sn": "ORD20250107123456789",
        "status": "processing",
        "count": 65000,
        "period": "1h",
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "price_trx": "10.4000",
        "price": 16000000,
        "fee": 0,
        "amount": 10.4,
        "balance": null
    }
}
status 说明
  • processing：订单已受理，余额已扣除，委托正在后台执行。请用同一 order_sn 轮询 query_result（建议间隔 1~2 秒），或使用同一 x-idempotency-key 重试下单接口获取当前状态。
  • completed：能量已委托到账（仅在接口返回前已完成时才直接出现，通常需要先收到 processing）。
  • failed / refund_pending：委托失败，余额会自动退回或进入退款处理，最终以 query_result 为准。
GET /api/v1/query_result 查询订单结果 ▼

描述

根据订单号查询订单执行结果和委托详情。

收到 processing 后建议每 1~2 秒轮询一次，直到状态变为 completed / failed / refund_pending；completed 表示能量已委托到账，此时可安全发送链上交易。

请求参数

参数 类型 必填 说明
order_sn string 是 订单号，购买时返回的 order_sn

请求示例

GET https://trxhh.com/api/v1/query_result?order_sn=ORD20250107123456789

响应示例

{
    "code": 1,
    "msg": "success",
    "time": "1704614400",
    "data": {
        "order_sn": "ORD20250107123456789",
        "status": "completed",
        "status_detail": "success",
        "count": 65000,
        "period": "1h",
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "price_trx": "10.4000",
        "amount": 10.4,
        "price": 16000000,
        "fee": 0,
        "orders": [
            {
                "from_address": "TYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "tx_id": "abc123...",
                "count": 65000
            }
        ]
    }
}

订单状态说明

状态值 说明
pending待处理，订单已创建，等待系统处理
processing处理中，正在执行能量委托（或结果待确认）
completed已完成，能量已成功委托到目标地址
failed失败，订单执行失败（余额已退回）
refund_pending失败待退款审核，平台确认后自动退回余额
refunded已退款，订单已取消并退款
status_detail 为平台内部细分状态（waiting / review_pending / success / failed），仅用于排查问题，业务判断请使用 status。

智能托管 (Smart Delegation)

GET /api/v1/get_smart_price 获取智能托管价格 ▼

描述

获取 65K / 131K 每次智能能量委托的单价（决定充值额度的消耗速度）、各能量通道的价格与押金，以及单次充值额度上下限。

响应示例

{
    "code": 1,
    "msg": "success",
    "time": "1704614400",
    "data": {
        "currency": "TRX",
        "price_65k": 0.5775,
        "price_131k": 1.09725,
        "min_balance": 1,
        "max_balance": 1000000,
        "channels": [
            {
                "channel": "high_frequency",
                "price_65k": 0.462,
                "price_131k": 0.924,
                "deposit_trx": 15,
                "deposit_period_hours": 72,
                "min_energy_count": 455000,
                "min_transaction_count": 7
            }
        ]
    }
}

字段说明

字段 类型 说明
price_65knumber每笔 65K 交易的最终额度成本（TRX）
price_131knumber每笔 131K 交易的最终额度成本（TRX）
min_balance / max_balancenumber单次充值额度的最小 / 最大金额（TRX）
channelsarray高频及以上通道的最终单价、押金、统计周期与最低消耗要求
POST /api/v1/delegate_energy_smart 委托智能托管额度 ▼

描述

为指定地址增加智能能量托管服务的可用额度（余额）。地址每次发起交易时自动从额度中扣减 65K/131K 单价并获得能量，无需人工干预。

幂等保护 此接口要求携带 x-idempotency-key。重试时复用同一个幂等键、更换新的 x-nonce 并重新签名；相同幂等键只会充值一次，不会重复扣费。

请求头

请求头 必填 说明
x-api-key是API Key
x-timestamp是Unix 时间戳（秒）
x-nonce是每个请求唯一随机串，重复使用会被拦截
x-signature是请求级 HMAC-SHA256 签名（需把 x-idempotency-key 一起算进签名）
x-idempotency-key是业务幂等键，仅允许字母、数字、连字符和下划线，最长128字符
Content-Type是application/json 或 application/x-www-form-urlencoded

请求参数（JSON 或 Form）

参数 类型 必填 说明
address string 是 要增加额度的 TRON 地址（必须已激活）
balance number 是 增加的额度数量（TRX，正数，最小 1，最大 1000000）
channel string 否 能量通道：normal（默认）/ high_frequency / jisu_frequency / guangsu_frequency
hf_deposit number 否 押金金额（TRX，可选）；-1 跟随系统设置、0 不扣押金，不传则以实际收取为准
押金说明 押金以实际收取为准；如需押金的通道，会在下单时随单收取，具体金额与要求可通过 get_smart_price 查询。

请求示例

POST https://trxhh.com/api/v1/delegate_energy_smart
Content-Type: application/json
x-api-key: ak_xxxxxxxx
x-timestamp: 1704614400
x-nonce: req_20250324_abcd1234
x-signature: a1b2c3d4...
x-idempotency-key: smart_20250107_001

{
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "balance": 10
}

响应示例

{
    "code": 1,
    "msg": "success",
    "time": "1704614400",
    "data": {
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "balance": "20.5000",
        "status": "start",
        "quota": 10,
        "charge_amount": 11.55
    }
}

字段说明

字段 类型 说明
balancestring充值后的剩余可用额度（TRX）
statusstring服务状态：start 启用 / stop 暂停
quotanumber本次充值额度（TRX）
charge_amountnumber本次实际扣款金额（TRX，含加价）
计费说明 本次扣款 = 充值额度 + 押金（如涉及，押金以实际收取为准），最终以接口返回的 charge_amount 为准。 若受理结果不确定（超时/网络异常），接口返回 code: 1、status 可能与预期不同，余额已扣除但未确定最终结果，请稍后用 query_energy_smart 确认。
GET /api/v1/query_energy_smart 查询智能托管状态 ▼

描述

获取指定地址的剩余额度、服务状态以及消耗记录（分页）。地址必须是通过本 API Key 充值过智能托管的地址。

请求参数

参数 类型 必填 说明
address string 是 要查询的 TRON 地址
page number 否 页码，默认 1

请求示例

GET https://trxhh.com/api/v1/query_energy_smart?address=TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&page=1

响应示例

{
    "code": 1,
    "msg": "success",
    "time": "1704614400",
    "data": {
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "balance": "20.5000",
        "status": "start",
        "order_count": 15,
        "page_size": 20,
        "page": 1,
        "orders": [
            {
                "energy_type": "65k",
                "amount": 0.5,
                "balance": 20.5,
                "currency": "trx",
                "status": "delegate_success",
                "used_energy": 65000,
                "used_times": 1,
                "delegate_count": 65000,
                "delegate_tx_id": "abc123...",
                "delegate_time": 1704614300,
                "createtime": 1704614300
            }
        ]
    }
}

消耗记录状态说明

状态值 说明
init已创建，等待处理
waiting_delegate等待委托能量
delegate_success能量委托成功
delegate_failed能量委托失败
waiting_un_delegate等待回收能量
un_delegate_success能量回收成功
un_delegate_failed能量回收失败
POST /api/v1/update_energy_smart 更新智能托管状态 ▼

描述

启用（start）或暂停（stop）指定地址的智能能量托管服务。

请求参数（JSON 或 Form）

参数 类型 必填 说明
address string 是 要更新状态的 TRON 地址
status string 是 目标状态：start 启用 / stop 暂停

请求示例

POST https://trxhh.com/api/v1/update_energy_smart
Content-Type: application/json

{
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "stop"
}

响应示例

{
    "code": 1,
    "msg": "success",
    "time": "1704614400",
    "data": {
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "balance": "20.5000",
        "status": "stop"
    }
}
GET /api/v1/statistics_smart_by_address 获取智能托管统计 ▼

描述

获取指定地址在不同时间段的智能托管消耗统计（区分 65K / 131K 类型）。

请求参数

参数 类型 必填 说明
address string 是 要获取统计的 TRON 地址

请求示例

GET https://trxhh.com/api/v1/statistics_smart_by_address?address=TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应示例

{
    "code": 1,
    "msg": "success",
    "time": "1704614400",
    "data": {
        "days": {
            "2025-03-20": { "65k": 8, "131k": 2 },
            "2025-03-21": { "65k": 12, "131k": 5 }
        },
        "today": { "65k": 8, "131k": 2 },
        "yesterday": { "65k": 12, "131k": 5 },
        "this_week": { "65k": 40, "131k": 12 },
        "this_month": { "65k": 150, "131k": 35 }
    }
}

字段说明

字段 类型 说明
daysobject最近 5 天统计，键为日期（YYYY-MM-DD）
todayobject今日消耗统计
yesterdayobject昨日消耗统计
this_weekobject本周消耗统计（周一至今）
this_monthobject本月消耗统计（1号至今）
GET /api/v1/get_times_price 查询笔数托管单价 ▼

描述

查询当前 API Key 对应用户的笔数托管最终单价。笔数托管按次数计费，无押金。

响应示例

{
    "code": 1,
    "msg": "查询成功",
    "time": "1704614400",
    "data": {
        "currency": "TRX",
        "unit_price_trx": 1.98,
        "min_times_per_order": 5
    }
}
POST /api/v1/delegate_energy_times 下单笔数托管 ▼

描述

为指定地址开通或追加笔数托管次数：地址在托管期间发起交易时自动补充能量，按次数扣减，无需人工干预。首次开通与追加次数由系统自动判断。

幂等保护 此接口要求携带 x-idempotency-key。重试时复用同一个幂等键、更换新的 x-nonce 并重新签名；相同幂等键只会下单一次，不会重复扣费。

请求参数（JSON 或 Form）

参数 类型 必填 说明
address string 是 要开通/追加笔数托管的 TRON 地址（必须已激活）
rent_times number 是 下单次数（整数，最少 5，最大 100000）
free_pause_days number 否 空闲暂停天数：2 / 3 / 5 / 7，不传表示不暂停
resource_replenish string 否 资源补充：0 不补充 / 1 自动补充带宽或 TRX

请求示例

POST https://trxhh.com/api/v1/delegate_energy_times
Content-Type: application/json
x-api-key: ak_xxxxxxxx
x-timestamp: 1704614400
x-nonce: req_20250324_times01
x-signature: a1b2c3d4...
x-idempotency-key: times_20250107_001

{
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "rent_times": 20,
    "free_pause_days": 3,
    "resource_replenish": "1"
}

响应示例

{
    "code": 1,
    "msg": "下单成功",
    "time": "1704614400",
    "data": {
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "rent_times": 20,
        "remain_times": 18,
        "provided_times": 2,
        "status": "start",
        "free_pause_days": 3,
        "resource_replenish": "开启",
        "charge_amount": 39.6
    }
}
计费说明 扣款金额 = 下单次数 × 单价，无押金；单价可通过 get_times_price 查询。 若受理结果不确定（超时/网络异常），接口返回 code: 1、status 为 unknown，余额已扣除但结果待确认，请稍后用 query_energy_times 确认，不要重复下单。
GET /api/v1/query_energy_times 查询笔数托管状态 ▼

描述

查询指定地址的笔数托管状态：剩余笔数、租用次数、已下发次数、空闲暂停天数与启停状态。

请求参数

参数 类型 必填 说明
address string 是 要查询的 TRON 地址

响应示例

{
    "code": 1,
    "msg": "查询成功",
    "time": "1704614400",
    "data": {
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "rent_times": 20,
        "remain_times": 18,
        "provided_times": 2,
        "status": "start",
        "free_pause_days": 3,
        "resource_replenish": "开启"
    }
}
POST /api/v1/update_energy_times 启用/暂停笔数托管 ▼

描述

启用或暂停指定地址的笔数托管。与目标状态一致时直接返回当前状态，不会重复下发。

请求参数（JSON 或 Form）

参数 类型 必填 说明
address string 是 要更新状态的 TRON 地址
status string 是 start 启用 / stop 暂停

响应示例

{
    "code": 1,
    "msg": "托管已暂停",
    "time": "1704614400",
    "data": {
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "rent_times": 20,
        "remain_times": 18,
        "provided_times": 2,
        "status": "stop",
        "free_pause_days": 3,
        "resource_replenish": "开启"
    }
}
错误码说明
code HTTP状态码 说明 解决方案
1 200 请求成功 -
0 401 认证失败 检查 API Key、时间戳、nonce、签名串以及实际发送的 Query/Body 是否一致
0 409 请求被判定为重放 更换新的 x-nonce、x-timestamp 并重新签名；不要复用同一组鉴权头
0 403 IP 不在白名单 在 API Key 设置中添加当前 IP 到白名单
0 429 请求过于频繁 降低请求频率，或联系管理员提高限制
0 425 相同幂等键的请求正在处理中 稍后用同一个 x-idempotency-key 重试，或先用 query_result 查询结果
0 504 请求处理超时 用同一个 x-idempotency-key 重试，或调用 query_result 确认结果；不会重复扣费
0 400 参数错误 检查请求参数是否完整和正确
0 503 OpenAPI 认证服务暂时不可用 稍后重试；如持续出现请联系技术支持
0 500 服务器内部错误 请稍后重试或联系技术支持
速率限制

每个 API Key 默认限制为 300 次/分钟。超出限制将返回 HTTP 429 错误。

如需提高限制，请联系管理员。