ryley-o

---
name: scaffold-art-script
description: Build or convert Art Blocks generative art scripts using artblocks-mcp. Use when helping a user create, scaffold, port, or convert an art script for Art Blocks, or when working with tokenData, hash-based PRNG, FLEX dependencies, PostParams, window.$features traits, p5.js, Three.js, or the Art Blocks generator format.
---

# Scaffolding Art Blocks Projects

## Always Fetch the Generator Spec First

Before any art script work, fetch this MCP resource:

```
artblocks://generator-spec
```

It contains the authoritative reference for: `tokenData` structure, hash-based PRNG patterns, FLEX dependency types (IPFS, Arweave, ONCHAIN, Dependency Registry), supported script types and library versions, HTML structure requirements, and `window.$features`. It also includes the step-by-step conversion guide for porting existing scripts.

## Scaffolding a New Project

Use `scaffold_artblocks_project` to generate a ready-to-run `index.html` + starter art script.

### Parameters

| Param                    | Options / Notes                                                                                   |
|--------------------------|---------------------------------------------------------------------------------------------------|
| `scriptType`             | `"js"` (vanilla), `"p5js"`, `"threejs"` — **required**                                          |
| `dependencyVersion`      | p5.js: `"1.0.0"` or `"1.9.0"` (default). Three.js: `"0.124.0"`, `"0.160.0"`, `"0.167.0"` (default). Ignored for `"js"`. |
| `includePostParams`      | `true` — adds ONCHAIN/PostParams (PMP) stubs in `tokenData` and example usage                    |
| `includeFlexDependencies`| `true` — adds IPFS and Arweave dependency stubs with usage patterns                              |
| `includeFeatures`        | `true` — adds `window.$features` trait assignment stub                                           |

**Note on Three.js v0.167.0**: uses ES module import maps instead of a global `<script>` tag. This affects script type detection on-chain — see the generator spec for details.

### Other supported script types

`scaffold_artblocks_project` covers vanilla JS, p5.js, and Three.js. Art Blocks supports many more via the on-chain dependency registry: regl, Tone.js, Babylon.js, A-Frame, Paper.js, Zdog, Processing, and custom types. See `artblocks://generator-spec` for the full list and how to reference them.

## Converting an Existing Script

When a user has an existing piece to convert to Art Blocks format:

1. Fetch `artblocks://generator-spec` — it contains a detailed step-by-step conversion guide
2. Use `scaffold_artblocks_project` with the matching `scriptType` to get the correct HTML shell
3. Walk through conversion:

**Conversion checklist:**
- Replace `Math.random()` with hash-based PRNG derived from `tokenData.hash`
- Replace hardcoded canvas dimensions with `window.innerWidth` / `window.innerHeight`
- Ensure the **initial render** is deterministic from the hash alone — same hash must always produce the same initial visual output
- Interactive elements (mouse, keyboard, touch) are allowed and encouraged, but must not change the initial render. Interaction should only modify the view *after* the artwork has loaded deterministically.
- Remove any time-based variation (`Date.now()`, `setTimeout`) that affects the initial render (time-based animation after load is fine)
- Extract visual traits into `window.$features` (optional but recommended for reveals) — features must be set synchronously before or during initial render
- Verify determinism: reload the page with the same `tokenData.hash` and confirm identical initial output

## When to Enable Each Flag

| Flag                     | Enable when...                                                        |
|--------------------------|-----------------------------------------------------------------------|
| `includeFeatures`        | Script has distinct visual categories worth exposing as traits        |
| `includePostParams`      | Script will have configurable on-chain parameters after minting (PMP) |
| `includeFlexDependencies`| Script loads external assets from IPFS or Arweave                    |

---
name: query-artblocks-data
description: Query Art Blocks on-chain data using the artblocks-mcp GraphQL tools. Use when fetching projects, tokens, artists, sales, traits, or any Art Blocks on-chain data via graphql_query, build_query, explore_table, graphql_introspection, validate_fields, or query_optimizer. These are advanced escape-hatch tools — prefer domain-specific tools (discover_projects, get_project, get_artist, get_wallet_tokens, get_token_metadata) when they cover the use case.
---

# Querying Art Blocks Data

## When to Use GraphQL vs Domain Tools

The domain-specific tools cover most use cases and are easier to use:

| Need | Tool |
|------|------|
| Browse/search projects | `discover_projects` |
| Full project details | `get_project` |
| Artist's body of work | `get_artist` |
| Portfolio overview | `get_wallet_summary` |
| Collector's tokens | `get_wallet_tokens` |
| Token details | `get_token_metadata` |
| Live mints | `discover_live_mints` |
| Upcoming drops | `discover_upcoming_releases` |
| Mint eligibility | `check_allowlist_eligibility` |

Use the GraphQL tools below as an **escape hatch** for custom queries not covered above — sales history, aggregations, complex joins, or tables without a dedicated tool.

## Resource: `artblocks://about`

Fetch this resource for platform context — vocabulary, verticals, chains, tags, user profiles, and a guide to which tool handles what.

## Tool Hierarchy

Use tools in this order — skip steps you don't need:

1. **Discover schema** → `explore_table` (single table with fields + relationships) or `graphql_introspection` (full schema)
2. **Build a validated query** → `build_query` (validates fields, adds suggestions, auto-filters by chain)
3. **Optimize** → `query_optimizer` (rewrites to preferred tables, e.g. `projects_metadata` over `projects`)
4. **Execute** → `graphql_query`

If you already know the schema, go straight to `build_query` → `graphql_query`.

## Tool: `explore_table`

For well-known tables (`projects_metadata`, `tokens_metadata`), returns a curated shortlist of the most useful fields organized by category (Identity, Status, Media, Market, etc.) plus key relationships with suggested subfields. Pass `showAllFields: true` to see the full schema dump instead.

| Param          | Required | Notes                                                   |
| -------------- | -------- | ------------------------------------------------------- |
| `tableName`    | yes      | Table to explore                                        |
| `showAllFields`| —        | `true` for full schema dump (default: curated shortlist)|

## Preferred Tables

Always use the `_metadata` variants — they include richer joined data:

| Use this              | Not this    |
|-----------------------|-------------|
| `projects_metadata`   | `projects`  |
| `tokens_metadata`     | `tokens`    |
| `contracts_metadata`  | `contracts` |

`query_optimizer` will automatically rewrite queries that use the wrong table.

## Chain IDs

| Chain            | ID      |
|------------------|---------|
| Ethereum mainnet | `1` (default) |
| Arbitrum         | `42161` |
| Base             | `8453`  |

Pass `chainId` to `graphql_query` to make `$chainId` available as a variable in your query.

## Common Query Patterns

These examples show queries that **require** raw GraphQL — things the domain tools can't do.

### Recent sales (no domain tool covers purchases)
```graphql
query {
  purchases_metadata(
    order_by: { block_timestamp: desc }
    limit: 20
    where: { chain_id: { _eq: 1 } }
  ) {
    token_id
    price_in_eth
    block_timestamp
    buyer_address
    seller_address
  }
}
```

### Aggregate token count by owner for a project
```graphql
query {
  tokens_metadata_aggregate(
    where: { project_id: { _eq: "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-78" } }
    distinct_on: owner_address
  ) {
    aggregate { count }
  }
}
```

### All tokens for a project (domain tools only return per-wallet)
```graphql
query {
  tokens_metadata(
    where: { project_id: { _eq: "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-0" } }
    order_by: { invocation: asc }
    limit: 50
  ) {
    token_id
    invocation
    owner_address
    features
  }
}
```

### Projects with specific on-chain attributes
```graphql
query {
  projects_metadata(
    where: {
      script_type_and_version: { _ilike: "%three%" }
      chain_id: { _eq: 1 }
      complete: { _eq: false }
    }
    limit: 20
  ) {
    id
    name
    artist_name
    script_type_and_version
    invocations
    max_invocations
  }
}
```

## Tips

- Use `explore_table` to understand fields and relationships before writing a query — the curated view is much easier to scan than the full schema dump
- `build_query` is the safest way to start — it validates fields and tells you what's available
- Always pass `chainId` when querying multi-chain data to avoid cross-chain noise
- For unknown fields, `validate_fields` is faster than a full introspection

---
name: mint-artblocks-token
description: Mint (purchase) an Art Blocks token using the artblocks-mcp tools. Use when a user wants to mint, purchase, or buy an Art Blocks NFT, or needs to understand minting mechanics, minter types, pricing, allowlists, Dutch auctions, or build_purchase_transaction.
---

# Minting an Art Blocks Token

## Project ID Format

All minting tools require a full project ID: `<contract_address>-<project_index>`

Example: `0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-0`

Use `discover_projects` to find the project ID from a name or search term. To find projects currently open for minting, pass `mintable: true` — this filters to only projects with active minters and remaining supply.

## Minting Workflow

### Step 1 — Understand the minter

Call `get_project_minter_config` first. Returns:

- Minter type (set price, Dutch auction, allowlist, RAM, etc.)
- Current price and currency (ETH or ERC-20)
- Remaining supply (`max_invocations - invocations`)
- Auction timing (start/end, price decay curve for DA minters)
- Allowlist details (for gated minters)

### Step 2 — Check eligibility (gated projects only)

If the minter type is `MinterMerkleV5` or `MinterHolderV5`, call `check_allowlist_eligibility` before proceeding.

Accepts a `walletAddress` (including ENS names) or an Art Blocks `username`. When the input resolves to an Art Blocks profile, **all wallets linked to that profile are checked** for eligibility. At least one of `walletAddress` or `username` is required.

| Param           | Type   | Notes                                                                      |
| --------------- | ------ | -------------------------------------------------------------------------- |
| `projectId`     | string | Required. Full project ID.                                                 |
| `walletAddress` | string | Wallet address or ENS name. Provide this or `username`.                    |
| `username`      | string | Art Blocks username — checks all linked wallets.                           |
| `chainId`       | number | Default `1`. `1`, `42161`, `8453`.                                         |

Returns: eligibility status, gate type, which wallets are eligible (for multi-wallet profiles), and for holder-gated minters, which projects the wallet must hold tokens from.

### Step 3 — Build the transaction

`build_purchase_transaction` currently supports **MinterSetPriceV5 (ETH)** only.

| Param        | Required | Notes                                                                                                                                 |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId`  | yes      | `<contract_address>-<project_index>`                                                                                                  |
| `chainId`    | —        | Default `1`. See chain IDs below.                                                                                                     |
| `purchaseTo` | —        | Mint to a different address (gifting). Check `purchaseTo.disabled` in `get_project_minter_config` first — some projects disable this. |

Returns `{ transaction, project, minter, price, purchaseTo, warnings }`. The `warnings` array contains non-fatal issues (paused project, sold out, complete) — always surface these to the user before they sign.

## Minter Types

| Minter             | Description                           | `build_purchase_transaction` |
| ------------------ | ------------------------------------- | ---------------------------- |
| `MinterSetPriceV5` | Fixed ETH price                       | Supported                    |
| `MinterDAExpV5`    | Dutch auction — exponential decay     | Use wallet directly          |
| `MinterDALinV5`    | Dutch auction — linear decay          | Use wallet directly          |
| `MinterMerkleV5`   | Merkle allowlist gating               | Use wallet directly          |
| `MinterHolderV5`   | Holder-gated (must own another token) | Use wallet directly          |
| `RAM`              | Ranked auction mechanism              | Use wallet directly          |

For unsupported minters, explain the mechanics from `get_project_minter_config` data and direct the user to their wallet.

## Chain IDs

| Chain            | ID      |
| ---------------- | ------- |
| Ethereum mainnet | `1`     |
| Arbitrum         | `42161` |
| Base             | `8453`  |

## Notes

- **User profiles**: When a wallet address or username resolves to an Art Blocks profile, eligibility is checked across all linked wallets. The response includes `walletAddresses` (all checked), `profile` info, and for Merkle gates, `eligibleWallets` showing which specific wallets passed.
- **ERC-20 projects**: `get_project_minter_config` indicates the currency token address. `build_purchase_transaction` only supports ETH — direct ERC-20 users to their wallet.
- **Dutch auctions**: current price decreases over time. Use `start_price`, `end_price`, `auction_start_time`, and `auction_end_time` from `get_project_minter_config` to explain current pricing.
- **`purchaseTo`**: useful for gifting — mints the token directly to a recipient address instead of the signer.

---
name: get-token-metadata
description: Retrieve rich metadata for a specific Art Blocks token using artblocks-mcp. Use when a user wants to look up a minted token's details, traits, features, media URLs, owner, listing info, live view, or project context using get_token_metadata.
---

# Getting Art Blocks Token Metadata

## Tool: `get_token_metadata`

Retrieves a single token's full metadata in one call — traits, media URLs, owner, hash, listing info, and project context. Prefer this over `graphql_query` when you need rich token details for a known token ID.

## Token ID Format

`<contract_address>-<token_number>`

Example: `0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-78000000`

## Parameters

| Param     | Required | Notes                                      |
|-----------|----------|--------------------------------------------|
| `tokenId` | yes      | Full token ID `<contract_address>-<token_number>` |
| `chainId` | —        | Default `1` (Ethereum). `1`, `42161` (Arbitrum), `8453` (Base) |

## Response Shape

The response has three top-level keys: `token`, `media`, and `project`.

```
token:
  id, tokenId, chainId, contractAddress, projectId
  hash              — 32-byte hex, the source of all randomness
  invocation        — mint number within the project (0-indexed)
  features          — on-chain traits object
  featuresStatus    — "not_defined" | "defined_empty" | "defined"
  mintedAt, mintTransactionHash
  ownerAddress
  listing           — null if not listed, otherwise:
    listing.price      — listing price
    listing.currency   — currency symbol (ETH, WETH, etc.)
    listing.platform   — marketplace name
    listing.url        — listing URL
  artBlocksUrl      — direct link to the token page on artblocks.io

media:
  imageUrl          — primary rendered image
  previewUrl        — preview asset URL
  liveViewUrl       — live interactive generator URL
  hasVideo          — true if a video render exists

project:
  id, name, artistName, slug
  artBlocksUrl      — direct link to the project page on artblocks.io
  description, website, license
  scriptTypeAndVersion
  maxInvocations, invocations, remaining
  active, paused, complete
  aspectRatio, curationStatus, verticalName, verticalDisplay
  renderComplete
```

## When to Use vs GraphQL

| Use `get_token_metadata` when... | Use `graphql_query` when... |
|---|---|
| You have a specific token ID and want everything about it | You need to query multiple tokens at once |
| You need media URLs (`liveViewUrl`, `imageUrl`) | You need fields not in this response |
| You want features + project context in one call | You're building complex filters or aggregations |

## Notes

- `liveViewUrl` is the canonical way to share or preview a generative token — always include it when presenting a token to a user
- `features` is the on-chain traits object — same data shown on Art Blocks website
- `featuresStatus` distinguishes between "artist hasn't defined features" (`not_defined`), "features are defined but empty for this token" (`defined_empty`), and "features exist" (`defined`)
- `hash` uniquely identifies the token's visual output — same hash always produces the same artwork
- `listing` is `null` when the token has no active secondary-market listing; when present it contains `price`, `currency`, `platform`, and `url`
- Both `token.artBlocksUrl` and `project.artBlocksUrl` link to artblocks.io — use these when presenting tokens to users

---
name: get-artist
description: Look up an Art Blocks artist and their body of work using artblocks-mcp. Use when a user wants to find an artist, see their projects, explore an artist's portfolio, or search by artist name, slug, or wallet address using get_artist.
---

# Looking Up Art Blocks Artists

## Tool: `get_artist`

Finds an artist and returns all their Art Blocks projects with full metadata, floor prices, tags, and direct artblocks.io links. Results are ordered by most recently launched.

## Search Options

Provide at least one — they can be combined:

| Param          | Type   | Notes                                                          |
| -------------- | ------ | -------------------------------------------------------------- |
| `artistName`   | string | Case-insensitive partial match (e.g. `"hobbs"` finds Tyler Hobbs) |
| `artistSlug`   | string | Exact artist profile slug (e.g. `"tyler-hobbs"`)               |
| `artistAddress`| string | Artist's wallet address (exact match)                          |
| `chainId`      | number | Optional — filter projects to a specific chain                 |
| `limit`        | number | Max projects to return (1–100, default 50)                     |

## Response Shape

```
artistNames        — deduplicated list of artist display names matched
artistProfiles     — unique artist profile objects: { slug, displayName }
totalProjects      — total project count matching the query
projects[]         — array of project objects, each containing:
  id                 — full project ID (contract_address-project_index)
  name, artistName, description, slug
  artBlocksUrl       — direct link to project on artblocks.io
  chainId, contractAddress, projectIndex
  verticalName, verticalDisplay, curationStatus
  active, paused, complete, invocations, maxInvocations, remaining
  startDatetime, completedAt
  aspectRatio, scriptTypeAndVersion, renderComplete
  website, license
  lowestListing      — floor price in ETH (null if no listings)
  featuredTokenImageUrl — hero image URL (null if none)
  tags[]             — tag name strings (e.g. "ab500", "animated")
  artistProfiles[]   — { slug, displayName }
```

## When to Use vs Other Tools

| Use `get_artist` when...                              | Use something else when...                        |
| ----------------------------------------------------- | ------------------------------------------------- |
| You want all projects by a specific artist             | You want to browse projects broadly → `discover_projects` |
| You know the artist's name, slug, or wallet address    | You have a specific project ID → `get_project`    |
| You want to compare an artist's body of work           | You need token-level data → `get_token_metadata`  |

## Notes

- Results include `artBlocksUrl` for each project — use these when presenting projects to users
- The `artistSlug` field in results (under `artistProfiles`) can be used for subsequent lookups
- The tool excludes unassigned/test projects automatically
- If the artist name is ambiguous (partial match returns multiple artists), the `artistNames` array will show all matched names
- `projectIndex` is the project number on the contract (e.g. `78`); `id` is the full project ID (e.g. `0xa7d8...d270-78`)

---
name: discover-artblocks-projects
description: Browse, search, and explore Art Blocks projects, collections, and collector portfolios using artblocks-mcp. Use when a user wants to find, filter, browse, or explore Art Blocks projects by name, artist, vertical, chain, tag, floor price, or mintability status, or when asking what is minting now, what is dropping soon, what tokens a wallet holds, or to get a portfolio summary. Uses discover_projects, get_project, discover_live_mints, discover_upcoming_releases, get_wallet_summary, get_wallet_tokens, get_artist, and list_tags.
---

# Discovering Art Blocks Projects

## Choosing the Right Tool

| Goal                                         | Tool                         |
| -------------------------------------------- | ---------------------------- |
| What's minting right now?                    | `discover_live_mints`        |
| What's dropping soon?                        | `discover_upcoming_releases` |
| Browse/filter by vertical, artist, chain, tag | `discover_projects`         |
| Full details on a known project              | `get_project`                |
| All projects by a specific artist            | `get_artist`                 |
| High-level portfolio summary for a collector | `get_wallet_summary`         |
| Individual tokens a collector owns           | `get_wallet_tokens`          |
| See available tags for filtering             | `list_tags`                  |

## Resource: `artblocks://about`

Fetch this resource first if you need platform context — it covers vocabulary, verticals, chains, tags, user profiles, and a quick-start guide for which tool to use.

## Tool: `discover_projects`

Browses and filters Art Blocks collections with optional text search, chain, vertical, tag, floor price, and mintability filters. Returns project metadata with truncated descriptions, floor price, mint progress, featured token image, and a direct artblocks.io link. Test/dev projects (unassigned vertical) are excluded by default.

### Filters

| Param              | Type    | Notes                                                                                                             |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `search`           | string  | Searches project name and artist name (case-insensitive partial match)                                            |
| `artistName`       | string  | Filter by artist name (case-insensitive partial match)                                                            |
| `chainId`          | number  | `1` (Ethereum), `42161` (Arbitrum), `8453` (Base)                                                                 |
| `verticalName`     | string  | See verticals below                                                                                               |
| `mintable`         | boolean | `true` = actively mintable projects only                                                                          |
| `tag`              | string  | Filter by tag (e.g. `"ab500"`, `"animated"`, `"curated series 1"`). Use `list_tags` to see all available tags.    |
| `minFloorPrice`    | number  | Minimum floor price in ETH                                                                                        |
| `maxFloorPrice`    | number  | Maximum floor price in ETH — only returns projects with a listing at or below this price                          |
| `isArtblocks`      | boolean | `true` = Art Blocks flagship only, `false` = Engine only, omit for all                                            |
| `includeUnassigned`| boolean | Include test/dev projects (default false)                                                                         |
| `sortBy`           | string  | `newest` (default), `oldest`, `name_asc`, `recently_updated`, `floor_asc`, `floor_desc`, `most_collected`, `edition_size_desc` |
| `limit`            | number  | Default 25, max 200                                                                                               |
| `offset`           | number  | For pagination                                                                                                    |

### Verticals

| Value          | Description                                           |
| -------------- | ----------------------------------------------------- |
| `curated`      | Art Blocks Curated — highest-curation tier            |
| `studio`       | Art Blocks Studio — artist-driven projects            |
| `presents`     | Art Blocks Presents                                   |
| `explorations` | Art Blocks Explorations                               |
| `playground`   | Art Blocks Playground                                 |
| `flex`         | Art Blocks Flex — scripts with off-chain dependencies |
| `fullyonchain` | Fully on-chain — no external dependencies             |

## Tool: `get_project`

Returns full details for a single project. Use this when you need more than `discover_projects` provides — it returns the **complete untruncated description**, **trait/feature distribution with per-value rarity percentages**, artist profiles, tags, floor price, mint progress, minting config, featured token image, and artblocks.io link.

| Param       | Type   | Notes                                                           |
| ----------- | ------ | --------------------------------------------------------------- |
| `projectId` | string | Full project ID (e.g. `"0xa7d8...d270-78"`). Provide this or slug. |
| `slug`      | string | Project slug (e.g. `"fidenza-by-tyler-hobbs"`). Provide this or projectId. |

Key fields unique to `get_project` (not in `discover_projects`):
- `featureFields` — trait distribution: each feature name with all values, counts, and rarity percentages
- Full `description` (not truncated — `discover_projects` truncates at ~800 chars)

## Tool: `get_artist`

Looks up an artist and returns all their projects with metadata, floor price, tags, and artblocks.io links. Search by name (partial), profile slug (exact), or wallet address.

| Param          | Type   | Notes                                                   |
| -------------- | ------ | ------------------------------------------------------- |
| `artistName`   | string | Case-insensitive partial match                          |
| `artistSlug`   | string | Exact profile slug (e.g. `"tyler-hobbs"`)               |
| `artistAddress`| string | Wallet address (exact match)                            |
| `chainId`      | number | Optional chain filter                                   |
| `limit`        | number | Max projects to return (1–100, default 50)              |

At least one of `artistName`, `artistSlug`, or `artistAddress` is required.

## Tool: `discover_live_mints`

Returns projects currently active, unpaused, not complete, and past their start date. Ordered by most recently started. Includes minter type, pricing, supply, and artblocks.io links.

| Param     | Type   | Notes                         |
| --------- | ------ | ----------------------------- |
| `search`  | string | Filter by project/artist name |
| `chainId` | number | `1`, `42161`, `8453`          |
| `limit`   | number | Default 25, max 200           |

## Tool: `discover_upcoming_releases`

Returns projects with a future `start_datetime`, ordered by soonest first. Includes minter configuration and artblocks.io links.

| Param     | Type   | Notes                         |
| --------- | ------ | ----------------------------- |
| `search`  | string | Filter by project/artist name |
| `chainId` | number | `1`, `42161`, `8453`          |
| `limit`   | number | Default 25, max 100           |

## Tool: `list_tags`

Returns all distinct tag names that can be used with the `discover_projects` `tag` filter. No parameters. Common tags: `"ab500"`, `"animated"`, `"interactive"`, `"audio"`, `"responsive"`, `"curated series 1"`, `"evolving"`.

## Tool: `get_wallet_summary`

High-level portfolio summary for an Art Blocks collector. Returns total token count, unique project count, chain distribution, and a per-project breakdown (project name, artist, token count, artblocks.io link) sorted by number held.

| Param           | Type   | Notes                                                                             |
| --------------- | ------ | --------------------------------------------------------------------------------- |
| `walletAddress` | string | Wallet address or ENS name. Provide this or `username` (at least one required).   |
| `username`      | string | Art Blocks username — aggregates across all linked wallets.                        |
| `chainId`       | number | Optional chain filter                                                             |
| `projectId`     | string | Filter to a specific project                                                      |
| `limit`         | number | Max projects in breakdown (1–100, default 25)                                     |
| `offset`        | number | Pagination offset                                                                 |

## Tool: `get_wallet_tokens`

Returns individual Art Blocks tokens owned by a collector with project context, media URLs, features/traits, mint date, and artblocks.io links.

| Param           | Type   | Notes                                                                             |
| --------------- | ------ | --------------------------------------------------------------------------------- |
| `walletAddress` | string | Wallet address or ENS name. Provide this or `username` (at least one required).   |
| `username`      | string | Art Blocks username — aggregates across all linked wallets.                        |
| `chainId`       | number | Optional chain filter                                                             |
| `projectId`     | string | Filter to tokens from a specific project                                          |
| `sortBy`        | string | `recently_collected` (default), `first_collected`, `newest_mint`, `oldest_mint`   |
| `limit`         | number | Default 100, max 250                                                              |
| `offset`        | number | For pagination                                                                    |

## User Profiles and Linked Wallets

Art Blocks users can link multiple wallets to a single profile. `get_wallet_summary`, `get_wallet_tokens`, and `check_allowlist_eligibility` all accept either a `walletAddress` (including ENS) or an Art Blocks `username`. When a profile is found, tokens and eligibility are aggregated across **all linked wallets**, giving a complete view of a collector's holdings.

## Project ID Format

The `id` field in results is the full project ID used by all downstream tools:

`<contract_address>-<project_index>`

Example: `0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-0`

Use this directly with `get_project`, `get_project_minter_config`, `build_purchase_transaction`, and `check_allowlist_eligibility`.

## Following Up with GraphQL

The domain-specific tools above handle most use cases. For deeper data (sales history, aggregations, custom joins), use the GraphQL tools (`graphql_query`, `build_query`, `explore_table`) as an escape hatch.

## Pagination

```
# Page 1
discover_projects(tag: "ab500", sortBy: "floor_asc", limit: 25, offset: 0)

# Page 2
discover_projects(tag: "ab500", sortBy: "floor_asc", limit: 25, offset: 25)
```

---
name: configure-postparams
description: Configure PostParam (Post-Mint Parameter / PMP) values on Art Blocks tokens using artblocks-mcp. Use when a user wants to customize, update, or set on-chain parameters on a minted token, or when working with build_configure_postparams_transaction, discover_postparams, or post-mint configuration.
---

# Configuring PostParams on Art Blocks Tokens

## What Are PostParams?

PostParams (Post-Mint Parameters / PMP) are on-chain configurable parameters embedded in certain Art Blocks art scripts. After minting, authorized wallets can set values that directly affect the token's on-chain visual output — no re-mint required.

Each parameter has an `authOption` controlling who can configure it:

| `authOption` | Who can configure |
|---|---|
| `Artist` | Project artist only |
| `TokenOwner` | Current token owner only |
| `Address` | A specific configured contract address only |
| `ArtistAndTokenOwner` | Artist or token owner |
| `ArtistAndAddress` | Artist or specific contract address |
| `TokenOwnerAndAddress` | Token owner or specific contract address |
| `ArtistAndTokenOwnerAndAddress` | Artist, token owner, or specific contract address |

## Token ID Format

`<contract_address>-<token_number>`

Example: `0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270-78000000`

## Workflow

### Step 1 — Discover available params

```
discover_postparams(tokenId, chainId?)
```

Returns: param keys, types, value constraints, current values, and `authOption` for each param. Always show this to the user before asking for values — they need to know what's configurable and within what constraints.

### Step 2 — Build the configuration transaction

```
build_configure_postparams_transaction(tokenId, values, chainId?, signerAddress?)
```

- `values` is a key-value object — keys must match param keys from `discover_postparams`
- Always pass `signerAddress` when known — needed to determine artist status and validate authorization
- One transaction configures all passed params at once

Returns an unsigned transaction object ready to sign and submit.

## Value Formats by Type

| Type           | Format                              | Example           |
|----------------|-------------------------------------|-------------------|
| `Bool`         | `"true"` or `"false"`              | `"true"`          |
| `Select`       | One of the allowed option strings   | `"red"`           |
| `Uint256Range` | Non-negative integer string         | `"42"`            |
| `Int256Range`  | Integer string (can be negative)    | `"-5"`            |
| `DecimalRange` | Decimal string                      | `"3.14"`          |
| `HexColor`     | Hex color with `#`                  | `"#FF0000"`       |
| `Timestamp`    | Unix timestamp in seconds           | `"1700000000"`    |
| `String`       | Any text string                     | `"hello world"`   |

## Notes

- **Always call `discover_postparams` first** — param keys and types are project-specific and not guessable
- **`String` params**: the `configuringArtistString` flag on the built transaction depends on whether `signerAddress` matches the project artist — always pass `signerAddress` for `String` type params
- **Authorization**: if the user's address doesn't match the `authOption` for a param, the transaction will revert on-chain. Check `authOption` against the user's role before proceeding
- **One transaction per call**, but you can configure multiple params in a single call by passing multiple keys in `values`