ARC-74: NFT Indexer API

REST API for reading data about Application's NFTs.

Author	William G Hatch
Discussions-To	https://github.com/algorandfoundation/ARCs/issues/170
Status	Final
Type	Standards Track
Category	Interface
Created	2023-02-17
Requires	72

Abstract
Motivation
Specification
- GET /nft-indexer/v1/tokens
- GET /nft-indexer/v1/transfers
Rationale
Backwards Compatibility
Security Considerations
Copyright

Abstract

This specifies a REST interface that can be implemented by indexing services to provide data about NFTs conforming to the ARC-72 standard.

Motivation

While most data is available on-chain, reading and analyzing on-chain logs to get a complete and current picture about NFT ownership and history is slow and impractical for many uses. This REST interface standard allows analysis of NFT contracts to be done in a centralized manner to provide fast, up-to-date responses to queries, while allowing users to pick from any indexing provider.

Specification

This specification defines two REST endpoints: /nft-index/v1/tokens and /nft-index/v1/transfers. Both endpoints respond only to GET requests, take no path parameters, and consume no input. But both accept a variety of query parameters.

`GET /nft-indexer/v1/tokens`

Produces application/json.

Optional Query Parameters:

Name	Schema	Description
round	integer	Include results for the specified round. For performance reasons, this parameter may be disabled on some configurations.
next	string	Token for the next page of results. Use the `next-token` provided by the previous page of results.
limit	integer	Maximum number of results to return. There could be additional pages even if the limit is not reached.
contractId	integer	Limit results to NFTs implemented by the given contract ID.
tokenId	integer	Limit results to NFTs with the given token ID.
owner	address	Limit results to NFTs owned by the given owner.
mint-min-round	integer	Limit results to NFTs minted on or after the given round.
mint-max-round	integer	Limit results to NFTs minted on or before the given round.

When successful, returns a response with code 200 and an object with the schema:

Name	Required?	Schema	Description
tokens	required	array	Array of Token objects that fit the query parameters, as defined below.
current-round	required	integer	Round at which the results were computed.
next-token	optional	string	Used for pagination, when making another request provide this token as the `next` parameter.

The Token object has the following schema:

Name	Required?	Schema	Description
owner	required	address	The current owner of the NFT.
contractId	required	integer	The ID of the ARC-72 contract that defines the NFT.
tokenId	required	integer	The tokenID of the NFT, which along with the contractId addresses a unique ARC-72 token.
mint-round	optional	integer	The round at which the NFT was minted (IE the round at which it was transferred from the zero address to the first owner).
metadataURI	optional	string	The URI given for the token by the `metadataURI` API of the contract, if applicable.
metadata	optional	object	The result of resolving the `metadataURI`, if applicable and available.

When unsuccessful, returns a response with code 400 or 500 and an object with the schema:

Name	Required?	Schema
data	optional	object
message	required	string

`GET /nft-indexer/v1/transfers`

Produces application/json.

Optional Query Parameters:

Name	Schema	Description
round	integer	Include results for the specified round. For performance reasons, this parameter may be disabled on some configurations.
next	string	Token for the next page of results. Use the `next-token` provided by the previous page of results.
limit	integer	Maximum number of results to return. There could be additional pages even if the limit is not reached.
contractId	integer	Limit results to NFTs implemented by the given contract ID.
tokenId	integer	Limit results to NFTs with the given token ID.
user	address	Limit results to transfers where the user is either the sender or receiver.
from	address	Limit results to transfers with the given address as the sender.
to	address	Limit results to transfers with the given address as the receiver.
min-round	integer	Limit results to transfers that were executed on or after the given round.
max-round	integer	Limit results to transfers that were executed on or before the given round.

When successful, returns a response with code 200 and an object with the schema:

Name	Required?	Schema	Description
transfers	required	array	Array of Transfer objects that fit the query parameters, as defined below.
current-round	required	integer	Round at which the results were computed.
next-token	optional	string	Used for pagination, when making another request provide this token as the `next` parameter.

The Transfer object has the following schema:

Name	Required?	Schema	Description
contractId	required	integer	The ID of the ARC-72 contract that defines the NFT.
tokenId	required	integer	The tokenID of the NFT, which along with the contractId addresses a unique ARC-72 token.
from	required	address	The sender of the transaction.
to	required	address	The receiver of the transaction.
round	required	integer	The round of the transfer.

When unsuccessful, returns a response with code 400 or 500 and an object with the schema:

Name	Required?	Schema
data	optional	object
message	required	string

Rationale

This standard was designed to feel similar to the Algorand indexer API, and uses the same query parameters and results where applicable.

Backwards Compatibility

This standard presents a versioned REST interface, allowing future extensions to change the interface in incompatible ways while allowing for the old service to run in tandem.

Security Considerations

All data available through this indexer API is publicly available.

Copyright

Citation

Please cite this document as:

William G Hatch, "ARC-74: NFT Indexer API," Algorand Requests for Comments, no. 74, February 2023. [Online serial]. Available: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0074.md.

ARC-74: NFT Indexer API Source