Skip to main content

GraphQL API Reference

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

Quick Start​

Testing the API​

# Basic connectivity test
curl -X POST http://localhost:3000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

# Get sync status
curl -X POST http://localhost:3000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ syncStatus }"}'

Interactive Exploration​

The node provides interactive GraphQL explorers:

API Endpoints​

Query Endpoints​

Network and Node Status​

syncStatus​

Get the current synchronization status of the node.

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

Get comprehensive daemon status information.

query {
  daemonStatus {
    blockchainLength
    chainId
    commitId
    stateHash
    numAccounts
    globalSlotSinceGenesisBestTip
    ledgerMerkleRoot
    coinbaseReceiver
  }
}
networkID​

Get the network identifier.

query {
  networkID # Returns: "mina:devnet" or similar
}
version​

Get the node version (git commit hash).

query {
  version # Returns: git commit hash
}

Blockchain Data​

bestChain(maxLength: Int!)​

Get the best chain blocks up to specified length.

query RecentBlocks {
  bestChain(maxLength: 10) {
    stateHash
    protocolState {
      consensusState {
        blockHeight
        slotSinceGenesis
      }
      previousStateHash
    }
    transactions {
      userCommands {
        id
        fee
        amount
        memo
      }
    }
  }
}
block(height: Int, stateHash: String)​

Get a specific block by height or state hash.

query GetBlock {
  block(height: 455450) {
    stateHash
    protocolState {
      consensusState {
        blockHeight
      }
    }
    creator
    transactions {
      userCommands {
        amount
        fee
        from
        to
      }
    }
  }
}
genesisBlock​

Get the genesis block.

query {
  genesisBlock {
    stateHash
    protocolState {
      consensusState {
        blockHeight
      }
    }
  }
}
genesisConstants​

Get genesis constants and network parameters.

query {
  genesisConstants {
    accountCreationFee
    genesisTimestamp
    coinbase
  }
}

Account Information​

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

Get account information by public key.

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
      setZkappUri
      editActionState
      setTokenSymbol
      incrementNonce
      setVotingFor
    }
  }
}

Transaction Pool​

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

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

query PooledUserCommands($publicKey: String) {
  pooledUserCommands(publicKey: $publicKey) {
    id
    amount
    fee
    from
    to
    nonce
    memo
    isDelegation
    hash
    kind
  }
}
pooledZkappCommands(publicKey: String, hashes: [String], ids: [String])​

Get pending zkApp commands from the transaction pool.

query PooledZkApps($publicKey: String) {
  pooledZkappCommands(publicKey: $publicKey) {
    id
    hash
    zkappCommand {
      feePayer {
        body {
          publicKey
          fee
          nonce
        }
      }
      accountUpdates {
        body {
          publicKey
          balanceChange
        }
      }
    }
  }
}

Transaction Status​

transactionStatus(payment: String, zkappTransaction: String)​

Get the status of a specific transaction.

query TransactionStatus($transactionId: String!) {
  transactionStatus(payment: $transactionId) # Returns: PENDING | INCLUDED | UNKNOWN
}

SNARK Work​

snarkPool​

Get completed SNARK work from the pool.

query {
  snarkPool {
    fee
    prover
  }
}
pendingSnarkWork​

Get pending SNARK work that needs to be completed.

query {
  pendingSnarkWork {
    workBundle {
      sourceFirstPassLedgerHash
      targetFirstPassLedgerHash
      sourceSecondPassLedgerHash
      targetSecondPassLedgerHash
      workId
    }
  }
}
currentSnarkWorker​

Get information about the currently configured SNARK worker.

query {
  currentSnarkWorker {
    key
    fee
    account {
      publicKey
      balance {
        total
      }
    }
  }
}

Mutation Endpoints​

Transaction Submission​

sendPayment​

Submit a payment transaction.

mutation SendPayment(
  $input: SendPaymentInput!
  $signature: UserCommandSignature!
) {
  sendPayment(input: $input, signature: $signature) {
    payment {
      id
      hash
      amount
      fee
      from
      to
    }
  }
}
sendDelegation​

Submit a delegation transaction.

mutation SendDelegation(
  $input: SendDelegationInput!
  $signature: UserCommandSignature!
) {
  sendDelegation(input: $input, signature: $signature) {
    delegation {
      id
      hash
      delegator
      delegate
      fee
    }
  }
}
sendZkapp​

Submit a zkApp transaction.

mutation SendZkApp($input: SendZkAppInput!) {
  sendZkapp(input: $input) {
    zkapp {
      id
      hash
      zkappCommand {
        feePayer {
          body {
            publicKey
            fee
          }
        }
      }
    }
  }
}

Implementation Details​

The GraphQL API is implemented in the following source files:

Core Implementation​

Type Implementations​

Common Patterns​

Error Handling​

All GraphQL queries return either successful data or structured errors:

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

Pagination and Limits​

Many queries accept maxLength or similar parameters:

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

Optional Parameters​

Most queries accept optional parameters for filtering:

query {
  # Get all pooled commands
  pooledUserCommands

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

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

Example Queries​

Get Node Information​

curl -X POST http://localhost:3000/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query NodeInfo {
      syncStatus
      networkID
      version
      daemonStatus {
        blockchainLength
        peers
        uptimeSecs
      }
    }"
  }'

Get Recent Blockchain Activity​

curl -X POST http://localhost:3000/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query RecentActivity {
      bestChain(maxLength: 5) {
        stateHash
        protocolState {
          consensusState {
            blockHeight
          }
        }
        transactions {
          userCommands {
            amount
            fee
            from
            to
          }
        }
      }
    }"
  }'

Check Account Balance​

curl -X POST http://localhost:3000/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetBalance($publicKey: String!) {
      account(publicKey: $publicKey) {
        balance {
          total
          liquid
          locked
        }
        nonce
        delegate
      }
    }",
    "variables": {
      "publicKey": "B62qp3B9VW1ir5qL1MWRwr6ecjC2NZbGr8vysGeme9vXGcFXTMNXb2t"
    }
  }'

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

Next Steps​