Skip to content

Tokenbound iFrame

By using an animation_url developers may embed a web app as the media for NFT on OpenSea, and some other platforms. This allows users to view detailed information about the tokenbound account (TBA) of NFTs directly within the marketplace interface.

This basic iframe implementation lets users explore their NFT's tokenbound accounts and view information such as:

  • Contents of the NFT's tokenbound account: ERC-721, ERC-1155, ether and ERC-20 tokens

  • Whether or not any ERC-721, or ERC-1155 tokens have global or token level approvals. This information provides context for users who are looking to buy an NFT and the contents within it's TBA, since tokens with pending approvals have the potential be transferred before the transaction for the parent NFT is finalized.

  • Whether the status of the TBA is locked or unlocked. A locked state allows users to confidently purchase an NFT, knowing that none of the contents of the TBA will be transferred for the specified time period.

URL Implementation

The URL method is recommended for NFT projects using static images for their artwork, and/or existing projects and wish to show their NFT's Tokenbound account. This method requires updating the animation_url of your NFT's metadata to match this pattern:

  "animation_url": "<contractAddress>/<tokenId>/<chainId>"

contractAddress: the contract address of the NFT collection you wish to display
tokenId: the token ID of the individual NFT to be rendered in the iframe
chainId: the chain ID of where your NFT collection resides. The following tables shows currently supported chains.

NetworkChain ID
Ethereum Mainnet1
Ethereum Goerli5
Ethereum Sepolia11155111
Polygon Mainnet137
Polygon Mumbai80001
Optimism Mainnet420

For example, using token ID 1 from the Sapienz collection on mainnet 1:

This iframe implementation relies on Alchemy's indexer to render the NFT's media. If your project uses a custom API to render the NFT's media, use the custom implementation below.

Custom Implementation

Fork and clone the iframe repo

git clone

Setup environment variables

cat .env.example > .env.local

Create an Alchemy account and API key

Navigate to and create a new app

Update your environment variables with your Alchemy


Create a Graph studio account and API key

Navigate to and create an API key (used for checking token approvals)

You will need to fund your account with GRT tokens.

Update NEXT_PUBLIC_GRAPH_API_KEY with your sub graph credentials.


Use in your custom api endpoint to fetch your NFT's media

The application expects the endpoint to be: string | string[], where the string is a url link to your NFT's assets. It should dynamically have a route for each tokenId.

For example the NEXT_PUBLIC_NFT_ENDPOINT env variable is The application will then take the tokenId from the URL and make a fetch to that endpoint:<tokenId>.


Host your application

Host your application on a service provider of your choice and set your metadata server with that host.

  "animation_url": "<contractAddress>/<tokenId>/<chainId>"


Add the query param ?disableloading=true to not have Tokenbound logo animation before the iframe starts.