Appearance
TWAP Oracle
Coda prices cards using a Time-Weighted Average Price (TWAP) oracle. The methodology is documented here so integrators and auditors can understand how prices are derived and verify that outputs are consistent.
Algorithm: twap_24h_outlier_v3_floor_q20
This is the current methodology key. It is stored on every oracle snapshot so results are reproducible by window and methodology.
Steps
1. Ingest
Reference prices are pulled nightly from PriceCharting and stored with full provenance. eBay sold listings are ingested continuously.
2. Fetch observations
All observations for the product's condition group are fetched over a prefetch window wider than the requested window_hours to support outlier and floor computations.
3. Filter to window
Apply the requested window_hours cutoff (default 24h).
4. Outlier removal
Observations beyond N standard deviations from the mean are dropped (N = outlier_stddevs, default 2). This removes data entry errors and anomalous transactions.
5. Time-weighted average
TWAP is computed over the remaining observations, producing a baseline truth_price_minor in integer cents.
6. Trimmed median blend
A trimmed median is computed on the same observations. If the TWAP diverges significantly from the median, the two are blended using proprietary weights. This limits tail-driven distortions without discarding time weighting.
7. Floor guard
A price floor is applied using eBay and PriceCharting sources:
- Quantile-based floor (not raw minimum)
- Minimum depth and source diversity checks
- Maximum downward adjustment cap
8. Return
TwapOracleResult with price_minor, included_points, excluded_points, window bounds, and meta.
Grade-band blend (grades 1-9)
After the floor step, grades 1-9 apply a composite band blend that incorporates market-level grade signals alongside the card-specific TWAP. The exact weighting is proprietary.
| Band | Source field | Market signal |
|---|---|---|
GRADE7 | cib-price | PSA 7, BGS 7, etc. |
GRADE8 | new-price | PSA 8, BGS 8, etc. |
GRADE9 | graded-price | PSA 9, BGS 9, etc. |
On live oracle calls, the band leg uses a 30-day rolling window. Grade 10 has no band blend. Grades 1-6 use the GRADE7 band as a proxy.
meta diagnostic fields
| Key | Meaning |
|---|---|
source_counts | Observation counts by source (ebay, pricecharting) |
slab_grade_band_blend_pre_minor | TWAP before band blend |
slab_grade_band_blend_post_minor | TWAP after band blend |
slab_grade_band_blend_band_minor | Composite band price used |
slab_grade_band_blend_band_points | Band observation count |
grade_band_twap_effective_window_hours | Window used for band leg |
slab_grade_band_live_historical_band_window | true when 30-day band window is active |
slab_grade_band_proxy_to_grade7_band | true for grades 1-6 |
Data sources
| Source | Cadence | Notes |
|---|---|---|
| eBay sold listings | Real-time | Highest volume source |
| PriceCharting | Daily | Reference prices, market data, and composite bands |
Idempotency
Snapshots have a unique constraint on (product_definition_id, window_start, window_end, methodology). Re-running the same window returns the same result.