Skip to main content

Metadata API Reference & Usage

The Sequence Metadata API service offers a simple and fast API to query token & NFT metadata for Ethereum-compatible chains.

Quite simply, the Metadata API allows you to query the token metadata of any ERC20, ERC721 or ERC1155 contract on a number of supported Ethereum chains.

Please note, for your dev convenience, the Sequence Metadata service is automatically integrated in the Sequence Indexer. But as we demonstrate below, it's also useful to be able to query the token/contract metadata directly too :)

Example

Let's say you'd like to query the metadata of a Skyweaver 1155 card on the Polygon network. Of course, the below example will work for any network / contract / token combination as well.

First, the Skyweaver 1155 assets contract is located at address 0x631998e91476DA5B870D741192fc5Cbc55F5a52E on the Polygon network. Second, let's build the metadata lookup endpoint to query Skyweaver's contract for token ID 20:

Request: https://metadata.sequence.app/tokens/polygon/0x631998e91476DA5B870D741192fc5Cbc55F5a52E/20

Response:

[
{
"tokenId": "20",
"contractAddress": "0x631998e91476da5b870d741192fc5cbc55f5a52e",
"name": "Unstoppable Chop",
"description": "Attach Silence to target unit. Do 4 damage to it.",
"image": "https://assets.skyweaver.net/TNqWLuJZ/webapp/cards/full-cards/6x/20-silver.png",
"decimals": 2,
"properties": {
"baseCardId": 20,
"goldCardId": 131092,
"grade": "oldSilver",
"id": 20,
"silverCardId": 65556
},
"attributes": null
}
]

If you'd like to query a number of tokens at the same time, you can include more token ids comma-separated: https://metadata.sequence.app/tokens/polygon/0x631998e91476DA5B870D741192fc5Cbc55F5a52E/20,21,22 -- click to see the JSON response to query token ids 20, 21, and 22 in a single batched request.

Feel free to try tweaking the metadata.sequence.app URL above for your own contract, or another popular project to see how the responses come back. You can change the network to one of our supported networks and specify any contract and/or token id.

In addition to easily querying token-level metadata like in the above example, you can also query contract-level metadata. Contract-level metadata provides you more information about a contract address such as a name, contract type, logo, and description. Simply change the metadata URL above to just query the contract address: https://metadata.sequence.app/tokens/polygon/0x631998e91476DA5B870D741192fc5Cbc55F5a52E

and see result:

{
"chainId": 137,
"address": "0x631998e91476da5b870d741192fc5cbc55f5a52e",
"name": "Skyweaver",
"type": "ERC1155",
"symbol": "SKYWVR",
"logoURI": "https://assets.skyweaver.net/_tX5dRVi/webapp/icons/skyweaver-token.png",
"extensions": {
"link": "https://www.skyweaver.net/",
"description": "Skyweaver is a Free-to-Play, trading card game powered by Polygon and Ethereum.",
"ogImage": "https://skyweaver.net/images/skyweavercover.jpg",
"originAddress": "0x631998e91476da5b870d741192fc5cbc55f5a52e"
}
}

Usage

The Metadata API service is accessible either with a simple REST interface, or a RPC client. For the RPC client, we offer Web browser, node and Go clients. We recommend the RPC client for most integrations, but make the REST interface available for convenience.


REST endpoints

As mentioned in the example above. The general format of the REST endpoint is:

GET https://metadata.sequence.app/tokens/<network>/<contractAddress>[/<tokenID>]

Where <network> must be one of the Chain ID or Chain Handle of the supported networks.


Fetch contract-level metadata:

GET https://metadata.sequence.app/tokens/<network>/<contractAddress>

Example: https://metadata.sequence.app/tokens/polygon/0x631998e91476DA5B870D741192fc5Cbc55F5a52E


Fetch token-level metadata:

GET https://metadata.sequence.app/tokens/<network>/<contractAddress>/<tokenID>[,<tokenID>,...]

Examples:


RPC Client

The Metadata RPC interface offers the full capabilities of the Metadata service.

We provide SDKs for Web / node.js and Go. Or if you'd like to integrate the Metadata service with another language target, simply follow the API reference below to implement the HTTP requests. Additionally, read the Typescript client source code as reference implementation of the Metadata RPC client as well.

Web / node.js Installation

npm install 0xsequence

or

npm install @0xsequence/metadata

then in your app,

import { SequenceMetadataClient } from '@0xsequence/metadata'

// TODO: review ..
const metadata = new SequenceMetadataClient()

// see examples below for the kinds of queries you can make
const tokenBalances = await indexer.getTokenBalances(...)

NOTE: if you're using @0xsequence/metadata from node.js, we recommend using node v18.x or newer.


Go Installation

go get -u github.com/0xsequence/[email protected]

then in your app,

import (
"github.com/0xsequence/go-sequence/metadata"
)

seqMetadata := metadata.NewMetadataClient("https://metadata.sequence.app", http.DefaultClient)

// TODO: review ...
// see examples below for the kinds of queries you can make
tokenBalances, err := seqIndexer.GetTokenBalances(...)

Unity or Unreal Installation

The Sequence Metadata is integrated directly inside of the respective Sequence Web3 Unity and Sequence Web3 Unreal SDKs.


Metadata RPC Methods

Metadata API endpoint: https://metadata.sequence.app

Metadata RPC methods:

  • GetTokenMetadata - fetch token metadata of ERC721 or ERC1155 tokens from a single contract
  • GetTokenMetadataBatch - fetch token metadata of ERC721 or ERC1155 token from a batch of contracts
  • GetContractInfo - fetch contract metadata of an ERC20, ERC721 or ERC1155 contract address
  • GetContractInfoBatch - fetch contract metadata of a batch of ERC20, ERC721 or ERC1155 contract addresses

Fetch token metadata of any ERC721 or ERC1155 contract

Sequence Metadata GetTokenMetadata Method:

  • Request: POST /rpc/Metadata/GetTokenMetadata
  • Content-Type: application/json
  • Body (in JSON):
    • chainID (string) -- the chain id, as a name or number (ie. "1" or "mainnet", "137" or "polygon", etc.)
    • contractAddress (string) -- the contract address
    • tokenIDs (array of strings) -- array of strings containing token ids to fetch metadata

Example: GetTokenMetadata of some Skyweaver tokens on Polygon

curl -X POST -H"Content-Type: application/json" https://metadata.sequence.app/rpc/Metadata/GetTokenMetadata -d '{ "chainID": "polygon", "contractAddress": "0x631998e91476DA5B870D741192fc5Cbc55F5a52E", "tokenIDs": ["65537", "65538", "65539"] }'

Fetch contract metadata of any ERC20, ERC721 or ERC1155 contract address

Sequence Metadata GetContractInfoBatch Method:

  • Request: POST /rpc/Metadata/GetContractInfoBatch
  • Content-Type: application/json
  • Body (in JSON):
    • chainID (string) -- the chain id, as a name or number (ie. "1" or "mainnet", "137" or "polygon", etc.)
    • contractAddresses (string of strings) -- array of contract addresses

Example: GetContractInfoBatch of some contracts on Polygon

curl -X POST -H"Content-Type: application/json" https://metadata.sequence.app/rpc/Metadata/GetContractInfoBatch -d '{ "chainID": "polygon", "contractAddresses": ["0x631998e91476DA5B870D741192fc5Cbc55F5a52E", "0x17b66009af459dc8ebf37acf8a8b355379be2fe5", "0x2791bca1f2de4661ed88a30c99a7a9449aa84174", "0x2953399124f0cbb46d2cbacd8a89cf0599974963", "0x7227e371540cf7b8e512544ba6871472031f3335", "0x7c0ebabfc394ec6d926e801fe0e69a1f15a7fe4d", "0x8f3cf7ad23cd3cadbd9735aff958023239c6a063", "0xa1c57f48f0deb89f569dfbe6e2b7f46d33606fd4"] }'