Skip to content
Royal Product Docs

Metadata Control

This document describes the REST API for managing metadata associated with NFTs. For details on authentication, refer to the Authentication page, and for general guidelines, see API Guidelines.

Overview

Each application with a registrar 🔗 required for using the registration API has an NFT contract 🔗 deployed. The registration API uses your NFT contract to mint NFTs and set up metadata using fields provided by you.

These endpoints allow you to update metadata, but only for tokens on your contract. Note that once metadata is updated, the Toolkit attempts to update caches automatically. However, due to the nature of the NFT landscape, some services may not update their cache automatically, and manual updates may be necessary.

Prerequisites

To use the metadata API:

Quick Start

Fetch Raw Metadata

To fetch raw metadata for a token:

Terminal window
curl -X GET https://api.royal.io/v0/metadata/<token_id> \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY"

A successful response includes the metadata and token identifier:

{
  "metadata": <raw metadata>,
  "token_identifier": {
    "contract_identifier": {
      "contract_address": <contract_address>,
      "chain": <chain id>
    },
    "prefix": "provenance",
    "token_id": <token_id>
  },
  "metadata_url": <url>
}

Update Metadata

To update metadata for a token:

Terminal window
curl -X PUT https://api.royal.io/v0/metadata/<token_id> \
  -H "Authorization: Bearer ryl_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": <new metadata>,"provenance_attributes": <provenance attributes>}'

A successful response includes the merged metadata and token identifier:

{
  "metadata": <merged metadata>,
  "token_identifier": {
    "contract_identifier": {
      "contract_address": <contract_address>,
      "chain": <chain id>
    },
    "prefix": "provenance",
    "token_id": <token_id>
  },
  "metadata_url": <url>
}

API Endpoints

Fetch Raw Metadata

Terminal window
GET /v0/metadata/:token_id

Description

Fetches metadata for a given token ID. This operation checks the validity of input parameters and the deployment status of the registrar.

Request Format

Path Parameters
  • token_id: The identifier of the token for which metadata is being fetched.

Response Format

Success (200 OK):

{
  "metadata": <raw metadata>,
  "token_identifier": {
    "contract_identifier": {
      "contract_address": <contract_address>,
      "chain": <chain id>
    },
    "prefix": "provenance",
    "token_id": <token_id>
  },
  "metadata_url": <url>
}

Error:

Returns an error if there is a blank token ID, or undeployed registrar.

Update Metadata

Terminal window
PUT /v0/metadata/:token_id

Description

Merges new metadata with existing metadata for a given token ID and owner. This operation checks the validity of input parameters and the deployment status of the registrar. Provenance attributes are appended to existing ones, and other metadata is merged with existing metadata.

Request Format

Path Parameters
  • token_id: The identifier of the token for which metadata is being merged.
Body Parameters
  • metadata: An object containing the new metadata to be merged.
  • provenance_attributes: A list of provenance attributes to be appended.

Response Format

Success (200 OK):

{
  "metadata": <merged metadata>,
  "token_identifier": {
    "contract_identifier": {
      "contract_address": <contract_address>,
      "chain": <chain id>
    },
    "prefix": "provenance",
    "token_id": <token_id>
  },
  "metadata_url": <url>
}

Error:

Returns an error if there is a blank token ID, or undeployed registrar.