Keeper & API
The keeper loop, the read API, the verifier endpoints, running your own.
Feebric operates two services next to the program: the keeper, which runs the permissionless cranks and indexes payouts, and the verifier, which turns an X or GitHub login into a signed attestation. Both are replaceable by design.
The keeper loop
For every known vault, about once a minute:
- pump.fun distribute when the coin's creator vault holds pending fees and the vault is a shareholder of the coin's fee-sharing config:
sweep + distribute_creator_fees_v2. - settle when the vault holds more than its booked buckets (or has carry).
- pay_wallet for each Wallet rule with a balance, then pay_treasury.
- drip for each Dump Shield rule: read the price source, skip when the market-cap line is hit, build the verified holder snapshot (associated token accounts, on-curve, system-owned owners, sorted by owner), drop holders below the minimum holding or with a zero or unpayable share, and send batches that fit one transaction until the epoch budget is spent.
- buyback for each Buyback & Burn rule with a spendable bucket: plan the venue (curve or PumpSwap) and the spend cap, fund the buyer account's rent floor once, send the purchase with a 3% floor on tokens out.
- expire_social for social escrows past their deadline.
Compute units are sized from a simulation of each transaction; the priority fee is the 75th percentile of recent fees, clamped to configured bounds. Holder snapshots use an indexed RPC (Helius DAS) because public RPCs refuse token-program scans.
The keeper also runs an indexer: program transactions are decoded into Anchor events and per-recipient payouts, including transactions sent by somebody else. This is what the token page's Payouts and History show.
Read API
Base URL: https://api.feebric.app. JSON, read-only, CORS open. Chain state is decoded from the vault accounts; history comes from the indexer.
| route | returns |
|---|---|
GET /health | keeper status and index counts |
GET /api/vaults?mint=<mint> | vaults for a coin, with decoded state and wired (in pump.fun's fee-sharing config) |
GET /api/vaults?manager=<wallet> | vaults managed by a wallet |
GET /api/vaults/:vault | one vault with payout totals per rule |
GET /api/vaults/:vault/events?limit= | decoded program events, newest first |
GET /api/vaults/:vault/payouts?limit=&kind= | per-recipient payouts; kind is wallet, drip, buyback, social or treasury |
GET /api/vaults/:vault/runs?limit= | the keeper's own action log for the vault |
GET /api/recipients/:wallet | payouts a wallet has received across vaults |
A vault's decoded state carries the fields described in Program reference: identity, platformFeeBps, lockUntil, sumBuckets, carry, lifetime totals and the rules array with per-rule kind, bps, balance, totalPaid and kind-specific parameters.
The web app degrades gracefully when the API is down: token pages still show live state from the chain, only history is missing.
Verifier endpoints
Base URL: https://verify.feebric.app.
| route | purpose |
|---|---|
GET /health | status |
GET /pubkey | the verifier's Ed25519 public key |
GET /claim/info?vault=&rule= | what the claim page shows for an escrow |
GET /claim/start?vault=&rule=&recipient=&return= | validates the rule on chain and redirects to the provider's login |
GET /oauth/{x,github}/callback | provider callback; redirects back to return with the attestation in the URL fragment |
| `GET /resolve?platform=x | github&handle=` |
The default verifier key for new vaults is 5FrQpwQsFT6X8WDrzm3wSGpemFaSuK5udC2Xzp2riRDo. It is a per-vault parameter; a manager can set a different one while the vault is unlocked.
Running your own keeper
Everything the keeper calls is permissionless, so you can run one for your own vaults or for all of them. The reference implementation lives in the keeper/ package of the Feebric repository (TypeScript, SQLite via node:sqlite). It needs a Solana RPC, a Helius API key for holder snapshots, and a funded keypair for transaction fees. The holder snapshot it submits must follow the program's rules (associated token accounts only, system-owned on-curve owners, strictly ascending by owner); anything else is rejected on chain, so a misbehaving keeper can waste its own fees but cannot misdirect payouts.