Oracle

Why a public surface

Prediction markets only work if traders can verify outcomes themselves. We publish the full resolution pipeline so you can audit every decision. Outcomes are proposed under bond by a KYC-verified user, exposed via public read endpoints during a 2-hour dispute window, and auto-finalised if no one disputes. If a dispute upholds and escalates, the final outcome is decided by a panel of voters — every step is queryable on-chain-style through the oracle endpoints.

• Anyone can list markets currently in the dispute window and read the proposed winner.
• Anyone can list markets that closed but have not yet been resolved — useful for watchdogs.
• Anyone can list every resolved and settled market in history, with the winning outcome attached.

Public endpoints

Three GET endpoints carry the entire transparency surface. None require authentication. All paginate with the standard page and size parameters; results are filterable by category and search query.

# All three endpoints are public — no auth required.
curl https://staging.satoriex.io/api/v1/oracle/verify?page=1&size=50
curl https://staging.satoriex.io/api/v1/oracle/propose
curl https://staging.satoriex.io/api/v1/oracle/settled?category=politics

These endpoints are intentionally cacheable. Watchdog services typically poll /verify every few minutes during dispute windows.

Response shape

All three endpoints return the same envelope — a paginated list of markets, each with its outcomes, current price, dispute count, and dispute end time. Field names match the underlying market model.

{
  "code": 0,
  "data": {
    "markets": [{
      "id": "mkt_01H...",
      "title": "Will the central bank cut rates in May?",
      "status": "resolved",
      "winning_outcome_id": "out_01H...",
      "resolved_at": "2026-05-08T14:02:31Z",
      "dispute_end_time": "2026-05-09T14:02:31Z",
      "dispute_count": 0,
      "outcomes": [{ "id": "out_01H...", "label": "Yes", "price_bps": 7400 }]
    }],
    "total": 1247,
    "page": 1,
    "size": 50
  }
}

The resolution action

Reading the oracle is open. Acting on it is not. The single mutating endpoint, POST /oracle/resolve, accepts a winning outcome and an HMAC-SHA256 signature over the resolution payload.

POST /api/v1/oracle/resolve
Content-Type: application/json

{
  "market_id":           "mkt_01H...",
  "winning_outcome_id":  "out_01H...",
  "timestamp":           "2026-05-11T14:02:31Z",
  "signature":           "<HMAC-SHA256 over: market_id:winning_outcome_id:unix_ts>"
}

# Signature pre-image uses ':' as delimiter and the unix epoch
# seconds form of timestamp. Requests older than 5 minutes are
# rejected as replay-suspect.

• Requires a server-side shared secret — never expose the signing key in client code.
• Signature pre-image is `market_id:winning_outcome_id:unix_ts`. Requests older than 5 minutes are rejected as replay-suspect.
• Only the server-side oracle service can produce a valid signature — the signing key never leaves the server, and it is held by SatoriEx super-admins.
• Two-person approval still applies — see the Resolution concept page for the full lifecycle.

Trust model at a glance

Different actions require different privileges. Anything you can read is public; anything you can write requires a bonded user account — proposing an outcome locks the proposer's bond, and filing a dispute locks the disputer's bond. Both bonds settle predictably from the outcome of the dispute window or voter panel.

Two-person approval is enforced server-side. The same admin account cannot both propose and confirm.