REST · Markets

市场数据全部为 public（无需认证）端点。响应键名为 snake_case。

#GET /v1/markets

GET/v1/markets公开

市场列表（支持过滤、排序、分页）。

#Query parameters

名称	类型	说明	默认值
status	"ACTIVE" \| "RESOLVED" \| "CANCELLED"	按状态过滤。仅接受这三个值——LOCKED 和 PENDING 会返回 400。	ACTIVE
category	"CRYPTO" \| "SPORTS" \| "POLITICS" \| "ENTERTAINMENT" \| "SCIENCE" \| "FINANCE" \| "OTHER"	按分类过滤。	—
subCategory	string (≤50 chars)	按子类别筛选(与存储的原始值精确匹配,如 'Bitcoin')。	—
q	string	关键词搜索（对问题和描述做不区分大小写的子串匹配）。	—
sortBy	"VOLUME" \| "LIQUIDITY" \| "CREATED" \| "TRENDING" \| "ENDING"	排序基准。	CREATED
sortOrder	"ASC" \| "DESC"	排序方向。	DESC
limit	number (1..100)	单页返回的条目数。	20
offset	number (≥0)	跳过的条目数。	0

未定义的查询参数会被 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
}

#字段说明

字段	含义
`status`	`PENDING`、`ACTIVE`、`LOCKED`、`RESOLVED`、`CANCELLED` 之一。列表只返回可过滤的三种状态；通过 id 或 slug 查询的市场可能处于五种状态中的任意一种。
`platform_fee`	Taker 手续费率（小数）——`0.02` = 2%（200 bps）。
`spread`	价格最小变动单位（美分，整数）——`1` = $0.01。
`total_volume`	累计成交量（USDT，小数，非 wei）。
`outcomes[].probability`	该结果当前概率，以百分比（0..100）表示（两位小数）。它不是盘口和时序价格使用的 0..1 价格——比较时请除以 100。已结算市场按赔付值显示（胜出 100、未胜出 0；取消的市场显示赔付比例）。
`outcomes[].question_id` / `condition_id` / `position_id`	链上标识符。`position_id` 是 ERC-1155 仓位 id 的十进制字符串。市场在链上注册之前，三者均为 `null`。
`outcomes[].payout_wei`	每份的结算金额（18 位小数 wei），在市场结算时写入；其他情况为 `null`。
`winning_outcome_id` / `winning_outcome`	结算后的获胜结果（`winning_outcome` 是完整的结果对象）；结算前为 `null`。
`resolved_at` / `resolved_by` / `resolution_source` / `resolution_note`	展示给用户的结算元数据；填写前为 `null`。
`settled_at`	结算或取消在链上生效的时间；市场进行中为 `null`。与 `resolved_at` 不同，取消的市场也会记录。
`external_source`	原生市场为 `null`；从外部平台镜像的市场为平台名称（如 `"predict_fun"`）。
`video_url` / `video_poster_url` / `video_source_url` / `video_provider` / `video_status`	市场视频（可选）；没有视频时全部为 `null`。

#示例

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

#GET /v1/markets/{id}

GET/v1/markets/{id}公开

通过 UUID 查询单个市场。

#Path parameters

名称	类型	说明	默认值
id*	uuid	市场 ID。	—

#Response 200

是列表条目的超集（单个对象）。与列表条目相比：

增加 total_liquidity（盘口中挂单的 USDT）、top_traders[]（username、profile_image_url、volume）、comments[]（最多 50 条，每条带 user 对象）和 external_market_id
若为价格市场、镜像市场或用户创建的市场，可能分别增加 price_market、predict_market、creator 对象
不包含 comments_count

#Errors

404 —— Market not found: <id>

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

GET/v1/markets/slug/{slug}公开

通过 URL 友好的 slug 查询单个市场。

#Path parameters

名称	类型	说明	默认值
slug*	string	市场 slug。例如："btc-100k-by-eoy"	—

#Response 200

与上面相同。

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

GET/v1/markets/{id}/orderbook公开

特定结果的盘口。

#Path parameters

名称	类型	说明	默认值
id*	uuid	市场 ID。	—

#Query parameters

名称	类型	说明	默认值
outcomeId*	uuid	结果 ID——市场响应中的 outcomes[].id。	—

#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" }
  ]
}

字段	含义
`outcome_side`	显示用标签 `"<结果名称> - <side>"`（如 `"Yes - YES"`、`"Brazil - NO"`）——不是枚举。请用 `outcome_id` 识别结果。
`bids`	买入挂单，价格降序（最高者在前）
`asks`	卖出挂单，价格升序（最低者在前）
`price`	0..1 的价格，三位小数的 string
`shares`	该价位的总数量，两位小数的 string

原生市场只列出限价单 —— 市价单的未成交部分不会显示；相互可成交的订单会先相抵，因此盘口显示的是撮合之后剩余的状态。数量不超过 0.05 份的价位不会返回。镜像市场（设置了 external_source）直接返回外部平台的盘口。

#Errors

400 —— outcomeId is required（字符串，而非数组），或 Outcome does not belong to this market
404 —— Market not found: <id> 或 Outcome not found

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

GET/v1/markets/slug/{slug}/orderbook公开

通过 slug 查询盘口。响应格式与上面相同。

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

GET/v1/markets/{id}/prices-history公开

结果的时序价格（用于折线图）。

#Query parameters

名称	类型	说明	默认值
outcomeId*	uuid	结果 ID。	—
startTs	unix seconds	开始时刻。	当前 − 7 天
endTs	unix seconds	结束时刻。	当前
fidelity	minutes (1, 5, 15, 60, ...)	分桶大小。	1

#Response 200

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

字段	含义
`t`	unix seconds（分桶起始时刻）
`p`	该分桶的最后成交价格（0..1 float）

查询区间有上限

省略 startTs 时返回的是最近 7 天，而不是全部历史。此外，一次请求在分桶前最多只读取区间内最近的 1,000 笔成交，因此在成交活跃的市场请求较长区间时，较早的部分会被截断——要继续向前查询，请逐步前移 endTs。

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

GET/v1/markets/slug/{slug}/prices-history公开

通过 slug 查询时序。响应格式相同。

#下一步

Documentation → 核心概念 —— 深入了解市场结构与生命周期
分页 —— list 端点通用约定

本页面是否有帮助？