REST · Markets

All market-data endpoints are public (no auth required). Responses use snake_case keys.

#GET /v1/markets

GET/v1/marketsPublic

List of markets (supports filtering, sorting, and pagination).

#Query parameters

Name	Type	Description	Default
status	"ACTIVE" \| "RESOLVED" \| "CANCELLED"	Filter by status. Only these three values are accepted — LOCKED and PENDING return 400.	ACTIVE
category	"CRYPTO" \| "SPORTS" \| "POLITICS" \| "ENTERTAINMENT" \| "SCIENCE" \| "FINANCE" \| "OTHER"	Filter by category.	—
subCategory	string (≤50 chars)	Filter by sub-category (exact match against the stored raw value, e.g. 'Bitcoin').	—
q	string	Keyword search (case-insensitive substring match over question and description).	—
sortBy	"VOLUME" \| "LIQUIDITY" \| "CREATED" \| "TRENDING" \| "ENDING"	Sort key.	CREATED
sortOrder	"ASC" \| "DESC"	Sort direction.	DESC
limit	number (1..100)	Number of items to return per page.	20
offset	number (≥0)	Number of items to skip.	0

Unknown query parameters are rejected with 400 (property <name> should not exist).

#Response 200

{
  "markets": [
    {
      "id": "uuid",
      "slug": "btc-100k-by-eoy",
      "question": "Will BTC break $100,000 by December 31?",
      "description": "...",
      "category": "CRYPTO",
      "sub_category": "Bitcoin",
      "type": "BINARY",
      "status": "ACTIVE",
      "trading_starts_at": "2026-01-01T00:00:00+00:00",
      "trading_ends_at": "2026-12-31T23:59:59+00:00",
      "resolution_date": null,
      "winning_outcome_id": null,
      "winning_outcome": null,
      "resolved_at": null,
      "settled_at": null,
      "resolved_by": null,
      "resolution_source": null,
      "resolution_note": null,
      "platform_fee": 0.02,
      "spread": 1,
      "total_volume": 15234.5,
      "comments_count": 12,
      "image_url": "https://conviction-image.s3.amazonaws.com/...",
      "video_url": null,
      "video_poster_url": null,
      "video_source_url": null,
      "video_provider": null,
      "video_status": null,
      "external_source": null,
      "tags": ["bitcoin", "macro"],
      "views": 12345,
      "verified": true,
      "featured": false,
      "created_at": "2026-01-15T10:00:00+00:00",
      "updated_at": "2026-04-20T03:21:00+00:00",
      "outcomes": [
        {
          "id": "uuid",
          "market_id": "uuid",
          "name": "Yes",
          "side": "YES",
          "index": 0,
          "probability": 42,
          "description": null,
          "image_url": null,
          "color": null,
          "question_id": "0x...",
          "condition_id": "0x...",
          "position_id": "53...long-int...",
          "payout_wei": null,
          "created_at": "2026-01-15T10:00:00+00:00",
          "updated_at": "2026-04-20T03:21:00+00:00"
        },
        {
          "id": "uuid",
          "market_id": "uuid",
          "name": "No",
          "side": "NO",
          "index": 1,
          "probability": 58,
          "description": null,
          "image_url": null,
          "color": null,
          "question_id": "0x...",
          "condition_id": "0x...",
          "position_id": "98...long-int...",
          "payout_wei": null,
          "created_at": "2026-01-15T10:00:00+00:00",
          "updated_at": "2026-04-20T03:21:00+00:00"
        }
      ]
    }
  ],
  "total": 347,
  "limit": 20,
  "offset": 0
}

#Field notes

Field	Meaning
`status`	One of `PENDING`, `ACTIVE`, `LOCKED`, `RESOLVED`, `CANCELLED`. The list only returns the three filterable states; a market fetched by id or slug can be in any of the five.
`platform_fee`	Taker fee rate as a fraction — `0.02` = 2% (200 bps).
`spread`	Price tick in cents, as an integer — `1` = $0.01.
`total_volume`	Cumulative traded volume in USDT (decimal number, not wei).
`outcomes[].probability`	The outcome's current probability as a percent, 0..100 (two decimals). This is not the 0..1 price used by the order book and price history — divide by 100 to compare. On a settled market it follows the payout (winner 100, loser 0; a cancelled market shows its payout ratio).
`outcomes[].question_id` / `condition_id` / `position_id`	On-chain identifiers. `position_id` is the ERC-1155 position id as a decimal string. All three are `null` until the market is registered on-chain.
`outcomes[].payout_wei`	Per-share payout in 18-decimal wei, written when the market settles; `null` otherwise.
`winning_outcome_id` / `winning_outcome`	The winning outcome (`winning_outcome` is the full outcome object) once resolved; `null` before.
`resolved_at` / `resolved_by` / `resolution_source` / `resolution_note`	Resolution metadata shown to users; `null` until filled in.
`settled_at`	When the resolution or cancellation landed on chain; `null` while the market is open. Unlike `resolved_at`, it is also set for cancelled markets.
`external_source`	`null` for native markets; the venue name (e.g. `"predict_fun"`) for a market mirrored from an external venue.
`video_url` / `video_poster_url` / `video_source_url` / `video_provider` / `video_status`	Optional market video; all `null` when the market has none.

#Example

curl 'https://api.conviction.bet/v1/markets?status=ACTIVE&category=CRYPTO&sortBy=VOLUME&limit=10'

#GET /v1/markets/{id}

GET/v1/markets/{id}Public

Fetch a single market by UUID.

#Path parameters

Name	Type	Description	Default
id*	uuid	Market ID.	—

#Response 200

A superset of a list item (a single object). Compared with a list item it:

adds total_liquidity (USDT resting on the book), top_traders[] (username, profile_image_url, volume), comments[] (up to 50, each with a user object), and external_market_id
may add price_market, predict_market, and creator objects when the market is a price market, a mirrored market, or was created by a user
omits comments_count

#Errors

404 — Market not found: <id>

#GET /v1/markets/slug/{slug}

GET/v1/markets/slug/{slug}Public

Fetch a single market by URL-friendly slug.

#Path parameters

Name	Type	Description	Default
slug*	string	Market slug. e.g. "btc-100k-by-eoy"	—

#Response 200

Same as above.

#GET /v1/markets/{id}/orderbook

GET/v1/markets/{id}/orderbookPublic

The order book for a specific outcome.

#Path parameters

Name	Type	Description	Default
id*	uuid	Market ID.	—

#Query parameters

Name	Type	Description	Default
outcomeId*	uuid	Outcome ID — an outcomes[].id from the market response.	—

#Response 200

{
  "outcome_id": "uuid",
  "outcome_side": "Yes - YES",
  "bids": [
    { "price": "0.420", "shares": "1234.50" },
    { "price": "0.410", "shares": "899.00" }
  ],
  "asks": [
    { "price": "0.450", "shares": "567.20" },
    { "price": "0.460", "shares": "880.10" }
  ]
}

Field	Meaning
`outcome_side`	A display label, `"<outcome name> - <side>"` (e.g. `"Yes - YES"`, `"Brazil - NO"`) — not an enum. Use `outcome_id` to identify the outcome.
`bids`	Buy orders, descending by price (highest first)
`asks`	Sell orders, ascending by price (lowest first)
`price`	A 0..1 price as a string with three decimals
`shares`	Total shares at that level as a string with two decimals

For a native market, only limit orders are listed — a market order's unfilled rest is never shown — and crossing orders are netted out first, so the book shows what remains after they match. Levels holding 0.05 shares or less are left out. A mirrored market (external_source set) passes the venue's book through.

#Errors

400 — outcomeId is required (a plain string, not an array), or Outcome does not belong to this market
404 — Market not found: <id> or Outcome not found

#GET /v1/markets/slug/{slug}/orderbook

GET/v1/markets/slug/{slug}/orderbookPublic

Fetch the order book by slug. Same response format as above.

#GET /v1/markets/{id}/prices-history

GET/v1/markets/{id}/prices-historyPublic

An outcome's price history (for line charts).

#Query parameters

Name	Type	Description	Default
outcomeId*	uuid	Outcome ID.	—
startTs	unix seconds	Start time.	now − 7 days
endTs	unix seconds	End time.	now
fidelity	minutes (1, 5, 15, 60, ...)	Bucket size.	1

#Response 200

{
  "history": [
    { "t": 1740000000, "p": 0.41 },
    { "t": 1740000060, "p": 0.42 },
    { "t": 1740000120, "p": 0.43 }
  ]
}

Field	Meaning
`t`	unix seconds (start of the bucket)
`p`	the last trade price in that bucket (0..1 float)

The window is capped

Without startTs you get the last 7 days, not the full history. A request also reads at most the 1,000 most recent trades in the window before bucketing, so on a busy market a long range is truncated at the old end — page backwards with endTs to walk further into the past.

#GET /v1/markets/slug/{slug}/prices-history

GET/v1/markets/slug/{slug}/prices-historyPublic

Fetch the price history by slug. Same response format.

#Next

Documentation → Core concepts — a deeper look at market structure and lifecycle
Pagination — the common convention for list endpoints

Was this page helpful?