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

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/test-basic-connectivity.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/basic-connectivity.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/sync-status.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/sync-status.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

Interactive Exploration

The node provides interactive GraphQL explorers:

GraphQL Playground: http://localhost:3000/playground
GraphiQL: http://localhost:3000/graphiql

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.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/daemon-status.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/daemon-status.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`networkID`

Get the network identifier.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/network-id.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/network-id.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`version`

Get the node version (git commit hash).

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/version.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/version.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

Blockchain Data

`bestChain(maxLength: Int!)`

Get the best chain blocks up to specified length.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/best-chain.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/best-chain.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`block(height: Int, stateHash: String)`

Get a specific block by height or state hash.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/block.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/block.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`genesisBlock`

Get the genesis block.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/genesis-block.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/genesis-block.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`genesisConstants`

Get genesis constants and network parameters.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/genesis-constants.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/genesis-constants.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

Account Information

`account(publicKey: String!, token: String)`

Get account information by public key.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/account.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/account.graphql")
VARIABLES='{"publicKey": "B62qp3B9VW1ir5qL1MWRwr6ecjC2NZbGr8vysGeme9vXGcFXTMNXb2t"}'
JSON_PAYLOAD=$(echo '{}' | jq --arg query "$QUERY" --argjson variables "$VARIABLES" '.query = $query | .variables = $variables')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

Transaction Pool

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

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

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/pooled-user-commands.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/pooled-user-commands.graphql")
VARIABLES='{"publicKey": "B62qmGtQ7kn6zbw4tAYomBJJri1gZSThfQZJaMG6eR3tyNP3RiCcEQZ"}'
JSON_PAYLOAD=$(echo '{}' | jq --arg query "$QUERY" --argjson variables "$VARIABLES" '.query = $query | .variables = $variables')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`pooledZkappCommands(publicKey: String, hashes: [String], ids: [String])`

Get pending zkApp commands from the transaction pool.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/pooled-zkapp-commands.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/pooled-zkapp-commands.graphql")
VARIABLES='{"publicKey": "B62qmZB4E4KhmpYwoPDHe5c4yeQeAreCEwwgkGUrqSa6Ma3uC2RDZRY"}'
JSON_PAYLOAD=$(echo '{}' | jq --arg query "$QUERY" --argjson variables "$VARIABLES" '.query = $query | .variables = $variables')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

Transaction Status

`transactionStatus(payment: String, zkappTransaction: String)`

Get the status of a specific transaction.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/examples/transaction-status.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
QUERY=$(tr '\n' ' ' < "$SCRIPT_DIR/../query/transaction-status.graphql" | sed 's/  */ /g')
curl -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "{\"query\": \"$QUERY\", \"variables\": {\"payment\": \"5Ju2GQkUHy8iMXaeJDbDCyaV8fR1in3ewuM82Rq4z3sdqNrKkzgp\"}}"

SNARK Work

`snarkPool`

Get completed SNARK work from the pool.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/snark-pool.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/snark-pool.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`pendingSnarkWork`

Get pending SNARK work that needs to be completed.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/pending-snark-work.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/pending-snark-work.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`currentSnarkWorker`

Get information about the currently configured SNARK worker.

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/current-snark-worker.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/current-snark-worker.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

Mutation Endpoints

Transaction Submission

`sendPayment`

Submit a payment transaction.

GraphQL Mutation
Curl Command

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

website/docs/developers/scripts/graphql-api/mutations/curl/send-payment.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
# WARNING: This mutation modifies the blockchain state
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/send-payment.graphql")

# Example variables - replace with actual values
VARIABLES='{
  "input": {
    "from": "B62qmGtQ7kn6zbw4tAYomBJJri1gZSThfQZJaMG6eR3tyNP3RiCcEQZ",
    "to": "B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtB5sNVpxyRwWGcDEhpMzc8g",
    "amount": "1000000000",
    "fee": "10000000",
    "memo": "Test payment"
  },
  "signature": {
    "field": "...",
    "scalar": "..."
  }
}'

JSON_PAYLOAD=$(echo '{}' | jq --arg query "$QUERY" --argjson variables "$VARIABLES" '.query = $query | .variables = $variables')
curl -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

`sendDelegation`

Submit a delegation transaction.

GraphQL Mutation
Curl Command

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

website/docs/developers/scripts/graphql-api/mutations/curl/send-delegation.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
# WARNING: This mutation modifies the blockchain state
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
QUERY=$(tr '\n' ' ' < "$SCRIPT_DIR/../query/send-delegation.graphql" | sed 's/  */ /g')

# Example variables - replace with actual values
VARIABLES='{
  "input": {
    "from": "B62qmGtQ7kn6zbw4tAYomBJJri1gZSThfQZJaMG6eR3tyNP3RiCcEQZ",
    "to": "B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtB5sNVpxyRwWGcDEhpMzc8g",
    "fee": "10000000",
    "memo": "Test delegation"
  },
  "signature": {
    "field": "...",
    "scalar": "..."
  }
}'

curl -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "{\"query\": \"$QUERY\", \"variables\": $VARIABLES}"

`sendZkapp`

Submit a zkApp transaction.

GraphQL Mutation
Curl Command

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

website/docs/developers/scripts/graphql-api/mutations/curl/send-zkapp.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
# WARNING: This mutation modifies the blockchain state
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
QUERY=$(tr '\n' ' ' < "$SCRIPT_DIR/../query/send-zkapp.graphql" | sed 's/  */ /g')

# Example variables - replace with actual zkApp transaction data
VARIABLES='{
  "input": {
    "zkappCommand": {
      "feePayer": {
        "body": {
          "publicKey": "B62qmGtQ7kn6zbw4tAYomBJJri1gZSThfQZJaMG6eR3tyNP3RiCcEQZ",
          "fee": "10000000",
          "validUntil": null,
          "nonce": 0
        },
        "authorization": "..."
      },
      "accountUpdates": [],
      "memo": "zkApp transaction"
    }
  }
}'

curl -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "{\"query\": \"$QUERY\", \"variables\": $VARIABLES}"

Implementation Details

The GraphQL API is implemented in the following source files:

Core Implementation

Main module: node/native/src/graphql/mod.rs - Root GraphQL schema and query/mutation implementations
HTTP routing: node/native/src/http_server.rs - HTTP server setup and GraphQL endpoint routing

Type Implementations

Account types: node/native/src/graphql/account.rs - Account queries and balance information
Block types: node/native/src/graphql/block.rs - Block queries and blockchain data
Transaction types: node/native/src/graphql/transaction.rs - Transaction status and submission
User commands: node/native/src/graphql/user_command.rs - Payments and delegations
zkApp types: node/native/src/graphql/zkapp.rs - zkApp transactions and smart contracts
SNARK types: node/native/src/graphql/snark.rs - SNARK work and proof data
Constants: node/native/src/graphql/constants.rs - Network constants and genesis parameters

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

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/node-info.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/node-info.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

Get Recent Blockchain Activity

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/recent-activity.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/recent-activity.graphql")
JSON_PAYLOAD=$(echo "{}" | jq --arg query "$QUERY" '.query = $query')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

Check Account Balance

GraphQL Query
Curl Command

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

website/docs/developers/scripts/graphql-api/queries/curl/account-balance.sh
#!/bin/bash
# Usage: $0 [GRAPHQL_ENDPOINT]
# GRAPHQL_ENDPOINT: GraphQL endpoint URL (default: http://mina-rust-plain-1.gcp.o1test.net/graphql)

GRAPHQL_ENDPOINT="${1:-http://mina-rust-plain-1.gcp.o1test.net/graphql}"

# Replace with your own node endpoint: http://localhost:3000/graphql
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Read the query and create JSON payload using jq for proper escaping
QUERY=$(< "$SCRIPT_DIR/../query/account-balance.graphql")
VARIABLES='{ "publicKey": "B62qp3B9VW1ir5qL1MWRwr6ecjC2NZbGr8vysGeme9vXGcFXTMNXb2t" }'
JSON_PAYLOAD=$(echo '{}' | jq --arg query "$QUERY" --argjson variables "$VARIABLES" '.query = $query | .variables = $variables')
curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$JSON_PAYLOAD"

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

Endpoint	Description	Priority	Rust Status	Notes
Core Queries
`daemonStatus`	Get running daemon status	HIGH	✅ Implemented	Full daemon status with network info
`account`	Find account via public key and token	HIGH	✅ Implemented	Account balance, nonce, delegate
`block`	Retrieve block by hash or height	HIGH	✅ Implemented	Full block with transactions
`pooledUserCommands`	User commands in transaction pool	HIGH	✅ Implemented	Payments and delegations
`pooledZkappCommands`	zkApp commands in transaction pool	HIGH	✅ Implemented	Smart contract transactions
`transactionStatus`	Get transaction status	HIGH	✅ Implemented	PENDING, INCLUDED, or UNKNOWN
`networkID`	Chain-agnostic network identifier	HIGH	✅ Implemented	Returns `mina:<network_name>`
Blockchain Info
`syncStatus`	Network sync status	-	✅ Implemented	Sync state tracking
`version`	Node version (git commit hash)	-	✅ Implemented	Build information
`bestChain`	Blocks from root to best tip	-	✅ Implemented	Ordered chain of blocks
`genesisBlock`	Get the genesis block	-	✅ Implemented	Initial block data
`genesisConstants`	Genesis configuration	-	✅ Implemented	Network parameters
SNARK Pool
`snarkPool`	Completed SNARK works	-	✅ Implemented	Proofs with fees
`pendingSnarkWork`	SNARK work to be done	-	✅ Implemented	Available work items
`currentSnarkWorker`	Current SNARK worker info	-	✅ Implemented	Worker configuration
Not Yet Implemented
`accounts`	All accounts for a public key	-	❌ Not Implemented	Multiple account support
`tokenAccounts`	All accounts for a token ID	-	❌ Not Implemented	Token-specific queries
`tokenOwner`	Account that owns a token	-	❌ Not Implemented	Token ownership
`trackedAccounts`	Accounts with tracked private keys	-	❌ Not Implemented	Wallet management
`getPeers`	Connected peers list	-	⚠️ Partial	Only via daemonStatus
`initialPeers`	Initial connection peers	-	❌ Not Implemented	Bootstrap peers
`trustStatus`	Trust status for IP	-	❌ Not Implemented	Peer trust management
`trustStatusAll`	All peers trust status	-	❌ Not Implemented	Network trust state
`validatePayment`	Validate payment format	-	❌ Not Implemented	Transaction validation
`runtimeConfig`	Runtime configuration	-	❌ Not Implemented	Node configuration
`fork_config`	Blockchain fork config	-	❌ Not Implemented	Fork parameters
`evaluateVrf`	Evaluate VRF for public key	-	❌ Not Implemented	VRF operations
`checkVrf`	Check VRF evaluation	-	❌ Not Implemented	VRF verification
`blockchainVerificationKey`	Protocol state proof key	-	❌ Not Implemented	Verification keys
`signatureKind`	Signature type in use	-	❌ Not Implemented	Cryptography info
`timeOffset`	Blockchain time offset	-	❌ Not Implemented	Time synchronization
`connectionGatingConfig`	Connection rules	-	❌ Not Implemented	Network policies
`threadGraph`	Internal thread graph	-	❌ Not Implemented	Debugging tool
`getFilteredLogEntries`	Structured log events	-	❌ Not Implemented	Testing/debugging

Mutation Endpoints Status

Endpoint	Description	Priority	Rust Status	Notes
Core Mutations
`sendPayment`	Send a payment	HIGH	✅ Implemented	Full payment submission
`sendDelegation`	Change delegation	HIGH	✅ Implemented	Stake delegation
`sendZkapp`	Send zkApp transaction	HIGH	✅ Implemented	Smart contracts
Not Yet Implemented
`createAccount`	Create new account	-	❌ Not Implemented	Account creation
`createHDAccount`	Create HD account	-	❌ Not Implemented	HD wallet support
`unlockAccount`	Unlock account	-	❌ Not Implemented	Enable transactions
`lockAccount`	Lock account	-	❌ Not Implemented	Disable transactions
`deleteAccount`	Delete private key	-	❌ Not Implemented	Key management
`reloadAccounts`	Reload account info	-	❌ Not Implemented	Account refresh
`importAccount`	Import from file	-	❌ Not Implemented	Account import
`mockZkapp`	Mock zkApp (testing)	-	❌ Not Implemented	Testing tool
`sendTestPayments`	Test payment series	-	❌ Not Implemented	Testing tool
`sendRosettaTransaction`	Rosetta format tx	-	❌ Not Implemented	Rosetta API
`exportLogs`	Export daemon logs	-	❌ Not Implemented	Log management
`setCoinbaseReceiver`	Set coinbase key	-	❌ Not Implemented	Block production
`setSnarkWorker`	Configure SNARK worker	-	❌ Not Implemented	SNARK configuration
`setSnarkWorkFee`	Set SNARK work fee	-	❌ Not Implemented	Fee configuration
`setConnectionGatingConfig`	Set connection rules	-	❌ Not Implemented	Network policies
`addPeers`	Connect to peers	-	❌ Not Implemented	Peer management
`archivePrecomputedBlock`	Archive precomputed	-	❌ Not Implemented	Archive operations
`archiveExtensionalBlock`	Archive extensional	-	❌ Not Implemented	Archive operations

Subscription Endpoints Status

Endpoint	Description	Rust Status	Notes
`newSyncUpdate`	Sync status changes	❌ Not Implemented	Uses EmptySubscription
`newBlock`	New block events	❌ Not Implemented	Uses EmptySubscription
`chainReorganization`	Best tip changes	❌ Not Implemented	Uses 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

Node Architecture - Understanding the node's internal structure
Archive Database Queries - SQL queries and database analysis
Network Configuration - Configuring your node for different networks

Quick Start​

Testing the API​

Interactive Exploration​

API Endpoints​

Query Endpoints​

Network and Node Status​

syncStatus​

daemonStatus​

networkID​

version​

Blockchain Data​

bestChain(maxLength: Int!)​

block(height: Int, stateHash: String)​

genesisBlock​

genesisConstants​

Account Information​

account(publicKey: String!, token: String)​

Transaction Pool​

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

pooledZkappCommands(publicKey: String, hashes: [String], ids: [String])​

Transaction Status​

transactionStatus(payment: String, zkappTransaction: String)​

SNARK Work​

snarkPool​

pendingSnarkWork​

currentSnarkWorker​

Mutation Endpoints​

Transaction Submission​

sendPayment​

sendDelegation​

sendZkapp​

Implementation Details​

Core Implementation​

Type Implementations​

Common Patterns​

Error Handling​

Pagination and Limits​

Optional Parameters​

Example Queries​

Get Node Information​

Get Recent Blockchain Activity​

Check Account Balance​

Development and Testing​

CLI Introspection Tools​

List All Endpoints​

Inspect Endpoint Schema​

Run GraphQL Queries​

Simple query​

Query from stdin​

Query from file​

Query with variables​

Query remote node​

Using with OCaml Nodes​

OCaml-specific endpoints​

Schema Introspection​

Rate Limiting and Performance​

Implementation Status Comparison​

Query Endpoints Status​

Mutation Endpoints Status​

Subscription Endpoints Status​

Implementation Summary​

Next Steps​