nft

API Context

Endpoint: https://api.onesource.io/federation/{chain}/graphql Auth Header: x-bp-token: BP-{YOUR_API_KEY} Method: POST | Content-Type: application/json

Look up a specific NFT by its contract address and token ID. Returns null if the NFT doesn't exist or hasn't been minted.

Schema Definition

nft(
  contract: AddressString!
  tokenId: TokenId!
): NFT

Arguments

Argument	Type	Description
contract	AddressString! non-null scalar	The NFT contract address (0x-prefixed, 42 characters).
tokenId	TokenId! non-null scalar	The token ID within the contract (as a string to support uint256 values).

Return Type

Type	Description
NFT interface	Base interface for non-fungible tokens (NFTs). Implemented by SingleHolderNFT (ERC-721) and MultiHolderNFT (ERC-1155). Contains fields common to all NFT types regardless of ownership model.

Common Use Cases

• Build NFT detail pages by looking up a specific token with its full metadata, media, and ownership information.
• Verify NFT ownership and authenticity for marketplace listings, gating, or wallet displays.
• Display NFT artwork and media with optimized thumbnails at various preset sizes for galleries and collection viewers.
• Check whether an NFT has been burned by inspecting the burned field and burnTransaction.
• Retrieve mint provenance by accessing the mintTransaction field for historical analysis or verification.
• Differentiate between ERC-721 and ERC-1155 NFTs using inline fragments to access standard-specific fields like holder or holdersCount.

Example

Query

Look Up an ERC-721 NFT with Metadata and Media

query GetNFTDetails($contract: AddressString!, $tokenId: TokenId!) {
  nft(contract: $contract, tokenId: $tokenId) {
    tokenId
    name
    standard
    contract {
      address
      name
      symbol
      standards
    }
    metadata {
      description
      image
      attributes {
        traitType
        value
      }
    }
    media {
      url
      contentType
      thumbnails(preset: MEDIUM) {
        url
        width
        height
      }
    }
    ... on SingleHolderNFT {
      holder {
        address
      }
      burned
      mintTransaction {
        hash
        timestamp
      }
    }
    ... on MultiHolderNFT {
      totalSupply
      holdersCount
      holders(first: 5) {
        entries {
          address {
            address
          }
          balance
        }
      }
    }
  }
}

Variables

{
  "contract": "0xC9041f80DCe73721A5f6a779672Ec57EF255d27c",
  "tokenId": "42141102"
}

Response

{
  "data": {
    "nft": {
      "tokenId": "42141102",
      "name": "Singular Focus",
      "standard": "ERC721",
      "contract": {
        "address": "0xC9041f80DCe73721A5f6a779672Ec57EF255d27c",
        "name": "Art Blocks",
        "symbol": "BLOCKS",
        "standards": ["ERC721"]
      },
      "metadata": {
        "description": "The Partition is formed by a set of recursive subdivisions of the canvas...",
        "image": "ipfs://QmExample123abc456def789ghi",
        "attributes": [
          {
            "traitType": "Artist",
            "value": "Example Artist"
          },
          {
            "traitType": "Collection",
            "value": "Curated"
          }
        ]
      },
      "media": [
        {
          "url": "https://media.onesource.io/nft/1/42141102.png",
          "contentType": "image/png",
          "thumbnails": [
            {
              "url": "https://media.onesource.io/thumbnails/medium/1/42141102.png",
              "width": 300,
              "height": 300
            }
          ]
        }
      ],
      "holder": {
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2"
      },
      "burned": false,
      "mintTransaction": {
        "hash": "0x9f8e7d6c5b4a3210fedcba9876543210fedcba9876543210fedcba9876543210",
        "timestamp": "2025-03-20T16:45:22Z"
      }
    }
  }
}

Implementation Notes

note

• Both contract and tokenId arguments are required to uniquely identify an NFT. The tokenId is a string to support the full uint256 range.
• The nft query returns null if the NFT doesn't exist or hasn't been minted. Always handle the null case in your application.
• The return type is the NFT interface, which resolves to either SingleHolderNFT (ERC-721) or MultiHolderNFT (ERC-1155). Use inline fragments (... on SingleHolderNFT, ... on MultiHolderNFT) to access type-specific fields.
• For ERC-721 NFTs, the holder field returns the single current owner. For ERC-1155 NFTs, use holdersCount and the paginated holders field to access multiple owners and their balances.
• The metadata field contains parsed token metadata including description, image, and attributes. This data is fetched and cached from the token URI — it may be null if the metadata hasn't been fetched yet or the URI is unreachable.
• The media array contains processed media files with pre-generated thumbnails at various presets (SMALL, MEDIUM, LARGE, ORIGINAL). Use thumbnails for performant rendering in galleries and lists.
• To search and filter across multiple NFTs, use the nfts query with pagination and filtering support.