GraphQL queries provide read access to blockchain data. The Query type is the main entry point for all read operations.
Root Query Fields
The Query type provides these top-level fields:
chainIdentifier
Returns the chain identifier for the chain that the server is tracking.
Response:
{
"data": {
"chainIdentifier": "4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S"
}
}
serviceConfig
Returns the server’s configuration including limits and version information.
{
serviceConfig {
maxQueryDepth
maxQueryNodes
maxOutputNodes
maxPageSize
requestTimeoutMs
}
}
protocolConfig
Query the protocol configuration for a specific version or the latest version.
The protocol version to query. If omitted, returns the latest version.
{
protocolConfig(protocolVersion: 50) {
protocolVersion
configs {
key
value
}
featureFlags {
key
value
}
}
}
epoch
Query information about an epoch by its ID.
The epoch ID. If omitted, returns the latest epoch.
{
epoch(id: 100) {
epochId
referenceGasPrice
startTimestamp
endTimestamp
totalCheckpoints
totalTransactions
totalGasFees
}
}
Object Queries
object
Query a specific on-chain object by its address.
The address of the object to query
The version of the object. If omitted, returns the latest version.
{
object(address: "0x5") {
address
version
digest
storageRebate
owner {
__typename
... on AddressOwner {
owner {
address
}
}
}
previousTransactionBlock {
digest
}
}
}
objects
Query multiple objects with filtering and pagination.
Number of items to fetch from the start
Cursor for forward pagination
Number of items to fetch from the end
Cursor for backward pagination
Filter criteria for objects
Filter by object type (e.g., “0x2::coin::Coin”)
Filter by specific object IDs
{
objects(first: 10, filter: { type: "0x2::coin::Coin<0x2::iota::IOTA>" }) {
pageInfo {
hasNextPage
endCursor
}
nodes {
address
version
digest
}
}
}
Address Queries
address
Query an address and its associated data.
{
address(address: "0x479c602460ae68771dcb9bfcef607dccc678859fb72d7d8aa8d9ce58c9430747") {
address
balance {
coinType { repr }
coinObjectCount
totalBalance
}
coins(first: 5) {
nodes {
contents {
type { repr }
}
}
}
}
}
Transaction Queries
transactionBlock
Query a specific transaction block by its digest.
The Base58-encoded transaction digest
{
transactionBlock(digest: "Dv5XRBjWvZTwiHVrhUetvDTgxyM8xVMb6P8pCAZv51tq") {
sender {
address
}
gasInput {
gasSponsor { address }
gasPayment { nodes { address } }
gasPrice
gasBudget
}
kind {
__typename
}
signatures
digest
effects {
timestamp
status
gasEffects {
gasObject { address }
gasSummary {
computationCost
storageCost
storageRebate
}
}
}
}
}
transactionBlocks
Query multiple transaction blocks with filtering and pagination.
Number of items to fetch from the start
Cursor for forward pagination
Number of items to fetch from the end
Cursor for backward pagination
Filter criteria for transactionsShow TransactionBlockFilter
Filter by Move function (format: “package::module::function”)
kind
TransactionBlockKindInput
Filter by transaction kind
Include only transactions after this checkpoint
Include only transactions before this checkpoint
Include only transactions at this checkpoint
Filter by recipient address
Filter by specific transaction digests
Maximum number of transactions to scan (required for complex filters)
{
transactionBlocks(
first: 10
filter: { signAddress: "0x479c602460ae68771dcb9bfcef607dccc678859fb72d7d8aa8d9ce58c9430747" }
) {
pageInfo {
hasNextPage
endCursor
}
nodes {
digest
sender { address }
effects {
timestamp
status
}
}
}
}
Checkpoint Queries
checkpoint
Query a checkpoint by its sequence number or digest.
The checkpoint sequence number
The checkpoint digest (Base58-encoded)
{
checkpoint(sequenceNumber: 1000) {
sequenceNumber
digest
timestamp
networkTotalTransactions
validatorSignatures
transactionBlocks(first: 5) {
nodes {
digest
}
}
}
}
checkpoints
Query multiple checkpoints with pagination.
Number of checkpoints to fetch from the start
Cursor for forward pagination
Number of checkpoints to fetch from the end
Cursor for backward pagination
{
checkpoints(first: 10) {
pageInfo {
hasNextPage
endCursor
}
nodes {
sequenceNumber
timestamp
networkTotalTransactions
}
}
}
Coin Queries
Query metadata for a specific coin type.
The coin type (e.g., “0x2::iota::IOTA”)
{
coinMetadata(coinType: "0x2::iota::IOTA") {
decimals
name
symbol
description
iconUrl
supply
}
}
Event Queries
events
Query events with filtering and pagination.
Number of events to fetch
Filter criteria for events
Filter by transaction digest
Filter by emitting package
Filter by emitting module
{
events(
first: 10
filter: { sender: "0x479c602460ae68771dcb9bfcef607dccc678859fb72d7d8aa8d9ce58c9430747" }
) {
pageInfo {
hasNextPage
endCursor
}
nodes {
sendingModule {
package { address }
name
}
type { repr }
sender { address }
timestamp
json
bcs
}
}
}
System Queries
iotaSystemStateV2
Query the current IOTA system state.
{
iotaSystemStateV2 {
epoch
protocolVersion
systemStateVersion
iotaTotalSupply
storageRebate
referenceGasPrice
activeValidators {
name
iotaAddress
stakingPoolId
votingPower
}
}
}
availableRange
Query the range of checkpoints available on the server.
{
availableRange {
first {
sequenceNumber
digest
}
last {
sequenceNumber
digest
}
}
}
{
<query>(first: 10, after: "cursor") {
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
edges {
cursor
node {
# ... fields
}
}
nodes {
# ... fields (shorthand for edges.node)
}
}
}
Type Introspection
Query the schema itself:
{
__schema {
queryType {
name
fields {
name
description
type { name }
}
}
}
}