# TRON 能量开放 API — REST 接口、Webhooks、OpenAPI | TEnergy

Source: https://tenergy.me/zh/api

1.  [TEnergy](/zh)
2.  API

# TRON 能量开放 API

仅需五个请求即可完成从算价到能量委托的全流程：预估、报价、下单、轮询、Webhook 回调。所有请求均采用 HMAC 签名，每个订单支持自定义幂等键，协议完全基于 OpenAPI 规范发布。

主网接口根地址为 `https://api.tenergy.me/v1`，Nile 测试网为 `https://api-nile.tenergy.me/v1`，拥有独立的 API 密钥、测试账户与账本。

[快速上手指南 →](/zh/docs/quickstart) [API 接口参考](/zh/docs/api/orders)

-   OpenAPI
-   HMAC
-   Webhooks
-   TypeScript SDK
-   Python SDK
-   MCP 服务器
-   Nile 测试网

订单费用预估 — 无需 API 密钥

```
curl -sG https://api-nile.tenergy.me/v1/estimate \
  -d resource=energy -d amount=65000 -d tier=1h
```

```
const query = new URLSearchParams({ resource: "energy", amount: "65000", tier: "1h" });
const res = await fetch(`https://api-nile.tenergy.me/v1/estimate?${query}`);
const estimate = await res.json();

// integers in SUN: 1 TRX = 1,000,000 SUN
console.log(estimate.price_sun_per_unit, "SUN per energy");
console.log(estimate.total_amount_sun / 1e6, "TRX for 65,000 energy, 1 hour");
```

```
import json, urllib.parse, urllib.request

query = urllib.parse.urlencode({"resource": "energy", "amount": 65000, "tier": "1h"})
with urllib.request.urlopen(f"https://api-nile.tenergy.me/v1/estimate?{query}") as res:
    estimate = json.load(res)

# integers in SUN: 1 TRX = 1,000,000 SUN
print(estimate["price_sun_per_unit"], "SUN per energy")
print(estimate["total_amount_sun"] / 1e6, "TRX for 65,000 energy, 1 hour")
```

运行按钮会向 api.tenergy.me（主网）发送公开价格请求，无需鉴权；下方代码示例使用 Nile 测试网。 

点击「发送请求」查看实时接口返回。

## 三种购买方式

完全相同的链上能量委托交付 — 根据您的调用规模和自动化程度自由选择。

| 方式 | 需要什么 | 账户 | 价格 |
| --- | --- | --- | --- |
| 直接转账 | 一个 TRON 钱包：向下单表单中的地址转入 TRX | 不需要 | 您的 TRX ÷ 实时价格，最少 64,000 能量 |
| 控制台 | 用钱包登录并充值余额 | 钱包登录 | 实时价格 |
| API | API 密钥和已充值的余额 | 钱包登录、API 密钥 | 实时价格 |

## SDK 与软件包

### TypeScript 与 Python SDK `@tenergy/sdk · tenergy`

每个操作一个类型化方法，两种语言均提供。

-   自动为每次请求附带最新时间戳与数字签名，内置智能重试机制
-   仅针对安全且幂等的 GET 和 DELETE 进行自动重试；创建订单严格保证单次提交
-   内置 waitForOrder / wait\_for\_order 订单状态等待与 Webhook 签名快速验签函数

已作为 beta 版发布到 npm 和 PyPI。不想加依赖时，快速入门里的签名辅助函数可用 cURL、TypeScript 或 Python 完成同样的事。

[阅读 SDK 指南 →](/zh/docs/quickstart#step-2--sign-requests-with-your-key)

五行代码完成首笔订单

```
import { TenergyClient } from "@tenergy/sdk";

const tenergy = new TenergyClient({
  baseUrl: "https://api-nile.tenergy.me/v1",
  apiKey: process.env.TENERGY_KEY!,
  apiSecret: process.env.TENERGY_SECRET!,
});

const quote = await tenergy.createQuote({
  resource: "energy", amount: 65_000, tier: "1h", receiver,
});
const order = await tenergy.createOrder({
  quote_id: quote.id, client_order_id: `payout-${invoiceId}`,
});
const done = await tenergy.waitForOrder(order.id);
if (done.partial) await reconcile(done.delivered_amount, done.refunded_amount_sun);
```

```
import os
from tenergy import Client

tenergy = Client(
    os.environ["TENERGY_KEY"], os.environ["TENERGY_SECRET"], network="nile",
)

quote = tenergy.create_quote({
    "resource": "energy", "amount": 65_000,
    "tier": "1h", "receiver": receiver,
})
order = tenergy.create_order({
    "quote_id": quote["id"], "client_order_id": f"payout-{invoice_id}",
})
done = tenergy.wait_for_order(order["id"])
if done.get("partial"):
    reconcile(done["delivered_amount"], done["refunded_amount_sun"])
```

| 软件包 | 说明 | 指南 |
| --- | --- | --- |
| @tenergy/sdk | TypeScript，完整类型，基于契约生成 · npm beta 版 | [阅读 SDK 指南](/zh/docs/sdk/typescript) |
| tenergy | Python，同步与异步客户端，Webhook 验证 · PyPI beta 版 | [阅读 SDK 指南](/zh/docs/sdk) |
| mcp.tenergy.me | 托管的 MCP 服务器，供 AI 代理使用 · 无需安装 | [MCP](/zh/docs/mcp) |

已经在用其他能量服务？无需安装任何包：保留现有 API，只改 base URL。 [兼容 API →](/zh/compatibility)

## 支持任意顺序阅读的现代化文档

三栏式布局，支持 Ctrl+K 全局极速搜索，提供 cURL、TypeScript、Python 多语言代码片段，接口参考直接源自契约生成 — 每个文档页面在路径后附加 .md 即可直接获取 Markdown 格式原文。

[浏览开发文档 →](/zh/docs)

[![TEnergy 开发文档快速入门页面预览：左侧目录导航，居中代码片段，右侧页面大纲](/images/docs-quickstart-1280.webp)](/zh/docs/quickstart)

## 新手推荐阅读

-   [**快速开始** 通过三种语言的五个请求，实现从费用预估到订单链上确认。](/zh/docs/quickstart)
-   [**AI Agent 快速入门** 即插即用的提示词，让您的代码助手直接接入而无需人工翻找端点。](/zh/docs/agent-quickstart)
-   [**错误码与频控限制** 详细说明每个业务错误码、对应 HTTP 状态以及重试策略。](/zh/docs/errors)

## 机器可读规范

| 规范文档 | 用途说明 |
| --- | --- |
| [/openapi.yaml](/openapi.yaml) | 契约源头。直接用于代码生成；任何与说明文字冲突之处以本契约规范为准。 |
| [/llms.txt](/llms.txt) | 专为 AI Agent 优化的上下文导图：按最短采购路径编排的必读文档精选。 |
| [/llms-full.txt](/llms-full.txt) | 将完整语料库聚合为单个 Markdown 文件，适合偏好一次性读取的 Agent。 |
| [/.well-known/quickstart.json](/.well-known/quickstart.json) | JSON 格式购买流程：包含端点、鉴权、计量单位及需要人工确认的步骤。 |
| [/docs/agent-quickstart](/zh/docs/agent-quickstart) | 直接粘贴至您自己编码 Agent 中的操作者系统提示词，支持一键复制。 |
| [/docs/quickstart.md](/docs/quickstart.md) | 所有文档页面均提供 Markdown 格式：在任意文档 URL 后附加 .md 即可获取。 |

## 常见问题

01

### API 请求如何进行身份签名验证？

需要提供三个请求头：X-API-KEY、X-API-TIMESTAMP 及 X-API-SIGN。签名算法为 base64(HMAC-SHA256(secret, timestamp + method + path + query + body))。允许的时钟偏差为 5 秒以内。

02

### 新建的 API 密钥默认具有哪些权限？

严格取决于您勾选的权限范围。scopes 字段为必填项，无论在合约层、控制台还是 Agent 接入流程中，均不提供默认权限，也不存在任何隐式预选。

03

### 应该使用轮询还是 Webhooks？

如果您拥有公网 HTTPS 服务器，强烈推荐使用 Webhook 回调：我们对每次回调附带签名，您只需验签即可。对于没有公网 URL 的 Agent 本地运行时，文档支持轮询 GET /v1/orders/{id} 作为官方备选方案。

没有找到答案？请在 Telegram 联系 [@tenergymebot](https://t.me/tenergymebot)，或发邮件至 [support@tenergy.me](mailto:support@tenergy.me)，我们会把答案补充到这里。