API endpoints

API reference

Ponder's HTTP server is built with Hono, a fast and lightweight routing framework.

Hono

Hono supports all standard HTTP methods and an intuitive middleware API.

method	description
`get`	Register a handler for GET requests
`post`	Register a handler for POST requests
`use`	Register middleware for a path
...and many more

File requirements

The src/api/index.ts file must default export a Hono app instance. You can use other files in src/api/ to organize your code, just be sure to export the Hono app instance correctly.

src/api/index.ts

import { Hono } from "hono";
 
const app = new Hono();
 
app.get("/hello", (c) => {
  return c.text("Hello, world!");
});
 
export default app;

`ponder:schema`

The ponder:schema virtual module conveniently re-exports the ponder.schema.ts file.

src/api/index.ts

import { db } from "ponder:api";
import { accounts } from "ponder:schema"; 
import { Hono } from "hono";
 
const app = new Hono();
 
app.get("/account/top-10", async (c) => {
  const account = await db 
    .select()
    .from(accounts) 
    .limit(10)
 
  return c.json(account);
});
 
export default app;

`ponder:api`

The ponder:api virtual module exports a ready-to-use Drizzle database client and Viem clients configured according to ponder.config.ts.

`db`

A read-only Drizzle database client backed by a client-side connection pool.

Usage

src/api/index.ts

import { db } from "ponder:api"; 
import { accounts } from "ponder:schema";
import { Hono } from "hono";
import { eq } from "ponder";
 
const app = new Hono();
 
app.get("/account/:address", async (c) => {
  const address = c.req.param("address");
 
  const account = await db 
    .select() 
    .from(accounts) 
    .where(eq(accounts.address, address)); 
 
  return c.json(account);
});
 
export default app;

`publicClients`

A object containing a Viem Public Client for each chain defined in ponder.config.ts.

Usage

src/api/index.ts

import { publicClients } from "ponder:api"; 
import { Hono } from "hono";
 
const app = new Hono();
 
app.get("/balance/:address", async (c) => {
  const address = c.req.param("address");
 
  const balance = await publicClients[8453].getBalance({ address }); 
 
  return c.json({ address, balance });
});
 
export default app;

Middlewares

`graphql`

The graphql function is a Hono middleware that converts your schema into a performant GraphQL API.

field	type	description
db	`Database`	Required. Drizzle database object exported from `"ponder:api"`.
schema	`Schema`	Required. Drizzle schema exported from `"ponder:schema"`.

Usage

src/api/index.ts

import { db } from "ponder:api";
import schema from "ponder:schema";
import { graphql } from "ponder"; 
import { Hono } from "hono";
 
const app = new Hono();
 
app.use("/", graphql({ db, schema })); 
app.use("/graphql", graphql({ db, schema })); 
 
export default app;

`client`

The client function is a Hono middleware that serves SQL client queries submitted by @ponder/client.

field	type	description
db	`Database`	Required. Drizzle database object exported from `"ponder:api"`.
schema	`Schema`	Required. Drizzle schema exported from `"ponder:schema"`.

Usage

src/api/index.ts

import { db } from "ponder:api";
import schema from "ponder:schema";
import { Hono } from "hono";
import { client } from "ponder"; 
 
const app = new Hono();
 
app.use("/sql/*", client({ db, schema })); 
 
export default app;

Reserved routes

Ponder reserves a few routes for standard use. If you register custom endpoints that conflict with these routes, the build will fail.

route	description
`/health`	Returns status code `200` immediately after the process starts.
`/ready`	Returns status code `503` during the backfill, and status code `200` after the backfill is complete.
`/status`	Returns the current indexing status. Read more.
`/metrics`	Prometheus metrics endpoint. Read more.