Documentation
Get started
Create a new project

Quickstart

Create a new Ponder project

If the contract you're indexing has already been deployed, use the Etherscan contract link template.

shell
pnpm create ponder

You will be asked for a project name, and if you are using a template (recommended). Then, it will create a project directory, install dependencies, and initialize a git repository.

Start the development server

Just like Next.js and Vite, Ponder has a development server that automatically reloads when you save changes in any project file. It also prints console.log statements and errors encountered while running your code.

First, cd into your project directory, then start the server.

pnpm dev

Add an RPC URL

Ponder fetches data using the standard Ethereum RPC API. To get started, you'll need an RPC URL from a provider like Alchemy or Infura.

Open .env.local and paste in RPC URLs for any networks that your project uses.

Each RPC URL environment variable is named PONDER_RPC_URL postfixed with the chain ID (e.g. PONDER_RPC_URL_8453 for Base Mainnet):

.env.local
PONDER_RPC_URL_1 = "https://eth-mainnet.g.alchemy.com/v2/..."

Design your schema

The ponder.schema.ts file contains the database schema, and defines the shape data that the GraphQL API serves.

ponder.schema.ts
import { createSchema } from "@ponder/core";
 
export default createSchema((p) => ({
  BlitmapToken: p.createTable({
    id: p.string(),
    owner: p.string(), // Ethereum address
  }),
}));

See the design your schema guide for more details.

Write indexing functions

Files in the src/ directory contain indexing functions, which are TypeScript functions that process a contract event. The purpose of these functions is to insert data into the store.

Here's a sample indexing function for an ERC721 Transfer event.

src/index.ts
import { ponder } from "@/generated";
 
ponder.on("Blitmap:Transfer", async ({ event, context }) => {
  const { BlitmapToken } = context.db;
 
  await BlitmapToken.create({
    id: event.args.tokenId,
    data: {
      owner: event.args.to,
    },
  });
});

See Create & update records for a detailed guide on writing indexing functions.

Query the GraphQL API

As you write your indexing functions and start inserting data, open the GraphiQL interface at http://localhost:42069/graphql to explore your GraphQL API locally. Any changes you make to your ponder.schema.ts file will be reflected here.

Query
query {
  blitmapTokens {
    id
    owner
  }
}
Result
{
  "blitmapTokens": [
    { "id": 1452, "owner": "0xaf3d5..." },
    { "id": 7164, "owner": "0x9cb3b..." },
  ]
}