API Reference

Complete reference for the Oracle AI backend REST API.

Base URL

Production: https://api.oracleai.xyz
Development: http://localhost:3001

Authentication

Currently, the API is public and does not require authentication.

---

Endpoints

Health Check

GET /health

Check if the API is running.

Response:

{
  "status": "ok",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "version": "1.0.0"
}

---

Markets

GET /markets

List all prediction markets.

Query Parameters:

Response:

{
  "markets": [
    {
      "id": 0,
      "address": "0x1234...",
      "question": "Will ETH reach $5000?",
      "deadline": 1735689600,
      "state": "TRADING",
      "prices": {
        "yes": 0.65,
        "no": 0.35
      },
      "volume": "1000000000000000000000"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

---

GET /markets/:address

Get details for a specific market.

Response:

{
  "id": 0,
  "address": "0x1234...",
  "question": "Will ETH reach $5000 by Dec 31, 2024?",
  "resolutionCriteria": "Based on Coinbase price...",
  "deadline": 1735689600,
  "state": "TRADING",
  "finalOutcome": null,
  "creator": "0xabcd...",
  "prices": {
    "yes": 0.65,
    "no": 0.35
  },
  "reserves": {
    "yes": "500000000000000000000",
    "no": "500000000000000000000"
  },
  "volume": "1000000000000000000000",
  "evidenceUrls": [
    "https://coinbase.com/price/ethereum"
  ]
}

---

GET /markets/:address/trades

Get trade history for a market.

Response:

{
  "trades": [
    {
      "id": "0x...",
      "trader": "0x...",
      "type": "BUY",
      "outcome": "YES",
      "amount": "100000000000000000000",
      "cost": "65000000000000000000",
      "price": 0.65,
      "timestamp": 1704067500,
      "txHash": "0x..."
    }
  ],
  "total": 250
}

---

Resolvers

GET /resolvers

List all resolvers.

Query Parameters:

Response:

{
  "resolvers": [
    {
      "address": "0x...",
      "stakedAmount": "100000000000000000000000",
      "reputation": 150,
      "resolvedCount": 45,
      "correctCount": 43,
      "isActive": true,
      "accuracy": 0.9556
    }
  ],
  "total": 25
}

---

GET /resolvers/:address

Get resolver details.

Response:

{
  "address": "0x...",
  "stakedAmount": "100000000000000000000000",
  "reputation": 150,
  "resolvedCount": 45,
  "correctCount": 43,
  "isActive": true,
  "recentResolutions": [
    {
      "marketId": 42,
      "outcome": "NO",
      "correct": true,
      "reward": "10500000000000000000000"
    }
  ]
}

---

Statistics

GET /stats

Get protocol statistics.

Response:

{
  "markets": {
    "total": 150,
    "trading": 45,
    "resolution": 10,
    "finalized": 95
  },
  "volume": {
    "total": "1000000000000000000000000",
    "24h": "50000000000000000000000"
  },
  "resolvers": {
    "total": 25,
    "active": 20,
    "totalStaked": "5000000000000000000000000"
  }
}

---

Error Handling

Error Response Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Market not found"
  }
}

Error Codes