> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/docs/api-reference/graphql-api.md).

# GraphQL API Reference

> **Work in Progress** -- This document is under active development. Some schemas and details may change.

## Overview

The Lithosphere GraphQL API is built with **Apollo Server v4+** and serves as the primary GraphQL gateway for querying blockchain data, interacting with smart contracts, and subscribing to real-time events on the Lithosphere network.

## Features

* **Blockchain data querying and indexing** -- Query blocks, transactions, accounts, and token balances.
* **Smart contract interactions** -- Read contract state and submit transactions through GraphQL mutations.
* **Real-time event subscriptions** -- Subscribe to on-chain events via GraphQL subscriptions for live updates.

## Endpoint

The GraphQL API is typically available at:

```
/graphql
```

In development mode, a **GraphQL Playground** is available at the same endpoint, allowing you to explore the schema, build queries interactively, and inspect documentation.

## Local Development

Start the GraphQL server locally using:

```bash
pnpm dev:api
```

This launches the Apollo Server with hot-reload enabled. The GraphQL Playground will be accessible at `http://localhost:<port>/graphql`.

## SubQuery Indexer

The GraphQL backend is powered by a **SubQuery indexer** that indexes on-chain events from the Lithosphere network. The indexer processes blocks and transactions, storing structured data in PostgreSQL for efficient querying through the GraphQL layer.

## Example Query

```graphql
query GetBlockInfo {
  block(number: 12345) {
    hash
    number
    timestamp
    transactions {
      hash
      from
      to
      value
    }
  }
}
```

```graphql
query GetAccountBalance {
  account(address: "0x...") {
    balance
    nonce
    transactions(first: 10) {
      hash
      value
      timestamp
    }
  }
}
```

> **Note:** The schema above is illustrative. The full schema will be documented once it is finalized.

## Further Reading

Detailed schema documentation, mutation references, and subscription guides are coming soon.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.litho.ai/docs/api-reference/graphql-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.