#API Overview

An overview of the current Art Blocks APIs.

Quick Links:

#Hosted APIs

As a quick overview, the main APIs that exist currently are:


#Token API

Provides the token metadata for a given Art Blocks token.

Mainnet

  • Note: Contract address is required for Engine
Contract TypePatternSample
Flagshiphttps://token.artblocks.io/{tokenID}https://token.artblocks.io/0
Enginehttps://token.artblocks.io/{contractAddress}/{tokenID}https://token.artblocks.io/0x0a1bbd57033f57e7b6743621b79fcb9eb2ce3676/110000

Testnet

Contract TypePatternSample
Flagshiphttps://token.staging.artblocks.io/{contractAddress}/{tokenID}https://token.staging.artblocks.io/0xda62f67be7194775a75be91cbf9feedcc5776d4b/103000000
Enginehttps://token.sepolia.artblocks.io/{contractAddress}/{tokenID}https://token.sepolia.artblocks.io/0x6ceab51fc8ee931df84d3db66e747b617eb7de21/12

Arbitrum One

  • Note: Contract address is required
Contract TypePattern
Enginehttps://token.arbitrum.artblocks.io/{contractAddress}/{tokenID}

Arbitrum Testnet

  • Note: Contract address is required
Contract TypePattern
Enginehttps://token.arbitrum-sepolia.artblocks.io/{contractAddress}/{tokenID}

Base Mainnet

  • Note: Contract address is required
Contract TypePattern
Enginehttps://token.base.artblocks.io/{contractAddress}/{tokenID}

#Generator API

Provides an i-frame-able live-view for the art associated with a given Art Blocks token.

Mainnet

  • Note: Contract address is required for Engine
Contract TypePatternSample
Flagshiphttps://generator.artblocks.io/{tokenID}https://generator.artblocks.io/0
Enginehttps://generator.artblocks.io/{contractAddress}/{tokenID}https://generator.artblocks.io/0x0a1bbd57033f57e7b6743621b79fcb9eb2ce3676/11000083

Testnet

Contract TypePatternSample
Flagshiphttps://generator-staging-sepolia.artblocks.io/{contractAddress}/{tokenID}https://generator-staging-goerli.artblocks.io/0xda62f67be7194775a75be91cbf9feedcc5776d4b/8000002
Enginehttps://generator-staging-sepolia.artblocks.io/{contractAddress}/{tokenID}https://generator-staging-goerli.artblocks.io/0xe745243b82ebc46e5c23d9b1b968612c65d45f3d/1000001

Arbitrum One

  • Note: Contract address is required
Contract TypePattern
Enginehttps://generator.arbitrum.artblocks.io/{contractAddress}/{tokenID}

Arbitrum Testnet

  • Note: Contract address is required
Contract TypePattern
Enginehttps://generator.arbitrum-sepolia.artblocks.io/{contractAddress}/{tokenID}

Base Mainnet

  • Note: Contract address is required
Contract TypePattern
Enginehttps://generator.base.artblocks.io/{contractAddress}/{tokenID}

#Media API/Media server

Provides a static snapshot of the rendered live-view for a given Art Blocks token.

Mainnet

Contract TypePatternSample
Flagshiphttps://media.artblocks.io/{tokenID}.pnghttps://media.artblocks.io/0.png
Enginehttps://media-proxy.artblocks.io/{contractAddress}/{tokenId}.pnghttps://media-proxy.artblocks.io/0x145789247973c5d612bf121e9e4eef84b63eb707/782.png

Testnet

Contract TypePatternSample
Flagshiphttps://media-proxy-staging.artblocks.io/{tokenID}.pnghttps://media-proxy-staging.artblocks.io/0.png
Enginehttps://media-proxy-staging.artblocks.io/{contractAddress}/{tokenID}.pnghttps://media-proxy-staging.artblocks.io/0xe745243b82ebc46e5c23d9b1b968612c65d45f3d/1000001

Arbitrum One

  • Note: Contract address is required
Contract TypePattern
Enginehttps://media-proxy-arbitrum.artblocks.io/{contractAddress}/{tokenID}

Arbitrum Testnet

  • Note: Contract address is required
Contract TypePattern
Enginehttps://media-proxy-arbitrum-staging.artblocks.io/{contractAddress}/{tokenID}

Base Mainnet

  • Note: Contract address is required
Contract TypePattern
Enginehttps://media-proxy-base.artblocks.io/{contractAddress}/{tokenID}

In addition to the standard static renders provided for each token, there are two other static renders currently provided: "HD" and "thumbnail". These items can be found at:

  • HD Renders – https://media.artblocks.io/hd/{tokenID}.png
  • Thumbnail Renders – https://media.artblocks.io/thumb/{tokenID}.png

Please note that these additional static render formats are still currently being back-filled and may not yet be present for all tokens. Our current recommendation for those looking to depend on the "HD" or "thumbnail" responses is to a) first attempt the HD/thumb image resource that you would prefer, b) if this resource is not available, fall back to the standard sized image resource. For the current state of the ongoing backfill of HD and thumbnail assets, please refer to this spreadsheet.

Please also note that the Generator API and Media API links for a given token are included in the token response for that token from the Token API.

#Art Blocks Subgraph

Art Blocks has subgraphs deployed to The Graph Network for every supported network.

These subgraphs can be used to query for on-chain data related to the Art Blocks contracts, including minter suite data, token data, and project data. They provide a way to access on-chain data in a more efficient and user-friendly way than directly querying the blockchain, while keeping infrastructure decentralized, transparent, and reliable.

The Art Blocks subgraph is developed in public, and all source code and development activity can be found in the Art Blocks subgraph repository.

#Ethereum Mainnet

  • Explorer Page
  • Graphql Endpoint: https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/6bR1oVsRUUs6czNiB6W7NNenTXtVfNd5iSiwvS4QbRPB

#Arbitrum One

  • Explorer Page
  • Graphql Endpoint: https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/5WwGsBwJ2hVBpc3DphX4VHVMsoPnRkVkuZF4HTArZjCm

#Artist Staging - Sepolia Testnet

  • Explorer Page
  • Graphql Endpoint: https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/9G5q5avz4X8GZ8UEGdu197433nSWSCsFa2eo6vHNBooc

#Artist Staging - Arbitrum-Sepolia Testnet

  • Explorer Page
  • Graphql Endpoint: https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/33E6obKFpWGUhnWD5eja74Gt6oTXktiHMZVFrshg9xGe

#Helpful Resources

#Querying the Subgraph

The Art Blocks subgraphs can be queried at any of the graphql endpoints listed in the previous section.

#Getting Minter Details

A few example queries are provided below to help you get started with querying the Art Blocks subgraph for data related to a project's minter. In addition to the subgraph, the fields are also able to be queried from our Hasura GraphQL API. In the future, Art Blocks will release an SDK that will interact with these data in an even more convenient way.

A project's active minter configuration (as configured in the artist dashboard) may be queried by pulling it from the Project entity:

query { project(id: "0x99a9b7c1116f9ceeb1652de04d5969cce509b069-404") { id minterConfiguration { id priceIsConfigured currencySymbol currencyAddress basePrice maxInvocations extraMinterDetails minter { id extraMinterDetails } } } }

note: if querying the Hasura GraphQL API, use projects_metadata instead of project

The extraMinterDetails json field of minterConfiguration will contain a JSON string that can be parsed to obtain the project-minter-configuration details that may be specific to the minter type. For example, for a Dutch Auction minter, the extraMinterDetails field may contain the following JSON string:

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

note: if querying the Hasura GraphQL API, the returned type will be a JSONB

Additionally, the minter's extraMinterDetails will contain a JSON string that can be parsed to obtain any minter-specific configuration details. For example, for a Dutch Auction minter, the extraMinterDetails field may contain the following JSON string:

{ "minimumHalfLifeInSeconds": 45, "maximumHalfLifeInSeconds": 3600 }

note: if querying the Hasura GraphQL API, use minters_metadata instead of minters, and the returned type will be a JSONB

All of these queries can help you to obtain information about a project's minter configuration, which can be used to display purchase information for the project on your website. The data are available on both the subgraph, and the Hasura GraphQL API.

#GraphQL API

Provides a broader set of the data that our front-end consumes — this includes both on-chain and off-chain data.

ChainEnvironmentURL
EthereumProductionhttps://data.artblocks.io/v1/graphql
EthereumStaginghttps://ab-staging-sepolia.hasura.app/v1/graphql
EthereumStaging (deprecated)https://ab-staging-goerli.hasura.app/v1/graphql
ArbitrumProductionhttps://ab-prod-arbitrum.hasura.app/v1/graphql
ArbitrumStaginghttps://ab-staging-arbitrum.hasura.app/v1/graphql
BaseMainnethttps://ab-prod-base.hasura.app/v1/graphql

#Authentication

The following documentation explains how to authenticate with the Art Blocks API to retrieve a JSON Web Token (JWT). This JWT can then be used to gain authenticated access to our GraphQL API. The methods explained here are intended for a client-side environment where a signer is available to sign messages. The procedures are explained using two approaches: Direct API endpoints and GraphQL.

We recommend using the GraphQL-based approach as we have more control over it and can ensure its stability even if underlying API endpoints change. Note that the domain for authentication may change in the future for the Direct API-based approach, while the GraphQL endpoint will remain the same.

The GraphQL-based approach leverages the GraphQL schema provided by Art Blocks. This is the recommended approach for stability and future-proofing your implementation.

Here are the functions used in this flow:

async function fetchMessageFromApiGql(userAddress) { const query = gql` query GetAuthMessage($publicAddress: String!, $domain: String!, $uri: String!) { getAuthMessage(publicAddress: $publicAddress, domain: $domain, uri: $uri) { authMessage } } `; const variables = { publicAddress: userAddress, domain: window.location.host, uri: window.location.origin, }; const result = await request(AB_GRAPHQL_ENDPOINT, query, variables); if (!result || !result.getAuthMessage) { throw new Error("Failed to fetch auth message"); } return result.getAuthMessage.authMessage; } async function getJwtGql(userAddress) { const message = await fetchMessageFromApiGql(userAddress); // Sign message here using the client-side signer const signature = /* code to sign message goes here */ const mutation = gql` mutation Authenticate($input: AuthenticateInput!) { authenticate(input: $input) { jwt expiration } } `; const variables = { input: { publicAddress: userAddress, message, signature } }; const result = await request(AB_GRAPHQL_ENDPOINT, mutation, variables); if (!result || !result.authenticate) { return null; } return { jwt: result.authenticate.jwt, expiration: result.authenticate.expiration, }; }
#Direct API-based Authentication Flow

The Direct API-based approach involves interacting with the https://artblocks.io/api/get-auth-message and https://artblocks.io/api/authenticate endpoints. We recommend using the GraphQL-based flow instead because of its improved stability and future-proofing, but we're providing the Direct API-based method for those who prefer it.

⚠️ Warning: The domain for authentication may change in the future for the Direct API-based approach. Using the GraphQL-based approach is recommended to avoid future disruptions.

Here are the functions used in this flow:

async function fetchMessageFromApi(userAddress) { const response = await fetch(AB_MESSAGE_API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ publicAddress: userAddress, domain: window.location.host, uri: window.location.origin, }), }); const result = await response.json(); if (!result.ok) { throw new Error(result.error); } return result.data.message; } async function getJwtApi(userAddress) { const message = await fetchMessageFromApi(userAddress); // Sign message here using the client-side signer const signature = /* code to sign message goes here */ const response = await fetch(`${AB_WEBSITE_BASE_URL}/api/authenticate`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ publicAddress: userAddress, signature, message }), }); const result = await response.json(); if (!result.ok) { return null; } return result.data.jwt; }

In both methods, you will find a placeholder /* code to sign message goes here */ where you should implement your code to sign the message using your client-side signer.

#Using the JWT for Authenticated Access

Once the JWT has been obtained using either of the above methods, it can be used to make authenticated requests to the Art Blocks GraphQL API. The JWT should be included in the Authorization header of the request. Here's an example:

// Assume jwt contains the JWT you received from the previous steps const jwt = "your-jwt-token"; // An example of a GraphQL request using the JWT const query = gql` query { // Your query here } `; const response = await fetch(AB_GRAPHQL_ENDPOINT, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${jwt}`, }, body: JSON.stringify({ query }), });

For a full detailed overview of this GraphQL API, please reference: https://docs.artblocks.io/public-api-docs/

Additionally, you can use this interactive Hasura playground to test out queries: https://cloud.hasura.io/public/graphiql?endpoint=https://data.artblocks.io/v1/graphql