How to Use NFT Endpoints in the Stacks API

NFTs have taken the crypto world by storm, and in the past 6 months, we’ve seen interest in Bitcoin NFTs on Stacks skyrocket:

• 7 organic marketplaces emerged
• 140,000+ NFTs minted
• >4M STX volume traded
• Top NFT series are up 10-50X
  

The Stacks community has embraced Bitcoin NFTs as a way to own part of Bitcoin culture, and Hiro has made it easier for Stacks developers to capitalize on that interest and build new applications around NFTs by adding new NFT endpoints to the Stacks API. Those endpoints include:

1. Non-Fungible Token holdings
2. Non-Fungible Token history
3. Non-Fungible Token mints
   

Let’s dive into each endpoint and explore what you can do with them.

Non-Fungible Token holdings

This endpoint can retrieve all of the NFTs owned by a specific STX address or by a smart contract ID. For example, if you want to get all NFTs owned by the STX address SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR you would call this URL:

https://stacks-node-api.mainnet.stacks.co/extended/v1/tokens/nft/holdings?principal=SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR‍

Once called, the API response will look something like:

{
  "limit": 50,
  "offset": 0,
  "total": 4,
  "results": [
    {
      "asset_identifier": "SP000000000000000000002Q6VF78.bns::names",
      "value": {
        "hex": "0x0c00000002046e616d65020000000672616661656c096e616d6573706163650200000003627463",
        "repr": "(tuple (name 0x72616661656c) (namespace 0x627463))"
      },
      "tx_id": "0x0153a41ed24a0e1d32f66ea98338df09f942571ca66359e28bdca79ccd0305cf"
    },
    {
      "asset_identifier": "SP176ZMV706NZGDDX8VSQRGMB7QN33BBDVZ6BMNHD.project-indigo-act1::Project-Indigo-Act1",
      "value": {
        "hex": "0x0100000000000000000000000000000095",
        "repr": "u149"
      },
      "tx_id": "0xfb4bfc274007825dfd2d8f6c3f429407016779e9954775f82129108282d4c4ce"
    },
    {
      "asset_identifier": "SP2KAF9RF86PVX3NEE27DFV1CQX0T4WGR41X3S45C.wasteland-apes-nft::Wasteland-Apes",
      "value": {
        "hex": "0x0100000000000000000000000000000cf8",
        "repr": "u3320"
      },
      "tx_id": "0x13b8d8aadb86ffd85c041c5bdcde50eb7fb1de45646114c68a262e40a5aec820"
    },
    {
      "asset_identifier": "SP3QSAJQ4EA8WXEDSRRKMZZ29NH91VZ6C5X88FGZQ.crashpunks-v2::crashpunks-v2",
      "value": {
        "hex": "0x0100000000000000000000000000000d55",
        "repr": "u3413"
      },
      "tx_id": "0x6c4086f5be19d3942545e331adc95b106ddc9c75e95b5ba0df3d207927372648"
    }
  ]
}
    

As you can see in the sample response, the endpoint returns all of the NFT assets held by that address. In this case, the user owns 4 NFTs, including a BNS name, as well as NFTs from Project Indigo, Wasteland Apes, and Crashpunks.

These results can also be filtered by one or more asset identifiers (such as the name of the NFT collection) and can be configured to include metadata about each asset transaction (such as the STX price the user paid for each NFT).

Developers can use this endpoint to confirm whether a user holds a specific NFT. With that information, developers can create whitelists or gated access to specific app features, based on whether the user holds an NFT from a particular collection.

This endpoint also enables developers to build user profiles that show off the user’s NFT portfolio. For example, a NFT marketplace might create these user profiles to foster a stronger sense of community. These public profiles would allow users to display their NFT collection and select a profile picture from among the NFTs in their collection.

To learn more about the available request parameters and response fields for this endpoint, visit https://docs.hiro.so/api#operation/get_nft_holdings.

Non-Fungible Token history

Through this endpoint, you can pull all events and transactions that affected a particular NFT. This is useful for developers who want to look at the ownership history of a particular asset. For example, to get the history of The Explorer Guild NFT #2051, you would call this URL:

https://stacks-node-api.mainnet.stacks.co/extended/v1/tokens/nft/history?asset_identifier=SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild%3A%3AThe-Explorer-Guild&value=0x0100000000000000000000000000000803 

Note how the NFT "value" (2051 in this case) has to be encoded into its Clarity hex representation. Once called, the API response will look something like:

{
  "limit": 50,
  "offset": 0,
  "total": 2,
  "results": [
    {
      "sender": "SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR",
      "recipient": "SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v4",
      "event_index": 0,
      "asset_event_type": "transfer",
      "tx_id": "0xf4effc62178003225df86dc78e35176c6042598acf41d7e18fded3956855837d"
    },
    {
      "sender": null,
      "recipient": "SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR",
      "event_index": 1,
      "asset_event_type": "mint",
      "tx_id": "0x12e6f88724d0e630de26c376f172cf1781e25435e2b4ee54d36a949b244e429c"
    }
  ]
}
    

The endpoint then retrieves a list of all events that affected this NFT. In this example, you can see both a mint and transfer to marketplace event in the “asset_event_type”. This endpoint can also retrieve transfers to owners, as well as relevant details for each event, such as listing and purchase prices. 

With this data, developers can build price charts for specific NFTs, monitor trading activity, and more.

To learn more about the available request parameters and response fields for this endpoint, visit https://docs.hiro.so/api#operation/get_nft_history.

Non-Fungible Token mints

This endpoint can help developers identify which NFTs of a particular collection have been minted, and by whom. For example, if you want to get the last 3 NFTs minted from the Megapont Ape collection, you would call this URL:

‍https://stacks-node-api.mainnet.stacks.co/extended/v1/tokens/nft/mints?asset_identifier=SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335.megapont-ape-club-nft%3A%3AMegapont-Ape-Club&limit=3 

Once called, the API response will look something like:

{
  "limit": 3,
  "offset": 0,
  "total": 2500,
  "results": [
    {
      "recipient": "SP1X6M947Z7E58CNE0H8YJVJTVKS9VW0PHD4Q0A5F",
      "event_index": 0,
      "value": {
        "hex": "0x01000000000000000000000000000009c4",
        "repr": "u2500"
      },
      "tx_id": "0xb4d323681746a1593319f9dbf51b86755b83684af536e72972edafa2f4996870"
    },
    {
      "recipient": "SPR11YBZY0MM5AZFTQQEX1X1K9EN9TZZF0G21YBJ",
      "event_index": 0,
      "value": {
        "hex": "0x01000000000000000000000000000009c3",
        "repr": "u2499"
      },
      "tx_id": "0xc6d3f6fecb9a12d7d6f70c3c22f409c9f2a70faa2bd9e6512fa917cb35866214"
    },
    {
      "recipient": "SP36KY6SG05FK21AZGTNNY7HD5CPH5MQT8Q85HPD8",
      "event_index": 20,
      "value": {
        "hex": "0x01000000000000000000000000000009c2",
        "repr": "u2498"
      },
      "tx_id": "0x98b14d9d31e2d82da17340e9e272a35e27d8fb538d5a1457a3620ae72542d168"
    }
  ]
}
    

This code retrieves the mint history from a specific NFT collection, including optional data about each event such as the price for minting and any fees incurred.

With this information, developers can figure out how many NFT mints are remaining in a new collection, get a list of all addresses that participated in the mint, find out which address minted the most of a particular collection, and more.

To learn more about the available request parameters and response fields for this endpoint, visit https://docs.hiro.so/api#operation/get_nft_mints.

Conclusion

We’re eager to see what you can build with these endpoints! If you want to learn more about NFTs on Stacks, check out our NFT Tutorial to learn how you can create your own NFT project in 6 steps and learn more about the token standards in Stacks in our general documentation. If you're a visual learner, you can also watch Rafael break down this endpoints in a video on our YouTube channel.