Indexes on-chain events from CoW Protocol's ComposableCoW contract, decodes eight programmatic order types (TWAP, Stop Loss, Perpetual Swap, Good After Time, Trade Above Threshold, Circles Backing Order, Swap Order Handler, ERC4626 CoW Swap Fee Burner), 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.
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.