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

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​

Schema Introspection​

Rate Limiting and Performance​

Implementation Status Comparison​

Query Endpoints Status​

Mutation Endpoints Status​

Subscription Endpoints Status​

Implementation Summary​

Next Steps​