How to Build Subgraphs on NEAR

·

The NEAR blockchain has emerged as a powerful platform for building scalable and user-friendly decentralized applications. As the ecosystem grows, so does the need for efficient data indexing and querying. This is where subgraphs come into play. By leveraging The Graph protocol, developers can create subgraphs to index and query data from NEAR smart contracts using GraphQL. This guide walks you through the process of building, deploying, and querying subgraphs on NEAR.

What Is a NEAR Subgraph?

A subgraph is a tool provided by The Graph that allows developers to index blockchain events and serve them via a GraphQL API. With recent support for NEAR, Graph Nodes can now process NEAR blockchain events, enabling developers to build powerful data indexing layers for their dApps.

Subgraphs are event-driven. They listen to on-chain activity and transform it into structured data. Currently, NEAR subgraphs support two types of handlers:

According to NEAR’s documentation, receipts are the only actionable objects in the system. When we talk about “processing transactions” on NEAR, it ultimately means “applying receipts” at some point in the execution flow.

👉 Discover how blockchain data powers next-gen dApps — explore developer tools today.

Setting Up Your Development Environment

To build subgraphs on NEAR, you’ll need the following tools:

These tools are essential for scaffolding, building, and deploying your subgraph. The development experience closely mirrors that of Ethereum-based subgraphs, making it accessible to developers familiar with The Graph ecosystem.

A complete subgraph consists of three core components:

1. subgraph.yaml – The Subgraph Manifest

This configuration file defines the data sources and how they should be processed. For NEAR, a new kind: near data source type is introduced.

Example:

specVersion: 1.3.0
schema:
  file: ./src/schema.graphql
dataSources:
  - kind: near
    network: near-mainnet
    source:
      account: app.good-morning.near
    startBlock: 10662188
    mapping:
      apiVersion: 0.0.9
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock
      receiptHandlers:
        - handler: handleReceipt
      file: ./src/mapping.ts

Key points:

Handlers:

2. schema.graphql – Data Structure Definition

This file defines the entities to be stored and how they can be queried via GraphQL. It abstracts the raw blockchain data into a structured format suitable for frontend applications.

For example:

type Transfer @entity {
  id: ID!
  from: String!
  to: String!
  amount: BigInt!
  blockNumber: BigInt!
}

This schema enables queries like:

{
  transfers(first: 5) {
    from
    to
    amount
  }
}

3. AssemblyScript Mappings – Transforming Data

Mappings are written in AssemblyScript and convert blockchain events into entities defined in the schema.

NEAR-specific types are available in the Graph TS API:

class ExecutionOutcome {
  gasBurnt: u64
  blockHash: Bytes
  id: Bytes
  logs: Array<string>
  receiptIds: Array<Bytes>
  tokensBurnt: BigInt
  executorId: string
}

class ActionReceipt {
  predecessorId: string
  receiverId: string
  id: CryptoHash
  signerId: string
  gasPrice: BigInt
  actions: Array<Action>
}

class Block {
  author: string
  header: BlockHeader
  chunks: Array<ChunkHeader>
}

class ReceiptWithOutcome {
  outcome: ExecutionOutcome
  receipt: ActionReceipt
  block: Block
}

Block handlers receive a Block object, while receipt handlers receive a ReceiptWithOutcome.

Additionally, NEAR logs often contain JSON strings. A new utility function, json.fromString(), allows easy parsing:

let logJson = json.fromString(eventLog);
if (logJson.isObj) {
  let obj = logJson.toObj();
  let amount = obj.get("amount").toString();
}

Common commands during development:

graph codegen    # Generates TypeScript types from schema
graph build      # Compiles mappings to WebAssembly

Deploying Your NEAR Subgraph

Once your subgraph is built, it can be deployed to a Graph Node that supports NEAR (version 0.26.x or higher).

Supported networks in Subgraph Studio and The Graph Network:

To deploy:

  1. Authenticate:

    graph auth https://api.thegraph.com/deploy/ <ACCESS_TOKEN>

  2. Deploy:

    graph deploy --product studio your-username/near-subgraph

For local deployment:

graph deploy \
  --node http://localhost:8020/ \
  --ipfs http://localhost:5001

After deployment, monitor indexing progress with:

{
  _meta {
    block {
      number
    }
  }
}

👉 Learn how real-time blockchain indexing enhances dApp performance — dive deeper now.

Querying Your NEAR Subgraph

Once indexed, your subgraph exposes a GraphQL endpoint. Queries follow standard GraphQL syntax and are based on your defined schema.

Example query to fetch recent transfers:

{
  transfers(first: 10, orderBy: blockNumber, orderDirection: desc) {
    from
    to
    amount
    blockNumber
  }
}

You can access this endpoint via The Graph’s hosted service, Subgraph Studio, or your own Graph Node instance.

Example Subgraphs for Reference

Explore these official examples to get started:

These repositories demonstrate practical implementations of block and receipt handlers.

Frequently Asked Questions

Can a subgraph index both NEAR and EVM chains?

No. A single subgraph can only index data from one chain or network. Cross-chain indexing requires separate subgraphs or external aggregation.

Are function call triggers supported?

Currently, only block and receipt triggers are supported. Support for function call filters is under evaluation. Future integration with native NEAR events could enable more granular triggers.

Do receipt handlers include subaccounts?

Only if explicitly defined. Using the accounts field with suffixes or prefixes allows matching subaccounts. For example:

accounts:
  suffixes:
    - mintbase1.near

This matches all subaccounts under mintbase1.near.

Can I make view calls to NEAR accounts during mapping?

Not currently. Making runtime calls to contracts during indexing is not supported. The team is assessing whether this functionality is necessary for common use cases.

Is the “pending” deployment feature available for NEAR subgraphs?

No. Unlike Ethereum subgraphs, NEAR does not yet support pending versions. As a workaround, deploy updates to a staging subgraph name, wait for sync, then redeploy to the main name using the same deployment ID for seamless switching.

Where can I get help building NEAR subgraphs?

For general development questions, refer to The Graph documentation. For NEAR-specific support, join the Graph Protocol Discord and visit the #near channel, or email [email protected].

👉 Unlock advanced blockchain analytics — see what’s possible with decentralized indexing.

Core Keywords

By integrating these keywords naturally throughout this guide, we ensure strong SEO performance while delivering valuable technical insights for developers building on NEAR.