Lightyear CryptoPunks

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).

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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_merkle_root).

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Filter counts to a specific type (e.g. 'Male', 'Zombie')"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

{
  "type": "object",
  "properties": {
    "types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Type names to include (e.g. ['Male', 'Zombie']). Empty = all types."
    },
    "includedTraits": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Traits to include"
    },
    "excludedTraits": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Traits to exclude"
    },
    "matchMode": {
      "type": "string",
      "enum": [
        "all",
        "any"
      ],
      "default": "all",
      "description": "'all' = punk must have every included trait, 'any' = at least one"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

{
  "type": "object",
  "properties": {
    "punkIds": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9999
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Punk IDs to look up (1-100)"
    }
  },
  "required": [
    "punkIds"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

{
  "type": "object",
  "properties": {
    "punkIds": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9999
      },
      "minItems": 1,
      "maxItems": 10000,
      "description": "Punk IDs to include in the Merkle tree (1-10000)"
    }
  },
  "required": [
    "punkIds"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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 `totalActive` (publicly buyable listings, same denominator as get_floor_price) and `matchedCount` (after your filters). Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_punk_details, get_floor_price, get_bids_for_punk, get_bids_for_merkle_root).

{
  "type": "object",
  "properties": {
    "minPriceEth": {
      "type": "number",
      "description": "Minimum price in ETH"
    },
    "maxPriceEth": {
      "type": "number",
      "description": "Maximum price in ETH"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Max results (default 50)"
    },
    "includeRestricted": {
      "type": "boolean",
      "default": false,
      "description": "Include restricted (onlySellTo) and zero-value listings. Default false — matches get_floor_price."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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_punk_details, get_listings, get_bids_for_punk, get_bids_for_merkle_root).

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

{
  "type": "object",
  "properties": {
    "punkId": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9999,
      "description": "Punk ID to look up bids for"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 5,
      "description": "Max bids to return (default 5)"
    }
  },
  "required": [
    "punkId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

{
  "type": "object",
  "properties": {
    "merkleRoot": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$",
      "description": "Merkle root (0x-prefixed, 32 bytes hex)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 5,
      "description": "Max bids to return (default 5)"
    }
  },
  "required": [
    "merkleRoot"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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 when needed. Rate limit: 1 per 1 min (recommend bucket).

{
  "type": "object",
  "properties": {
    "types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Type names to filter (e.g. ['Male', 'Zombie'])"
    },
    "includedTraits": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Traits to include"
    },
    "excludedTraits": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Traits to exclude"
    },
    "matchMode": {
      "type": "string",
      "enum": [
        "all",
        "any"
      ],
      "default": "all"
    },
    "punkIds": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9999
      },
      "description": "Explicit punk IDs (overrides trait filters)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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: false` for unknown roots; constructing a root locally and passing it here will not work. Rate limit: 5 per 10 min (compute bucket — shared with filter_punks, compute_merkle_root).

{
  "type": "object",
  "properties": {
    "merkleRoot": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$",
      "description": "Merkle root to resolve (0x-prefixed, 32 bytes hex)"
    }
  },
  "required": [
    "merkleRoot"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}