Paid Settlement API

The public settlement layer remains free to read through UMA, on-chain logs, and Arweave references. The paid API is for platforms that need operator-grade settlement risk data before or during their own market-resolution workflow.

This API is not a consumer stats feed. It exposes PropsOracle's settlement decision record for a market.

Endpoint

GET /functions/v1/settlement-api?market_id=0x...
GET /functions/v1/settlement-api/markets/0x...
GET /functions/v1/settlement-api?external_provider=kalshi&external_market_id=KX...
GET /functions/v1/settlement-api?external_provider=polymarket&external_market_id=0x...
GET /functions/v1/settlement-api?external_provider=kalshi&external_event_id=KX...

Public requests require no API key. Paid requests use either header:

Authorization: Bearer po_live_...
x-props-oracle-key: po_live_...

External Kalshi and Polymarket lookups require paid access. Public callers can still read finalized settlement data by PropsOracle market_id and verify it against UMA and Arweave.

Field Access

Data	Public Arweave / UMA / on-chain	Paid API
Final market result	Yes	Yes
Final stat value	Yes	Yes
Risk level	No	Yes
Postponement reason	No	Yes
Trigger codes	No	Yes
Stat-change history	No	Yes
Recommended settlement time	No	Yes
Evidence package for operators	No	Yes
Kalshi/Polymarket event IDs	No	Yes
Kalshi/Polymarket market IDs	No	Yes

Consumption Flow

A partner service should call the API with the identifier it already has. For example, a Kalshi-indexed service can poll by Kalshi market ID:

GET /functions/v1/settlement-api?external_provider=kalshi&external_market_id=KXJUDGEHITS
Authorization: Bearer po_live_...

The API resolves the external market to a PropsOracle market_id, loads the canonical event, and returns settlement data plus all known external mappings for that event and market.

Client behavior should be simple:

If market.status is pending, keep the local market pending.
If market.status is void, apply the client's voiding or fallback policy.
If market.status is manual_review, apply the client's fallback policy.
If market.status is resolved and the returned risk is acceptable for the client's policy, settle from final_market_result or final_stat_value.
If risk.risk_level is HIGH or CRITICAL, hold or route to review according to the client's settlement policy.
If independent verification is needed, use ids.props_oracle.market_id, ids.props_oracle.canonical_event_id, public_sources.uma, and public_sources.arweave.

Event-level lookup is for discovery. It returns the mapped PropsOracle event and the PropsOracle markets currently mapped to the external event:

GET /functions/v1/settlement-api?external_provider=polymarket&external_event_id=poly-event
Authorization: Bearer po_live_...

Public Response Shape

{
  "access_tier": "public",
  "ids": {
    "props_oracle": {
      "market_id": "0x...",
      "canonical_event_id": "0x...",
      "game_id": 42
    }
  },
  "market": {
    "market_id": "0x...",
    "market_ticker": "MLB-NYY-BOS-JUDGE-HITS-1_5",
    "game_id": 42,
    "canonical_event_id": "0x...",
    "oracle_player_id": "0x...",
    "market_key": "batter_hits",
    "stat_type_code": 200,
    "line_value": 1.5,
    "comparator": "OVER",
    "status": "resolved",
    "final_market_result": "YES",
    "final_stat_value": 2,
    "resolved_at": "2026-05-13T03:30:00Z"
  },
  "game": {
    "league_code": "MLB",
    "sport_key": "baseball_mlb",
    "home_team": "NYY",
    "away_team": "BOS",
    "commence_time": "2026-05-12T23:05:00Z",
    "canonical_state": "Final"
  },
  "public_sources": {
    "uma": {
      "assertion_id": "0x...",
      "tx_hash": "0x...",
      "target_chain": "polygon_amoy",
      "status": "posted",
      "signal_bucket": "LOW"
    },
    "on_chain": {
      "canonical_event_id": "0x...",
      "assertion_type": "MARKET_RESOLUTIONS"
    },
    "arweave": {
      "tx_id": "..."
    }
  }
}

Paid Additions

Paid responses include the public shape plus:

{
  "ids": {
    "props_oracle": {
      "market_id": "0x...",
      "canonical_event_id": "0x...",
      "game_id": 42
    },
    "external": {
      "events": [
        {
          "provider": "kalshi",
          "external_event_id": "KXEVENT",
          "external_event_ticker": "KXMLB",
          "external_event_slug": null,
          "url": "https://kalshi.com/markets/KXMLB"
        }
      ],
      "markets": [
        {
          "provider": "polymarket",
          "external_market_id": "0x...",
          "external_market_slug": "judge-over-1-5-hits",
          "external_event_id": "poly-event",
          "url": "https://polymarket.com/market/judge-over-1-5-hits"
        }
      ]
    }
  },
  "risk": {
    "risk_level": "LOW",
    "prescan_risk_level": "LOW",
    "challenge_window_hours": 2,
    "settlement_delay_min": 75,
    "recommended_settlement_time": "2026-05-13T04:00:00.000Z",
    "postponement_reason": null,
    "trigger_codes": ["T2", "INFIELD_SINGLE_ADVANCE"],
    "trigger_details": [],
    "stat_change_history": []
  },
  "operator_evidence": {
    "evidence_package_for_operators": {
      "arweave_tx_id": "...",
      "arweave_manifest": {},
      "uma_metadata": "Volatility: LOW",
      "volatility_report": {},
      "market_volatility_report": {},
      "state_transition_history": []
    }
  }
}

stat_change_history includes revision snapshots and raw snapshot data. operator_evidence includes the staged Arweave manifest and volatility report used by operators and disputers. These fields are deliberately absent from public responses.

External mappings are convenience metadata for integration. Settlement authority remains the PropsOracle market_id, canonical_event_id, UMA assertion, and Arweave evidence.

API Keys

Paid API keys are stored as SHA-256 hashes in api_clients. A key must be active and include the settlement:read scope. Raw keys are never stored.

Manual Mapping Upsert

Until automated Kalshi and Polymarket feed syncs are live, operators can populate mappings through the service-role-only admin-upsert-external-mappings function. The function accepts event and market batches and validates that referenced PropsOracle games and markets exist before writing.