Skip to main content

GraphQL API Reference

The Mina Rust node provides a comprehensive GraphQL API for querying blockchain data, account information, transaction status, and network statistics. The API is built using Juniper and is available at http://localhost:3000/graphql when running a node.

You can also use one of the nodes deployed by o1Labs. See the Infrastructure section for available nodes and connection details.

Quick Start

Testing the API

website/docs/developers/scripts/graphql-api/queries/query/basic-connectivity.graphql
{ __typename }
website/docs/developers/scripts/graphql-api/queries/query/sync-status.graphql
{ syncStatus }

Interactive Exploration

The node provides interactive GraphQL explorers:

API Endpoints

Query Endpoints

Network and Node Status

syncStatus

Get the current synchronization status of the node.

query {
syncStatus # Returns: CONNECTING | LISTENING | OFFLINE | BOOTSTRAP | SYNCED | CATCHUP
}
daemonStatus

Get comprehensive daemon status information.

website/docs/developers/scripts/graphql-api/queries/query/daemon-status.graphql
query {
daemonStatus {
blockchainLength
chainId
commitId
stateHash
numAccounts
globalSlotSinceGenesisBestTip
ledgerMerkleRoot
coinbaseReceiver
}
}
networkID

Get the network identifier.

website/docs/developers/scripts/graphql-api/queries/query/network-id.graphql
query {
networkID
}
version

Get the node version (git commit hash).

website/docs/developers/scripts/graphql-api/queries/query/version.graphql
query {
version
}

Blockchain Data

bestChain(maxLength: Int!)

Get the best chain blocks up to specified length.

website/docs/developers/scripts/graphql-api/queries/query/best-chain.graphql
query RecentBlocks {
bestChain(maxLength: 10) {
stateHash
protocolState {
consensusState {
blockHeight
slotSinceGenesis
}
previousStateHash
}
transactions {
userCommands {
id
fee
amount
memo
}
}
}
}
block(height: Int, stateHash: String)

Get a specific block by height or state hash.

website/docs/developers/scripts/graphql-api/queries/query/block.graphql
query GetLatestBlock {
bestChain(maxLength: 1) {
stateHash
protocolState {
consensusState {
blockHeight
}
}
creator
transactions {
userCommands {
amount
fee
from
to
}
}
}
}
genesisBlock

Get the genesis block.

website/docs/developers/scripts/graphql-api/queries/query/genesis-block.graphql
query {
genesisBlock {
stateHash
protocolState {
consensusState {
blockHeight
}
}
}
}
genesisConstants

Get genesis constants and network parameters.

website/docs/developers/scripts/graphql-api/queries/query/genesis-constants.graphql
query {
genesisConstants {
accountCreationFee
genesisTimestamp
coinbase
}
}

Account Information

account(publicKey: String!, token: String)

Get account information by public key.

website/docs/developers/scripts/graphql-api/queries/query/account.graphql
query GetAccount($publicKey: String!) {
account(publicKey: $publicKey) {
balance {
total
liquid
locked
}
nonce
delegateAccount {
publicKey
}
votingFor
receiptChainHash
publicKey
token
tokenSymbol
zkappUri
zkappState
permissions {
editState
send
receive
access
setDelegate
setPermissions
setVerificationKey {
auth
txnVersion
}
setZkappUri
editActionState
setTokenSymbol
incrementNonce
setVotingFor
}
}
}

Transaction Pool

pooledUserCommands(publicKey: String, hashes: [String], ids: [String])

Get pending user commands (payments/delegations) from the transaction pool.

website/docs/developers/scripts/graphql-api/queries/query/pooled-user-commands.graphql
query PooledUserCommands($publicKey: String) {
pooledUserCommands(publicKey: $publicKey) {
id
amount
fee
from
to
nonce
memo
isDelegation
hash
kind
}
}
pooledZkappCommands(publicKey: String, hashes: [String], ids: [String])

Get pending zkApp commands from the transaction pool.

website/docs/developers/scripts/graphql-api/queries/query/pooled-zkapp-commands.graphql
query PooledZkApps($publicKey: String) {
pooledZkappCommands(publicKey: $publicKey) {
id
hash
zkappCommand {
feePayer {
body {
publicKey
fee
nonce
}
}
accountUpdates {
body {
publicKey
balanceChange {
magnitude
sgn
}
}
}
}
}
}

Transaction Status

transactionStatus(payment: String, zkappTransaction: String)

Get the status of a specific transaction.

website/docs/developers/scripts/graphql-api/queries/examples/transaction-status.graphql
query TransactionStatus($payment: String!) {
transactionStatus(payment: $payment)
}

SNARK Work

snarkPool

Get completed SNARK work from the pool.

website/docs/developers/scripts/graphql-api/queries/query/snark-pool.graphql
query SnarkPool {
snarkPool {
fee
prover
}
}
pendingSnarkWork

Get pending SNARK work that needs to be completed.

website/docs/developers/scripts/graphql-api/queries/query/pending-snark-work.graphql
query PendingSnarkWork {
pendingSnarkWork {
workBundle {
sourceFirstPassLedgerHash
targetFirstPassLedgerHash
sourceSecondPassLedgerHash
targetSecondPassLedgerHash
workId
}
}
}
currentSnarkWorker

Get information about the currently configured SNARK worker.

website/docs/developers/scripts/graphql-api/queries/query/current-snark-worker.graphql
query CurrentSnarkWorker {
currentSnarkWorker {
key
fee
account {
publicKey
balance {
total
}
}
}
}

Mutation Endpoints

Transaction Submission

sendPayment

Submit a payment transaction.

website/docs/developers/scripts/graphql-api/mutations/query/send-payment.graphql
mutation SendPayment(
$input: SendPaymentInput!
$signature: UserCommandSignature!
) {
sendPayment(input: $input, signature: $signature) {
payment {
id
hash
amount
fee
from
to
}
}
}
sendDelegation

Submit a delegation transaction.

website/docs/developers/scripts/graphql-api/mutations/query/send-delegation.graphql
mutation SendDelegation(
$input: SendDelegationInput!
$signature: UserCommandSignature!
) {
sendDelegation(input: $input, signature: $signature) {
delegation {
id
hash
delegator
delegate
fee
}
}
}
sendZkapp

Submit a zkApp transaction.

website/docs/developers/scripts/graphql-api/mutations/query/send-zkapp.graphql
mutation SendZkApp($input: SendZkAppInput!) {
sendZkapp(input: $input) {
zkapp {
id
hash
zkappCommand {
feePayer {
body {
publicKey
fee
}
}
}
}
}
}

Implementation Details

The GraphQL API is implemented in the following source files:

Core Implementation

Type Implementations

Common Patterns

Error Handling

All GraphQL queries return either successful data or structured errors:

{
"data": null,
"errors": [
{
"message": "Could not find block with height: `999999` in transition frontier",
"locations": [{ "line": 2, "column": 3 }]
}
]
}

Pagination and Limits

Many queries accept maxLength or similar parameters:

query {
bestChain(maxLength: 100) # Get up to 100 recent blocks
}

Optional Parameters

Most queries accept optional parameters for filtering:

query {
# Get all pooled commands
pooledUserCommands

# Get commands from specific sender
pooledUserCommands(publicKey: "B62q...")

# Get specific commands by hash
pooledUserCommands(hashes: ["5Jt8..."])
}

Example Queries

Get Node Information

website/docs/developers/scripts/graphql-api/queries/query/node-info.graphql
query NodeInfo {
networkID
version
daemonStatus {
blockchainLength
chainId
}
}

Get Recent Blockchain Activity

website/docs/developers/scripts/graphql-api/queries/query/recent-activity.graphql
query RecentActivity {
bestChain(maxLength: 5) {
stateHash
protocolState {
consensusState {
blockHeight
}
}
transactions {
userCommands {
amount
fee
from
to
}
}
}
}

Check Account Balance

website/docs/developers/scripts/graphql-api/queries/query/account-balance.graphql
query GetBalance($publicKey: String!) {
account(publicKey: $publicKey) {
balance {
total
liquid
locked
}
nonce
delegateAccount {
publicKey
}
}
}

Development and Testing

CLI Introspection Tools

The Mina CLI provides built-in commands to explore and inspect the GraphQL API. These tools work with both Rust and OCaml Mina nodes, allowing you to discover and inspect endpoints regardless of the node implementation.

List All Endpoints

Discover all available GraphQL query and mutation endpoints by querying the server's introspection API:

website/docs/developers/scripts/cli/graphql-list.sh
# shellcheck shell=bash
mina internal graphql list

This command dynamically queries the GraphQL server and displays:

  • All query endpoints (alphabetically sorted)
  • All mutation endpoints (alphabetically sorted)
  • Endpoint descriptions from the schema
  • Argument names and types for each endpoint
  • Usage hints for the inspect command

To query a remote node, use the --node flag:

mina internal graphql list --node http://remote-node:3000/graphql

Inspect Endpoint Schema

Get detailed schema information for a specific endpoint:

website/docs/developers/scripts/cli/graphql-inspect.sh
# shellcheck shell=bash
mina internal graphql inspect syncStatus

This displays:

  • Endpoint description
  • Required and optional arguments with types
  • Return type and structure
  • Example GraphQL query
  • Curl command for testing
  • Live example response from your node (if running)

To inspect an endpoint on a remote node:

website/docs/developers/scripts/cli/graphql-inspect-remote.sh
# shellcheck shell=bash
mina internal graphql inspect syncStatus --node http://mina-rust-plain-3.gcp.o1test.net/graphql

Run GraphQL Queries

Execute arbitrary GraphQL queries directly from the CLI:

Simple query
website/docs/developers/scripts/cli/graphql-run-simple.sh
# shellcheck shell=bash
# Execute a simple GraphQL query
mina internal graphql run 'query { syncStatus }'

This executes the query and returns the formatted JSON response.

Query from stdin
website/docs/developers/scripts/cli/graphql-run-stdin.sh
# shellcheck shell=bash
# Execute a GraphQL query from stdin
echo 'query { version }' | mina internal graphql run

Useful for piping queries from other commands or scripts.

Query from file
website/docs/developers/scripts/cli/graphql-run-file.sh
# shellcheck shell=bash
# Execute a GraphQL query from a file
mina internal graphql run -f query.graphql

Convenient for complex queries stored in .graphql files.

Query with variables
website/docs/developers/scripts/cli/graphql-run-variables.sh
# shellcheck shell=bash
# Execute a GraphQL query with variables
# shellcheck disable=SC2016
mina internal graphql run \
'query($maxLen: Int!) { bestChain(maxLength: $maxLen) { stateHash } }' \
-v '{"maxLen": 5}'

Variables must be provided as a JSON object. This allows parameterized queries for dynamic values.

Query remote node
website/docs/developers/scripts/cli/graphql-run-remote.sh
# shellcheck shell=bash
# Execute a GraphQL query on a remote node
mina internal graphql run \
'query { syncStatus }' \
--node http://mina-rust-plain-3.gcp.o1test.net/graphql

The run command supports three input methods:

  • Command line argument: Pass the query directly as an argument
  • Standard input: Pipe or redirect queries from stdin
  • File input: Use -f flag to read from a .graphql file

You can combine any input method with:

  • -v or --variables: Pass variables as JSON string
  • --node: Specify a custom GraphQL endpoint URL

These tools are particularly useful for:

  • Learning available endpoints without reading documentation
  • Generating curl commands for API testing
  • Verifying endpoint signatures and return types
  • Quickly prototyping GraphQL queries

Using with OCaml Nodes

The CLI introspection tools work seamlessly with OCaml Mina nodes. You can use o1Labs' devnet OCaml nodes to explore the GraphQL API:

# List all endpoints on an OCaml node
mina internal graphql list --node https://devnet-plain-1.gcp.o1test.net/graphql

# Inspect a specific endpoint
mina internal graphql inspect daemonStatus --node https://devnet-plain-1.gcp.o1test.net/graphql

# Run a query against an OCaml node
mina internal graphql run 'query { syncStatus }' --node https://devnet-plain-1.gcp.o1test.net/graphql

This is useful for:

  • Comparing GraphQL schemas between Rust and OCaml implementations
  • Testing cross-compatibility of queries
  • Validating that your queries work with both node types
  • Exploring OCaml-specific endpoints or differences in implementations
OCaml-specific endpoints

Some endpoints are only available in OCaml nodes. For example, the protocolState endpoint provides detailed protocol state information:

website/docs/developers/scripts/cli/graphql-inspect-ocaml-protocolstate.sh
# shellcheck shell=bash
# Inspect OCaml-specific protocolState endpoint
mina internal graphql inspect protocolState --node https://devnet-plain-1.gcp.o1test.net/graphql

You can query this endpoint directly:

website/docs/developers/scripts/cli/graphql-run-ocaml-protocolstate.sh
# shellcheck shell=bash
# Execute a query against OCaml-specific protocolState endpoint
mina internal graphql run 'query { protocolState }' --node https://devnet-plain-1.gcp.o1test.net/graphql

These OCaml-specific endpoints are useful for understanding implementation differences and ensuring compatibility when migrating from OCaml to Rust nodes.

Schema Introspection

Get the complete schema information:

query IntrospectionQuery {
__schema {
queryType {
fields {
name
description
args {
name
type {
name
}
}
type {
name
}
}
}
mutationType {
fields {
name
description
}
}
}
}

Rate Limiting and Performance

The GraphQL API shares the same resources as the node's internal operations. Consider:

  • Complex queries: Deep nested queries may impact performance
  • Large result sets: Use appropriate maxLength parameters
  • Concurrent requests: The API handles concurrent requests but intensive queries may affect node performance

Implementation Status Comparison

This table tracks the implementation status of GraphQL endpoints in the Mina Rust node compared to the OCaml node. For more details, see the tracking issue #1039.

Query Endpoints Status

EndpointDescriptionPriorityRust StatusNotes
Core Queries
daemonStatusGet running daemon statusHIGH✅ ImplementedFull daemon status with network info
accountFind account via public key and tokenHIGH✅ ImplementedAccount balance, nonce, delegate
blockRetrieve block by hash or heightHIGH✅ ImplementedFull block with transactions
pooledUserCommandsUser commands in transaction poolHIGH✅ ImplementedPayments and delegations
pooledZkappCommandszkApp commands in transaction poolHIGH✅ ImplementedSmart contract transactions
transactionStatusGet transaction statusHIGH✅ ImplementedPENDING, INCLUDED, or UNKNOWN
networkIDChain-agnostic network identifierHIGH✅ ImplementedReturns mina:<network_name>
Blockchain Info
syncStatusNetwork sync status-✅ ImplementedSync state tracking
versionNode version (git commit hash)-✅ ImplementedBuild information
bestChainBlocks from root to best tip-✅ ImplementedOrdered chain of blocks
genesisBlockGet the genesis block-✅ ImplementedInitial block data
genesisConstantsGenesis configuration-✅ ImplementedNetwork parameters
SNARK Pool
snarkPoolCompleted SNARK works-✅ ImplementedProofs with fees
pendingSnarkWorkSNARK work to be done-✅ ImplementedAvailable work items
currentSnarkWorkerCurrent SNARK worker info-✅ ImplementedWorker configuration
Not Yet Implemented
accountsAll accounts for a public key-❌ Not ImplementedMultiple account support
tokenAccountsAll accounts for a token ID-❌ Not ImplementedToken-specific queries
tokenOwnerAccount that owns a token-❌ Not ImplementedToken ownership
trackedAccountsAccounts with tracked private keys-❌ Not ImplementedWallet management
getPeersConnected peers list-⚠️ PartialOnly via daemonStatus
initialPeersInitial connection peers-❌ Not ImplementedBootstrap peers
trustStatusTrust status for IP-❌ Not ImplementedPeer trust management
trustStatusAllAll peers trust status-❌ Not ImplementedNetwork trust state
validatePaymentValidate payment format-❌ Not ImplementedTransaction validation
runtimeConfigRuntime configuration-❌ Not ImplementedNode configuration
fork_configBlockchain fork config-❌ Not ImplementedFork parameters
evaluateVrfEvaluate VRF for public key-❌ Not ImplementedVRF operations
checkVrfCheck VRF evaluation-❌ Not ImplementedVRF verification
blockchainVerificationKeyProtocol state proof key-❌ Not ImplementedVerification keys
signatureKindSignature type in use-❌ Not ImplementedCryptography info
timeOffsetBlockchain time offset-❌ Not ImplementedTime synchronization
connectionGatingConfigConnection rules-❌ Not ImplementedNetwork policies
threadGraphInternal thread graph-❌ Not ImplementedDebugging tool
getFilteredLogEntriesStructured log events-❌ Not ImplementedTesting/debugging

Mutation Endpoints Status

EndpointDescriptionPriorityRust StatusNotes
Core Mutations
sendPaymentSend a paymentHIGH✅ ImplementedFull payment submission
sendDelegationChange delegationHIGH✅ ImplementedStake delegation
sendZkappSend zkApp transactionHIGH✅ ImplementedSmart contracts
Not Yet Implemented
createAccountCreate new account-❌ Not ImplementedAccount creation
createHDAccountCreate HD account-❌ Not ImplementedHD wallet support
unlockAccountUnlock account-❌ Not ImplementedEnable transactions
lockAccountLock account-❌ Not ImplementedDisable transactions
deleteAccountDelete private key-❌ Not ImplementedKey management
reloadAccountsReload account info-❌ Not ImplementedAccount refresh
importAccountImport from file-❌ Not ImplementedAccount import
mockZkappMock zkApp (testing)-❌ Not ImplementedTesting tool
sendTestPaymentsTest payment series-❌ Not ImplementedTesting tool
sendRosettaTransactionRosetta format tx-❌ Not ImplementedRosetta API
exportLogsExport daemon logs-❌ Not ImplementedLog management
setCoinbaseReceiverSet coinbase key-❌ Not ImplementedBlock production
setSnarkWorkerConfigure SNARK worker-❌ Not ImplementedSNARK configuration
setSnarkWorkFeeSet SNARK work fee-❌ Not ImplementedFee configuration
setConnectionGatingConfigSet connection rules-❌ Not ImplementedNetwork policies
addPeersConnect to peers-❌ Not ImplementedPeer management
archivePrecomputedBlockArchive precomputed-❌ Not ImplementedArchive operations
archiveExtensionalBlockArchive extensional-❌ Not ImplementedArchive operations

Subscription Endpoints Status

EndpointDescriptionRust StatusNotes
newSyncUpdateSync status changes❌ Not ImplementedUses EmptySubscription
newBlockNew block events❌ Not ImplementedUses EmptySubscription
chainReorganizationBest tip changes❌ Not ImplementedUses EmptySubscription

Implementation Summary

  • Total endpoints in OCaml node: ~61 (excluding deprecated)
  • Implemented in Rust: 18 endpoints
  • Partially implemented: 1 endpoint
  • Not implemented: ~37 endpoints
  • Deprecated (skipped): 8 endpoints

All HIGH priority endpoints required for basic node operation are fully implemented. The Rust implementation focuses on core functionality needed for:

  • Blockchain synchronization
  • Account queries
  • Transaction submission (payments, delegations, zkApps)
  • SNARK work coordination
  • Network status monitoring

Next Steps