安全设置

TronGrid 提供多种 API key 安全设置，用于限制 key 可以从哪里使用、可以访问哪些 API，以及是否需要额外的签名令牌。生产环境不应只依赖 API key 本身；建议结合业务形态配置允许列表或 JWT。

📘
注意
本页描述的安全配置主要适用于 HTTP 请求。gRPC 或其他接入方式是否支持相同策略，以 TronGrid 当前控制台和服务行为为准。

安全设置概览

设置	适用场景	作用
User-Agent 允许列表	移动 App、桌面 App、可控客户端	只允许带有指定 User-Agent 特征的请求使用 key
Origin 允许列表	Web DApp、浏览器前端	只允许来自指定 Origin 的浏览器请求使用 key
合约地址允许列表	只访问固定合约的应用	只允许访问或调用指定合约地址
请求 API 允许列表	只需要少量固定接口的服务	只允许调用明确列出的 API 方法
JWT	后端服务、需要强认证的请求	在 API key 之外增加基于 RS256 签名的令牌校验

User-Agent 允许列表

User-Agent 允许列表用于限制请求来源的客户端标识。配置后，只有 User-Agent 请求头匹配允许列表的请求才能使用该 API key。

匹配通常按子字符串进行。例如允许列表配置为：

com.example.wallet

请求头中包含该字符串即可匹配：

curl --request GET \
  --url 'https://api.trongrid.io/v1/accounts/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  --header 'TRON-PRO-API-KEY: <your-trongrid-api-key>' \
  --header 'User-Agent: com.example.wallet/1.2.0 (Android)'

User-Agent 可以被伪造，因此它适合作为基础过滤条件，不适合作为唯一安全边界。对高价值后端请求，应结合请求 API 允许列表、合约地址允许列表或 JWT。

Origin 允许列表

Origin 允许列表用于限制浏览器请求来源。它适合 Web DApp 或管理后台，防止其他网站直接复用你的 API key。

例如你的 DApp 部署在：

https://app.example.com

可以把该 Origin 加入允许列表。配置后，不包含匹配 Origin 请求头的浏览器请求会被拒绝。

Origin 匹配规则

Origin 规则可以包含 scheme，例如 https://。如果规则包含 scheme，请求的 scheme 必须一致。

通配符只能用于最左侧子域名，并且只匹配一个子域名层级。例如：

https://*.example.com

匹配结果：

Origin	结果	原因
`https://app.example.com`	允许	scheme 一致，一级子域名匹配
`https://admin.example.com`	允许	scheme 一致，一级子域名匹配
`http://app.example.com`	拒绝	scheme 不一致
`https://example.com`	拒绝	缺少子域名层级
`https://a.b.example.com`	拒绝	通配符只匹配一个子域名层级

请求示例：

curl --request GET \
  --url 'https://api.trongrid.io/v1/accounts/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  --header 'TRON-PRO-API-KEY: <your-trongrid-api-key>' \
  --header 'Origin: https://app.example.com'

合约地址允许列表

合约地址允许列表用于限制某把 API key 只能访问指定合约地址。它适合只服务固定 Token、固定 DApp 合约或固定业务合约的后端。

例如只允许访问某个 TRC-20 合约：

TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

允许列表生效后，涉及合约地址参数的兼容接口如果传入其他地址，会被拒绝。

请求示例：

curl --request GET \
  --url 'https://api.trongrid.io/v1/contracts/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/events' \
  --header 'TRON-PRO-API-KEY: <your-trongrid-api-key>'

请求 API 允许列表

请求 API 允许列表用于限制 API key 只能调用指定方法。它适合职责明确的服务，例如只读取账户交易历史、只查询事件，或只调用某个标准节点代理接口。

如果允许列表不为空，未列入的方法会被拒绝。建议生产环境按最小权限原则配置：服务需要哪些 API，就只开放哪些 API。

配置示例：

GET /v1/accounts/{address}/transactions
GET /v1/contracts/{address}/events
POST /walletsolidity/gettransactionbyid

实际可配置的方法名称和格式以 TronGrid 控制台为准。

JWT

JWT 为 API key 增加一层签名认证。启用 JWT 后，请求不仅需要携带 TRON-PRO-API-KEY，还需要在 Authorization 请求头中携带有效的 Bearer token。

TronGrid 当前使用 RS256 签名。你需要生成 RSA 密钥对，把公钥配置到 TronGrid 控制台，并在自己的服务端用私钥签发 JWT。

生成 RSA 密钥对

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

请妥善保管 private.pem。私钥只能保存在受控后端或密钥管理系统中，不能放到前端、移动 App、公开仓库或日志中。

JWT Header 和 Payload

Header 示例：

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "<jwt-key-id>"
}

Payload 示例：

{
  "aud": "trongrid.io",
  "exp": 1893456000
}

字段说明：

字段	说明
`alg`	固定为 `RS256`
`typ`	固定为 `JWT`
`kid`	TronGrid 控制台为该 JWT 公钥生成的 Key ID
`aud`	固定为 `trongrid.io`
`exp`	令牌过期时间，Unix timestamp

使用 JWT 请求 TronGrid

curl --request GET \
  --url 'https://api.trongrid.io/v1/accounts/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  --header 'TRON-PRO-API-KEY: <your-trongrid-api-key>' \
  --header 'Authorization: Bearer <jwt-token>'

Bearer 与 token 之间必须有一个空格。JWT 过期、签名错误、kid 不匹配或 aud 不正确时，请求会被拒绝。

场景	推荐配置
Web DApp	Origin 允许列表 + 请求 API 允许列表
移动 App 或桌面 App	User-Agent 允许列表 + 请求 API 允许列表，敏感请求转后端
后端服务	请求 API 允许列表 + 合约地址允许列表 + JWT
数据分析或索引器	单独 API key + 速率限制监控 + 最小 API 范围

注意

安全设置概览

User-Agent 允许列表

Origin 允许列表

Origin 匹配规则

合约地址允许列表

请求 API 允许列表

JWT

生成 RSA 密钥对

JWT Header 和 Payload

使用 JWT 请求 TronGrid

推荐配置

相关资源