#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
Testnet
Arbitrum One
- Note: Contract address is required
Arbitrum Testnet
- Note: Contract address is required
Base Mainnet
- Note: Contract address is required
#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
Testnet
Arbitrum One
- Note: Contract address is required
Arbitrum Testnet
- Note: Contract address is required
Base Mainnet
- Note: Contract address is required
#Media API/Media server
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
Base Mainnet
- 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 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.
As of June 12, 2024, Hosted Service subgraphs are deprecated. Please use the Decentralized Graph Network subgraphs listed below for all networks, or use the Art Blocks' Hasura GraphQL API as an alternative.
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
- 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
#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.
Note that only Engine contracts that have migrated to the shared minter suite will have their minters indexed and available on the subgraph and Hasura GraphQL API. Only globally approved minters are indexed, so custom, one-off minters designed by Engine partners will not be indexed.
A project's active minter configuration (as configured in the artist dashboard) may be queried by pulling it from the Project
entity:
note: if querying the Hasura GraphQL API, use
projects_metadata
instead ofproject
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:
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:
note: if querying the Hasura GraphQL API, use
minters_metadata
instead ofminters
, 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.
#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.
#GraphQL-based Authentication Flow (Recommended)
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:
#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:
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:
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