🧵 Migrate token history endpoints to v2

This guide covers the changes required to migrate the token history list endpoints — mints, transfers, and burns — from v1.8.1 to v2.0.0. Deprecation Date: 31/10/2026

What changed

In v1.8.1:

Endpoint	Behaviour
GET /tokens/{tokenId}/mints	Returns a bare JSON array, no pagination control. Deprecated.
GET /tokens/{tokenId}/transfers	Returns a bare JSON array, no pagination control. Deprecated.
GET /tokens/{tokenId}/burns	Returns a bare JSON array, no pagination control. Deprecated.

In v2.0.0:

v2.0.0 endpoint	Replaces
GET /v2/tokens/{tokenId}/mints	/tokens/{tokenId}/mints + /tokens/{tokenId}/mints-paginated
GET /v2/tokens/{tokenId}/transfers	/tokens/{tokenId}/transfers + /tokens/{tokenId}/transfers-paginated
GET /v2/tokens/{tokenId}/burns	/tokens/{tokenId}/burns + /tokens/{tokenId}/burns-paginated

Query parameter changes

The v2 endpoints accept the following query parameters (same for mints, transfers, and burns):

Parameter	Type	Default	Description
limit	integer (1–1000)	1000	Maximum number of results to return.
order	asc | desc	desc	Chronological order of results.
cursorEventId	string	—	Event ID returned as nextCursor in a previous response. Pass it to fetch the next page.

Response shape changes

v1.8.1 returned a bare JSON array:

[
  {
    "id": "0x3a86d5c08e30dac722fff85c94198d21014b0b4fb07363199078543b69325e54:4:80001",
    "to": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826",
    "amount": "1.0",
    "timestamp": 1665475375
  }
]

v2.0.0 wraps every list response in a pagination envelope:

{
  "items": [
    {
      "id": "0x3a86d5c08e30dac722fff85c94198d21014b0b4fb07363199078543b69325e54:4:80001",
      "to": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826",
      "amount": "1.0",
      "timestamp": 1665475375
    }
  ],
  "hasNext": true,
  "nextCursor": "9de778af-a2f6-488f-a183-b47079673b56"
}

Any code that iterates or destructures the response directly — response.forEach(...), const [first] = response, etc. — will break and must be updated to operate on response.items.

Migration steps

1. Update the URL

Prepend /v2/ to the path:

- GET /tokens/{tokenId}/mints
+ GET /v2/tokens/{tokenId}/mints

- GET /tokens/{tokenId}/transfers
+ GET /v2/tokens/{tokenId}/transfers

- GET /tokens/{tokenId}/burns
+ GET /v2/tokens/{tokenId}/burns

2. Cursor query parameter

+ ?cursor.eventId=9de778af-a2f6-488f-a183-b47079673b56

3. Update response handling

- const mints = await getMints(tokenId);
- mints.forEach((mint) => process(mint));

+ const { items, hasNext, nextCursor } = await getMints(tokenId);
+ items.forEach((mint) => process(mint));
+ if (hasNext) {
+   // fetch next page using nextCursor
+ }