如果你在今年之前接入过 EOPEN，代码里多半还在用 pledgeAddress + rentalCount 加 API-KEY header。v1 把请求与响应字段名统一了——旧名字仍能用，但建议尽快迁。本文是迁移指南的精简版。

1. 为什么改？

旧字段有两个问题。pledgeAddress（pledge）听起来像「质押地址」，但它其实是「接收地址」。rentalCount 看起来像「租赁笔数」，但它实际上是「能量数量」。v1 用更清晰的语义和符合 REST/JSON 习惯的 snake_case 解决这两个问题，同时方便 SEO/GEO 工具理解。

2. 字段对照表

旧字段	v1 新字段	类型	说明
`pledgeAddress`	`receive_address`	字符串（TRON base58）	能量接收地址
`rentalCount`	`energy`	数字	委托能量数量（>= 32000）
`period`	`duration`	字符串	`'1h'` / `'6h'` / `'1d'`
`API-KEY`（header）	`X-API-Key`（header）	HTTP header	身份验证

3. curl 前后对比

旧字段（仍可用）：

curl -X POST https://api.eopen.io/v1/orders \
  -H 'API-KEY: $EOPEN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"pledgeAddress":"T...","rentalCount":65000,"period":"1h","currency":"USDT"}'

v1 新字段（推荐）：

curl -X POST https://api.eopen.io/v1/orders \
  -H 'X-API-Key: $EOPEN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"receive_address":"T...","energy":65000,"duration":"1h","currency":"USDT"}'

4. 响应体（v1 期间双字段兼容）

v1 期间响应同时包含新字段与旧别名。你可以分两步迁移：先改请求体，再改响应解析，最后清理旧代码。

{
  "id": "ord_01H...",
  "status": "delegated",
  "receive_address": "T...",
  "energy": 65000,
  "tx_hash": "abc123...",

  // legacy alias —— v1 期间仍然返回
  "pledgeAddress": "T...",
  "rentalCount": 65000
}

5. 废弃时间线

v1（当前）：请求与响应都同时支持新旧字段。
v2（约 6 个月后）：响应不再返回 legacy alias。请求仍接受旧字段。
v3（约 12 个月后）：完全废弃旧字段。仅含 pledgeAddress / rentalCount / period 的请求将返回 400。

每次升级前 30 天，我们会邮件通知所有 API Key 持有者。

6. 常见问题

现在改代码会影响线上吗？不会。v1 双向兼容新旧字段，可以分阶段灰度发布。

为什么旧博客和教程还在用 pledgeAddress？它们是 v1 统一之前写的。今后请以 API 参考与迁移指南为准。

docs.eopen.io 的交互式控制台呢？docs.eopen.io 也在跟随本次升级迁移到 v1 字段名，迁移期内两套名字都能用。

7. 下一步

阅读完整的 v1 API 参考
收藏迁移指南
在 docs.eopen.io 试用 v1 endpoint

权威来源：v1 API 参考与迁移指南。v1 期间旧字段仍接受，无需仓促迁移，但新接入项目请直接使用 v1 字段名。

迁移到 v1 字段名：pledgeAddress → receive_address，API-KEY → X-API-Key