# Oracles and Pricing

## Goals

1. track a fair “spot” for each skin (per market-relevant variant)
2. make it hard to spoof (wash trades, thin-book spikes, stale quotes)
3. keep the feed cheap + fast enough for funding, margin, and liquidations

***

### 1) Data sources

**Aggregators & APIs**

* **Pricempire**: multi-market aggregator with a real API (current + historical, volume stats, wear/sticker meta). Use as your *primary* consolidation layer and to quickly fan out to per-market quotes.
* **Skinport**: stable, well-documented REST API; good for executable spot quotes.
* **Steam Community Market**: official pricehistory endpoint; useful for baseline + long tails, but beware fees and different liquidity regime.
* **BUFF163**: no official API but will fetch these prices from Pricempire when available considering it has the deepest liquidity of any market available at the moment

***

### 2) What’s a contract and what’s an item?

Skins come in many **variants** (wear/float, stickers, pattern index). We will list:

* **Specific-item perps** (e.g., “AK-47 | Redline (Field-Tested)”), or
* **Index perps** (a “collection floor” for X class of items).

***

### 3) Oracle architecture

**A. Fast path (real-time mark/reference)**

* Poll Pricempire (and direct markets) every few seconds for **best bid/ask + last trade** per venue.
* Compute a **venue-weighted median** of *midprices*, with **liquidity weights** (recent volume × active listings) and **latency decay** (quotes older than N seconds down-weighted).
* Publish this “**Oracle Spot**” every \~3s (same cadence as hl). Use it in the **mark price** and **funding basis**.

**B. Robust path (safety backstop)**

* Maintain a rolling **VWAP/TWAP** over 15–60 min per venue; compute a **trimmed-median index** across venues (drop top/bottom outliers by %).
* If the fast path trips guardrails, **fall back** to the robust index until conditions normalize.&#x20;

***

### 4) Normalization

Before aggregation, **normalize** quotes:

* **Fees & currency**: convert all venues to net proceeds (buyer/seller fees, FX).
* **Liquidity screen**: require minimum active listings and recent trades per venue to be eligible for weighting.

***

### 5) Manipulation resistance

Borrowing from Hyperliquid “robust price indices” plus NFT floor pricing practice:\
**Outliers & stale data**

* **Trimmed set**: per tick, drop quotes beyond **k·MAD** (median absolute deviation) from the venue-weighted median.
* **Stale cutoff**: any quote older than, say, **15–30s** excluded or heavily down-weighted.
* **Depth check**: ignore prints whose size would not clear at least *dollars X* or *Y items* at the venue’s current book protects against micro-size wash spikes.

**Venue trust & dilution**

* **Dynamic venue weights**: function of 24h volume, current depth, uptime, and historical deviation from cross-venue medians.
* **Steam vs. OTC markets**: account for Steam fee regime; treat Steam as *signal* but not sole anchor.

**Wash-trade filters**

* Per venue, require **distinct counterparties**, minimum notional, and **time-separation**; de-prioritize self-matched or ping-pong patterns

**Circuit breakers & fallbacks**

* If fast-path deviates > **X%** from robust TWAP (or if eligible venues < M), freeze to robust index and widen funding caps until recovery

***

### 6) What the DEX *actually* uses

**Mark price** (for PnL, margin, liquidations):

* Median of: {fast-path Oracle Spot, robust TWAP index, last on-chain mid (if orderbook), and a safety “reference” (e.g., Steam 24h VWAP net of fees)} with caps on pairwise divergence.

**Funding rate** (keep perp in line with spot):

* Hourly: `funding = clamp( k * (PerpIndex - OracleSpot) / OracleSpot , ±cap )`. Use the **Oracle Spot** as the external anchor like Hyperliquid; cap funding during oracle fallbacks.&#x20;

**Index governance**

* List only items whose venues pass liquidity/uptime SLOs; add/remove venues by governance and auto-scoring (volume, quote quality, downtime).

***

### 7) On-chain availability

* Publish the oracle on-chain every few seconds via a **validator set** or **keepers**.&#x20;
* Expose a **precompile or lightweight view** (if on your own L2/appchain) or a simple **Oracle contract** with: `getPrice(id)`, `getTWAP(id, window)`, `isFallback(id)` and **round IDs** for auditability

***

#### TL;DR blueprint

* Aggregate **many venues** (via **Pricempire** + direct APIs). Normalize for fees/variants.
* Compute a **liquidity-weighted median** fast price, updated every \~3s. Backstop with a **trimmed, multi-venue TWAP**.
* Use a **median of robust components** as your **mark**; anchor **funding** to the oracle spot; enforce **outlier, staleness, and depth** guards; and **fall back** cleanly under stress.
