# API Overview

An overview of the current Art Blocks APIs.

Quick Links:

• Token API
• Generator API
• Media API/Media Server
• Art Blocks Subgraph
• GraphQL API

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

Provides the token metadata for a given Art Blocks token.

Mainnet

• Note: Contract address is required for Engine

Testnet

Arbitrum One

• Note: Contract address is required

Arbitrum Testnet

• Note: Contract address is required

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

Testnet

Arbitrum One

• Note: Contract address is required

Arbitrum Testnet

• Note: Contract address is required

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

Mainnet

Testnet

Arbitrum One

• Note: Contract address is required

Arbitrum Testnet

• Note: Contract address is required

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 pefer, 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.

Mainnet (Engine)

We are working on a media server for Engine partners. Currently, media is accessible through individual s3 buckets.

Testnet

Art Blocks has a GraphQL API Endpoint hosted by The Graph called a subgraph for indexing and organizing data from the Art Blocks smart contracts.

This subgraph can be used to query for on-chain data related to the Art Blocks contracts, including minter suite data, token data, and project data.

Subgraph information is serviced by a decentralized group of server operators called Indexers.

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

• Video Tutorial on creating an API Key
• Managing your API Key & setting your indexer preferences
• Querying from an application
• How to use the explorer and playground to query on-chain data

The Art Blocks mainnet subgraph can currently be queried a few ways:

The Art Blocks testnet subgraph can be queried at the URL below:

The Art Blocks Arbitrum subgraphs can be queried at the URLs below:

Recommendation: Using the above links, familiarize yourself with the subgraph’s schema, via the GraphQL playground.

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's. The data are available on both the subgraph, and the Hasura GraphQL API.

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

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,
  };
}

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.

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 plaground to test out queries: https://cloud.hasura.io/public/graphiql?endpoint=https://data.artblocks.io/v1/graphql