Migrate to v1 Field Names: pledgeAddress → receive_address, API-KEY → X-API-Key

If you integrated EOPEN before this year, your code probably still posts pledgeAddress + rentalCount with an API-KEY header. In v1 we standardized the request and response field names — and the old names still work, but you should plan the move. This post is the short version of the migration guide.

1. Why we changed the names

The legacy names had two problems. pledgeAddress sounded like the address pledging Energy when it actually receives Energy. rentalCount looked like a count of rentals when it was actually an Energy amount in units of Energy. v1 fixes both with clearer semantics and snake_case that fits REST/JSON conventions and parses cleanly in SEO/GEO tooling.

2. Field-by-field mapping

3. curl before / after

Legacy — still works:

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 Current — recommended:

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. Response shape (dual-field during v1)

During v1, the response includes both new fields and legacy aliases. You can update your code in two steps: switch the request payload first, then your response parser, then drop the legacy fields.

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

  // legacy aliases — still emitted during v1
  "pledgeAddress": "T...",
  "rentalCount": 65000
}

5. Deprecation timeline

• v1 (current): dual-field compatibility on requests and responses.
• v2 (~6 months out): responses drop the legacy aliases. Requests still accept legacy names.
• v3 (~12 months out): legacy fields fully removed; requests with only pledgeAddress / rentalCount / period return 400.

All API key holders receive an email 30 days before each transition.

6. FAQ

Will updating my code break production now? No. v1 accepts and returns both naming styles, so you can roll the change out incrementally.

Why do older blogs and tutorials still show pledgeAddress? Those were written before the v1 standardization. The API reference and migration guide are the authoritative sources going forward.

What about the docs.eopen.io interactive console? docs.eopen.io is migrating to v1 names alongside this rollout. During the transition you can use either name.

7. Next steps

• Read the full v1 API reference
• Bookmark the migration guide
• Try v1 endpoints live on docs.eopen.io

Authoritative source: the v1 reference and migration guide. Legacy aliases remain accepted during v1 — there is no rush, but every new integration should start with the v1 names.