{
  "openapi": "3.0.1",
  "info": {
    "title": "TRX 能量租赁平台 OpenAPI V1",
    "description": "用于 TRON 能量租赁平台开放接口对接的 OpenAPI 文档。接口采用请求级 HMAC-SHA256 签名认证，支持查询价格、购买能量、查询订单结果以及智能托管（Smart Delegation）相关操作。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://trxhh.com/api/v1"
    }
  ],
  "tags": [
    {
      "name": "基础接口",
      "description": "探活与基础检查。"
    },
    {
      "name": "账户",
      "description": "获取当前 API Key 对应账户信息。"
    },
    {
      "name": "能量订单",
      "description": "能量价格查询、下单与订单结果查询。"
    },
    {
      "name": "智能托管",
      "description": "智能托管价格、额度充值、状态查询、启停与统计。"
    },
    {
      "name": "笔数托管",
      "description": "笔数托管价格、下单、状态查询与启停（按次数计费，无押金）。"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "OpenAPI 认证要求在请求头中包含 `x-api-key`、`x-timestamp`、`x-nonce`、`x-signature`。其中 `x-signature = HMAC-SHA256(stringToSign, api_secret)`，`stringToSign = METHOD + \"\\n\" + rawPath + \"\\n\" + rawQuery + \"\\n\" + sha256(rawBody) + \"\\n\" + x-timestamp + \"\\n\" + x-nonce + \"\\n\" + x-api-key + \"\\n\" + (x-idempotency-key || \"\")`。"
      }
    },
    "parameters": {
      "XApiKeyHeader": {
        "name": "x-api-key",
        "in": "header",
        "required": true,
        "description": "您的 API Key，在首页 → 个人资料 → 开放API Key 模块创建。",
        "schema": {
          "type": "string",
          "example": "ak_xxxxxxxxxxxxxxxx"
        }
      },
      "XTimestampHeader": {
        "name": "x-timestamp",
        "in": "header",
        "required": true,
        "description": "10 位 Unix 时间戳（秒），允许与服务端相差 ±5 分钟。",
        "schema": {
          "type": "string",
          "example": "1704614400"
        }
      },
      "XNonceHeader": {
        "name": "x-nonce",
        "in": "header",
        "required": true,
        "description": "每个请求唯一随机串，仅允许字母、数字、_、-，长度 16-128；重复使用会返回 409。",
        "schema": {
          "type": "string",
          "example": "req_20250324_abcd1234"
        }
      },
      "XSignatureHeader": {
        "name": "x-signature",
        "in": "header",
        "required": true,
        "description": "对 stringToSign 做 HMAC-SHA256 后得到的小写 hex。",
        "schema": {
          "type": "string",
          "example": "a1b2c3d4e5f6..."
        }
      },
      "XIdempotencyKeyHeader": {
        "name": "x-idempotency-key",
        "in": "header",
        "required": true,
        "description": "buy_energy 与 delegate_energy_smart 必填。业务幂等键，最长 128 字符，仅允许字母、数字、连字符和下划线；相同幂等键重复请求返回同一结果，不会重复扣费。",
        "schema": {
          "type": "string",
          "example": "order_20250324_001"
        }
      },
      "OrderSnQuery": {
        "name": "order_sn",
        "in": "query",
        "required": true,
        "description": "购买能量时返回的订单号。",
        "schema": {
          "type": "string",
          "example": "ORD20250107123456789"
        }
      },
      "TypeQuery": {
        "name": "type",
        "in": "query",
        "required": true,
        "description": "资源类型。当前主要支持 energy；传 net 时服务端可能返回不支持。",
        "schema": {
          "type": "string",
          "enum": [
            "energy",
            "net"
          ],
          "example": "energy"
        }
      },
      "CountQuery": {
        "name": "count",
        "in": "query",
        "required": true,
        "description": "资源数量。",
        "schema": {
          "type": "integer",
          "example": 65000
        }
      },
      "PeriodQuery": {
        "name": "period",
        "in": "query",
        "required": true,
        "description": "租赁周期，例如 1h、1day、3day。",
        "schema": {
          "type": "string",
          "example": "1h"
        }
      },
      "AddressQuery": {
        "name": "address",
        "in": "query",
        "required": true,
        "description": "TRON 地址。",
        "schema": {
          "type": "string",
          "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
      },
      "PageQuery": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "页码，默认 1。",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "example": 1
        }
      }
    },
    "schemas": {
      "BaseResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "状态码，1 表示成功。",
            "enum": [
              1
            ],
            "example": 1
          },
          "msg": {
            "type": "string",
            "description": "响应消息。",
            "example": "success"
          },
          "time": {
            "type": "string",
            "description": "服务器 Unix 时间戳（秒）。",
            "example": "1704614400"
          },
          "data": {
            "type": "object",
            "nullable": true
          }
        },
        "required": [
          "code",
          "msg",
          "time"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "状态码，0 表示失败。",
            "enum": [
              0
            ],
            "example": 0
          },
          "msg": {
            "type": "string",
            "description": "错误消息。",
            "example": "参数错误"
          },
          "time": {
            "type": "string",
            "description": "服务器 Unix 时间戳（秒）。",
            "example": "1704614400"
          },
          "data": {
            "type": "object",
            "nullable": true,
            "example": null
          }
        },
        "required": [
          "code",
          "msg",
          "time"
        ]
      },
      "PingResponseData": {
        "nullable": true,
        "example": null
      },
      "UserInfoData": {
        "type": "object",
        "properties": {
          "balance_trx": {
            "type": "string",
            "description": "TRX 余额。",
            "example": "1000.50"
          },
          "balance_usdt": {
            "type": "string",
            "description": "USDT 余额。",
            "example": "500.25"
          }
        },
        "required": [
          "balance_trx",
          "balance_usdt"
        ]
      },
      "QueryPriceData": {
        "type": "object",
        "properties": {
          "price": {
            "type": "integer",
            "description": "能量单价（SUN，按 65000 能量为基准单位）。",
            "example": 16000000
          },
          "amount": {
            "type": "string",
            "description": "本次订单总金额（TRX）。",
            "example": "10.4000"
          },
          "fee": {
            "type": "string",
            "description": "手续费（TRX）。",
            "example": "0.0000"
          },
          "remark": {
            "type": "string",
            "description": "价格说明。",
            "example": "65000 能量 x 1h"
          },
          "price_trx": {
            "type": "string",
            "description": "本次订单总金额（TRX），与 amount 相同。",
            "example": "10.4000"
          },
          "price_usdt": {
            "type": [
              "string",
              "null"
            ],
            "description": "本次订单总金额的 USDT 参考价；取不到汇率时为 null。",
            "example": "3.2000"
          }
        },
        "required": [
          "price",
          "amount",
          "fee",
          "remark"
        ]
      },
      "BuyEnergyRequest": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "description": "能量数量。",
            "example": 65000
          },
          "period": {
            "type": "string",
            "description": "租赁周期。",
            "example": "1h"
          },
          "address": {
            "type": "string",
            "description": "接收能量的 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          }
        },
        "required": [
          "count",
          "period",
          "address"
        ]
      },
      "BuyEnergyData": {
        "type": "object",
        "properties": {
          "order_sn": {
            "type": "string",
            "description": "订单号。",
            "example": "ORD20250107123456789"
          },
          "status": {
            "type": "string",
            "description": "订单状态：processing=已受理，余额已扣除，委托正在后台执行，请轮询 query_result；completed=能量已委托到账（仅当接口在返回前已完成时才直接出现）；pending=排队中。注意：受理成功不代表能量已到账，业务判断请以 query_result 的最终状态为准。",
            "enum": [
              "pending",
              "processing",
              "completed"
            ],
            "example": "processing"
          },
          "count": {
            "type": "integer",
            "description": "购买的能量数量。",
            "example": 65000
          },
          "period": {
            "type": "string",
            "description": "购买周期。",
            "example": "1h"
          },
          "address": {
            "type": "string",
            "description": "接收能量的 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "price_trx": {
            "type": "string",
            "description": "本次订单实际扣款金额（TRX），与 amount 相同。",
            "example": "10.4000"
          },
          "price": {
            "type": [
              "integer",
              "null"
            ],
            "description": "能量单价（SUN）。",
            "example": 16000000
          },
          "fee": {
            "type": [
              "number",
              "null"
            ],
            "description": "手续费（TRX）。",
            "example": 0
          },
          "amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "本次订单实际扣款金额（TRX）。",
            "example": 10.4
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "description": "扣款后的 TRX 可用余额；幂等重放时可能为 null。",
            "example": 989.6
          }
        },
        "required": [
          "order_sn",
          "status",
          "amount"
        ]
      },
      "QueryResultOrderItem": {
        "type": "object",
        "properties": {
          "from_address": {
            "type": "string",
            "description": "委托来源地址。",
            "example": "TYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "tx_id": {
            "type": "string",
            "nullable": true,
            "description": "链上交易哈希。",
            "example": "abc123..."
          },
          "count": {
            "type": "integer",
            "description": "该笔委托的资源数量。",
            "example": 65000
          }
        },
        "required": [
          "from_address",
          "count"
        ]
      },
      "QueryResultData": {
        "type": "object",
        "properties": {
          "order_sn": {
            "type": "string",
            "description": "订单号。",
            "example": "ORD20250107123456789"
          },
          "status": {
            "type": "string",
            "description": "订单状态（对外枚举）：pending=排队中，processing=处理中，completed=已完成，failed=失败（余额已退回），refund_pending=失败待退款审核，refunded=已退款。",
            "enum": [
              "pending",
              "processing",
              "completed",
              "failed",
              "refund_pending",
              "refunded"
            ],
            "example": "completed"
          },
          "status_detail": {
            "type": "string",
            "description": "平台内部细分状态（waiting / review_pending / success / failed），排查问题用。",
            "example": "success"
          },
          "count": {
            "type": "integer",
            "description": "订单中的能量数量（智能托管订单为 null）。",
            "example": 65000
          },
          "period": {
            "type": "string",
            "description": "订单周期。",
            "example": "1h"
          },
          "address": {
            "type": "string",
            "description": "目标 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "price_trx": {
            "type": "string",
            "description": "订单扣款金额（TRX），与 amount 相同。",
            "example": "10.4000"
          },
          "amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "订单扣款金额（TRX）。",
            "example": 10.4
          },
          "price": {
            "type": [
              "integer",
              "null"
            ],
            "description": "订单的能量单价（SUN）。",
            "example": 16000000
          },
          "fee": {
            "type": [
              "number",
              "null"
            ],
            "description": "订单手续费（TRX）。",
            "example": 0
          },
          "orders": {
            "type": "array",
            "description": "委托明细列表。",
            "items": {
              "$ref": "#/components/schemas/QueryResultOrderItem"
            }
          }
        },
        "required": [
          "order_sn",
          "status",
          "orders"
        ]
      },
      "SmartPriceData": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "description": "计价币种。",
            "example": "TRX"
          },
          "price_65k": {
            "type": "number",
            "description": "每笔 65K 交易的最终额度成本（TRX）。",
            "example": 0.5775
          },
          "price_131k": {
            "type": "number",
            "description": "每笔 131K 交易的最终额度成本（TRX）。",
            "example": 1.09725
          },
          "min_balance": {
            "type": "number",
            "description": "单次充值额度下限（TRX）。",
            "example": 1
          },
          "max_balance": {
            "type": "number",
            "description": "单次充值额度上限（TRX）。",
            "example": 1000000
          },
          "channels": {
            "type": "array",
            "description": "高频及以上通道的最终单价、押金与最低消耗要求。",
            "items": {
              "type": "object",
              "properties": {
                "channel": {
                  "type": "string",
                  "enum": [
                    "high_frequency",
                    "jisu_frequency",
                    "guangsu_frequency"
                  ],
                  "example": "high_frequency"
                },
                "price_65k": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "该通道每笔 65K 交易的最终额度成本（TRX）。",
                  "example": 0.462
                },
                "price_131k": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "该通道每笔 131K 交易的最终额度成本（TRX）。",
                  "example": 0.924
                },
                "deposit_trx": {
                  "type": "number",
                  "description": "该通道保证金（TRX）。",
                  "example": 15
                },
                "deposit_period_hours": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "保证金统计周期（小时）。",
                  "example": 72
                },
                "min_energy_count": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "统计周期内最低消耗能量数。",
                  "example": 455000
                },
                "min_transaction_count": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "最低消耗能量折算的笔数（按 65K/笔）。",
                  "example": 7
                }
              }
            }
          }
        },
        "required": [
          "price_65k",
          "price_131k"
        ]
      },
      "DelegateEnergySmartRequest": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "要增加额度的 TRON 地址（必须已激活）。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "balance": {
            "type": "number",
            "format": "float",
            "description": "增加的额度（TRX，正数，最小 1，最大 1000000）。",
            "example": 10
          },
          "channel": {
            "type": "string",
            "enum": [
              "normal",
              "high_frequency",
              "jisu_frequency",
              "guangsu_frequency"
            ],
            "description": "能量通道（可选，默认 normal）。",
            "example": "normal"
          },
          "hf_deposit": {
            "type": "number",
            "description": "押金金额（TRX，可选）：-1 跟随系统设置、0 不扣押金；不传则以实际收取为准。",
            "example": 15
          }
        },
        "required": [
          "address",
          "balance"
        ]
      },
      "SmartDelegationData": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "目标 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "balance": {
            "type": "string",
            "description": "充值后的剩余可用额度（TRX）。",
            "example": "20.5000"
          },
          "status": {
            "type": "string",
            "enum": [
              "start",
              "stop"
            ],
            "description": "服务状态。",
            "example": "start"
          },
          "quota": {
            "type": [
              "number",
              "null"
            ],
            "description": "本次充值额度（TRX）；幂等重放时可能为 null。",
            "example": 10
          },
          "charge_amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "本次实际扣款金额（TRX，含加价）。",
            "example": 11.55
          },
          "channel": {
            "type": [
              "string",
              "null"
            ],
            "description": "本单使用的能量通道。",
            "example": "normal"
          },
          "deposit_trx": {
            "type": [
              "number",
              "null"
            ],
            "description": "本单随单收取的押金（TRX）；普通通道或选择了不扣押金时为 0。",
            "example": 0
          }
        },
        "required": [
          "address",
          "balance",
          "status"
        ]
      },
      "TimesPriceData": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "description": "计价币种。",
            "example": "TRX"
          },
          "unit_price_trx": {
            "type": "number",
            "description": "单次笔数托管的最终单价（TRX）。",
            "example": 1.98
          },
          "min_times_per_order": {
            "type": "integer",
            "description": "单次最少下单次数。",
            "example": 5
          }
        },
        "required": [
          "unit_price_trx"
        ]
      },
      "DelegateEnergyTimesRequest": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "要开通/追加笔数托管的 TRON 地址（必须已激活）。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "rent_times": {
            "type": "integer",
            "description": "下单次数（整数，最少 5，最大 100000）。",
            "example": 20
          },
          "free_pause_days": {
            "type": [
              "integer",
              "null"
            ],
            "description": "空闲暂停天数（可选，2/3/5/7；不传表示不暂停）。",
            "example": 3
          },
          "resource_replenish": {
            "type": "string",
            "enum": [
              "0",
              "1"
            ],
            "description": "资源补充（可选）：0 不补充、1 自动补充带宽/TRX。",
            "example": "1"
          }
        },
        "required": [
          "address",
          "rent_times"
        ]
      },
      "TimesDelegationData": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "目标 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "rent_times": {
            "type": [
              "integer",
              "null"
            ],
            "description": "本次租用次数。",
            "example": 20
          },
          "remain_times": {
            "type": [
              "integer",
              "null"
            ],
            "description": "剩余可用笔数。",
            "example": 18
          },
          "provided_times": {
            "type": [
              "integer",
              "null"
            ],
            "description": "已下发次数。",
            "example": 2
          },
          "status": {
            "type": "string",
            "description": "托管状态：start 已开启 / stop 已暂停 / unknown 待确认。",
            "example": "start"
          },
          "free_pause_days": {
            "type": [
              "integer",
              "null"
            ],
            "description": "空闲暂停天数（null 表示不暂停）。",
            "example": 3
          },
          "resource_replenish": {
            "type": [
              "string",
              "null"
            ],
            "description": "资源补充显示状态。",
            "example": "开启"
          },
          "charge_amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "本次实际扣款金额（TRX，含加价）。",
            "example": 39.6
          }
        },
        "required": [
          "address",
          "status"
        ]
      },
      "TimesDelegationStateData": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "目标 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "rent_times": {
            "type": [
              "integer",
              "null"
            ],
            "description": "租用次数。",
            "example": 20
          },
          "remain_times": {
            "type": [
              "integer",
              "null"
            ],
            "description": "剩余可用笔数。",
            "example": 18
          },
          "provided_times": {
            "type": [
              "integer",
              "null"
            ],
            "description": "已下发次数。",
            "example": 2
          },
          "status": {
            "type": "string",
            "description": "托管状态：start 已开启 / stop 已暂停 / unknown 待确认。",
            "example": "start"
          },
          "free_pause_days": {
            "type": [
              "integer",
              "null"
            ],
            "description": "空闲暂停天数（null 表示不暂停）。",
            "example": 3
          },
          "resource_replenish": {
            "type": [
              "string",
              "null"
            ],
            "description": "资源补充显示状态。",
            "example": "开启"
          }
        },
        "required": [
          "address",
          "status"
        ]
      },
      "UpdateEnergyTimesRequest": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "要更新状态的 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "status": {
            "type": "string",
            "enum": [
              "start",
              "stop"
            ],
            "description": "目标状态：start 启用 / stop 暂停。",
            "example": "start"
          }
        },
        "required": [
          "address",
          "status"
        ]
      },
      "SmartDelegationStateData": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "目标 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "balance": {
            "type": "string",
            "description": "剩余可用额度（TRX）。",
            "example": "20.5000"
          },
          "status": {
            "type": "string",
            "enum": [
              "start",
              "stop"
            ],
            "description": "服务状态。",
            "example": "stop"
          }
        },
        "required": [
          "address",
          "balance",
          "status"
        ]
      },
      "SmartOrderItem": {
        "type": "object",
        "properties": {
          "energy_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "能量类型：65k / 131k。",
            "example": "65k"
          },
          "amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "本次消耗金额（TRX）。",
            "example": 0.5
          },
          "balance": {
            "type": [
              "number",
              "null"
            ],
            "description": "消耗后剩余额度。",
            "example": 20.5
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "币种。",
            "example": "trx"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "消耗状态。",
            "example": "delegate_success"
          },
          "used_tx_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "消耗能量的交易哈希。",
            "example": "abc123..."
          },
          "used_energy": {
            "type": [
              "integer",
              "null"
            ],
            "description": "消耗的能量值。",
            "example": 65000
          },
          "used_times": {
            "type": [
              "integer",
              "null"
            ],
            "description": "使用笔数。",
            "example": 1
          },
          "remain_times": {
            "type": [
              "integer",
              "null"
            ],
            "description": "地址剩余总笔数。",
            "example": 85
          },
          "delegate_count": {
            "type": [
              "integer",
              "null"
            ],
            "description": "委托的能量数量。",
            "example": 65000
          },
          "delegate_tx_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "委托交易哈希。",
            "example": "def456..."
          },
          "delegate_time": {
            "type": [
              "integer",
              "null"
            ],
            "description": "委托时间戳。",
            "example": 1704614300
          },
          "un_delegate_tx_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "回收交易哈希。",
            "example": null
          },
          "un_delegate_time": {
            "type": [
              "integer",
              "null"
            ],
            "description": "回收时间戳。",
            "example": null
          },
          "createtime": {
            "type": [
              "integer",
              "null"
            ],
            "description": "记录创建时间戳。",
            "example": 1704614300
          }
        }
      },
      "QueryEnergySmartData": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "查询的 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "balance": {
            "type": "string",
            "description": "剩余可用额度（TRX）。",
            "example": "20.5000"
          },
          "status": {
            "type": "string",
            "enum": [
              "start",
              "stop"
            ],
            "description": "服务状态。",
            "example": "start"
          },
          "order_count": {
            "type": "integer",
            "description": "总消耗记录数。",
            "example": 15
          },
          "page_size": {
            "type": "integer",
            "description": "每页记录数。",
            "example": 20
          },
          "page": {
            "type": "integer",
            "description": "当前页码。",
            "example": 1
          },
          "orders": {
            "type": "array",
            "description": "当前页消耗记录。",
            "items": {
              "$ref": "#/components/schemas/SmartOrderItem"
            }
          }
        },
        "required": [
          "address",
          "balance",
          "status",
          "order_count",
          "page_size",
          "page",
          "orders"
        ]
      },
      "UpdateEnergySmartRequest": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "要更新状态的 TRON 地址。",
            "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          "status": {
            "type": "string",
            "enum": [
              "start",
              "stop"
            ],
            "description": "目标状态：start 启用 / stop 暂停。",
            "example": "stop"
          }
        },
        "required": [
          "address",
          "status"
        ]
      },
      "SmartStatisticsDetail": {
        "type": "object",
        "properties": {
          "65k": {
            "type": "integer",
            "description": "65K 类型操作笔数。",
            "example": 8
          },
          "131k": {
            "type": "integer",
            "description": "131K 类型操作笔数。",
            "example": 2
          }
        },
        "required": [
          "65k",
          "131k"
        ]
      },
      "StatisticsSmartData": {
        "type": "object",
        "properties": {
          "days": {
            "type": "object",
            "description": "最近 5 天统计（键为 YYYY-MM-DD）。",
            "additionalProperties": {
              "$ref": "#/components/schemas/SmartStatisticsDetail"
            }
          },
          "today": {
            "$ref": "#/components/schemas/SmartStatisticsDetail"
          },
          "yesterday": {
            "$ref": "#/components/schemas/SmartStatisticsDetail"
          },
          "this_week": {
            "$ref": "#/components/schemas/SmartStatisticsDetail"
          },
          "this_month": {
            "$ref": "#/components/schemas/SmartStatisticsDetail"
          }
        },
        "required": [
          "days",
          "today",
          "yesterday",
          "this_week",
          "this_month"
        ]
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/ping": {
      "get": {
        "tags": [
          "基础接口"
        ],
        "summary": "探活接口",
        "description": "用于检测 API 服务是否正常运行，此接口无需认证。",
        "operationId": "pingV1",
        "security": [],
        "responses": {
          "200": {
            "description": "服务正常。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "msg": {
                          "example": "pong"
                        },
                        "data": {
                          "$ref": "#/components/schemas/PingResponseData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/user_info": {
      "get": {
        "tags": [
          "账户"
        ],
        "summary": "获取用户信息",
        "description": "获取当前 API Key 关联用户的账户信息，包括余额等。",
        "operationId": "getUserInfoV1",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "成功获取用户信息。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/UserInfoData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/query_price": {
      "get": {
        "tags": [
          "能量订单"
        ],
        "summary": "查询价格",
        "description": "查询指定资源类型、数量和周期的价格。",
        "operationId": "queryPriceV1",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          },
          {
            "$ref": "#/components/parameters/TypeQuery"
          },
          {
            "$ref": "#/components/parameters/CountQuery"
          },
          {
            "$ref": "#/components/parameters/PeriodQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回价格。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/QueryPriceData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/buy_energy": {
      "post": {
        "tags": [
          "能量订单"
        ],
        "summary": "购买能量",
        "description": "购买能量并委托到指定地址。此接口为异步受理：校验通过并扣款成功后立即返回订单号（`status=processing`），实际委托在后台完成；请用返回的 `order_sn` 轮询 `query_result` 获取最终结果（completed / failed / refund_pending）。此接口要求额外携带 `x-idempotency-key` 请求头，且该请求头也参与签名；重试请复用同一幂等键。",
        "operationId": "buyEnergyV1",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          },
          {
            "$ref": "#/components/parameters/XIdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuyEnergyRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/BuyEnergyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "订单已受理（余额已扣除，实际委托在处理中）。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BuyEnergyData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/query_result": {
      "get": {
        "tags": [
          "能量订单"
        ],
        "summary": "查询订单结果",
        "description": "根据订单号查询订单执行结果和委托详情。",
        "operationId": "queryResultV1",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          },
          {
            "$ref": "#/components/parameters/OrderSnQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回订单状态。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/QueryResultData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/get_smart_price": {
      "get": {
        "tags": [
          "智能托管"
        ],
        "summary": "获取智能托管价格",
        "description": "获取 65K / 131K 每次智能能量委托的单价、各能量通道的价格与押金，以及单次充值额度上下限。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SmartPriceData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/delegate_energy_smart": {
      "post": {
        "tags": [
          "智能托管"
        ],
        "summary": "委托智能托管额度",
        "description": "为指定地址增加智能托管可用额度（余额）。本次扣款 = 充值额度 + 押金（如涉及，押金以实际收取为准），最终以接口返回的 charge_amount 为准。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          },
          {
            "$ref": "#/components/parameters/XIdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DelegateEnergySmartRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/DelegateEnergySmartRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SmartDelegationData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误或缺少 x-idempotency-key。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "425": {
            "description": "相同幂等键的请求正在处理中。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/query_energy_smart": {
      "get": {
        "tags": [
          "智能托管"
        ],
        "summary": "查询智能托管状态",
        "description": "获取指定地址的剩余额度、服务状态与消耗记录（分页）。地址必须由当前 API Key 所属用户充值过。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          },
          {
            "$ref": "#/components/parameters/AddressQuery"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/QueryEnergySmartData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/update_energy_smart": {
      "post": {
        "tags": [
          "智能托管"
        ],
        "summary": "更新智能托管状态",
        "description": "启用（start）或暂停（stop）指定地址的智能托管服务。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateEnergySmartRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/UpdateEnergySmartRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SmartDelegationStateData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/statistics_smart_by_address": {
      "get": {
        "tags": [
          "智能托管"
        ],
        "summary": "获取智能托管统计",
        "description": "获取指定地址在不同时间段的智能托管消耗统计（区分 65K / 131K）。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          },
          {
            "$ref": "#/components/parameters/AddressQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/StatisticsSmartData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/get_times_price": {
      "get": {
        "tags": [
          "笔数托管"
        ],
        "summary": "查询笔数托管单价",
        "description": "查询当前 API Key 对应用户的笔数托管最终单价。笔数托管按次数计费，无押金。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TimesPriceData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/delegate_energy_times": {
      "post": {
        "tags": [
          "笔数托管"
        ],
        "summary": "下单笔数托管",
        "description": "为地址开通或追加笔数托管次数。扣款金额 = 次数 × 单价（含加价），无押金。首次开通最少 5 次。必须携带 x-idempotency-key。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          },
          {
            "$ref": "#/components/parameters/XIdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DelegateEnergyTimesRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/DelegateEnergyTimesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TimesDelegationData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误或缺少 x-idempotency-key。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "425": {
            "description": "相同幂等键的请求正在处理中。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/query_energy_times": {
      "get": {
        "tags": [
          "笔数托管"
        ],
        "summary": "查询笔数托管状态",
        "description": "查询指定地址的笔数托管状态：剩余笔数、租用次数、已下发次数、空闲暂停天数与启停状态。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          },
          {
            "name": "address",
            "in": "query",
            "required": true,
            "description": "要查询的 TRON 地址。",
            "schema": {
              "type": "string",
              "example": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TimesDelegationStateData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/update_energy_times": {
      "post": {
        "tags": [
          "笔数托管"
        ],
        "summary": "启用/暂停笔数托管",
        "description": "启用或暂停指定地址的笔数托管。与目标状态一致时直接返回当前状态，不重复下发。",
        "parameters": [
          {
            "$ref": "#/components/parameters/XApiKeyHeader"
          },
          {
            "$ref": "#/components/parameters/XTimestampHeader"
          },
          {
            "$ref": "#/components/parameters/XNonceHeader"
          },
          {
            "$ref": "#/components/parameters/XSignatureHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateEnergyTimesRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/UpdateEnergyTimesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功。",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TimesDelegationStateData"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}