Skip to main content

NFT Ownership Checker

Verify whether an address holds a token in a given NFT collection.

MCP tools

  • check_owner
  • get_owners
  • get_metadata

API endpoints

  • GET /v4/data/nft/owners
  • GET /v4/data/nft/metadata

Steps

  1. Resolve contract, tokenId, chain, and address.
  2. Call check_owner for the boolean answer.
  3. If positive and metadata is requested, call get_metadata.

Agent trace

The call sequence an MCP-capable agent logs when it runs this workflow.

  1. Resolve the collection contract 
    // e.g. BAYC on mainnet
const tokenAddress = "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d";
  2. Ask "who owns token id 1234?" 
    mcp.tatumio.get_owners({
  chain:        "ethereum-mainnet",
  tokenAddress,
  tokenId:      "1234"
})
// → { owners: ["0xab58…c9b"], count: 1 }
  3. Pull metadata if needed 
    mcp.tatumio.get_metadata({
  chain: "ethereum-mainnet",
  tokenAddress,
  tokenIds: ["1234"]
})

Possible failures

  • Wrong chain for the contract
  • Contract not an ERC-721/1155
  • Address normalization mismatch

Recovery guidance

  • Validate contract on the requested chain first
  • Fall back to `get_owners` if `check_owner` returns ambiguous results
  • Always compare addresses checksummed/normalized