GraphQL API

GraphQL provides an efficient alternative to JSON-RPC for querying blockchain data, especially for complex queries that would require multiple RPC calls.

Overview

Benefits of GraphQL:

Reduced Overhead — Get exactly the data you need in one request.
Efficient Queries — Fetch related data without multiple round trips.
Self-Documenting — Schema describes available queries.

Enabling GraphQL

kaly --graphql-http-enabled \
     --graphql-http-host=0.0.0.0 \
     --graphql-http-port=8547

Default endpoint: http://localhost:8547/graphql

note

GraphQL is only available over HTTP, not WebSocket.

Making Requests

Using cURL

curl -X POST \
  -H "Content-Type: application/json" \
  --data '{"query": "{syncing{startingBlock currentBlock highestBlock}}"}' \
  http://localhost:8547/graphql

Using GraphQL Client

const response = await fetch('http://localhost:8547/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `{
      block(number: "latest") {
        number
        hash
        timestamp
      }
    }`
  })
});

Example Queries

Get Sync Status

{
  syncing {
    startingBlock
    currentBlock
    highestBlock
  }
}

Response:

{
  "data": {
    "syncing": {
      "startingBlock": "0x0",
      "currentBlock": "0x2d0",
      "highestBlock": "0x66c0"
    }
  }
}

Get Block Details

{
  block(number: "latest") {
    number
    hash
    timestamp
    gasUsed
    gasLimit
    transactions {
      hash
      from {
        address
      }
      to {
        address
      }
      value
    }
  }
}

Get Account Information

{
  account(address: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD2b") {
    address
    balance
    transactionCount
    code
  }
}

Get Transaction with Receipt

{
  transaction(hash: "0x...") {
    hash
    nonce
    from {
      address
    }
    to {
      address
    }
    value
    gasPrice
    gas
    status
    logs {
      topics
      data
    }
  }
}

Get Multiple Blocks

{
  block1: block(number: "0x100") {
    number
    hash
  }
  block2: block(number: "0x101") {
    number
    hash
  }
}

Pending Transactions

Query pending transactions in the transaction pool:

Pending Transaction Count

{
  pending {
    transactionCount
  }
}

Pending Transaction Hashes

{
  pending {
    transactions {
      hash
      from {
        address
      }
      gasPrice
    }
  }
}

important

KalyChain doesn't execute pending transactions, so account, call, and estimateGas for pending don't reflect pending state.

Using GraphiQL

GraphiQL is an interactive GraphQL IDE:

Open GraphiQL app or browser extension.
Connect to http://localhost:8547/graphql.
Explore the schema and run queries interactively.

Features:

Schema exploration
Auto-completion
Query history
Response formatting

Schema

The GraphQL schema defines available types and queries. Key types include:

Block

type Block {
  number: Long!
  hash: Bytes32!
  parent: Block
  timestamp: Long!
  gasLimit: Long!
  gasUsed: Long!
  transactions: [Transaction!]!
  # ... more fields
}

Transaction

type Transaction {
  hash: Bytes32!
  nonce: Long!
  from: Account!
  to: Account
  value: BigInt!
  gasPrice: BigInt!
  gas: Long!
  status: Long
  # ... more fields
}

Account

type Account {
  address: Address!
  balance: BigInt!
  transactionCount: Long!
  code: Bytes!
}

Comparison with JSON-RPC

Scenario	Recommended
Get block with all transactions	GraphQL
Simple balance check	JSON-RPC
Aggregate data queries	GraphQL
Real-time subscriptions	JSON-RPC (Pub/Sub)
Contract calls	JSON-RPC

Overview​

Enabling GraphQL​

Making Requests​

Using cURL​

Using GraphQL Client​

Example Queries​

Get Sync Status​

Get Block Details​

Get Account Information​

Get Transaction with Receipt​

Get Multiple Blocks​

Pending Transactions​

Pending Transaction Count​

Pending Transaction Hashes​

Using GraphiQL​

Schema​

Block​

Transaction​

Account​

Comparison with JSON-RPC​

Further Reading​