Skip to main content

Update NFT metadata on Mavis Market with the API

Overview​

When you update an NFT's metadata, refreshing it on Mavis Market ensures the changes are visible. Use the Refresh NFT metadata to update metadata for up to 100 NFTs in a single request. This guide explains how to request API access and create a POST request to trigger the refresh.

Prerequisites​

An NFT collection on Mavis Market. For more information, see the List NFTs on Mavis Market.

Steps​

Step 1. Get your API key​

To use the Mavis Market API, you need an API key and permission to use the Mavis Market Partner service:

  1. Go to the Developer Console.

  2. Create a new app or select an existing app.

  3. Find your app's API key on the Information tab.

  4. Go to the App Permission tab, then Mavis Market Partner > Request Access.

When your request is approved, the Mavis Market Partner status changes to "Active."

Step 2. Send a POST request​

To trigger a metadata refresh for NFTs in your collection, form a POST request to the https://api-gateway.skymavis.com/mavis-market-partner/collections/{collection_address}/refresh_metadata endpoint, passing the collection address and an array of token IDs to refresh.

Example request:

curl --location --request POST 'https://api-gateway.skymavis.com/mavis-market-partner/collections/0xa899849929e113315200609be208e6a0858f645c/refresh_metadata' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data-raw '{
  "token_ids": ["1", "2", "3", "4", "5", "6"]
}'

Parameters:

  • collection_address (string): The address of the collection to refresh.
  • token_ids (array): The token IDs of the NFTs to refresh.

A successful response returns a 200 HTTP status code:

{
  "code": 200,
  "message": "Success"
}

Error handling​

The API returns standard HTTP status codes for errors:

  • 400 Bad Request:
    • Ensure the collection address and token IDs are correct.
    • Verify that you are not exceeding the limit of 100 token IDs in a single request.
  • 401 Unauthorized: the API key provided is invalid. Double-check the API key.
  • 403 Forbidden: you do not have permission to use this API. Check whether the Mavis Market Partner service is Active in the Developer Console.
  • 429 Too Many Requests: you have exceeded the rate limit of 10 requests per second. Implement backoff and retry logic as necessary.