Recurve Docs
Website GitHub Open app

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

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=

rangeLookbackBucket
24h24 hours10 minutes
7d (default)7 days1 hour
30d30 days6 hours
alleverything1 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.

kindEventaccountassets / shares
depositDepositownerboth
withdrawWithdraw (instant exit)ownerboth
queuedWithdrawalQueuedownershares only
claimedWithdrawalClaimedownerassets only
fundStrategyFundedthe strategyassets only
settleStrategySettledthe vaultassets 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
VariableMeaning
DATABASE_URLPostgres. Tables are created on boot
CHAIN_ID4663, the default; RPC_URL overrides the endpoint
VAULTSslug:vault:governor:name, comma separated. A malformed entry stops the indexer while the API stays up
DEPLOY_BLOCKThe 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_MSBlocks per eth_getLogs (at most 100,000 on the Robinhood Chain RPC) and the poll interval
CORS_ORIGIN, PORTOptional

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.