Refresh asset metadata

Metadata refreshes update off-chain asset metadata.

Read more about asset metadata.

This page contains code samples that explain how to use the metadata refresh API.

Use cases

Metadata refreshes help games:

• Support game play mechanics that rely on metadata such as levelling up characters, crafting and merging
• Refine the game balance
• Refine and correct game content such art and copy
• Delay reveals of primary sales
• Improve search discoverability through metadata

Requirements

In order for a refresh to be successful, first:

• Create and deploy the Metadata API, as it's the source of truth for asset metadata
  • Ensure your endpoint sets the response header Content-Type: application/json
• For reveals, update your Metadata API only once the asset is ready to be revealed. The flow for reveals would be something like:
  • Mint an asset
  • Once ready to reveal, update the Metadata API with the properties to be revealed
  • Refresh metadata for the assets to be revealed
• Ensure your Metadata API availability is aligned with the requirements. The metadata refresh service will concurrently request metadata for each asset from your Metadata API and requires a response time of less than 3 seconds per request in order to successfully update the metadata for that asset.
• If the request to the Metadata API fails to return a valid response, that particular asset will be marked as failed.
• The request to the Metadata API will be retried 2 times (with an exponential backoff function timing each retry) only if the Metadata API returns one of the following HTTP status codes:
  • 429 Too Many Requests
  • 503 Service Unavailable

API

Endpoints related to metadata refreshes are denoted via the url resource /metadata-refreshes.

The expected maximum time (estimate) to complete a refresh is approximately 48 hours. Updated metadata values will only be reflected in downstream systems e.g. marketplaces once the refresh for that asset is complete.

Authentication

Metadata refresh endpoints are protected via authentication - only the project owner will be able to call these endpoints.

The following headers are required for project owner authentication:

• x-imx-eth-address - the Ethereum address of the project owner making the request
• x-imx-eth-signature - the signature generated by the project owner
• x-imx-eth-timestamp - the timestamp used to generate the signature

View how to generate project owner authentication headers.

Requesting a metadata refresh

A metadata refresh can be requested by calling:

POST /v1/metadata-refreshes

and specifying the collection address and IDs of the tokens requiring a refresh:

{
  "collection_address": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d", // required
  "token_ids": ["1", "2"] // required
}

The user will receive the following response with a HTTP status code of 202 Accepted:

{
  "refresh_id": "21566bcb-4263-48bb-a495-602ba9a12f2c"
}

The refresh_id acts as a receipt and confirms that the refresh has been initiated and will be processed. It can be used to query the status of a particular refresh.

Projects can programmatically call the refresh endpoint at a specific time or based on a specific event in their system. There is currently no way to cancel a refresh once requested.

View the OpenAPI specification for requesting a metadata refresh.

Viewing the status of a metadata refresh

The status of a refresh can be queried by using the refresh_id with the following endpoint:

GET /v1/metadata-refreshes/:refresh_id

which will return the following response:

{
  "refresh_id": "21566bcb-4263-48bb-a495-602ba9a12f2c",
  "status": "completed",
  "collection_address": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d",
  "started_at": "2022-08-31T01:59:59.806449Z",
  "completed_at": "2022-08-31T02:00:09.786143Z",
  "summary": {
    "succeeded": 2,
    "failed": 0,
    "pending": 0
  }
}

Status

The status field of a refresh can be the following values:

• queued - the refresh has been requested but no tokens have been processed
• in_progress - the refresh has started processing and at least 1 token has been processed
• completed - all tokens have been processed

Summary

The summary field of a refresh displays the counts of the status of individual tokens belonging to that refresh:

• succeeded - the metadata for this token has been successfully updated
• failed - the metadata for this token was not able to be updated
• pending - the token has not been processed

Another endpoint is available to investigate the reason why the metadata for a particular token could not be updated.

View the OpenAPI specification for metadata refresh status.

Viewing metadata refresh errors

If 2 non-successful attemps have been made to retrieve the updated metadata values from the Metadata API, that token will be marked as failed. A more detailed explanation of why token metadata could not be updated for a particular refresh can be queried with the following endpoint:

GET /v1/metadata-refreshes/:refresh_id/errors

which will return a paginated list of tokens within that refresh that could not be updated and their respective error details:

{
  "result": [
    {
      "token_id": "1",
      "collection_address": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d",
      "client_token_metadata_url": "https://metadata-api.io/1",
      "client_response_status_code": 404,
      "client_response_body": "404 page not found\n",
      "error_code": "invalid_response_status_code",
      "created_at": "2022-09-06T02:14:04.935946Z"
    }
  ],
  "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMi0wOS0wNlQwMjoxNDowNC45MzU5NDZaIiwiaWQiOiIyYzU2ZDE5Ni1mY2ViLTQ1MzItYmMzOC0zZmZlMTFlOTM4Y2UifQ",
  "remaining": 0
}

Each item in the results array represents one failed token for that particular refresh.

• client_token_metadata_url - the url which was used to perform the Metadata API request
• client_response_status_code - the response status code that was received from the Metadata API
• client_response_body - any error details that were provided as a response body by the Metadata API
• error_code - describes why the metadata could not be updated

Error codes

Error code	Description
unable_to_retrieve_metadata	The metadata refresh service was unable to get a response from the Metadata API, for example the API timed out
invalid_response_status_code	The metadata refresh service received a non 200 response code when making a request to the Metadata API
unable_to_decode_response	The response received by the Metadata API was unable to be decoded
token_not_found	The token does not exist in our system

View the OpenAPI specification for metadata refresh errors.

Getting a list of all metadata refreshes

Users can fetch a list of all metadata refreshes in order to find a particular refresh_id, which can then be used to query the status of a particular refresh:

GET /v1/metadata-refreshes

The above endpoint will return a list of refreshes ordered by created_at , showing the most recent refreshes first.

Filter by collection address

The endpoint results can also be filtered by using the the query parameter collection_address:

GET /v1/metadata-refreshes?collection_address=COLLECTION_ADDRESS

The response returns a paginated list of refreshes:

{
  "result": [
    {
      "refresh_id": "ff52e750-2cc6-4455-b1ae-95a4280e4826",
      "status": "completed",
      "collection_address": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d",
      "started_at": "2022-09-06T02:11:03.065286Z",
      "completed_at": "2022-09-06T02:14:04.945285Z"
    }
  ],
  "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMi0wOC0zMFQwNzozODoxMS4xMzczMTRaIiwiaWQiOiI2YzhlMDNjNS04ZWYxLTQzNmQtOWNjZS1iM2ExNDdmYzc3NGIifQ",
  "remaining": 0
}

View the OpenAPI specification for a list of metadata refreshes.

Metadata refresh limits

There are limits on the number of the number of metadata refresh requests made per project, per hour.

• For a particular project, 5 metadata refresh requests can be made per second
• Up to 1,000 tokens can be requested per refresh
• Up to 30,000 tokens can be updated/refreshed per hour

Whenever a refresh is requested or when a refresh limit has been reached, the following headers will be returned:

• x-imx-refreshes-limit - the amount of refreshes that can be requested per hour
• x-imx-remaining-refreshes - the amount of refreshes remaining for the current hour interval
• x-imx-refresh-limit-reset - a UNIX timestamp indicating when the limit resets by rolling over into the next hour interval

If the refresh limit has been reached, the user will receive a response with a HTTP status code of 429 Too Many Requests:

{
  "code": "refresh_limit_exceeded",
  "message": "Refresh limit exceeded"
}

Additional requests

If you need to perform additional refresh requests, you can contact support.