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

# AI Oracle

> Understanding the delphAI oracle system and how AI resolves prediction markets

## What is an AI Oracle?

An **AI oracle** is a system that uses artificial intelligence to fetch real-world data and resolve onchain prediction markets automatically.

delphAI combines:

* **AI agents** that understand questions and fetch relevant data
* **Smart contracts** that enforce resolution onchain
* **Cryptographic proofs** that verify data authenticity

## Why AI for Oracles?

Traditional oracles rely on humans or simple scripts. AI oracles offer unique advantages:

<CardGroup cols={2}>
  <Card title="Natural Language Understanding" icon="comment">
    AI can parse complex questions and understand resolution criteria written in plain English
  </Card>

  <Card title="Multi-Source Verification" icon="layer-group">
    AI can query multiple data sources simultaneously and cross-verify information
  </Card>

  <Card title="Context Awareness" icon="brain">
    AI understands nuance and can handle edge cases that simple scripts would miss
  </Card>

  <Card title="Adaptive Learning" icon="arrows-rotate">
    AI improves over time based on resolution history and feedback
  </Card>
</CardGroup>

## How delphAI Works

### Architecture Overview

```mermaid theme={null}
graph TB
    A[Market Request] --> B[Resolution Scheduler]
    B --> C{Time Reached?}
    C -->|Yes| D[AI Agent Activated]
    D --> E[Parse Question & Criteria]
    E --> F[Fetch Data from Sources]
    F --> G[AI Analysis]
    G --> H{Confidence > Threshold?}
    H -->|Yes| I[Submit Resolution Onchain]
    H -->|No| J[Flag for Review]
    I --> K[Platform Receives Result]

    style D fill:#D4AF37
    style G fill:#D4AF37
```

### Resolution Process

<Steps>
  <Step title="Schedule Registration">
    When a platform requests resolution:

    ```solidity theme={null}
    oracle.requestResolution(
        marketId,
        "Will BTC reach $100k by Dec 31, 2025?",
        resolutionTime,
        "Use CoinGecko API. Check price at 23:59 UTC."
    )
    ```

    delphAI registers the market and schedules the AI agent.
  </Step>

  <Step title="Automated Trigger">
    At the exact resolution time:

    * Blockchain triggers the oracle contract
    * Oracle activates the assigned AI agent
    * No human intervention needed
  </Step>

  <Step title="Data Collection">
    The AI agent:

    * Parses the resolution criteria
    * Identifies required data sources
    * Queries APIs (CoinGecko, news APIs, etc.)
    * Collects multiple data points for verification
  </Step>

  <Step title="AI Analysis">
    The AI evaluates the data:

    * Applies logic from resolution criteria
    * Cross-references multiple sources
    * Checks for anomalies or inconsistencies
    * Calculates confidence score
  </Step>

  <Step title="Onchain Submission">
    If confidence threshold is met:

    * AI submits the resolution to smart contract
    * Includes cryptographic proof of data sources
    * Emits event for listening platforms
    * Market is marked as resolved
  </Step>
</Steps>

## Data Sources

delphAI's AI can access various types of data:

### Financial Data

<AccordionGroup>
  <Accordion title="Cryptocurrency Prices" icon="bitcoin">
    * **CoinGecko**: Comprehensive crypto price data
    * **CoinMarketCap**: Market cap and price information
    * **DEX Aggregators**: Onchain price feeds
    * **CEX APIs**: Binance, Coinbase, Kraken

    Example: "BTC price on Dec 31, 2025 at 23:59 UTC"
  </Accordion>

  <Accordion title="Traditional Finance" icon="chart-line">
    * **Stock APIs**: Yahoo Finance, Alpha Vantage
    * **Forex**: Exchange rate providers
    * **Commodities**: Gold, oil, wheat prices
    * **Economic Indicators**: GDP, unemployment, inflation

    Example: "S\&P 500 closing price on market close"
  </Accordion>
</AccordionGroup>

### Sports & Events

<AccordionGroup>
  <Accordion title="Sports Results" icon="futbol">
    * **Official League APIs**: NBA, NFL, FIFA
    * **Sports Data Providers**: ESPN, The Sports DB
    * **Live Score APIs**: Real-time game data

    Example: "Lakers vs Warriors final score on Feb 15, 2025"
  </Accordion>

  <Accordion title="Entertainment" icon="film">
    * **Box Office**: Movie revenue data
    * **Streaming**: Netflix/Spotify charts
    * **Awards**: Oscar, Grammy, Emmy results

    Example: "Best Picture winner at 2025 Oscars"
  </Accordion>
</AccordionGroup>

### Real-World Data

<AccordionGroup>
  <Accordion title="Weather & Climate" icon="cloud">
    * **Weather APIs**: OpenWeatherMap, NOAA
    * **Climate Data**: Temperature, precipitation
    * **Natural Events**: Hurricanes, earthquakes

    Example: "Temperature in NYC on Christmas Day at noon"
  </Accordion>

  <Accordion title="Political & Social" icon="landmark">
    * **Election Results**: Official government sources
    * **Polling Data**: Verified polling organizations
    * **Legislative Actions**: Bill tracking, votes

    Example: "Winner of 2026 US midterm election in District X"
  </Accordion>
</AccordionGroup>

### Onchain Data

<AccordionGroup>
  <Accordion title="Blockchain Events" icon="link">
    * **Token Transfers**: Whale movements
    * **Smart Contract Events**: Protocol actions
    * **DeFi Metrics**: TVL, volume, fees
    * **NFT Sales**: Floor prices, volume

    Example: "Total ETH staked on Ethereum by Jan 1, 2026"
  </Accordion>
</AccordionGroup>

## AI Capabilities

### Natural Language Processing

The AI can understand complex questions:

**Simple**: "Will BTC reach \$100k?"

* Direct price check

**Complex**: "Will Bitcoin's price on CoinGecko exceed \$100,000 at any point during December 2025?"

* Requires historical data scanning
* Time range analysis
* Peak detection

**Nuanced**: "Will the Lakers win more than 50% of their regular season games in 2024-25?"

* Requires counting wins/losses
* Calculating percentage
* Understanding sports seasons

### Multi-Source Verification

For critical resolutions, AI queries multiple sources:

```javascript theme={null}
// Example: Verifying election result
sources = [
  "Official Government API",
  "Associated Press",
  "Reuters",
  "Multiple news outlets"
]

// AI cross-references all sources
// Only resolves if consensus is reached
```

### Edge Case Handling

AI can handle unexpected situations:

<CardGroup cols={2}>
  <Card title="Data Source Down" icon="plug-circle-xmark">
    Automatically falls back to secondary sources specified in criteria
  </Card>

  <Card title="Ambiguous Outcome" icon="question">
    Flags market for manual review if confidence is too low
  </Card>

  <Card title="Partial Data" icon="puzzle-piece">
    Attempts to infer outcome from available related data
  </Card>

  <Card title="Contradictory Sources" icon="scale-unbalanced">
    Applies weighting based on source reliability
  </Card>
</CardGroup>

## Confidence Scoring

Every resolution includes a confidence score:

| Score   | Meaning         | Action                   |
| ------- | --------------- | ------------------------ |
| 95-100% | Certain         | Auto-resolve immediately |
| 80-94%  | High confidence | Auto-resolve with proof  |
| 60-79%  | Moderate        | Flag for verification    |
| 0-59%   | Low confidence  | Escalate to dispute      |

**Factors affecting confidence**:

* Source agreement (all sources say same thing)
* Data quality (official vs unofficial)
* Criteria clarity (unambiguous vs vague)
* Historical accuracy (source reliability)

## Security & Trust

### How to Trust AI Resolutions?

<AccordionGroup>
  <Accordion title="Transparent Data Sources" icon="eye">
    Every resolution includes:

    * List of APIs queried
    * Exact data received
    * Timestamps of queries
    * Source URLs

    All verifiable by anyone onchain.
  </Accordion>

  <Accordion title="Cryptographic Proofs" icon="lock">
    AI submits cryptographic proofs:

    * Data signatures from sources
    * Hash of raw data
    * Proof of execution

    Impossible to fake or manipulate.
  </Accordion>

  <Accordion title="Dispute Mechanism" icon="gavel">
    If resolution is contested:

    * Users can stake tokens to dispute
    * Community reviews the data
    * Potential re-resolution if error found
    * Disputer rewarded if correct
  </Accordion>

  <Accordion title="Reputation System" icon="star">
    AI agents have reputation scores:

    * Based on resolution accuracy
    * Disputed resolutions lower score
    * High-reputation agents get more markets
  </Accordion>
</AccordionGroup>

### Limitations & Risks

<Warning>
  **Be aware of limitations:**

  * AI relies on external data sources (if all sources are wrong, AI will be wrong)
  * Extremely ambiguous questions may not resolve with high confidence
  * New types of questions may require AI training/updates
  * Highly subjective questions are not suitable for AI resolution
</Warning>

## Best Practices for Platforms

When integrating delphAI:

### Write Clear Resolution Criteria

✅ **Good Example**:

```
"Use CoinGecko API endpoint /simple/price for Bitcoin (BTC).
Check price at 2025-12-31 23:59:59 UTC.
If price >= $100,000, resolve to YES.
If price < $100,000, resolve to NO.
If CoinGecko is down, use CoinMarketCap as backup."
```

❌ **Bad Example**:

```
"Check if Bitcoin reaches 100k by end of year"
```

### Specify Reliable Sources

* Use established, reputable data providers
* Specify exact API endpoints when possible
* Provide backup sources for redundancy
* Avoid sources known for downtime

### Set Appropriate Resolution Times

* Allow sufficient time for data to be available
* Consider timezone differences
* Account for API update delays
* Avoid microsecond-level precision unless necessary

## Next Steps

<CardGroup cols={2}>
  <Card title="Resolution Criteria" icon="list-check" href="/ai-oracle/resolution-criteria">
    Learn how to write effective resolution criteria
  </Card>

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

  <Card title="Oracle Contract" icon="file-contract" href="/contracts/oracle-contract">
    Explore the smart contract interface
  </Card>

  <Card title="AI Reliability" icon="shield-check" href="/ai-oracle/reliability">
    Deep dive into AI reliability and accuracy
  </Card>
</CardGroup>