Skip to main content

​
Overview

Follow these best practices to create clear, resolvable prediction markets that work seamlessly with delphAI’s AI oracle.

​
Writing Resolution Criteria

The quality of your resolution criteria directly impacts how accurately delphAI can resolve your market.

​
Good Resolution Criteria Example

✅ Well-defined market: 
Question: "Will Bitcoin reach $100,000 by December 31, 2025?"

Resolution Criteria:
- Data Source: CoinGecko API (api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd)
- Backup Source: CoinMarketCap API
- Resolution Time: December 31, 2025 at 23:59:59 UTC
- Resolution Logic:
  * If BTC price >= $100,000 → YES
  * If BTC price < $100,000 → NO
- Require minimum 2 data sources to agree
Why it’s good:
  • ✅ Clear, unambiguous question
  • ✅ Specific data sources with exact endpoints
  • ✅ Precise resolution time with timezone
  • ✅ Explicit resolution logic
  • ✅ Backup data source specified
  • ✅ Verification requirements stated

​
Bad Resolution Criteria Example

❌ Poorly-defined market: 
Question: "Will Bitcoin do well this year?"

Resolution Criteria:
- Check if Bitcoin price goes up
Why it’s bad:
  • ❌ “Do well” is subjective and vague
  • ❌ No data source specified
  • ❌ No specific time or date
  • ❌ No clear YES/NO logic
  • ❌ No backup plan if data unavailable

​
Resolution Criteria Checklist

Requirements:
  • Binary (YES/NO) or clear multiple choice
  • Objectively verifiable
  • No ambiguous terms
  • Time-bound
Examples:✅ “Will ETH price exceed $5,000 on Jan 1, 2026 at 00:00 UTC?”❌ “Will ETH do well next year?”
Requirements:
  • Name exact APIs or data providers
  • Include API endpoints when possible
  • Specify multiple sources for redundancy
  • Use reputable, reliable sources
Examples:✅ “CoinGecko API endpoint: /api/v3/simple/price”❌ “Check crypto price websites”
Requirements:
  • Exact date and time
  • Specify timezone (prefer UTC)
  • Account for data availability delays
  • Consider market close vs resolution time
Examples:✅ “December 31, 2025 at 23:59:59 UTC”❌ “End of 2025”
Requirements:
  • Define exact conditions for each outcome
  • Handle edge cases (ties, nulls, etc.)
  • Specify rounding rules if needed
  • Define what happens if data unavailable
Examples:✅ “If price >= $100,000 resolve YES, if < $100,000 resolve NO”❌ “Resolve based on the price”

​
Choosing Data Sources

Select reliable data sources that the AI can access and verify.

Cryptocurrency Prices

Primary Sources:
  • CoinGecko
  • CoinMarketCap
  • Binance API
  • Coinbase API
Best for: Price predictions, market cap, volume

Sports Results

Primary Sources:
  • ESPN API
  • The Sports DB
  • Official league APIs
  • SportsData.io
Best for: Game scores, tournament results, player stats

Weather Data

Primary Sources:
  • OpenWeatherMap
  • NOAA (weather.gov)
  • WeatherAPI.com
  • AccuWeather API
Best for: Temperature, precipitation, forecasts

Financial Markets

Primary Sources:
  • Yahoo Finance
  • Alpha Vantage
  • TradingView
  • Bloomberg API
Best for: Stock prices, forex, commodities

Political Events

Primary Sources:
  • Official government sites
  • Associated Press
  • Reuters
  • Ballotpedia
Best for: Election results, legislation, votes

Onchain Data

Primary Sources:
  • Etherscan API
  • The Graph
  • Dune Analytics
  • DefiLlama API
Best for: Token transfers, protocol metrics, TVL

​
Data Source Quality Criteria

When selecting data sources:
CriteriaWhat to Look For
Reliability99%+ uptime, established provider
AccuracyOfficial or widely trusted source
AccessibilityPublic API, no authentication required (when possible)
FreshnessReal-time or frequent updates
DocumentationClear API docs available

​
Market Timing

Set appropriate resolution times for accurate data availability.

​
Resolution Time Guidelines

Recommended gap: 1-5 minutes after target timeReason: Prices update in real-time, brief delay ensures all sources syncedExample: Target time 23:59 UTC → Resolution time 00:01 UTC (next day)
Recommended gap: 1-2 hours after game endReason: Official scores may take time to finalize, especially with reviewsExample: Game ends ~9pm → Resolution time 11pm
Recommended gap: 30 minutes after market closeReason: Closing prices need time to settle and propagateExample: NYSE closes 4pm ET → Resolution time 4:30pm ET
Recommended gap: 24-48 hours after polls closeReason: Official results take time, especially with recountsExample: Election day Nov 5 → Resolution Nov 7

​
Market Close vs Resolution Time

Timeline Example:

Market Created: Dec 1, 2025
   ↓
[Users can trade]
   ↓
Market Closes: Dec 31, 2025 23:00 UTC  ← Last chance to bet
   ↓
[30 min buffer for event to complete]
   ↓
Resolution Time: Dec 31, 2025 23:59 UTC  ← AI resolves market
   ↓
Platform Settlement  ← Users claim winnings
Always leave a buffer between market close and resolution time to ensure the event has fully concluded and data is available.

​
Market Question Design

Create questions that are objectively resolvable.

​
Question Types That Work Well

Price Comparisons

“Will [ASSET] be >= $X on [DATE]?”Easy for AI to verify with price APIs

Binary Events

“Will [EVENT] happen by [DATE]?”Clear yes/no outcome

Numeric Thresholds

“Will [METRIC] exceed X by [DATE]?”Objective numeric comparison

Rankings

“Will [TEAM] finish in top 3 of [TOURNAMENT]?”Verifiable through official rankings

​
Question Types to Avoid

Avoid these question types:
  • ❌ Subjective: “Will the movie be good?” (opinion-based)
  • ❌ Vague: “Will crypto do well?” (undefined criteria)
  • ❌ Unverifiable: “Will aliens visit Earth?” (no data source)
  • ❌ Ambiguous: “Will it be sunny?” (where? when exactly?)
  • ❌ Complex logic: “Will A AND B OR C happen?” (hard to parse)

​
Multiple Outcome Markets

For markets with more than 2 outcomes, follow these guidelines.

​
Good Multiple Choice Design

Question: "Who will win the 2026 World Cup?"

Outcomes:
1. Brazil
2. Argentina
3. France
4. Germany
5. England
6. Other (any team not listed above)

Resolution Criteria:
- Data Source: Official FIFA website (fifa.com)
- Resolution Time: 1 hour after final match
- Logic: Winner is determined by FIFA official announcement
- If winner is in list (1-5), resolve to that outcome
- If winner is not in list, resolve to "Other"
Best Practices:
  • ✅ Include “Other” category for unlisted outcomes
  • ✅ Make outcomes mutually exclusive
  • ✅ Keep number of outcomes reasonable (5-10)
  • ✅ Use official source for verification

​
Edge Case Handling

Plan for unexpected scenarios.

​
Common Edge Cases

Solution: Specify backup sources and retry policy
If CoinGecko API returns error:
1. Wait 5 minutes, retry
2. If still failing, use CoinMarketCap
3. If both failing, delay resolution by 1 hour
4. After 3 delays, trigger emergency resolution
Solution: Define behavior for exact values
Question: "Will BTC reach $100,000?"

Clear definition:
- If price >= $100,000.00 → YES
- If price < $100,000.00 → NO
- If price = exactly $100,000.00 → YES (use >= not >)
Solution: Define cancellation behavior upfront
If game is cancelled:
- Return all funds to participants
- OR resolve based on official league ruling
- OR postpone resolution until rescheduled game
Solution: Require consensus from multiple sources
If sources disagree:
- Require minimum 2 out of 3 sources to agree
- If no consensus, delay and recheck
- If still no consensus after 3 attempts, trigger dispute

​
Testing Your Criteria

Before launching, test your resolution criteria.

​
Testing Checklist

1

Read Aloud Test

Read your criteria to someone unfamiliar with the market. Can they understand exactly how it will be resolved?
2

Data Availability Check

Verify all specified data sources are accessible and provide the expected data format
3

Edge Case Review

List all possible edge cases and confirm your criteria addresses them
4

Simulation

Imagine the event happening - can you clearly determine the outcome from your criteria?
5

Peer Review

Have another developer review your criteria for ambiguities

​
Common Mistakes to Avoid

Top mistakes when creating markets:
  1. Vague data sources: “Check the price online” → Specify exact API
  2. Missing timezone: “Jan 1, 2026” → Add timezone (prefer UTC)
  3. No backup plan: Single data source → Always have backup
  4. Ambiguous logic: Unclear YES/NO conditions → Be explicit
  5. Too complex: Multi-part conditions → Keep it simple
  6. Subjective terms: “Good”, “high”, “significant” → Use numbers
  7. Unrealistic timing: Resolution too soon after event → Add buffer
  8. No edge cases: Assuming perfect conditions → Plan for failures

​
Examples by Category

​
Cryptocurrency

Question: "Will ETH/BTC ratio exceed 0.08 on Feb 1, 2026?"

Resolution Criteria:
- Primary: CoinGecko ETH/BTC pair at 2026-02-01 00:00:00 UTC
- Backup: CoinMarketCap ETH and BTC prices, calculate ratio
- Logic: If ratio >= 0.08 → YES, else → NO
- Require 2 sources to agree within 0.001 tolerance

​
Sports

Question: "Will the Lakers win vs Warriors on Dec 25, 2025?"

Resolution Criteria:
- Primary: ESPN API final score
- Backup: NBA.com official box score
- Resolution Time: 2 hours after scheduled tip-off (accounts for delays)
- Logic: Team with higher final score wins
- If game postponed: Resolve based on rescheduled game

​
Weather

Question: "Will temperature in NYC exceed 90°F on July 4, 2025?"

Resolution Criteria:
- Primary: NOAA weather station at Central Park
- Backup: OpenWeatherMap for NYC
- Check maximum temperature between 00:00-23:59 EDT
- Logic: If max temp >= 90°F → YES, else → NO
- If both sources unavailable: Delay 6 hours, retry

​
Next Steps

Market Lifecycle

Understand the full market lifecycle

AI Oracle

Learn how delphAI resolves markets

Security Best Practices

Security guidelines for integration

Integration Guide

Start integrating delphAI
⌘I