ONO / BONO API

Read-only analytics · v0.6.2

Use /api/v1/overview for dashboard cards and /api/v1/history/{burns|buybacks|rewards} for charts. Every request reads stored data; it does not start a Solana scan.

Conventions

• All dates and grouping boundaries use UTC. Dates are inclusive.
• Token and USD amounts are exact decimal strings in whole tokens/dollars, not atomic units. Holder counts are integers. The dashboard rounds price to four decimals and other values to at most two; API values remain exact.
• null means unavailable, not zero. An indexed, covered day with no burns/buybacks is "0".
• as_of is the snapshot time. Check /status for per-metric freshness; a retained metric may be older than the snapshot. History responses carry snapshot_id and are limited by that snapshot's event watermark.
• Before the first snapshot, data endpoints return 503. Invalid date/granularity input returns 422. /status remains available before collection starts.

Endpoints

History requests

All history endpoints accept:

curl "http://localhost:8000/api/v1/overview"
curl "http://localhost:8000/api/v1/history/burns?granularity=month"
curl "http://localhost:8000/api/v1/history/buybacks?granularity=day&start=2026-10-01&end=2026-10-15"
curl "http://localhost:8000/api/v1/history/rewards?granularity=month&start=2025-07-22"
curl "http://localhost:8000/api/v1/status"

History responses contain start, end, granularity, timezone, unit, snapshot_id, as_of, complete, history_complete and chronological points.

{
  "date": "2026-10-01",
  "period_start": "2026-10-01",
  "period_end": "2026-10-15",
  "complete": false,
  "ono_amount": "66226.34"
}

Illustrative monthly point: an observed subtotal over the selected portion of October, not a cumulative lifetime total. period_start/period_end are present for monthly points. Burns/buybacks also include event and transaction counts.

complete=false can mean missing older history, head catch-up or a stream error. A non-null burn/buyback amount in a partial interval is a found subtotal, not necessarily the final amount. Rewards need earlier registration and score context, so they stay null until the entire program stream is indexed. history_complete means the provider history boundary was reached and the head is caught up; it is not an independent archival completeness proof. dune_parity=unverified means no independent export reconciliation has established exact parity.

Calculation rules

Buybacks

Count Token-2022 transferChecked ONO amounts into destination SUScVReHqJ2krdKiS3UCrwYVukjJ6modQsqgQP4wD4q, with one of the three supplied transaction signers, after Jul 21, 2025. Exclude the seven supplied source accounts and transfers in the same outer instruction as Whirlpool collect_fees_v2 or increase_liquidity_v2. This is the supplied destination-transfer SQL method, not “all swaps” or a wallet-net calculation. Existing successful/failed transaction selection follows the configured service policy.

Burns: totals versus charts

/overview burned_total_ono and /metrics total_burned_ono are the lifetime burn metric and include the fixed 1,356,431 ONO adjustment exactly once. Burn chart points contain only dated on-chain burns from Jul 21, 2025 and never include that adjustment. In verified-fixed-issuance mode, the lifetime base is established by issuance proof and current supply rather than the chart scan. Thus a correct total can exist before dated burn history is ready.

Estimated rewards

Program: B9J9SDcXLBwpRq9JS9q9KJtsaYsermtddMeo9LojTLJQ.

daily estimated ONO = sum(last score per active (stream, miner))
                      × 6.623814000 × 5
monthly estimated ONO = sum(daily estimates in selected days)

• Read exact-byte registration 00 and deletion 03 instructions. Scores come from the supplied score-update log pattern, without an opcode filter; lines containing Burnt ONO amount are excluded.
• The supplied SQL uses earliest registration and latest deletion per stream. A stream is active at UTC day end if already registered and not yet deleted by that rule. This is not a reconstruction of separate re-registration lifecycle intervals.
• Keep the latest score per (stream, miner) at day end and carry it forward indefinitely. The SQL can count separate miner pairs for one stream. Equal timestamps use deterministic slot/signature/event ordering; SQL tie ordering is unspecified.
• Exclude streams 7ntP5wK6cCUAXXL5zsiKawASmJDb9TtFp365tmfPfkhm, HjTUsqK1LE7ib3WXy5cbcbp6eg3xF35MSoDm3ZcYJ512, XnmHjS1EWcSJ7PDUCqmhNmXEYF8pS5RTWRP1zxPwB5Q.
• The date calendar spans the first through latest exact-byte 00/01/03 activity, clipped to Jul 22, 2025 onward and the requested range. Outside those bounds amounts are null. Covered days inside those bounds with no active pairs are exposed as zero for chart continuity (the SQL omits such rows).
• Failed transaction logs are included for this new series because the supplied SQL has no success filter. This does not change the existing burn/buyback policy.
• Decimal arithmetic avoids binary floating-point rounding. These are calculated estimates, not payouts, claims or wallet transfers.

DC burns and exclusions

Exact mint: EuQUMH9gyJ2s2GEyA1wpLcsZ694m5hDDWyemrwX1EouU, Token-2022 with 9 decimals. “DC” is a display label from program logs, not a verified metadata symbol. These are not ONO burns.

Store every matching executed burn/burnChecked instruction before applying any exclusion. Failed transaction calls are included to match the supplied query's lack of a success-only filter; message instructions after the failure are omitted. Instruction amounts are not necessarily committed supply reductions. Missing/truncated relevant logs stop the page without advancing the cursor.

The two TXT files are the only source of DC exclusions. There are no hidden transaction or log-address fallback lists in code. The distributed defaults contain the five transaction signatures and five log-address rules from the supplied SQL. Deleting/commenting a rule changes the calculation; emptying both files removes all configurable DC exclusions. ONO/BONO, buybacks and rewards are unaffected.

Transaction signatures

config/dc-exclusions.txt: one full Solana signature per line. A signature alone excludes all matching DC burns in that transaction. Blank lines, duplicate entries and # comments are ignored. Optional exact instruction selection remains supported:

# Examples only: replace placeholder signatures with real full signatures.
FULL_TRANSACTION_SIGNATURE
ANOTHER_FULL_SIGNATURE 2.0 # just one DC burn instruction

Instruction IDs are zero-based; 2.0 means the first inner instruction under the third outer instruction. It does not match 2.1. Find IDs and current rule matches in stored raw DC data:

curl "http://localhost:8000/api/v1/dc/events?signature=FULL_TRANSACTION_SIGNATURE"

The endpoint reads raw DC events within the latest snapshot's watermark, including events currently excluded by either TXT file. It never downloads a transaction. Copy events[].instruction exactly. An empty result means no stored DC burn under that signature, not proof that the transaction does not exist on chain.

Addresses in transaction logs

config/dc-excluded-log-addresses.txt: one full Solana address per line, with the same blank-line/comment rules. Exclude a DC burn if any full transaction log contains a listed address as a substring. Merely appearing in account keys is not sufficient. The decoder retains base58-run evidence from all logs, including parent-program lines after the Token-2022 CPI, so rule changes do not require downloading or replaying raw receipts again.

Applying and undoing changes

Both files are covered by the existing read-only Compose config-directory mount. Save the files on the host; image rebuild/restart is not needed after normal rule edits. The worker checks during collection cycles and every 2 seconds while idle. It prepares a new daily DC cache from stored raw events, preserving lifetime carry-in for cumulative charts. Raw event IDs/amounts/sequences and all pagination boundaries remain intact.

Changing rules promptly returns cache_state: "preparing" and null amounts until the worker's matching cache is ready; old totals are never represented as newly filtered. Invalid or missing files return 503 from DC endpoints only, with an actionable file/line error. Other metrics continue. Correct the file to recover. dc_exclusions reports fingerprint, applied, transaction_rules, log_address_rules and active_rules; excluded_event_count counts excluded instructions once even if multiple rules match.

One-time upgrade from versions 0.5.x / 0.6.0

Older DC decoders discarded excluded burns before storing events, and did not retain log evidence on accepted events. Moving the lists alone cannot recover those old omissions. The new decoder must not silently label that old data reversible: DC responses expose cache_state: "migration_required" and null amounts until a local upgrade succeeds. ONO/BONO/reward history remains available.

Stop the worker, build the new application image, then inspect the read-only dry run:

docker compose stop worker
docker compose build
docker compose run --rm worker ono upgrade-dc-events

If the report is dry_run with no missing boundary receipts or stored-event archives, apply:

docker compose run --rm worker ono upgrade-dc-events --apply
docker compose up -d api worker

This command reads locally archived receipts only: no RPC calls and no database reset. It restores omitted DC burns and enriches old DC metadata, preserving existing amounts/IDs/sequences. A raw-schema marker is added to the DC cursor; head/oldest/forward boundaries and all other stream cursors are preserved. The write is atomic; decode conflicts/truncated relevant evidence roll back event/marker changes. The DC cache is rebuilt after committing the recovered events.

The dry run checks archive transaction counts against committed DC scanning progress, available pagination boundary receipts and archives for stored DC events. It is not an independent proof of archival completeness. If the archive is missing required data, the command returns blocked without applying writes. Restore missing transaction_archive data from a backup or investigate the report; do not delete the database or mark the stream complete manually. Fresh databases need no upgrade and use raw storage from their first page.

History response semantics

/history/dc/burns: daily amount is masked to the last 12 calendar months by UTC request date; months sum visible daily flow. A boundary month can be partial. Older masked dates are omitted from the dashboard axis/table, while the API retains nulls. /history/dc/cumulative-burns: lifetime total at day end or the last selected day of each month; never sum cumulative points. All eligible burns before the selected display start remain in the opening balance. No ONO adjustment is applied.

Both accept inclusive start/end and granularity=day|month (default month). Default start is the earliest eligible burn; end is capped to snapshot day. A fully covered zero-event day has zero flow and carried cumulative balance. GET reads prepared data, never source event history or RPC. Independent Dune parity remains unverified. Optional environment overrides: DC_EXCLUSIONS_FILE and DC_EXCLUDED_LOG_ADDRESSES_FILE; no environment changes are required for the default paths.

Removed legacy endpoints

/api/v1/buyback-burn, /api/v1/daily/burns and /api/v1/daily/buybacks have been removed and return 404. Use /api/v1/overview for totals and /api/v1/history/burns or /api/v1/history/buybacks with granularity=day|month for charts. All 18 /metrics fields remain; total_all_accounts is a token amount, not a count.

Prepared rewards history

The worker materializes daily rewards from persisted events, independently of chart requests. Changing dates or day/month grouping reads this prepared series; GET never reloads score events or contacts Helius. The series is reused across snapshots until reward source events change. cache_state is indexing, preparing or ready. On upgrade, the first preparation uses the existing database: no transaction re-download or cursor reset. While preparing, the API returns promptly with null amounts rather than calculating inside the request.

Operational notes

streams in /status exposes history_exhausted, head_caught_up, error and progress. Stream kind reward_state tracks the new reward program. Downloaded transactions and matched events are different counts. Restart resumes persisted cursors; chart filtering reads the database and does not re-download transactions. The first rewards scan is separate and needs full program history, including history before the visible date range. Keep the PostgreSQL volume when upgrading.

The interactive explorer at /docs requires its upstream Swagger assets to be reachable; this guide is bundled locally and works without them.