Cardano GraphQL

Cross-platform, typed, and queryable API for Cardano. The project contains multiple packages for composing GraphQL services to meet specific application demands, and a docker compose stack serving the included cardano-graphql-server Dockerfile, the extended hasura Dockerfile, cardano-submit-api, cardano-node. The schema is defined in native .graphql, and used to generate a TypeScript package for client-side static typing. A mutation is available to submit a signed and serialized transaction to the local node.

Apollo Server exposes the NodeJS execution engine over a HTTP endpoint, and includes support for open source metrics via Prometheus, and implementing operation filtering to deny unexpected queries. Should you wish to have more control over the server, or stitch the schema with an existing service, consider importing the executable schema from the @cardano-graphql/api-* packages only.

GraphQL is a query language and execution environment with server and client implementations across many programming languages. The language can be serialized for network transmission, schema implementations hashed for assurance, and is suited for describing most domains.

TypeScript (and JS) has the largest pool of production-ready libraries, developers, and interoperability in the GraphQL and web ecosystem in general. TypeScript definitions for the schema, generated by GraphQL Code Generator, are available on npm.

cardano-submit-api is a lightweight HTTP service for submitting signed transactions to cardano-node.

Recommended system requirements for running the full stack:

Check the releases for the latest version.

git clone \
  --single-branch \
  --branch 9.0.0 \
  --recurse-submodules \
  https://github.com/cardano-foundation/cardano-graphql.git \
  && cd cardano-graphql

Choose one of the following:

Boot the docker compose stack using a convention for container and volume scoping based on the network, as well as optionally hitting the remote cache to speed up the build. The containers are detached, so you can terminate the log console session freely. See Docker Compose docs to tailor for your use-case

docker compose --env-file .env.docker-compose up -d --build

docker compose --env-file .env.docker-compose-preprod up -d --build

Pull images from Docker Hub and run using a convention for container and volume scoping based on the network. The containers are detached, so you can terminate the log console session freely. See Docker Compose docs to tailor for your use-case.

docker compose --env-file .env.docker-compose up -d

docker compose --env-file .env.docker-compose-preprod up -d

The following commands will not remove volumes, however should you wish to do so, append -v

docker compose --env-file .env.docker-compose down

docker compose --env-file .env.docker-compose-preprod down

Important: Cardano GraphQL now uses the Token Registry V2 API, providing CIP-68 support alongside existing CIP-26 metadata.

Query Priority: By default, metadata is queried with priority CIP-68 → CIP-26. This priority can be configured via environment variables.

The local Token Metadata Registry synchronization process can be disabled by removing the COMPOSE_PROFILES variable from the .env.docker-compose file.

The public Token Metadata Registry has a limit of daily requests, this can lead to long sync times, when resyncing from scratch. If it's still needed to run with the global environment it's possible by removing the token-metadata-registry from docker-compose.yml. And change the variable in .env.docker-compose for Mainnet:

METADATA_SERVER_URI="https://tokens.cardano.org" docker compose up -d

For Preprod .env.docker-compose-preprod (other networks):

METADATA_SERVER_URI="https://metadata.world.dev.cardano.org"

The index service creates database indexes to improve query performance. It is recommended for production — in particular, the idx_ma_tx_mint_ident index is required for efficient new asset polling. Without it, asset polling still works but can take several seconds per cycle on mainnet instead of under 1ms. Index creation runs concurrently with db-sync and does not block synchronization.

To enable, add indexes to COMPOSE_PROFILES in your .env file:

# .env.docker-compose or .env.docker-compose-preprod
COMPOSE_PROFILES=token-registry,indexes

Then start/restart the stack:

docker compose --env-file .env.docker-compose up -d

Monitor index creation progress:

docker compose logs -f index-service

ℹ️ Index creation can take several hours but significantly speeds up queries for transactions by address and asset lookups. See Index Service Documentation for details on created indexes, customization, and best practices.

Use the GraphQL Playground in the browser at http://localhost:3100/graphql:

Note This Query is not available in early Era's of Cardano.

{ cardanoDbMeta { initialized syncPercentage assetSyncPercentage }}

or via command line:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "{ cardanoDbMeta { initialized syncPercentage assetSyncPercentage }}"}' \
  http://localhost:3100/graphql

ℹ️ Wait for initialized to be true and assetSyncPercentage to reach 100 to ensure the full dataset including token metadata is complete. After the first sync you may need to restart the services using docker compose restart cardano-graphql if the GraphQL server isn't running.

{ cardano { tip { number slotNo epoch { number } } } }

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "{ cardano { tip { number slotNo epoch { number } } } }"}' http://localhost:3100/graphql

{ "data": { "cardano": { "tip": { "number": 4391749, "slotNo": 4393973, "epoch": { "number": 203 } } } } }

For more information, have a look at the Wiki 📖.

When upgrading to cf-token-metadata-registry-api >= 1.5.0, a full resync from genesis is recommended. If resyncing is not an option, existing deployments with a persistent database may encounter a Flyway migration checksum mismatch error, causing the token-metadata-registry container to crash-loop on startup:

Migration checksum mismatch for migration version X.Y.Z

This happens because the migration SQL file was modified in the new image version, but the old checksum is recorded in the database. Fix it by repairing the Flyway schema history:

docker exec cardano-graphql-postgres-1 sh -c '
  PGPASSWORD=$(cat /run/secrets/postgres_password) \
  psql -h $(hostname) -p 5433 \
       -U $(cat /run/secrets/postgres_user) \
       -d $(cat /run/secrets/postgres_db) \
       -c "UPDATE tokenregistry.flyway_schema_history SET checksum = <resolved_checksum> WHERE version = '"'"'<version>'"'"';"
'

The <resolved_checksum> and <version> values are printed in the container logs. Then restart the service:

docker compose --env-file .env.docker-compose restart token-metadata-registry

Fresh deployments (no existing database) are not affected.

See Using Docker.

See Building.