Reference
Indexer API
A read-only JSON API over the funds the indexer watches: equity curves, flows, proposals and per-address cost basis. Everything the chain cannot answer cheaply.
Base
The Recurve Fund's indexer answers at the address below. Another fund runs its own (see Running it).
https://www.recurvemoney.xyz/indexer
GET only, CORS *, weak ETags (send If-None-Match to get a 304).
Unknown paths and methods answer 404 {"error":"not found"}; a crashed route
500 {"error":"internal"}. The app uses it for the TVL chart and the risk panel and
nothing else; every other number in the app is read from chain.
Conventions
- Every amount is a decimal string holding a full uint256 — never parse one
into a JS number. Asset amounts are in the asset's base units (
asset_decimals), share amounts in share units,share_priceis asset base units per 1e18 shares and is exactly"1000000000000000000"for an empty vault. - Block numbers and
executable_at(unix seconds) are strings too;state,watcher_blocks,log_index,asset_decimals,return_24h_pctand the health routes'lastOk(unix milliseconds) are numbers. - Timestamps are ISO-8601 UTC. Addresses and hashes are lowercase.
- Lists for an unknown fund are empty with a 200; only
/funds/:slug404s.
Routes
GET /funds
Every fund with its latest snapshot, largest TVL first.
{"funds": [{
"slug": "main", "name": "Recurve Fund",
"vault": "0x…", "governor": "0x…",
"asset": "0x…", "asset_symbol": "USDG", "asset_decimals": 6,
"total_assets": "2500000000", "float_assets": "250000000", "deployed": "2250000000",
"total_supply": "2500000000", "share_price": "1000000000000000000",
"updated_at": "2026-09-19T09:30:58.988Z",
"share_price_24h": "1000000000000000000", // newest snapshot at least 24h old, or null
"return_24h_pct": 0 // share_price / share_price_24h − 1, in percent; null without a 24h reference
}]}
GET /funds/:slug
One fund with the same snapshot columns plus created_at (when the indexer first
saw it), without the 24h fields. 404 {"error":"no such fund"} for an unknown
slug.
GET /funds/:slug/history?range=
range | Lookback | Bucket |
|---|---|---|
24h | 24 hours | 10 minutes |
7d (default) | 7 days | 1 hour |
30d | 30 days | 6 hours |
all | everything | 1 day |
{"range": "7d", "points": [
{"t": "2026-09-19T09:00:00.000Z", "total_assets": "5000000000000000", "share_price": "1000000000000000000"},
…
]}
Buckets are aligned to the epoch and carry the maximum of each value inside them.
Buckets with no snapshot are absent, not zero — a gap means the indexer was down. Any other
range answers 400 {"error":"bad range","allowed":["24h","7d","30d","all"]}.
GET /funds/:slug/proposals, GET /proposals
Newest first, capped at 100 per fund or 200 across all funds; the cross-fund route adds
slug and name to each row.
{"proposals": [{
"id": "0x…", // bytes32 proposal id
"governor": "0x…", "vault": "0x…", "target": "0x…",
"assets": "5000000000000000",
"posted_block": "108364501", "posted_at": "2026-08-27T…Z",
"executable_at": "1787943865", // unix seconds
"state": 4, // 1 Pending, 2 Vetoed, 3 Blocked, 4 Executed, 5 Settled
"veto_weight": "0", "watcher_blocks": 0,
"returned": null, "fee": null, // set by ProposalSettled
"updated_at": "…"
}]}
State follows governor events only; the indexer never reads the contract's state. Because a
watcher block is a revert on chain, 3 never actually appears, and a blocked or
abandoned proposal shows as 1 with an executable_at in the past
forever. Calldata is not stored (it is not in any event); read it from the governor.
GET /funds/:slug/flows
The newest 100 vault events, one row each.
kind | Event | account | assets / shares |
|---|---|---|---|
deposit | Deposit | owner | both |
withdraw | Withdraw (instant exit) | owner | both |
queued | WithdrawalQueued | owner | shares only |
claimed | WithdrawalClaimed | owner | assets only |
fund | StrategyFunded | the strategy | assets only |
settle | StrategySettled | the vault | assets returned |
{"flows": [{"id": "1", "vault": "0x…", "kind": "deposit", "account": "0x…",
"assets": "5000000000000000", "shares": "5000000000000000",
"block_number": "108251528", "tx_hash": "0x…", "log_index": 3, "occurred_at": "…"}]}
GET /portfolio/:address
Cost basis per fund for one address: deposits minus withdrawals and claims, in asset terms.
Current value needs a live share balance and price, which belong to a client that already
holds a chain connection. Malformed addresses answer 400 {"error":"not an address"};
an address with no history answers an empty positions list.
{"address": "0x…", "positions": [{
"slug": "main", "name": "Recurve Fund", "vault": "0x…",
"asset_symbol": "USDG", "asset_decimals": 6,
"deposited": "2500000000", "withdrawn": "0",
"net_deposited": "2500000000", // can go negative after a profitable exit
"events": "1", "last_block": "108251528"
}]}
GET /health, GET /health/indexer
/health pings the database and stays 200 while the indexer is merely behind, so
a long first backfill does not fail a deploy. /health/indexer answers 503 once a
loop that has succeeded before goes five poll intervals (60 seconds by default) without another
success. A first backfill shows lastOk: 0, cursor: null,
stale: false, and has thirty minutes to finish its first poll before that turns
stale too, so a loop that fails from the start does not read as healthy. An empty
VAULTS is never stale: there is nothing to index. A malformed one is stale at once,
with an error field saying so:
{"ok": true, "lastOk": 1758274258988, "cursor": "108451200", "stale": false}
Freshness
The indexer polls every 12 seconds and trails the head by two blocks. Timer snapshots of
every fund land roughly once a minute while the loop is healthy (never more often than every
60 seconds, and not at all while it is backing off from a failure), and the fund whose vault
emitted a StrategyFunded or StrategySettled gets an extra snapshot
pinned to that event's block, so the step when capital leaves and the jump when it comes back
sit on the curve at the right block rather than up to a minute late. History starts when the indexer started watching a fund; there is no reconstruction of
the past, because public RPCs do not serve historical state.
Running it
git clone https://github.com/Recurve-Money/recurve && cd recurve/api && npm install
cp .env.example .env # DATABASE_URL, CHAIN_ID, VAULTS, DEPLOY_BLOCK
npm run dev
| Variable | Meaning |
|---|---|
DATABASE_URL | Postgres. Tables are created on boot |
CHAIN_ID | 4663, the default; RPC_URL overrides the endpoint |
VAULTS | slug:vault:governor:name, comma separated. A malformed entry stops the indexer while the API stays up |
DEPLOY_BLOCK | The last block treated as already indexed when no cursor row exists yet; the first scan starts at DEPLOY_BLOCK + 1, so set it to the block before the deploy |
LOG_CHUNK, POLL_MS | Blocks per eth_getLogs (at most 100,000 on the Robinhood Chain RPC) and the poll interval |
CORS_ORIGIN, PORT | Optional |
The cursor is global: a fund added later is indexed from the current head, not backfilled.
Every insert is idempotent — flows on (tx_hash, log_index), snapshots on
(vault, block_number), proposals on their id, with state updates replayed in log
order — so rewinding the cursor row by hand and restarting is safe.