Lightyear CryptoPunks

io.github.lightyear-technologies-limited/cryptopunks

This connects Claude directly to the CryptoPunks NFT collection, letting you query the full 10,000 punks by traits like accessories, types, and attributes. You can pull live marketplace data including current listings and bids, check Merkle root verification for authenticity, and analyze bid pricing across the collection. Reach for this when you're building NFT analysis tools, researching punk valuations, or need to filter the collection programmatically without scraping OpenSea or writing custom contract calls. The streamable HTTP transport means you can integrate it remotely without running local infrastructure.

tools: 11
transport: HTTP
last updated: Mar 30, 2026

Open website

Install

From registry metadata

$ npx add-mcp https://punks.lightyear.build/api/mcp --name cryptopunks

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http cryptopunks https://punks.lightyear.build/api/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 11 tools

Verified live against the running server on Nov 6, 2026.

browse_typesList all CryptoPunk type categories with their counts. Rate limit: 10 per 10 min (read bucket — shared with browse_traits, get_punk_details, get_listings, get_floor_price, get_bids_for_punk, get_bids_for_merkle_root).

List all CryptoPunk type categories with their counts. Rate limit: 10 per 10 min (read bucket — shared with browse_traits, get_punk_details, get_listings, get_floor_price, get_bids_for_punk, get_bids_for_merkle_root).

No parameters. Call it with no arguments.

browse_traitsList all CryptoPunk traits with their counts. Optionally filter by type to see how many punks of that type have each trait. Rate limit: 10 per 10 min (read bucket — shared with browse_types, get_punk_details, get_listings, get_floor_price, get_bids_for_punk, get_bids_for_merkl...1 params

List all CryptoPunk traits with their counts. Optionally filter by type to see how many punks of that type have each trait. Rate limit: 10 per 10 min (read bucket — shared with browse_types, get_punk_details, get_listings, get_floor_price, get_bids_for_punk, get_bids_for_merkl...

Parameters* required

typestring

Filter counts to a specific type (e.g. 'Male', 'Zombie')

filter_punksFilter CryptoPunks by type and traits. Returns matching punk IDs and their Merkle root. Rate limit: 5 per 10 min (compute bucket — shared with compute_merkle_root, resolve_merkle_root).4 params

Filter CryptoPunks by type and traits. Returns matching punk IDs and their Merkle root. Rate limit: 5 per 10 min (compute bucket — shared with compute_merkle_root, resolve_merkle_root).

Parameters* required

excludedTraitsarray

Traits to exclude

includedTraitsarray

Traits to include

matchModestring

'all' = punk must have every included trait, 'any' = at least oneone of all · anydefault: all

typesarray

Type names to include (e.g. ['Male', 'Zombie']). Empty = all types.

get_punk_detailsGet metadata for specific CryptoPunks: type, traits with rarity percentages, and permalink. Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_listings, get_floor_price, get_bids_for_punk, get_bids_for_merkle_root).1 params

Get metadata for specific CryptoPunks: type, traits with rarity percentages, and permalink. Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_listings, get_floor_price, get_bids_for_punk, get_bids_for_merkle_root).

Parameters* required

punkIds*array

Punk IDs to look up (1-100)

compute_merkle_rootCompute the Merkle root for a set of CryptoPunk IDs. The root matches the on-chain Solady MerkleProofLib encoding used by the Stash contract. Rate limit: 5 per 10 min (compute bucket — shared with filter_punks, resolve_merkle_root).1 params

Compute the Merkle root for a set of CryptoPunk IDs. The root matches the on-chain Solady MerkleProofLib encoding used by the Stash contract. Rate limit: 5 per 10 min (compute bucket — shared with filter_punks, resolve_merkle_root).

Parameters* required

punkIds*array

Punk IDs to include in the Merkle tree (1-10000)

get_listingsGet currently listed CryptoPunks from the native marketplace. By default returns only publicly buyable listings (excludes restricted onlySellTo and zero-value entries); pass `includeRestricted: true` to include private bundle sales. Optionally filter by price range. Returns `t...4 params

Get currently listed CryptoPunks from the native marketplace. By default returns only publicly buyable listings (excludes restricted onlySellTo and zero-value entries); pass `includeRestricted: true` to include private bundle sales. Optionally filter by price range. Returns `t...

Parameters* required

includeRestrictedboolean

Include restricted (onlySellTo) and zero-value listings. Default false — matches get_floor_price.default: false

limitinteger

Max results (default 50)default: 50

maxPriceEthnumber

Maximum price in ETH

minPriceEthnumber

Minimum price in ETH

get_floor_priceGet the current floor ask price from the native CryptoPunks marketplace. Excludes restricted (onlySellTo) and zero-value listings. Returns `totalActive` (same denominator as get_listings). Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_pu...

Get the current floor ask price from the native CryptoPunks marketplace. Excludes restricted (onlySellTo) and zero-value listings. Returns `totalActive` (same denominator as get_listings). Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_pu...

No parameters. Call it with no arguments.

get_bids_for_punkGet pending EIP-712 bids that include a specific CryptoPunk. Returns bids from the CryptoPunks Bids API. Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_punk_details, get_listings, get_floor_price, get_bids_for_merkle_root).2 params

Get pending EIP-712 bids that include a specific CryptoPunk. Returns bids from the CryptoPunks Bids API. Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_punk_details, get_listings, get_floor_price, get_bids_for_merkle_root).

Parameters* required

limitinteger

Max bids to return (default 5)default: 5

punkId*integer

Punk ID to look up bids for

get_bids_for_merkle_rootGet pending EIP-712 bids matching a specific Merkle root. Useful for seeing competition on a trait-based bid set. Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_punk_details, get_listings, get_floor_price, get_bids_for_punk).2 params

Get pending EIP-712 bids matching a specific Merkle root. Useful for seeing competition on a trait-based bid set. Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_punk_details, get_listings, get_floor_price, get_bids_for_punk).

Parameters* required

limitinteger

Max bids to return (default 5)default: 5

merkleRoot*string

Merkle root (0x-prefixed, 32 bytes hex)

get_bid_recommendationAnalyze market data and recommend a bid price range for a CryptoPunk trait selection. Combines floor price, competing bids, and set composition into actionable guidance. `composition` lists only the traits that define the selection; use `absentTraits` for a full exclusion list...5 params

Analyze market data and recommend a bid price range for a CryptoPunk trait selection. Combines floor price, competing bids, and set composition into actionable guidance. `composition` lists only the traits that define the selection; use `absentTraits` for a full exclusion list...

Parameters* required

excludedTraitsarray

Traits to exclude

includedTraitsarray

Traits to include

matchModestring

one of all · anydefault: all

punkIdsarray

Explicit punk IDs (overrides trait filters)

typesarray

Type names to filter (e.g. ['Male', 'Zombie'])

resolve_merkle_rootReverse-engineer a Merkle root back to its punk IDs and inferred trait selection. ONLY works for roots that already have at least one bid in the CryptoPunks Bids API — this tool looks bids up by root, then derives trait config from the resulting punk set. Returns `resolved: fa...1 params

Reverse-engineer a Merkle root back to its punk IDs and inferred trait selection. ONLY works for roots that already have at least one bid in the CryptoPunks Bids API — this tool looks bids up by root, then derives trait config from the resulting punk set. Returns `resolved: fa...

Parameters* required

merkleRoot*string

Merkle root to resolve (0x-prefixed, 32 bytes hex)

Details

Transport: HTTP
Registry: MCP registry, active
Tools verified: Nov 6, 2026