# Prediction Market

## Introduction

### What is an AI oracle for prediction markets?

Prediction markets require an non-human controlled oracle solution: when a market matures (e.g., a deadline passes or an event occurs), the protocol needs a **canonical, verifiable** and **objective** outcome to settle positions. Unlike continuous price feeds, many prediction questions are **discrete** (“Did X happen?”) or **timepoint-specific** (“Was BTC ≥ $Y at T?”), and frequently involve **unstructured evidence** (press releases, regulatory announcements, news).

**APRO AI Oracle** provides a hybrid, AI-assisted oracle design to serve this need:

* **Tier-1 (AI Oracle / OCMP Layer)** turns raw, multi-source data (prices, documents, news) into an **answer proposal** with provenance.
* **Tier-2 (Verdict Layer)** acts as an **escalation backstop** for disputes and abnormal cases, ensuring finality with staking/slashing economics.
* Results are returned in a **signed report** that your contracts/backends can verify and store.

This guide explains **how to integrate APRO AI Oracle** for prediction-market settlement, including architecture, recommended workflows, and **API usage strictly per APRO’s official AI Oracle API v1/v2** documentation.

***

### System Overview

![](https://sg439mfof6b.sg.larksuite.com/space/api/box/stream/download/asynccode/?code=ZTcxMmM5YzFmZDIzN2FlNDIzYmFlZjc2ZjYxZWJkOTVfMVBXZzNMbkdSTzNwamVlYXJNQlBMaUc0MDdsVEh4YXZfVG9rZW46SGc1SGJtWXk1b25QN1R4OHZZSGw0TnQ4Z3FiXzE3NjM1MjM1ODM6MTc2MzUyNzE4M19WNA)

* **Tier-1 (AI Parsing & Proposal):** Distributed nodes ingest market metadata and evidence sources (e.g., price data, official pages, reputable news). Nodes run extraction/LLM parsing pipelines and produce a **structured resolution proposal** (answer + timestamp + evidence summary), then coordinate off-chain to aggregate a single signed report.
* **Tier-2 (Dispute & Finality):** Only activates on **challenge/abnormality**. Tier-2 validators re-evaluate the same evidence set, audit the Tier-1 reasoning, and issue the **final verdict**. Staking and slashing make malicious proposals uneconomic.

**Benefits to prediction markets**

* **Timepoint resolution:** signed answers carry precise timestamps to anchor settlement windows.
* **Semantic capability:** Tier-1 can interpret natural-language questions and unstructured sources.
* **Auditability:** reports include signatures and structured fields you can verify and persist on-chain.
* **Dispute traceability:** Tier-2 yields a documented final decision for contentious cases.

***

### End-to-End Flow

```sql
[Market Maturity at T]
   |
   +-- Your backend calls APRO official API (v1/v2)
   |     - If price-based: /ticker/currency/price
   |     - (v2) If social evidence needed: /socialmedia/proxy (+ support_paths)
   |
   +-- Receive signed JSON (includes status/data/... and signatures where applicable)
   |     - Verify timestamps & (if present) signature[]
   |
   +-- Protocol dispute window
         - No dispute -> finalize with Tier-1 report
         - Dispute -> wait for APRO Tier-2 final report -> finalize
```

***

## Integration Guide (Prediction-Market Perspective)

### Register/Track Markets

* When creating a market, **store minimal metadata** your system and APRO nodes can reference:
  * `marketId` (or contract address), human-readable question, allowed outcomes, **resolution time**.
  * Expose this metadata on-chain or off-chain (e.g., IPFS) so oracles can fetch it.

### How to Receive the Answer

* **Pull model (common):** after maturity, your **backend service** calls APRO’s **official AI Oracle API** to retrieve the signed result.
* **On-chain write:** your backend (or a keeper bot) posts the verified result to your market contract (emit `AnswerResolved` and store).

**Important:** Align your **dispute window** with APRO’s posterior workflow. If you allow challenges in your protocol, finalize only after that window elapses or you receive a **final** (Tier-2) verdict.

### Objective price-based markets (threshold/target)

For questions like “Was **BTC ≥ $Y** at **T**?”:

* Use APRO’s **Ticker Price** endpoint (API v2) **at or near** the resolution time to fetch the **consensus price** in your quote currency.
* Store the **signed report** and its `timestamp` with your on-chain record; confirm it falls inside your allowed resolution window before settling.
* For robustness, fetch multiple times around the window (e.g., T, T+Δ) and select per your market rules.

### Determinate non-price events (documents/news)

Your protocol may frame **binary questions** around authoritative sources (e.g., “Did agency X publish policy Y by time T?”). Tier-1 parses evidence; the final **signed report** includes the answer and `timestamp`. Your integration is the **same pattern**: fetch the signed report from **official API** (v2) and record it.

***

## **APRO AI Oracle APIs**

### Base

* **Base URL (illustrative in docs examples):**  `https://api-ai-oracle.apro.com`
* **Versions:** `/v1/...` (no key), `/v2/...` (requires API key/secret)
* **Auth for v2:** Use headers (as documented):
  * `X-API-KEY: <your_key>`
  * `X-API-SECRET: <your_secret>`

### Supported Currencies (List)

**GET** `/v1/ticker/currencies/list` **Query**:

* `page` (number)
* `size` (number)

**Example:**

```
curl -X GET "https://api-ai-oracle.apro.com/v1/ticker/currencies/list?size=50&page=1" \ 
-H "accept: application/json"
```

**Response (shape per docs):**

```
{
    "status": {
        "timestamp": 1742456493281,
        "code": 200,
        "message": ""
    },
    "data": [
        {
            "name": "Aave",
            "symbol": "AAVE",
            "keywords": [
                "aave"
            ],
            "support_providers": [
                "AggregationCoinMarketCap",
                "AggregationCoinGecko",
                "DexAve",
                "DexDexTools"
            ]
        }
    ]
}
```

**API v2**: use `/v2/ticker/currencies/list` with the same params and include required auth headers.

### Currency Support

**GET** `/v1/ticker/currency/support` **Query**:

* `name` (string) — currency identifier (name/symbol/keyword)
* `restricted` (string) — `"strict"` (default) or `"relaxed"`

**Example:**&#x20;

```
curl -X GET "https://api-ai-oracle.apro.com/v1/ticker/currency/support?name=aave&restricted=strict" \ 
-H "accept: application/json"
```

**Response (shape per docs)**:

```
{
    "status": {
        "timestamp": 1742456976497,
        "code": 200,
        "message": ""
    },
    "data": {
        "name": "Chainlink",
        "symbol": "LINK",
        "keywords": [
            "chainlink"
        ],
        "support_providers": [
            "DexAve",
            "DexDexTools",
            "AggregationCoinMarketCap",
            "AggregationCoinGecko"
        ]
    }
}
```

**Note:** `restricted=strict` generally enforces a minimum number of independent providers; use per docs guidance.&#x20;

**API v2**: `/v2/ticker/currency/support` (same query + v2 auth headers).

### Currency Price (Consensus)

**GET** `/v1/ticker/currency/price` **Query**:

* `name` (string) — base currency
* `quotation` (string) — quote currency
* `type` (string) — aggregation method: `"median"` (default) or `"average"`

**Example:**

```
curl -X GET "https://api-ai-oracle.apro.com/v1/ticker/currency/price?name=aave&quotation=usd&type=median" \
-H "accept: application/json"
```

**Response (shape per docs)**:

```
{
  "status": { "timestamp": 1742457195612, "code": 200, "message": "" },
  "data": {
    "name": "Aave",
    "symbol": "AAVE",
    "quotes": "United States Dollar",
    "quotes_symbol": "USD",
    "price": 176.76901955342512,
    "report_type": "median",
    "timestamp": 1742457195543,
    "signature": [
      {
        "signer": "0xB8d7...63",
        "hash": "0x4238...33cd",
        "signature": "e847...e01",
        "timestamp": 1742457195520
      }
      /* ...more node signatures... */
    ],
    "prices": [
      {
        "name": "Aave",
        "symbol": "AAVE",
        "quotes": "United States Dollar",
        "quotes_symbol": "USD",
        "price": 176.76901955342512,
        "provider_name": "DexDexTools",
        "direct_price": true,
        "last_updated": 1742457192
      }
      /* ...more provider rows... */
    ]
  }
}
```

**API v2:** `/v2/ticker/currency/price` (same query + v2 auth headers).&#x20;

The **`signature` array** allows you to verify integrity and origin using APRO node public keys (per official docs). Use **`timestamp`** to anchor settlement time in your protocol’s rules.

**No new/undocumented endpoints or fields are introduced here.**&#x20;

For additional surfaces, consult the exact pages you provided:

* [*APRO AI Oracle API v2*](https://docs.apro.com/ai-oracle/getting-started/quickstart/apro-ai-oracle-api-v2)

***

## Contract & Backend Consumption (Recommended Pattern)

Although APRO’s AI Oracle is API-first for posterior resolution, prediction-market teams typically want **on-chain attestations**. A common approach:

* Your **backend** calls the official API (v1/v2) at/after maturity and receives the **signed JSON report**.
* Backend **verifies the signatures** off-chain (optional but recommended), then **submits the report blob** to your market contract.
* Your **contract** verifies the same signatures (using APRO’s published node keys) and stores `(answer/value, timestamp, reportHash)`.
* Emit an event like `AnswerResolved(marketId, valueOrYesNo, timestamp)` and proceed to settlement **after** your dispute window.

This section intentionally avoids naming any un-documented on-chain function signatures to keep the spec consistent with the **official API**. The essence is: **verify APRO’s `signature[]` and honor the `timestamp`**.

***

## Example Playbooks

### Binary price threshold

*“Was **ETH ≥ $4,000** at 2025-12-15 00:00:00 UTC?”*

* At maturity (≈ that timestamp), call:
* `GET /v2/ticker/currency/price?name=eth&quotation=usd&type=median`
* Check `data.timestamp` is within your resolution window; compare `data.price` vs threshold.
* Store the **signed report** and finalize per your protocol’s dispute rules.

### Numeric final value

*“Settle on the **BTC/USD** median price at 2025-12-15 00:00 UTC.”*

* Call the same endpoint at maturity; use `data.price` as the canonical value.
* Persist signatures and `timestamp` along with the settlement record.

### Determinate non-price event

*“Did **Agency X** publish policy **Y** by time **T**?”*

* Use `/v2/socialmedia/support_paths` to fetch the supported paths
* then call `/v2/socialmedia/proxy` with a supported `path` to request the platform data, obtain the signed response, and persist it on-chain / in your database.

***

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.apro.com/ai-oracle/getting-started/prediction-market.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.