Skip to content
sui-mcp

NFTs

Tool Summary
get_nft_sales NFT marketplace sales over a recent window, with volume and per-marketplace totals.
get_top_holders Scan objects of a given type and return top holders.
list_nft_collections Summary of the NFT collections a wallet holds: every kiosk plus directly owned objects, one row per collection type with its count.
list_nfts List NFTs owned by a wallet, including kiosk-stored NFTs.

get_nft_sales

Section titled “get_nft_sales”
  • Title: Get NFT sales
  • Profile: forensics
  • Annotations: openWorldHint: true, readOnlyHint: true
  • Metadata: anthropic/maxResultSizeChars: 500000

NFT marketplace sales over a recent window, with volume and per-marketplace totals. Reads TradePort, BlueMove and OriginByte sale events. Also records which wallet holds which kiosk, which is what makes get_top_holders able to name a real owner for a kiosk-held NFT.

Parameter Type Required Description
hours number (1 to 168), default 24 no How far back to read, in hours (default 24, max 168)
collection_type string no Keep only sales of this Move type. Most sale events name no collection; those count as unattributable_sales, so a low count does not show the collection did not trade.
max_pages integer (1 to 200), default 40 no Request cap across all marketplaces (default 40, 50 events per request)
include_sales boolean, default false no Also return each sale with its checkpoint and time (default false, since a busy window has thousands of rows).
detail summary | full no With include_sales: ‘summary’ (default) lists the newest sales that fit and counts the rest in omitted; ‘full’ lists every sale.
network mainnet | testnet | devnet no Network: ‘mainnet’ (default) | ‘testnet’ | ‘devnet’

get_top_holders

Section titled “get_top_holders”
  • Title: Get top holders
  • Profile: forensics
  • Annotations: openWorldHint: true, readOnlyHint: true

Scan objects of a given type and return top holders. The scan is slow and paginated. Works for NFT collections (ranked by count) or tokens (ranked by balance, counting both Coin<T> objects and address balances, with the split and the holder’s kind per holder). Kiosk-stored NFTs are attributed using the kiosk’s self-declared owner field, which is marked as such because it does not follow the KioskOwnerCap. Accepts a Move type, coin type, or collection name. A scan stops after 35s and returns what it saw as a sample marked time_budget_reached. Results cached 24h.

Parameter Type Required Description
type string no NFT struct type or coin type, e.g. ‘0xabc::module::NFT’ or ‘0x2::sui::SUI’. A coin type is wrapped in Coin<…> automatically.
collection_name string no NFT collection name or slug to look up in the registry (e.g. ‘gawblenz’). Alternative to ‘type’.
mode nft | token no ‘nft’ ranks by count, ‘token’ by balance. If omitted, a type the chain knows as a coin is scanned as a token, anything else as an NFT collection.
limit integer (1 to 100) no Top N holders to return (default 20, max 100)
max_scan integer (1 to 50000) no Objects to scan per walk (default 5000, max 50000). Token mode walks Coin<T> objects and address balances separately, each to this bound. The 35s time budget applies regardless.
network mainnet | testnet | devnet no Network: ‘mainnet’ (default) | ‘testnet’ | ‘devnet’

list_nft_collections

Section titled “list_nft_collections”
  • Title: List NFT collections
  • Profile: core (default)
  • Annotations: openWorldHint: true, readOnlyHint: true

Summary of the NFT collections a wallet holds: every kiosk plus directly owned objects, one row per collection type with its count. Each collection carries an estimated value (tier heuristic): per item, the lower of the collection’s lowest active listing and its last sale in the 30 days before now, or whichever of the two exists (a listing alone only if placed in that window), with zero-price sales, sales within one address or kiosk, and sales where one side first funded the other left out; unpriced otherwise. estimated_value totals every collection; the default view keeps every priced collection and caps the rest, and detail: 'full' returns all rows. value: false skips the valuation.

Parameter Type Required Description
address string yes Owner wallet address (0x…)
value boolean, default true no Estimate each collection’s value from its market (default true). Costs a few requests per collection that has a market.
detail summary | full no ‘summary’ (default): priced collections, then the most-held others that fit; omitted counts the rest. ‘full’: every collection.
network mainnet | testnet | devnet no Network: ‘mainnet’ (default) | ‘testnet’ | ‘devnet’

list_nfts

Section titled “list_nfts”
  • Title: List NFTs
  • Profile: core (default)
  • Annotations: openWorldHint: true, readOnlyHint: true

(Recommended for NFTs) List NFTs owned by a wallet, including kiosk-stored NFTs. Each row has an object id, collection_ref (zero-based index into this page’s exact collection_types), kiosk and display metadata. detail: 'full' adds raw Move contents and valuation evidence. est_usd is a heuristic NFT estimate; other valued objects carry value_usd and a tier. value: false skips valuation. Pass next_cursor as cursor for the next page; its absence means the wallet is fully enumerated. Use list_nft_collections for a per-collection summary and wallet total.

Parameter Type Required Description
address string yes Owner wallet address (0x…)
limit integer (1 to 1000) no Most NFTs to return (default 50, max 1000).
cursor string no Opaque pagination token from a prior response’s next_cursor. Omit on first call.
detail summary | full no ‘summary’ (default) leaves out raw contents and valuation evidence, counted in omitted. ‘full’ includes both.
value boolean, default true no Estimate each NFT’s value from its collection’s market (default true). Costs a few requests per collection on the page.
network mainnet | testnet | devnet no Network: ‘mainnet’ (default) | ‘testnet’ | ‘devnet’