# Prediction markets

- Method: `GET`
- Path: `/predictions`
- Credits: 1
- x402 wallet payment: https://nebula-api.hiddensystems.ai/api/v1/x402/predictions (no Nebula account or API key; check the payment offer before signing)
- Payment guide: https://docs.hiddensystems.ai/nebula/api/#x402
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-predictions/
- Interactive docs: https://docs.hiddensystems.ai/nebula/api/#endpoint=get-predictions

## Description

Browse Polymarket and Kalshi contracts. Prices are outcome probabilities from each venue, not social sentiment. Volume retains its venue unit. Equivalent contracts share a market; related contracts remain separate. Subject metrics use the existing subject and asset endpoints.

Parameter rules:
- Send `asset_class` and `asset_id` together, or neither.
- `subject_id` cannot be combined with `asset_id` or `asset_class`.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/predictions' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `query` (string, optional): Case-insensitive search across public identifiers and names.
- `provider` (string, optional, allowed: polymarket, kalshi): Optional venue
- `status` (string, optional, default: open, allowed: open, closed, resolved, disputed, all): Defaults to open
- `asset_id` (string, optional): Asset ID from /assets or /search, such as NVDA, GLD, SPX, or bitcoin. Send it with the asset_class returned alongside it.
- `asset_class` (string, optional, allowed: equity, commodity, index, crypto): Restricts results to one class: equity (stocks and ETFs), commodity, index, or crypto. Required when asset_id is sent.
- `subject_id` (string, optional): Canonical non-asset identifier returned by /subjects or /search, such as text:jensen huang or handle:elonmusk. Accepted in any case. It cannot be combined with asset_id or asset_class.
- `limit` (integer, optional, default: 25, range: 1–100): Maximum results returned.
- `offset` (integer, optional, default: 0, range: 0–10000): Pagination offset

## Response

OK

- `has_more` (boolean, required): True when another page is available after the returned records.
- `limit` (integer, required): Maximum records requested.
- `markets` (array<object>, required): Canonical markets, ordered by best activity rank within each venue. Venue volumes are not summed.
- `markets[].entities` (array<object>, required): Linked identities for existing analytics endpoints. Assets carry asset_id and asset_class; non-assets carry subject_id. An identity without selectors is not yet available for analytics.
- `markets[].entities[].asset_class` (string): Asset class: equity, commodity, index or crypto.
- `markets[].entities[].asset_id` (string): Asset identifier accepted by asset analytics endpoints.
- `markets[].entities[].name` (string, required): Canonical subject display name.
- `markets[].entities[].subject_id` (string): Non-asset subject identifier accepted by subject analytics endpoints. Mutually exclusive with asset selectors.
- `markets[].id` (string, required): Stable identity within this object type.
- `markets[].listings` (array<object>, required): Venue listings with separately retained rules and quotes.
- `markets[].listings[].closes_at` (string (date-time), required): Venue trading close in UTC; not necessarily event occurrence or settlement.
- `markets[].listings[].event_id` (string, required): Venue event identifier, or empty if absent.
- `markets[].listings[].id` (string, required): Stable identity within this object type.
- `markets[].listings[].liquidity_usd` (number (double), required): Venue-reported liquidity in US dollars; null when unavailable.
- `markets[].listings[].market_id` (string, required): Canonical market identity; equivalent venue listings share it.
- `markets[].listings[].observed_at` (string (date-time), required): UTC time Nebula fetched this quote. Inspect freshness before comparing.
- `markets[].listings[].open_interest` (number (double), required): Venue open contracts; null when unavailable.
- `markets[].listings[].opens_at` (string (date-time), required): Venue opening time in UTC; null when unavailable.
- `markets[].listings[].outcomes` (array<object>, required): Ordered native outcomes with independent price evidence.
- `markets[].listings[].provider` (string, required): Venue: polymarket or kalshi.
- `markets[].listings[].provider_id` (string, required): Native venue market identifier.
- `markets[].listings[].provider_updated_at` (string (date-time), required): Venue metadata update time; null when unavailable.
- `markets[].listings[].question` (string, required): Original contract question.
- `markets[].listings[].resolution_source` (string, required): Venue resolution source, or empty if absent.
- `markets[].listings[].resolves_at` (string (date-time), required): Venue expected resolution time in UTC; null when unavailable.
- `markets[].listings[].result` (string, required): Venue settlement result; empty before a known result.
- `markets[].listings[].revision` (string, required): Legacy contract revision token; retained for compatibility.
- `markets[].listings[].rules` (string, required): Full venue resolution rules.
- `markets[].listings[].source_url` (string, required): Original venue listing URL.
- `markets[].listings[].status` (string, required): Listing lifecycle: open, closed, resolved or disputed. For subjects: resolved or pending.
- `markets[].listings[].volume` (number (double), required): Cumulative venue volume in volume_unit; null when unavailable.
- `markets[].listings[].volume_24h` (number (double), required): Last 24-hour venue volume in volume_unit; null when unavailable.
- `markets[].listings[].volume_unit` (string, required): usd for Polymarket, contracts for Kalshi. These quantities cannot be added.
- `markets[].question` (string, required): Original contract question.
- `markets[].subjects` (array<object>, required): Legacy attachment metadata retained for compatibility. Use entities for analytics selectors.
- `markets[].subjects[].fallback_image_urls` (array<string>, required): Ordered backend-resolved fallback icon candidates.
- `markets[].subjects[].image_url` (string, required): First backend-resolved subject icon candidate; empty uses fallbacks.
- `markets[].subjects[].name` (string, required): Canonical subject display name.
- `markets[].subjects[].role` (string, required): Question attachment role: entity, topic or place.
- `markets[].subjects[].status` (string, required): Listing lifecycle: open, closed, resolved or disputed. For subjects: resolved or pending.
- `markets[].subjects[].subject_id` (string, required): Canonical registry subject identifier; preserves existing asset or topic eligibility.
- `markets[].subjects[].types` (array<string>, required): Canonical subject types from the existing identity resolver.
- `offset` (integer, required): Number of matching records skipped.

Media type: `application/json`

## JSON Response

```json
{
  "has_more": false,
  "limit": 50,
  "markets": [
    {
      "entities": [
        {
          "asset_class": "equity",
          "asset_id": "NVDA",
          "name": "NVIDIA",
          "subject_id": "text:jensen huang"
        }
      ],
      "id": "polymarket:123",
      "listings": [
        {
          "closes_at": "2026-10-07T20:00:00Z",
          "event_id": "event-123",
          "id": "polymarket:123",
          "liquidity_usd": 5000,
          "market_id": "polymarket:123",
          "observed_at": "2026-10-06T12:00:00Z",
          "open_interest": 100,
          "opens_at": "2026-10-01T00:00:00Z",
          "outcomes": [],
          "provider": "polymarket",
          "provider_id": "123",
          "provider_updated_at": "2026-10-06T12:00:00Z",
          "question": "Will NVIDIA close above $200 on October 7?",
          "resolution_source": "Official exchange close",
          "resolves_at": "2026-10-08T00:00:00Z",
          "result": "yes",
          "revision": "revision-hash",
          "rules": "Resolves Yes if the official closing price exceeds $200.",
          "source_url": "https://polymarket.com/event/example",
          "status": "open",
          "volume": 10000,
          "volume_24h": 1000,
          "volume_unit": "usd"
        }
      ],
      "question": "Will NVIDIA close above $200 on October 7?",
      "subjects": [
        {
          "fallback_image_urls": [],
          "image_url": "https://example.com/nvda.png",
          "name": "NVIDIA",
          "role": "entity",
          "status": "open",
          "subject_id": "eq:NVDA",
          "types": []
        }
      ]
    }
  ],
  "offset": 0
}
```