REST · Markets

All market-data endpoints are public (no auth required).

#GET /v1/markets

GET/v1/marketsPublic

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

#Query parameters

Name	Type	Description	Default
status	"ACTIVE" \| "RESOLVED" \| "CANCELLED" \| "LOCKED" \| "PENDING"	Filter by status.	ACTIVE
category	"CRYPTO" \| "SPORTS" \| "POLITICS" \| "ENTERTAINMENT" \| "SCIENCE" \| "FINANCE" \| "OTHER"	Filter by category.	—
q	string	Keyword search (over question, description, and tags).	—
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

#Response 200

{
  "markets": [
    {
      "id": "uuid",
      "slug": "btc-100k-by-eoy",
      "question": "Will BTC break $100,000 by December 31?",
      "description": "...",
      "category": "CRYPTO",
      "type": "BINARY",
      "status": "ACTIVE",
      "trading_starts_at": "2026-01-01T00:00:00Z",
      "trading_ends_at": "2026-12-31T23:59:59Z",
      "resolution_date": null,
      "winning_outcome_id": null,
      "platform_fee": 200,
      "spread": 0.01,
      "image_url": "https://conviction-image.s3.amazonaws.com/...",
      "tags": ["bitcoin", "macro"],
      "views": 12345,
      "verified": true,
      "featured": false,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-04-20T03:21:00Z",
      "outcomes": [
        {
          "id": "uuid",
          "name": "Yes",
          "side": "YES",
          "index": 0,
          "probability": 0.42,
          "condition_id": "0x...",
          "position_id": "53...long-int..."
        },
        {
          "id": "uuid",
          "name": "No",
          "side": "NO",
          "index": 1,
          "probability": 0.58,
          "condition_id": "0x...",
          "position_id": "98...long-int..."
        }
      ]
    }
  ],
  "total": 347,
  "limit": 20,
  "offset": 0
}

#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

The same format as a single item in the list response above (a single object).

#Errors

404 — market does not exist

#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*	string	Outcome token ID. The outcomes[].id from the /v1/markets/{id} response	—

#Response 200

{
  "outcome_id": "uuid",
  "outcome_side": "YES",
  "bids": [
    { "price": "0.42", "shares": "1234.5" },
    { "price": "0.41", "shares": "899.0" }
  ],
  "asks": [
    { "price": "0.45", "shares": "567.2" },
    { "price": "0.46", "shares": "880.1" }
  ]
}

Field	Meaning
`bids`	Buy orders, descending by price (highest first)
`asks`	Sell orders, ascending by price (lowest first)
`price`	A string in 0..1
`shares`	A float string for UI display

#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 candle / line charts).

#Query parameters

Name	Type	Description	Default
outcomeId*	string	Outcome ID.	—
startTs	unix seconds	Start time.	—
endTs	unix seconds	End time.	—
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
`p`	the last trade price in that bucket (0..1 float)

#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?