SimpleHash API Overview

Currently live on Ethereum, Solana, Polygon, Optimism, Arbitrum, Flow, Avalanche, BSC, Gnosis, Palm, and testnets

Welcome!

The SimpleHash NFT API is a REST and webhook based API that provides the ability to query NFT metadata, media, and transaction history (including sales, listings and floor prices) across multiple chains.

If you'd like to skip ahead and just try out some of the endpoints, try one out here by using the example curl widget on the page

Example queries and responses are shown for each endpoint listed in the menu, and can be tested with the request widget on the right of each endpoint page.

SimpleHash is built by a team with extensive experience in crypto and web3 - we've indexed over 850M NFTs, and are backed by prominent players in the space, including OpenSea Ventures, Coinbase Ventures, and Y Combinator. Our goal is to provide the best developer NFT experience possible.


Support

If you need support integrating with the SimpleHash API, please contact [email protected]. For those on a paid plan, we also offer direct Slack or Telegram channel support and technical assistance.


Authentication

All endpoints require use of an API Key - these can be obtained by registering on the developer portal . The key should be passed within the request header in the following format: X-API-KEY: {API_KEY}


Formatting and Variables

  • chains: Specified as the name(s) of the desired chain. The available options are listed here: Supported Chains & Testnets

    • If you have feedback on the chains / networks you'd like to see supported, please contact [email protected].

  • contract_address: Address of the desired contract:

    • EVM chains: formatted as hex addresses, e.g., 0x52782699900df91b58ecd618e77847c5774dcd2e.
    • Solana: formatted as a Base58-encoded string uniquely representing the NFT itself, e.g., 2DfTukhzftoX9oF8xaUQ8kS85oPEVEHsmpa4DQiinQGD. These addresses on Solana are often elsewhere referred to as a Mint Address or Token Address.
    • Flow formatted as a hybrid string starting with with the capital A, followed by a period and the hexidecimal portion of the address, followed by a period and the name of the contract, e.g., A.0b2a3299cc857e29.TopShot

  • token_id: Numeric ID of the specific token on a given contract:

    • EVM chains: a numeric value, e.g., 1002
    • Solana: does not apply, the contract_address uniquely identifies the NFT
    • Flow: a numeric value, e.g., 1002

  • wallet_addresses: Address of the desired owner(s):

    • EVM chains: formatted as hex addresses, e.g., 0xb47902159c61b06ec03770a2cab692901d9a3759
    • Solana: formatted as Base58-encoded strings, e.g., Dg3C8UeEnCdZoFqeFCwYCfB96o5Erb6D63rDQJTmuTkW
    • Flow: formatted as hex addresses, e.g., 0x10285e5afddd80c3

Handling Media URLs

SimpleHash caches and saves the media files of all NFTs on the indexed chains. If an NFT has an image / media file cached on the SimpleHash CDN, it will appear in the following format, with one or all of the fields image_url, video_url, audio_url and model_url: <https://cdn.simplehash.com/assets/c95...12f7.png>.

In rare cases, only the original media links are available. Original media links (e.g., in the response on the image_original_url field within extra_metadata are usually returned as either base64 format (e.g., data:image/svg+xml;base64,PHN2Z...), in which case they can be rendered directly, or as an external link (e.g., ipfs://QmbAhtqQqiSQqwCwQgrRB6urGc3umTskiuVpgX7FvHhutU/8667.png).

In the case of an IPFS link, you have the option of appending an IPFS gateway to serve the image (such as https://ipfs.io/ipfs/), which will result in a link similar to this: <https://ipfs.io/ipfs/QmbAhtqQ...hutU/8667.png>


Media Previews

For most NFT responses, SimpleHash provides preview versions of the relevant media file within the previews field. These are a set of URLs linking 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). When generating previews of SVGs, images are converted to PNG format for improved compatibility.

  • The sizing of the preview image can be customized further by alterting the numeric value of the suffix =s{number} on the URL (for example: <https://lh3.googleusercontent.com/5Dli5GOSLNg6YYAFiXhEREwDdSH3LToRrMQu5xrgxAAeDd9pzJhNM1-yACxGkWpwrQ_m7GjvJHGDQiTjWncH6srQn-LKyHBGUHM=s900>)

Pagination & Cursors

Endpoints that return multiple items are paginated using a cursor system. To pull the next set of results, query the next field returned in the current results, e.g., <https://api.simplehash.com/api/v0/nfts?chains=optimism&cursor=cD0weDAwNmViNjEzYM...a23D>