Best Practices - delphAI Oracle

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

Clear Question

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?”

Specific Data Sources

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”

Precise Timing

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”

Explicit Logic

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.

Recommended Data Sources by Category

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:

Criteria	What to Look For
Reliability	99%+ uptime, established provider
Accuracy	Official or widely trusted source
Accessibility	Public API, no authentication required (when possible)
Freshness	Real-time or frequent updates
Documentation	Clear API docs available

Market Timing

Set appropriate resolution times for accurate data availability.

Resolution Time Guidelines

Crypto Price Markets

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)

Sports Markets

Recommended gap: 1-2 hours after game endReason: Official scores may take time to finalize, especially with reviewsExample: Game ends ~9pm → Resolution time 11pm

Financial Markets

Recommended gap: 30 minutes after market closeReason: Closing prices need time to settle and propagateExample: NYSE closes 4pm ET → Resolution time 4:30pm ET

Political Events

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

Data Source Unavailable

Solution: Specify backup sources and retry policy

If CoinGecko API returns error:
Wait 5 minutes, retry
If still failing, use CoinMarketCap
If both failing, delay resolution by 1 hour
After 3 delays, trigger emergency resolution

Exact Threshold

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 >)

Event Cancelled

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

Data Discrepancy

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

Read Aloud Test

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

Data Availability Check

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

Edge Case Review

List all possible edge cases and confirm your criteria addresses them

Simulation

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

Peer Review

Have another developer review your criteria for ambiguities

Common Mistakes to Avoid

Top mistakes when creating markets:

Vague data sources: “Check the price online” → Specify exact API
Missing timezone: “Jan 1, 2026” → Add timezone (prefer UTC)
No backup plan: Single data source → Always have backup
Ambiguous logic: Unclear YES/NO conditions → Be explicit
Too complex: Multi-part conditions → Keep it simple
Subjective terms: “Good”, “high”, “significant” → Use numbers
Unrealistic timing: Resolution too soon after event → Add buffer
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

​Overview

​Writing Resolution Criteria

​Good Resolution Criteria Example

​Bad Resolution Criteria Example

​Resolution Criteria Checklist

​Choosing Data Sources

​Recommended Data Sources by Category

Cryptocurrency Prices

Sports Results

Weather Data

Financial Markets

Political Events

Onchain Data

​Data Source Quality Criteria

​Market Timing

​Resolution Time Guidelines

​Market Close vs Resolution Time

​Market Question Design

​Question Types That Work Well

Price Comparisons

Binary Events

Numeric Thresholds

Rankings

​Question Types to Avoid

​Multiple Outcome Markets

​Good Multiple Choice Design

​Edge Case Handling

​Common Edge Cases

​Testing Your Criteria

​Testing Checklist

​Common Mistakes to Avoid

​Examples by Category

​Cryptocurrency

​Sports

​Weather

​Next Steps

Market Lifecycle

AI Oracle

Security Best Practices

Integration Guide

Overview

Writing Resolution Criteria

Good Resolution Criteria Example

Bad Resolution Criteria Example

Resolution Criteria Checklist

Choosing Data Sources

Recommended Data Sources by Category

Data Source Quality Criteria

Market Timing

Resolution Time Guidelines

Market Close vs Resolution Time

Market Question Design

Question Types That Work Well

Question Types to Avoid

Multiple Outcome Markets

Good Multiple Choice Design

Edge Case Handling

Common Edge Cases

Testing Your Criteria

Testing Checklist

Common Mistakes to Avoid

Examples by Category

Cryptocurrency

Sports

Weather

Next Steps