Oracle System
The oracle is the automated system that fetches external data and determines market outcomes.
How it works
Market closes (trading stops)
↓
Oracle cron runs every 10 minutes
↓
Fetches data from specified source(s)
↓
Applies resolution rule
↓
If confident: settles market
If uncertain: retries (Pending Recheck)
If conflict: flags for review (Needs Review)Oracle states
| State | Meaning | Next action |
|---|---|---|
| Open | Market is live; oracle not yet active | Wait for trading to close |
| Pending Recheck | Oracle ran but data was inconclusive or API unavailable | Retry on next cycle (every 10 min) |
| Needs Review | Oracle detected a data conflict it cannot resolve automatically | Admin verifies and settles manually |
| Resolved | Outcome confirmed; market settled | Done |
Data sources
Bags.fm graduation markets
| Check | Source | What it verifies |
|---|---|---|
| Token status | Bags.fm Public API v1 /token-launch/feed | status == MIGRATED |
| Pool existence | Helius Solana RPC getAccountInfo | DAMM v2 pool account exists on-chain |
Both checks must pass for YES. A NO requires only the deadline to pass with no graduation.
Bags.fm fee race markets
| Check | Source | What it verifies |
|---|---|---|
| Current fees | Bags.fm Public API v1 /token-launch/lifetime-fees | Fee growth since market open |
Fee snapshot at open is recorded at market creation. Resolver fetches current fees and computes delta.
Resolution audit trail
Every oracle attempt is logged to the bags_resolution_snapshots table. You can view the full history on any token detail page at /solana/bags/{mint}.
Each snapshot records:
- Timestamp of the attempt
- Observed Bags status at that moment
- DAMM pool key found (if any)
- On-chain confirmation result
- Outcome of the attempt (skipped / pending / YES / NO / needs_review)
- Reason code
Resolution is auditable. No hidden decisions — every oracle run is logged and visible on the token’s detail page.
Manual resolution
If a market enters Needs Review, an admin reviews the resolution snapshots and external data, then settles manually via the admin API.
Manual resolution requires documented evidence matching the resolution rule. Admin cannot settle based on judgment alone — the logged data must support the outcome.
What happens if the oracle fails permanently?
If a market cannot be resolved (e.g. data source permanently down), Cupdiction will void the market and refund all stakes.
This scenario is rare and would be communicated via the platform and community channels.