> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delphai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Best practices for creating effective prediction markets with delphAI

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

<AccordionGroup>
  <Accordion title="Clear Question" icon="message-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?"
  </Accordion>

  <Accordion title="Specific Data Sources" icon="database">
    **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"
  </Accordion>

  <Accordion title="Precise Timing" icon="clock">
    **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"
  </Accordion>

  <Accordion title="Explicit Logic" icon="code">
    **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"
  </Accordion>
</AccordionGroup>

## Choosing Data Sources

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

### Recommended Data Sources by Category

<CardGroup cols={2}>
  <Card title="Cryptocurrency Prices" icon="bitcoin">
    **Primary Sources**:

    * CoinGecko
    * CoinMarketCap
    * Binance API
    * Coinbase API

    **Best for**: Price predictions, market cap, volume
  </Card>

  <Card title="Sports Results" icon="futbol">
    **Primary Sources**:

    * ESPN API
    * The Sports DB
    * Official league APIs
    * SportsData.io

    **Best for**: Game scores, tournament results, player stats
  </Card>

  <Card title="Weather Data" icon="cloud">
    **Primary Sources**:

    * OpenWeatherMap
    * NOAA (weather.gov)
    * WeatherAPI.com
    * AccuWeather API

    **Best for**: Temperature, precipitation, forecasts
  </Card>

  <Card title="Financial Markets" icon="chart-line">
    **Primary Sources**:

    * Yahoo Finance
    * Alpha Vantage
    * TradingView
    * Bloomberg API

    **Best for**: Stock prices, forex, commodities
  </Card>

  <Card title="Political Events" icon="landmark">
    **Primary Sources**:

    * Official government sites
    * Associated Press
    * Reuters
    * Ballotpedia

    **Best for**: Election results, legislation, votes
  </Card>

  <Card title="Onchain Data" icon="link">
    **Primary Sources**:

    * Etherscan API
    * The Graph
    * Dune Analytics
    * DefiLlama API

    **Best for**: Token transfers, protocol metrics, TVL
  </Card>
</CardGroup>

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

<AccordionGroup>
  <Accordion title="Crypto Price Markets" icon="bitcoin">
    **Recommended gap**: 1-5 minutes after target time

    **Reason**: Prices update in real-time, brief delay ensures all sources synced

    **Example**: Target time 23:59 UTC → Resolution time 00:01 UTC (next day)
  </Accordion>

  <Accordion title="Sports Markets" icon="trophy">
    **Recommended gap**: 1-2 hours after game end

    **Reason**: Official scores may take time to finalize, especially with reviews

    **Example**: Game ends \~9pm → Resolution time 11pm
  </Accordion>

  <Accordion title="Financial Markets" icon="chart-candlestick">
    **Recommended gap**: 30 minutes after market close

    **Reason**: Closing prices need time to settle and propagate

    **Example**: NYSE closes 4pm ET → Resolution time 4:30pm ET
  </Accordion>

  <Accordion title="Political Events" icon="vote-yea">
    **Recommended gap**: 24-48 hours after polls close

    **Reason**: Official results take time, especially with recounts

    **Example**: Election day Nov 5 → Resolution Nov 7
  </Accordion>
</AccordionGroup>

### 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
```

<Note>
  Always leave a buffer between market close and resolution time to ensure the event has fully concluded and data is available.
</Note>

## Market Question Design

Create questions that are objectively resolvable.

### Question Types That Work Well

<CardGroup cols={2}>
  <Card title="Price Comparisons" icon="greater-than-equal">
    "Will \[ASSET] be >= \$X on \[DATE]?"

    Easy for AI to verify with price APIs
  </Card>

  <Card title="Binary Events" icon="check">
    "Will \[EVENT] happen by \[DATE]?"

    Clear yes/no outcome
  </Card>

  <Card title="Numeric Thresholds" icon="hashtag">
    "Will \[METRIC] exceed X by \[DATE]?"

    Objective numeric comparison
  </Card>

  <Card title="Rankings" icon="ranking-star">
    "Will \[TEAM] finish in top 3 of \[TOURNAMENT]?"

    Verifiable through official rankings
  </Card>
</CardGroup>

### Question Types to Avoid

<Warning>
  **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)
</Warning>

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

<AccordionGroup>
  <Accordion title="Data Source Unavailable" icon="plug-circle-xmark">
    **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
    ```
  </Accordion>

  <Accordion title="Exact Threshold" icon="equals">
    **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 >)
    ```
  </Accordion>

  <Accordion title="Event Cancelled" icon="ban">
    **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
    ```
  </Accordion>

  <Accordion title="Data Discrepancy" icon="scale-unbalanced">
    **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
    ```
  </Accordion>
</AccordionGroup>

## Testing Your Criteria

Before launching, test your resolution criteria.

### Testing Checklist

<Steps>
  <Step title="Read Aloud Test">
    Read your criteria to someone unfamiliar with the market. Can they understand exactly how it will be resolved?
  </Step>

  <Step title="Data Availability Check">
    Verify all specified data sources are accessible and provide the expected data format
  </Step>

  <Step title="Edge Case Review">
    List all possible edge cases and confirm your criteria addresses them
  </Step>

  <Step title="Simulation">
    Imagine the event happening - can you clearly determine the outcome from your criteria?
  </Step>

  <Step title="Peer Review">
    Have another developer review your criteria for ambiguities
  </Step>
</Steps>

## Common Mistakes to Avoid

<Warning>
  **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
</Warning>

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

<CardGroup cols={2}>
  <Card title="Market Lifecycle" icon="circle-notch" href="/core-concepts/market-lifecycle">
    Understand the full market lifecycle
  </Card>

  <Card title="AI Oracle" icon="robot" href="/core-concepts/ai-oracle">
    Learn how delphAI resolves markets
  </Card>

  <Card title="Security Best Practices" icon="shield" href="/security/best-practices">
    Security guidelines for integration
  </Card>

  <Card title="Integration Guide" icon="code" href="/quickstart">
    Start integrating delphAI
  </Card>
</CardGroup>