zh
zh
文档目录

账户管理 — API 参考

账户身份、余额查询与充值地址管理。

方法路径概览
GET/v1/account获取账户详情与完整状态
PATCH/v1/account修改账户显示名称
GET/v1/balance仅查询实时余额
GET/v1/deposit-addresses获取专属充值地址
GET/v1/ledger账户账本流水明细账单
GET/v1/account/addresses账户常用地址薄
POST/v1/account/addresses保存地址到地址薄
DELETE/v1/account/addresses/{entryId}从地址薄删除地址
GET/v1/account/stats服务端聚合的订单统计分析

基于 openapi.yaml 在构建时生成。基准 URL 为 https://api.tenergy.me/v1，Nile 测试网环境为 https://api-nile.tenergy.me/v1（详见环境说明）。下述每个请求均遵循身份鉴权规范进行签名，除非鉴权行另有说明。

获取账户详情与完整状态

GET /v1/account · getAccount

鉴权： API 密钥 (HMAC) 或引导令牌 (Bootstrap token)。

获取账户身份标识、可用余额、专属充值地址、当前生效配额与生命周期历史汇总指标。

亦支持使用引导令牌读取（Authorization: Bearer abt_…），从而允许注册流程在没有长期 API 密钥的情况下轮询首笔到账状态。

响应

状态码含义
200OK
401缺少、格式错误或已被拒绝的凭据。
429请求过于频繁。
500服务端内部错误。

响应字段 (Account)

字段类型必选说明
idstring是
brandstring是账户所属品牌。账户数据在各品牌间独立隔离。
networkenum: mainnet, nile是账户所属网络环境。主网与 Nile 测试网完全隔离。
owner_addressstring | null创建该账户时签署挑战的钱包地址（账户找回所有权根源）。
labelstring | null与 display_name 取值相同（保留此字段用于旧版本兼容）。
display_namestring | null所有者自定义的账户名称。若为 null，前端将自动展示缩略的 owner_address。
statusenum: unfunded, active, suspended, closed是
balance_suninteger (int64)是以 SUN 为单位的账户余额（1 TRX = 1,000,000 SUN）。始终为整数。
balance_usdtinteger (int64)USDT 余额（以代币最小单位计，6 位小数）。
reserved_suninteger (int64)正在处理中订单冻结的资金。不可挪作他用。
deposit_addressesarray of object (DepositAddress)是
deposit_addresses[].currencyenum: TRX, USDT是
deposit_addresses[].addressstring是Base58Check 编码的 TRON 地址（以 T 开头，34 个字符）。
deposit_addresses[].memostring | null自 2026-09-26 起恒为 null：单账户独立专属地址，无需附带 memo。
deposit_addresses[].confirmations_requiredinteger确认入账所需的区块深度。
deposit_addresses[].contractstring | null接收的 TRC-20 合约地址（仅针对 USDT；TRX 为 null）。
deposit_addresses[].rate_nownull | object仅适用于 USDT。扣除点差前的当前汇率，缓存 60 秒。
deposit_addresses[].rate_now.trx_per_usdtstring是
deposit_addresses[].rate_now.sourceenum: sunswap_v3, fixed_env是
deposit_addresses[].rate_now.atstring (date-time)是
deposit_addresses[].spread_bpsinteger | null点差基点（5 = 0.05%）。
deposit_addresses[].minstring | null单笔最低有效充值金额。
deposit_addresses[].maxstring | null单笔自动入账上限。
limitsobject
limits.max_order_energyinteger
limits.max_batch_receiversinteger
limits.orders_per_secondinteger
totalsobject账户生命周期累计统计。
totals.deposited_suninteger (int64)累计充值金额（SUN）。
totals.spent_suninteger (int64)累计消费金额（SUN）。
totals.refunded_suninteger (int64)累计退款金额（SUN）。
totals.orders_createdinteger
totals.energy_delegatedinteger (int64)
created_atstring (date-time)是

来自规范的 200 响应示例（示意数值）：

json
{
  "id": "acc_01J9Z4K2M7Q8",
  "brand": "tenergy.me",
  "network": "mainnet",
  "label": "Acme payments",
  "status": "active",
  "balance_sun": 1250400000,
  "balance_usdt": 0,
  "reserved_sun": 0,
  "deposit_addresses": [{"currency":"TRX","address":"TDepositAddressExample1111111111111"}],
  "limits": {"max_order_energy":3000000,"max_batch_receivers":100,"orders_per_second":30},
  "totals": {
    "deposited_sun": 5000000000,
    "spent_sun": 3749600000,
    "refunded_sun": 0,
    "orders_created": 1842,
    "energy_delegated": 119730000
  },
  "created_at": "2026-04-02T09:11:00.000Z"
}

修改账户显示名称

PATCH /v1/account · updateAccount

鉴权： 控制台会话 Cookie + X-CSRF-Token。

修改展示在控制台及相关报表中的账户别名。传入 null 将清空自定义别名并回退显示缩略的钱包地址。

属于控制台会话专属操作，要求拥有者 owner 权限。

请求体

JSON (AccountPatch)，必填。

字段类型必选说明
display_namestring | null账户自定义标题。不能全为空格且禁止包含控制字符。传入 null 清除。

响应

状态码含义
200已更新
400格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
401缺少、格式错误或已被拒绝的凭据。
403权限不足。
422语法合法但逻辑上无法满足操作要求。
500服务端内部错误。

响应字段 (Account)

与 GET /v1/account 响应中的字段结构相同。

仅查询实时余额

GET /v1/balance · getBalance

鉴权： API 密钥 (HMAC)。

为每次下单前高频轮询余额设计的轻量接口，资源开销显著低于完整的 /account 接口。

响应

状态码含义
200OK
401缺少、格式错误或已被拒绝的凭据。
429请求过于频繁。
500服务端内部错误。

响应字段 (Balance)

字段类型必选说明
balance_suninteger (int64)是账户总余额，以 SUN 为单位（1 TRX = 1,000,000 SUN）。始终为整数。
balance_usdtinteger (int64)
reserved_suninteger (int64)订单锁定中的冻结资金。
available_suninteger (int64)是balance_sun - reserved_sun。新订单实际可用的金额。
as_ofstring (date-time)是

来自规范的 200 响应示例（示意数值）：

json
{
  "balance_sun": 1250400000,
  "balance_usdt": 0,
  "reserved_sun": 0,
  "available_sun": 1250400000,
  "as_of": "2026-09-11T18:04:05.123Z"
}

获取专属充值地址

GET /v1/deposit-addresses · listDepositAddresses

鉴权： API 密钥 (HMAC)。

账户的专属充值地址：专属于此账户的 TRON 链上地址，无需任何附言或备注（memo 始终为 null）。接口返回两条记录（相同地址）：TRX 以及 USDT（TRC-20 合约），USDT 充值将在入账时按扣除点差后的实时汇率折算为 TRX 计入账本。

充值交易在达到指定确认区块数（confirmations_required）后完成入账，并触发 balance.credited Webhook 回调。

响应

状态码含义
200OK
401缺少、格式错误或已被拒绝的凭据。
429请求过于频繁。
500服务端内部错误。

响应字段

字段类型必选说明
dataarray of object (DepositAddress)是
data[].currencyenum: TRX, USDT是
data[].addressstring是Base58Check 编码的 TRON 地址（以 T 开头，34 个字符）。
data[].memostring | null恒为 null。
data[].confirmations_requiredinteger所需区块确认数。
data[].contractstring | null
data[].rate_nownull | object
data[].rate_now.trx_per_usdtstring是
data[].rate_now.sourceenum: sunswap_v3, fixed_env是
data[].rate_now.atstring (date-time)是
data[].spread_bpsinteger | null
data[].minstring | null
data[].maxstring | null
retiredarray of object账户曾用过的历史废弃地址（最新在前）。
retired[].addressstring是
retired[].retired_atstring (date-time)是
retired[].credited_untilstring (date-time)是在此时间点前向旧地址转账仍可自动到账。
rotationobject客服人工轮换地址规则参数。
rotation.byenum: support是
rotation.min_interval_daysinteger是
rotation.max_per_windowinteger是
rotation.window_daysinteger是
rotation.retired_credit_daysinteger是

来自规范的 200 响应示例（示意数值）：

json
{
  "data": [
    {
      "currency": "TRX",
      "address": "TDepositAddressExample1111111111111",
      "memo": null,
      "confirmations_required": 19
    }
  ],
  "retired": [
    {
      "address": "TRetiredAddressExample111111111111",
      "retired_at": "2026-09-20T10:00:00.000Z",
      "credited_until": "2026-10-20T10:00:00.000Z"
    }
  ],
  "rotation": {
    "by": "support",
    "min_interval_days": 7,
    "max_per_window": 3,
    "window_days": 90,
    "retired_credit_days": 30
  }
}

账户账本流水明细账单

GET /v1/ledger · listLedger

鉴权： 控制台会话 Cookie + X-CSRF-Token。

记录导致本账户余额变动的每一笔记账凭单流水（按最新时间倒序）：充值、下单扣款、退款及手续费。amount_sun / amount_usdt 为变动净额（正数为增加，负数为扣款）。

仅限控制台会话（需具备 viewer 或更高角色）。

请求参数

参数名位置类型必选说明
kindqueryenum: deposit, all流水类型过滤。
limitqueryinteger
cursorquerystring上次响应中 next_cursor 返回的不透明游标。

响应

状态码含义
200OK
400格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
401缺少、格式错误或已被拒绝的凭据。
403权限不足。
500服务端内部错误。

响应字段

字段类型必选说明
dataarray of object (LedgerEntry)是
data[].idstring是账本凭证全局流水号。
data[].kindenum: deposit, order_charge, order_refund, referral_payout, subscription_fee, subscription_usage, reserve_fee, invoice, withdrawal, adjustment是流水业务类别。
data[].amount_suninteger (int64)是TRX 余额净影响额（SUN），扣费为负数。
data[].amount_usdtinteger (int64)是USDT 余额净影响额。
data[].order_idstring | null是关联的订单 ID。
data[].depositnull | object是充值类型明细（非充值类别为 null）。
data[].deposit.txidstring | null是充值交易哈希。
data[].deposit.senderstring | null是汇款发起方地址。
data[].deposit.block_numberinteger | null是
data[].deposit.statusenum: credited, pending_rate, held_below_min, held_for_review是入账处理状态。
data[].deposit.confirmations_requiredinteger是
data[].deposit.assetenum: TRX, USDT
data[].deposit.usdt_amountstring | null收到 USDT 数量（十进制字符串）。
data[].deposit.ratestring | null折算汇率（扣除点差后）。
data[].deposit.rate_sourcestring | null汇率行情来源。
data[].deposit.spread_bpsinteger | null
data[].created_atstring (date-time)是
next_cursorstring | null是

来自规范的 200 响应示例（示意数值）：

json
{
  "data": [
    {
      "id": "jrn_01K5Y8Q2V9M3ZP4T7R1A2B3C4D",
      "kind": "order_charge",
      "amount_sun": -3900000,
      "amount_usdt": 0,
      "order_id": "ord_01K5Y8Q2V9M3ZP4T7R1A2B3C4E",
      "deposit": null,
      "created_at": "2026-09-25T10:12:04.000Z"
    },
    {
      "id": "jrn_01K5Y7A1B2C3D4E5F6G7H8J9K0",
      "kind": "deposit",
      "amount_sun": 50000000,
      "amount_usdt": 0,
      "order_id": null,
      "deposit": {
        "txid": "9f3c1e7a2b4d6f8091a3c5e7f9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7",
        "sender": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "block_number": 61000123,
        "status": "credited",
        "confirmations_required": 19
      },
      "created_at": "2026-09-25T09:58:40.000Z"
    }
  ],
  "next_cursor": null
}

账户常用地址薄

GET /v1/account/addresses · listAddressBook

鉴权： 控制台会话 Cookie + X-CSRF-Token。

返回此账户收藏保存的常用接收方地址（最新在前，最多 100 条）。

仅限控制台会话（需具备 viewer 或更高角色）。

响应

状态码含义
200OK
401缺少、格式错误或已被拒绝的凭据。
403权限不足。
500服务端内部错误。

响应字段

字段类型必选说明
dataarray of object (AddressBookEntry)是
data[].idstring是
data[].labelstring是
data[].addressstring是Base58Check 编码的 TRON 地址（以 T 开头，34 个字符）。
data[].created_atstring (date-time)是
data[].updated_atstring (date-time)是
limitinteger是
usedinteger是

来自规范的 200 响应示例（示意数值）：

json
{
  "data": [
    {
      "id": "adr_01K5Y9B7C8D9E0F1G2H3J4K5M6",
      "label": "Payouts hot wallet",
      "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
      "created_at": "2026-09-25T10:20:00.000Z",
      "updated_at": "2026-09-25T10:20:00.000Z"
    }
  ],
  "limit": 100,
  "used": 1
}

保存地址到地址薄

POST /v1/account/addresses · saveAddressBookEntry

鉴权： 控制台会话 Cookie + X-CSRF-Token。

将带有自定义标签名称的 address 保存到地址薄。每个账户内地址保持唯一：重复保存已存在的地址将直接覆盖其标签名称，返回 200 且不额外占用配额。

仅限控制台会话（需具备 editor 或更高角色）。

请求体

JSON (AddressBookRequest)，必填。

字段类型必选说明
labelstring是地址标签别名（修剪后 1–64 个字符）。
addressstring是Base58Check 编码的 TRON 地址（以 T 开头，34 个字符）。

来自规范的请求体示例（示意数值）：

json
{"label":"Payouts hot wallet","address":"TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"}

响应

状态码含义
200地址此前已存在；其标签别名已更新。
201成功保存为新条目。
400格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
401缺少、格式错误或已被拒绝的凭据。
403权限不足。
4093019 address_book_full —— 地址薄已达配额上限。
500服务端内部错误。

响应字段 (AddressBookEntry)

字段类型必选说明
idstring是
labelstring是
addressstring是Base58Check 编码的 TRON 地址（以 T 开头，34 个字符）。
created_atstring (date-time)是
updated_atstring (date-time)是

从地址薄删除地址

DELETE /v1/account/addresses/{entryId} · deleteAddressBookEntry

鉴权： 控制台会话 Cookie + X-CSRF-Token。

立即释放该条目在地址薄中占用的配额。要求具备 editor 角色的控制台会话。

请求参数

参数名位置类型必选说明
entryIdpathstring是

响应

状态码含义
204已删除。无响应体。
401缺少、格式错误或已被拒绝的凭据。
403权限不足。
404目标对象不存在或属于其他账户。
500服务端内部错误。

服务端聚合的订单统计分析

GET /v1/account/stats · getAccountStats

鉴权： API 密钥 (HMAC) 或控制台会话 Cookie + X-CSRF-Token。

专供控制台数据看板展示的分析统计指标，由服务端直接聚合计算时间范围 [from, to) 内的数据：

统计指标涵盖内容
orders所有已创建的订单总数
energy实际成功在链上完成质押交付的有效能量额度
spent_sun订单的净花费 total_amount_sun − refunded_amount_sun（包含激活费）
avg_price_sun_per_65k加权计算的每 65,000 能量平均单价（SUN）

历史数据保留周期：13 个月。 需要 orders.read 权限或控制台 viewer 角色。

请求参数

参数名位置类型必选说明
fromquerystring (date-time)起始时间。
toquerystring (date-time)截止时间。
bucketqueryenum: day时间聚合粒度。
utc_offset_minutesqueryinteger访问者客户端时区分钟偏移量。

响应

状态码含义
200OK
400格式错误的请求 —— 无效 JSON、未知字段或字段类型错误。
401缺少、格式错误或已被拒绝的凭据。
403权限不足。
429请求过于频繁。
500服务端内部错误。

响应字段 (AccountStats)

字段类型必选说明
fromstring (date-time)是实际计算所采用的起始时间戳。
tostring (date-time)是
requested_fromstring (date-time)是客户端原始请求指定的起始时间戳。
clampedboolean是当请求的起始时间早于平台数据保留期而被强制顺延时为 true。
retention_monthsinteger是数据保留最大月数。
bucketenum: day是
utc_offset_minutesinteger是
totalsobject是时间跨度内的汇总值。
totals.ordersinteger是
totals.energyinteger是
totals.spent_suninteger (int64)是以 SUN 为单位的金额（1 TRX = 1,000,000 SUN）。始终为整数。
totals.avg_price_sun_per_65kinteger | null是
seriesarray of object是按日分布的时序统计数据。
series[].datestring (date)是
series[].ordersinteger是
series[].energyinteger是
series[].spent_suninteger (int64)是以 SUN 为单位的金额（1 TRX = 1,000,000 SUN）。始终为整数。
weekday_hourarray of array of integer是活跃度热力矩阵：7 天（周一起始）× 24 小时分布。
top_receiversarray of object是接收资源消耗最多的热门地址列表。
top_receivers[].receiverstring是Base58Check 编码的 TRON 地址（以 T 开头，34 个字符）。
top_receivers[].ordersinteger是
top_receivers[].energyinteger是
top_receivers[].spent_suninteger (int64)是以 SUN 为单位的金额（1 TRX = 1,000,000 SUN）。始终为整数。

来自规范的 200 响应示例（示意数值）：

json
{
  "from": "2026-09-23T00:00:00.000Z",
  "to": "2026-09-25T00:00:00.000Z",
  "requested_from": "2026-09-23T00:00:00.000Z",
  "clamped": false,
  "retention_months": 13,
  "bucket": "day",
  "utc_offset_minutes": 0,
  "totals": {"orders":3,"energy":196000,"spent_sun":11760000,"avg_price_sun_per_65k":3900000},
  "series": [
    {"date":"2026-09-23","orders":1,"energy":65000,"spent_sun":3900000},
    {"date":"2026-09-24","orders":2,"energy":131000,"spent_sun":7860000}
  ],
  "weekday_hour": [[0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0]],
  "top_receivers": [
    {
      "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
      "orders": 2,
      "energy": 131000,
      "spent_sun": 7860000
    }
  ]
}

    ↑ ↓ 切换 · Enter 打开 · Esc 关闭