NFT model

The SimpleHash API returns NFT data in a standard format. The following are the fields included in the response (or as a list of NFT objects).

Field

Description

Type(s)

nft_id

Unique identifier for an NFT (chain.contract_address.token_id for EVM chains & Flow, chain.mint_address for Solana, chain.inscription_id for Bitcoin)

string

chain

Name of the blockchain (e.g., ethereum)

string

contract_address

Address of the NFT's contract (hex format for EVM compatible chains). For Solana, this is a Base58-encoded string uniquely representing the NFT itself. For Bitcoin, this is the inscription ID.

string

token_id

Token ID (usually numeric) of the NFT on its contract. Will be null for Solana and Bitcoin NFTs, which are identified by contract_address

string / null

name

Name of the NFT derived from its metadata

string / null

description

Description of the NFT derived from its metadata

string / null

previews

Set of URLs to resized preview images of the media, including an opengraph image, and blurhash, where available. Previews are sized to fit the maximum dimension in pixels as follows: (small: 250px, medium: 512px, large: 1000px).

These may be derived from images, videos, or 3D models.

{
image_small_url:string / null,
image_medium_url:string / null,
image_large_url:string / null,
image_opengraph_url:string / null,
blurhash: string / null,
predominant_color: string / null,
}

image_url

URL to cached image file on the SimpleHash CDN if available

string / null

image_properties

Image properties if available

{
width:int / null,
height: int / null,
size : int / null,
mime_type: str / null,
exif_orientation: int / null,
} / null

video_url

URL to cached video file on the SimpleHash CDN if available

string / null

video_properties

Video properties if available

{
width: int / null,
height: int / null,
duration: float / null,
video_coding: str / null,
audio_coding: str / null,
size: int / null,
mime_type: str / null,
} / null

audio_url

URL to cached audio file on the SimpleHash CDN if available

string / null

audio_properties

Audio properties if available

{
duration: float / null,
audio_coding: str / null,
size: int / null,
mime_type: str / null,
} / null

model_url

URL to cached 3D model file on the SimpleHash CDN if available

string / null

model_properties

Model properties if available

{
size: int / null,
mime_type: str / null,
} / null

other_url

URL to cached file on the SimpleHash CDN if available for other media types such as PDFs

string / null

other_properties

File properties if available

{
size: int / null,
mime_type: str / null,
} / null

background_color

Background color of the NFT derived from its metadata

string / null

external_url

External URL derived from the NFT's metadata, often with more information (such as about the project), where available

string / null

created_date

NFT minting datetime if known in timestamp format (e.g., 2021-07-03T23:45:00)

string / null

status

NFT status, one of lazy-minted, minted, or burned. Items that are lazy-minted will switch to minted status upon the first on-chain transfer or sale.

string

token_count

Known quantity of this NFT

int / null

owner_count

Known number of owners of this NFT

int / null

owners

Array of 0-50 top owners of this NFT (sorted by quantity desc). Dates are supplied in the yyyy-MM-dd'T'HH:mm:ss format

[{
owner_address:string,
quantity: int,
quantity_string: string,
first_acquired_date: string / null,
last_acquired_date: string
}]

last_sale

Detail on the most recent sale involving this NFT

last_sale / null

primary_sale

Detail on the original sale (during the mint) for this NFT

primary_sale / null

first_created

First creation NFT details

{
minted_to: string / null,
quantity: int / null,
quantity_string: string / null,
timestamp: string / null,
block_number: int / null,
transaction: string / null,
transaction_initiator: string / null
} / null

contract

Contract type info for this NFT (type is usually the standard for the contract, such as ERC721)

{
type:string,
name:string / null,
symbol:string / null
deployed_by: string / null
deployed_via_contract: string / null,
owned_by: string / null,
has_multiple_collections: bool
}

collection

The associated collection information for this NFT

Collection model

rarity

The associated rarity information for this NFT

Rarity model

royalty

Array of 0 or more royalty details, by source. Different marketplaces allow for different royalty amounts, so we show a list of the available information. When there are multiple sources, we list them from highest to lowest total_creator_fee_basis_points.

Current sources are: opensea, metaplex, erc2981

The list of recipients can have 0 or more wallets, as applicable. Amounts are shown in both basis_points (adding up to total_creator_fee_basis_points) and percentage, which is the share of this wallet's fees compared to other recipients.

Note that for the recipients list, OpenSea natively uses basis_points while Metaplex uses percentage, so if you need very precise amounts (i.e. no possibility of rounding), use basis_points for OpenSea & ERC2981 and percentage for Metaplex.

[{
source: string,
total_creator_fee_basis_points: int,
recipients: [{
address: string,
percentage: float,
basis_points: int
}][{
`address: string, \percentage: float, \basis_points: int`
}]
}]

extra_metadata

JSON field containing the additional custom metadata fields for the NFT added by the creator. Includes the image_original_url and animation_original_url links to the original media source (where available), and passes through other fields not standardized above (such as attributes or traits)

{
attributes: [{
trait_type:string / null,
value:string,
display_type:string / null
}][{
`trait_type:string / null, \value:string, \display_type:string / null }],\ ...,\ image_original_url:string / null,\ animation_original_url:string / null,\ metadata_original_url:string / null`
}