Skip to main content

GraphQL API

caution
  • Mina APIs are still under construction, so these endpoints may change.
  • By default, the GraphQL port is bound to localhost. Exposing the GraphQL API to the internet allows anyone to send Mina from the accounts known to the daemon.

The Mina daemon exposes a GraphQL API used to request information from and submit commands to a running node.

To use the GraphQL API, connect your GraphQL client to http://localhost:3085/graphql or open in your browser to use the GraphiQL IDE.

  • By default, an HTTP server runs on port 3085. You can configure a different port, use the -rest-port flag with the daemon startup command.

  • The default security permits only connections from localhost. To listen on all interfaces, add the -insecure-rest-server flag to the daemon startup command.

In addition to information about the running node, the GraphQL API can return data about the network's latest blocks. However, as the blockchain's historical state is not persisted in Mina, only blocks in the node's transition frontier are returned, i.e., the last k blocks. For other historical data, use the Archive Node that is designed to retain and retrieve historical data.

The full Mina GraphQL schema is available https://github.com/MinaProtocol/mina/blob/develop/graphql_schema.json.

Queries​

The Mina GraphQL API has a number of queries to extract data from a running node. GraphQL queries allow specifying the data to be returned in the response. For example, to get the latest block and creator information known to the daemon:

query {
  bestChain(maxLength: 1) {
    creator
    stateHash
    protocolState {
      consensusState {
        blockHeight
      }
      previousStateHash
    }
    transactions {
      coinbase
    }
  }
}

The following query requests all pending transactions in the transaction pool together with their fees. This query can be used to generate an estimate of a suggested fee for a transaction:

query {
  pooledUserCommands {
    id,
    fee
  }
}
tip

The memo field returned for a transaction is Base58Check encoded.

query {
  account(publicKey: "<B62...>") {
    balance {
      total
    }
    delegate
    nonce
  }
}

You can submit GraphQL requests from the command line of a node. For example, to use cURL to get the last ten block creators known to the node:

curl -d '{"query": "{
  bestChain(maxLength: 10) {
    creator
  }
}"}' -H 'Content-Type: application/json' http://localhost:3085/graphql

Mutations​

GraphQL mutations modify the running node in some way. For example, mutations may be used to send a payment, create a new account, or to add additional peers.

Consult the GraphQL schema for all available mutations.

Adding a new peer:

mutation {
   addPeers(peers:{
      libp2p_port:10511,
      host:"34.73.68.198",
      peer_id:"12D3KooWSJB2gZWi3ruVmtTF9JBCEBpCrJfuWCWzzRr8mMQWFQ9U"
   })
}

Update a SNARK worker to use a fee of 0.1 MINA:

mutation {
  setSnarkWorkFee(input: {fee: "100000000"})
}

Subscriptions​

A GraphQL subscription allows a GraphQL client to have data pushed to it when an event occurs. In Mina, there are subscriptions for:

  • newSyncUpdate - occurs when the sync status of the node changes.
  • newBlock - occurs when a new block is received.
  • chainReorganisation - occurs when the best tip of the node changes in a non-trivial way.

For example, to subscribe to all new blocks produced:

subscription {
  newBlock {
    creator
    stateHash
    protocolState {
      consensusState {
        blockHeight
      }
      previousStateHash
    }
  }
}

The new block subscription can also be limited to return only new blocks created by a defined public key with the publicKey argument.

GraphQL Public Proxy​

While exposing the GraphQL API to the internet is not recommended, an implementation of a GraphQL proxy is available that removes the queries that pose a threat, but still allows querying of the node's data from a public endpoint.

Resources​