Marketplace
Back to All

New Field: `encoded_token_ids`

July 26th, 2023

We are excited to announce the addition of a new field in the OpenSea API - the encoded_token_ids field. It is present in the responses of our collection and trait offer read endpoints in the criteria object - the new field is a concise and efficient way to represent a list of token ids that pertain to a given collection / trait offer. When decoded using the provided SDK function, developers can now see a list of all tokens that could be used to fulfill the offer.

Example (Collection Offer)

"criteria": {
  "collection": {
    "slug": "cool-cats-nft"
  },
  "contract": {
    "address": "0x1a92f7381b9f03921564a437210bb9396471050c"
  },
  "trait": null,
  "encoded_token_ids": "*"
},

Note: The wildcard (*) represents all tokens in a collection. More details below.

Example (Trait Offer)

"criteria": {
  "collection": {
    "slug": "doodles-official"
  },
  "contract": {
    "address": "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e"
  },
  "trait": {
    "type": "hair",
    "value": "wizard"
  },
  "encoded_token_ids": "67,192,235,526,583,639:640,698,789,823,837,1236,1295,1348,1476,1684,1794,2052,2067,2283,2369,2399,2662,2680,2720,2823,2840,2989,3675,3964,4089,4118,4133,4184,4238,4506,4792,4931,4997,5399,5517,5537,5826,6352,6604,6638,6736,6832,7020,7084,7141,7383,7403,7486,7633,7738,7881,8257,8311,8383,8451,8496,8690,8717,8768,8791,8869,9080,9529,9542,9837,9916,9953"
},

SDK Function: decodeTokenIds

Code: link

To ensure easy utilization of the "encoded_token_ids" field, we have added a new SDK function called decodeTokenIds. This function takes the encoded token ids as input and returns the corresponding token ids in a user-friendly string array format.

Decoding Examples:

  1. Example 1:

    • Encoded Token IDs: "123"
    • Decoded Output: ["123"]

  2. Example 2:

    • Encoded Token IDs: "1001:1005,1009:1012"
    • Decoded Output: ["1001", "1002", "1003", "1004", "1005", "1009", "1010", "1011", "1012"]

  3. Example 3:

  • Encoded Token IDs: "*"
  • Decoded Output: ["*"]

Usage Guidelines:

  1. Comma-Separated Values: The encoded_token_ids field is represented as a comma-separated list of numbers and ranges. Ranges are expressed as start:end, where both start and end are inclusive.

  2. Wildcard Support: When the encoded_token_ids field returns a Wildcard (*), that means that all of the token ids in the collection can be used to fulfill the offer.

Please refer to the updated API documentation for more details on utilizing this new feature. As always, your feedback is highly valuable to us as we continue to improve and expand the capabilities of the OpenSea API.