Indexes on-chain events from CoW Protocol's ComposableCoW contract, decodes the programmatic order types the indexer supports (see src/decoders/ for the canonical list), and serves the data through a GraphQL API. Built with Ponder by @bleu for CoW Protocol.
- Ponder 0.16.x -- blockchain indexing framework
- TypeScript
- viem -- Ethereum interactions and ABI encoding
- Hono -- API routing
- PostgreSQL
Requires Node.js >= 18.14, pnpm, and Docker.
git clone https://github.com/bleu/cow-programmatic-orders-api.git
cd cow-programmatic-orders-api
pnpm installCopy the env file and configure your RPC endpoints:
cp .env.example .env.localOpen .env.local and set MAINNET_RPC_URL and GNOSIS_RPC_URL. Optionally set <CHAIN>_WS_RPC_URL (e.g. MAINNET_WS_RPC_URL) to enable Ponder realtime WS subscriptions, which are more efficient than HTTP polling.
Start PostgreSQL and run the indexer:
docker compose up -d
pnpm devThe GraphQL API is at http://localhost:42069 once the dev server starts.
First run takes time. The indexer must backfill all on-chain events from the contract's deploy block before it goes live. This can take several hours depending on your RPC endpoint. The API is queryable the whole time — data just fills in progressively.
Use these endpoints to check indexer health without reading logs:
| Endpoint | What to expect |
|---|---|
GET /healthz |
200 {"status":"ok"} — process is alive |
GET /ready |
503 while backfilling, 200 once caught up |
GET /status |
Per-chain block progress (current vs. latest) |
GET /metrics |
Prometheus metrics (block lag, handler latency) |
Normal during backfill — /ready returns 503 and /status shows checkpoint far behind latest. The indexer is working; it just hasn't caught up yet. Expect this for several hours on first run.
Stuck vs. slow — if /status shows the same checkpoint block for more than 5 minutes after backfill (i.e., once /ready returned 200), the indexer may be stuck. Check docker logs <container> for errors.
Container crashed — /healthz returns a connection error. Restart the container and check logs.
| Command | What it does |
|---|---|
pnpm dev |
Start the indexer in dev mode |
pnpm start |
Start in production mode |
pnpm codegen |
Regenerate types after config or schema changes |
pnpm typecheck |
Run TypeScript type checking |
pnpm lint |
Run ESLint |
pnpm test |
Run tests |
- docs/api-reference.md -- Endpoints overview (GraphQL, SQL, REST). OpenAPI/Swagger for custom REST routes lives at
/docswhen the API is running. - docs/architecture.md -- System internals, data flow, schema design
- docs/deployment.md -- Production setup and configuration
- docs/supported-order-types.md -- Decoded order types and their parameters
Open source.