GraphQL Reference

Art Blocks GraphQL API and Subgraph — entities, relationships, and example queries.

The Art Blocks GraphQL API and Subgraph provide structured access to on-chain and off-chain data. This page covers the primary entities, their fields, and example queries for both the Hasura API and the Subgraph.

API Playground (Hasura): https://cloud.hasura.io/public/graphiql?endpoint=https://data.artblocks.io/v1/graphql

For AI-assisted querying, the Art Blocks MCP Server provides explore_table, build_query, and graphql_query tools that validate field names, handle chain filtering, and construct queries interactively.

Which API to Use

Hasura GraphQL API (data.artblocks.io) — recommended for most integrations. Provides on-chain + off-chain data including media URLs, minter configuration, descriptions, and project metadata. Uses _metadata table suffixes.

Subgraph (The Graph) — useful for on-chain-only data and integrations that require decentralized infrastructure. Uses camelCase field names.

Primary Entities

`projects_metadata`

Detailed information about Art Blocks projects, including on-chain and off-chain data.

Field	Type	Description
`id`	String!	`<contract_address>-<project_id>`
`project_id`	String	Project ID on the contract
`chain_id`	Int	Chain ID
`contract_address`	String	Core contract address
`name`	String	Project name
`artist_name`	String	Artist name
`artist_address`	String	Artist wallet address
`description`	String	Project description
`active`	Boolean!	Whether the project is publicly visible
`paused`	Boolean!	Whether purchases are paused
`complete`	Boolean!	Whether the project has reached max invocations
`completed_at`	timestamptz	When the project sold out
`activated_at`	timestamptz	When the project was activated
`invocations`	bigint!	Number of tokens minted
`max_invocations`	Int!	Maximum supply
`script`	String	Full project script
`script_type_and_version`	String	E.g. `p5js@1.0.0`
`aspect_ratio`	numeric	Artwork aspect ratio
`locked`	Boolean	Whether the script is permanently locked
`website`	String	Artist or project website
`license`	String	Project license
`lowest_listing`	float8	Current lowest secondary listing price
`vertical_name`	String	Category (curated, presents, studio, etc.)
`is_artblocks`	Boolean	Whether it's an Art Blocks flagship project
`slug`	String	URL slug
`render_delay`	Int	Seconds before static capture

Key relationships: contract, tokens, artist, minter_configuration, features, tags, vertical

`tokens_metadata`

Information about individual tokens.

Field	Type	Description
`id`	String!	`<contract_address>-<token_id>`
`token_id`	String	Token ID
`chain_id`	Int	Chain ID
`contract_address`	String	Core contract address
`project_id`	String	Associated project ID
`invocation`	Int	Invocation number within the project
`hash`	String	Token hash (used as PRNG seed)
`owner_address`	String	Current owner
`minted_at`	timestamptz	Mint timestamp
`features`	jsonb	Computed trait data
`live_view_url`	String	Generator URL for live artwork
`media_url`	String	Media proxy URL for static image
`primary_asset_url`	String	Primary asset URL
`preview_asset_url`	String	Thumbnail URL

Key relationships: contract, project, owner, image

`contracts_metadata`

Information about Art Blocks core contracts.

Field	Type	Description
`address`	String!	Contract address
`chain_id`	Int	Chain ID
`name`	String	Contract name
`core_version`	String	Core contract version
`admin`	String	Admin address
`minter_filter_address`	String	Associated minter filter
`dependency_registry_address`	String	Dependency registry address
`preferred_ipfs_gateway`	String	Preferred IPFS gateway (Flex)
`preferred_arweave_gateway`	String	Preferred Arweave gateway (Flex)

`project_minter_configurations`

Minting configuration for a project.

Field	Type	Description
`price_is_configured`	Boolean!	Whether price has been set
`currency_symbol`	String	Currency (ETH or ERC-20 symbol)
`base_price`	String	Price in wei
`max_invocations`	Int	Minter-level max invocations
`auction_start_time`	timestamptz	Auction start (for auction minters)
`auction_end_time`	timestamptz	Auction end (for auction minters)
`extra_minter_details`	jsonb	Minter-specific config (see below)

The extra_minter_details field is a JSONB object with minter-specific fields. For a Dutch Auction minter:

{
  "startTime": 1676052000,
  "halfLifeSeconds": 315,
  "approximateDAExpEndTime": 1676053820,
  "startPrice": "11000000000000000000",
  "currentSettledPrice": "557638888888888889",
  "auctionRevenuesCollected": true,
  "numSettleableInvocations": 172
}

Example Queries

Hasura API Examples

Always include chain_id in Hasura queries to scope to a specific network.

Get a project by ID on Ethereum:

{
  projects_metadata(
    where: {
      id: { _eq: "0x99a9b7c1116f9ceeb1652de04d5969cce509b069-385" }
      chain_id: { _eq: 1 }
    }
  ) {
    id
    name
    artist_name
    invocations
    max_invocations
  }
}

Get a token with project info:

{
  tokens_metadata(
    where: {
      id: { _eq: "0x99a9b7c1116f9ceeb1652de04d5969cce509b069-385000000" }
      chain_id: { _eq: 1 }
    }
  ) {
    id
    token_id
    hash
    owner_address
    live_view_url
    media_url
    features
    project {
      name
      artist_name
    }
  }
}

Get recently activated flagship projects on Ethereum:

{
  projects_metadata(
    where: { is_artblocks: { _eq: true }, chain_id: { _eq: 1 } }
    order_by: { activated_at: desc }
    limit: 5
  ) {
    id
    name
    artist_name
    invocations
    max_invocations
  }
}

Get minter configuration for a project:

{
  projects_metadata(
    where: {
      id: { _eq: "0x99a9b7c1116f9ceeb1652de04d5969cce509b069-385" }
      chain_id: { _eq: 1 }
    }
  ) {
    name
    minter_configuration {
      price_is_configured
      currency_symbol
      base_price
      extra_minter_details
      minter {
        address
        type {
          label
        }
      }
    }
  }
}

Subgraph Examples

The Subgraph uses camelCase field names and the base entity names (without _metadata suffix).

Get a project by short ID:

{
  projects(
    where: {
      projectId: "385"
      contract_in: ["0x99a9b7c1116f9ceeb1652de04d5969cce509b069"]
    }
  ) {
    id
    invocations
    artistName
    name
  }
}

Get the 5 most recently created projects:

{
  projects(first: 5, orderBy: createdAt, orderDirection: desc) {
    id
    name
    artistName
    invocations
    maxInvocations
  }
}

Get the top 10 projects by invocations:

{
  projects(first: 10, orderBy: invocations, orderDirection: desc) {
    id
    name
    artistName
    invocations
    maxInvocations
  }
}

Get all tokens owned by an address:

{
  tokens(where: { owner: "<owner-address>" }) {
    id
    tokenId
    project {
      name
      artistName
    }
  }
}

Get the script for a project:

{
  project(id: "0x059edd72cd353df5106d2b9cc5ab83a52287ac3a-0") {
    script
  }
}

Advanced GraphQL (MCP Tools)

The Art Blocks MCP Server includes six GraphQL tools for custom queries:

Tool	Purpose
`explore_table`	Inspect a table's fields, types, and relationships
`validate_fields`	Check whether specific fields exist on a table
`build_query`	Build a validated GraphQL query with WHERE filters
`query_optimizer`	Rewrite queries to use `*_metadata` tables
`graphql_query`	Execute a raw GraphQL query
`graphql_introspection`	Full schema introspection

Pagination

The Graph enforces limits: first <= 1000 and skip <= 5000. For large result sets, paginate using a cursor-style approach based on an attribute like token ID or block number rather than high skip values. See the Graph documentation for guidance.