Oracle API

Resolve PAX prediction markets as an optimistic-oracle provider. Mint a key, register, and post a bonded attestation — all curl, no SDK.

The oracle lives on its own host: https://origin.predictasiax.com — the PAX resolution gateway, separate from the trading host api.predictasiax.com. Every curl on this page targets that host. Public reads need no key; writes need an api-key carrying the oracle:write scope. Unlike the trading API, oracle responses are returned directly (they are not wrapped in the { data, meta } envelope).

How resolution works

PAX settles markets with an optimistic oracle: an outcome is accepted as true unless someone pays to contest it inside a time window. Economics — not permissions — secure honesty, so becoming a resolver is permissionless and requires no KYC.

If no one disputes before the deadline, the attestation finalizes in the proposer's favor automatically and the proposer's bond is returned. If it is disputed, an adjudication decides the winner: the correct party is made whole and rewarded out of the loser's slashed bond, and any slashed remainder accrues to the public forfeit pool.

Current protocol parameters (env-configurable; the authoritative values for any single attestation are always the bond_pax and liveness_expires_at fields on that attestation):

Authentication

Write endpoints (register, propose, challenge) require an oracle api-key with the oracle:write scope. Send it either way:

-H "Authorization: Bearer sk_live_..."     # or, equivalently:
-H "X-API-Key: sk_live_..."

Public reads (list providers, read an attestation, read the pool) take no key. The api-key is bound to your PAX user; the gateway resolves your identity from the key and ignores any client-supplied X-PAX-User-Id header.

Step 1 — Get an oracle api-key

Keys are minted against your platform login. The easiest path is the Oracle Provider console in the builder portal — log in, open Oracle Provider, and click to generate. The key is shown once; copy it immediately.

Programmatically, mint with a platform session or builder-portal token (not an api-key):

curl -X POST https://origin.predictasiax.com/v1/provider/keys \
  -H "Authorization: Bearer <your platform session token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-resolver"}'

Response — copy key immediately, it is shown only once:

{
  "key":        "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "sk_live_a1b2c3",
  "scopes":     ["oracle:write", "read"],
  "name":       "my-resolver",
  "note":       "store this key now; it is shown only once"
}

# Save it:
export OK=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Each user may hold up to 5 active keys. List them with GET /v1/provider/keys and revoke one with DELETE /v1/provider/keys/{id} (metadata only — secret material is never returned again).

Step 2 — Register as a provider

Create your resolver identity. adapter_kind is one of feed, official_source, regional_data, or manual; display_name is 1–80 characters.

curl -X POST https://origin.predictasiax.com/v1/oracle/providers \
  -H "Authorization: Bearer $OK" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Acme Regional Desk",
    "adapter_kind": "regional_data"
  }'

Response — 201 with your new provider:

{
  "id":                 "ovp_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "user_id":            "usr_0011223344556677889900aabbccddee",
  "display_name":       "Acme Regional Desk",
  "adapter_kind":       "regional_data",
  "status":             "active",
  "staked_pax":         "0",
  "attestations_total": 0,
  "disputed_total":     0,
  "slashed_total":      0,
  "rewards_pax":        "0",
  "created_at":         "2026-10-09T04:10:30Z",
  "updated_at":         "2026-10-09T04:10:30Z"
}

Anyone can read a provider's public reputation with GET /v1/oracle/providers/{id}, or list active providers (most-attested first) with GET /v1/oracle/providers.

Step 3 — Check your PAX bond

Proposing and disputing both lock a PAX bond — it is the only hard gate. Read your own balances with your api-key:

curl https://origin.predictasiax.com/v1/oracle/bond-account \
  -H "Authorization: Bearer $OK"
{
  "user_id":       "usr_0011223344556677889900aabbccddee",
  "available_pax": "1000",
  "locked_pax":    "0"
}
Funding during bootstrap. There is no public self-serve top-up endpoint yet — bonds for the first wave of providers are provisioned by the PAX team. If available_pax is short, request a bond allocation through Request access. Your locked_pax rises while an attestation or dispute of yours is live and is released or slashed when it finalizes.

Step 4 — Propose an attestation

Assert the outcome of a market that has closed but is not yet resolved. Attach the evidence URLs a disputer (or you) would check.

curl -X POST https://origin.predictasiax.com/v1/oracle/attestations \
  -H "Authorization: Bearer $OK" \
  -H "Content-Type: application/json" \
  -d '{
    "market_id":        "mkt_aabbccddeeff00112233445566778899",
    "proposed_outcome": "YES",
    "evidence_urls":    ["https://example.gov/official-result"],
    "provider_id":      "ovp_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
  }'

Response — 201; your bond is now locked and the liveness clock starts:

{
  "id":                  "att_1a2b3c4d5e6f70819a2b3c4d5e6f7081",
  "market_id":           "mkt_aabbccddeeff00112233445566778899",
  "proposer_user_id":    "usr_0011223344556677889900aabbccddee",
  "provider_id":         "ovp_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "proposed_outcome":    "YES",
  "evidence_urls":       ["https://example.gov/official-result"],
  "bond_pax":            "1000",
  "state":               "proposed",
  "liveness_expires_at": "2026-10-10T04:10:30Z",
  "reward_pax":          "0",
  "created_at":          "2026-10-09T04:10:30Z",
  "updated_at":          "2026-10-09T04:10:30Z"
}

Common rejections: 402 if your available bond is short, 404 if the market does not exist, and 409 if the market is not closed yet or is already resolved. provider_id is optional — omit it to propose without crediting a provider.

Step 5 — Dispute within the window

While an attestation is proposed and before liveness_expires_at, any user other than the proposer can contest it with a matching bond:

curl -X POST https://origin.predictasiax.com/v1/oracle/attestations/att_1a2b3c4d5e6f70819a2b3c4d5e6f7081/challenge \
  -H "Authorization: Bearer $OK" \
  -H "Content-Type: application/json" \
  -d '{
    "disputer_outcome": "NO",
    "evidence_urls":    ["https://example.com/counter-evidence"]
  }'

Response — 200; the attestation moves to disputed and both bonds are locked pending adjudication:

{
  "id":                "att_1a2b3c4d5e6f70819a2b3c4d5e6f7081",
  "state":             "disputed",
  "disputer_user_id":  "usr_ffeeddccbbaa00998877665544332211",
  "disputer_outcome":  "NO",
  "disputer_bond_pax": "1000",
  "disputed_at":       "2026-10-09T09:12:00Z",
  "...":               "(remaining attestation fields unchanged)"
}

Rejections: 400 for an empty outcome or an attempt to dispute your own attestation, 402 for insufficient bond, and 409 if the attestation is no longer open or the window has closed. If no dispute arrives before the deadline, the attestation finalizes in the proposer's favor automatically — no further call is needed.

Step 6 — Read attestations and the pool

These reads are public (no key):

# A single attestation by id
curl https://origin.predictasiax.com/v1/oracle/attestations/att_1a2b3c4d5e6f70819a2b3c4d5e6f7081

# A market's most relevant attestation (open disputes first), or null
curl https://origin.predictasiax.com/v1/oracle/markets/mkt_aabbccddeeff00112233445566778899/attestation

# The forfeit pool (slashed bonds accrue here)
curl https://origin.predictasiax.com/v1/oracle/pool
{ "pool_pax": "0", "pool_cap": "100000", "overflow_pax": "0", "updated_at": "2026-10-09T04:10:30Z" }

Endpoint reference

Full request/response schemas are in the REST API reference (tagged Oracle and Provider Keys). Summary:

Writes need bond, not just a key. A fresh key with an empty bond account can register a provider but cannot propose or challenge. Fund the bond first (see Step 3), then your oracle:write calls go through.

Next steps