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
{ __typename }
#!/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
{ syncStatus }
#!/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
query {
daemonStatus {
blockchainLength
chainId
commitId
stateHash
numAccounts
globalSlotSinceGenesisBestTip
ledgerMerkleRoot
coinbaseReceiver
}
}
#!/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
query {
networkID
}
#!/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
query {
version
}
#!/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
query RecentBlocks {
bestChain(maxLength: 10) {
stateHash
protocolState {
consensusState {
blockHeight
slotSinceGenesis
}
previousStateHash
}
transactions {
userCommands {
id
fee
amount
memo
}
}
}
}
#!/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
query GetLatestBlock {
bestChain(maxLength: 1) {
stateHash
protocolState {
consensusState {
blockHeight
}
}
creator
transactions {
userCommands {
amount
fee
from
to
}
}
}
}
#!/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
query {
genesisBlock {
stateHash
protocolState {
consensusState {
blockHeight
}
}
}
}
#!/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
query {
genesisConstants {
accountCreationFee
genesisTimestamp
coinbase
}
}
#!/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
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
}
}
}
#!/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
query PooledUserCommands($publicKey: String) {
pooledUserCommands(publicKey: $publicKey) {
id
amount
fee
from
to
nonce
memo
isDelegation
hash
kind
}
}
#!/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
query PooledZkApps($publicKey: String) {
pooledZkappCommands(publicKey: $publicKey) {
id
hash
zkappCommand {
feePayer {
body {
publicKey
fee
nonce
}
}
accountUpdates {
body {
publicKey
balanceChange {
magnitude
sgn
}
}
}
}
}
}
#!/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
query TransactionStatus($payment: String!) {
transactionStatus(payment: $payment)
}
#!/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
query SnarkPool {
snarkPool {
fee
prover
}
}
#!/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
query PendingSnarkWork {
pendingSnarkWork {
workBundle {
sourceFirstPassLedgerHash
targetFirstPassLedgerHash
sourceSecondPassLedgerHash
targetSecondPassLedgerHash
workId
}
}
}
#!/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
query CurrentSnarkWorker {
currentSnarkWorker {
key
fee
account {
publicKey
balance {
total
}
}
}
}
#!/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
mutation SendPayment(
$input: SendPaymentInput!
$signature: UserCommandSignature!
) {
sendPayment(input: $input, signature: $signature) {
payment {
id
hash
amount
fee
from
to
}
}
}
#!/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
mutation SendDelegation(
$input: SendDelegationInput!
$signature: UserCommandSignature!
) {
sendDelegation(input: $input, signature: $signature) {
delegation {
id
hash
delegator
delegate
fee
}
}
}
#!/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
mutation SendZkApp($input: SendZkAppInput!) {
sendZkapp(input: $input) {
zkapp {
id
hash
zkappCommand {
feePayer {
body {
publicKey
fee
}
}
}
}
}
}
#!/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
query NodeInfo {
networkID
version
daemonStatus {
blockchainLength
chainId
}
}
#!/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
query RecentActivity {
bestChain(maxLength: 5) {
stateHash
protocolState {
consensusState {
blockHeight
}
}
transactions {
userCommands {
amount
fee
from
to
}
}
}
}
#!/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
query GetBalance($publicKey: String!) {
account(publicKey: $publicKey) {
balance {
total
liquid
locked
}
nonce
delegateAccount {
publicKey
}
}
}
#!/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:
# 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:
# 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:
# 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
# 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
# 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
# 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
# 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
# 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
-fflag to read from a.graphqlfile
You can combine any input method with:
-vor--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:
# 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:
# 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
maxLengthparameters - 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