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`	테이커 수수료율(분수) — `0.02` = 2% (200 bps).
`spread`	가격 단위(센트, 정수) — `1` = $0.01.
`total_volume`	누적 거래량 (USDT, 소수 — wei 아님).
`outcomes[].probability`	결과의 현재 확률을 퍼센트(0..100) 로 나타낸 값(소수 2자리). 호가창·시계열에서 쓰는 0..1 가격이 아닙니다 — 비교하려면 100 으로 나누세요. 정산된 시장은 지급값 기준입니다(승자 100·패자 0, 취소는 지급 비율).
`outcomes[].question_id` / `condition_id` / `position_id`	온체인 식별자. `position_id` 는 ERC-1155 포지션 id 의 10진 문자열입니다. 시장이 온체인에 등록되기 전에는 셋 다 `null` 입니다.
`outcomes[].payout_wei`	주당 지급액(18-decimal 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-friendly 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"`) — enum 이 아닙니다. 결과 식별에는 `outcome_id` 를 쓰세요.
`bids`	매수 호가, 가격 내림차순 (가장 높은 것이 첫 번째)
`asks`	매도 호가, 가격 오름차순 (가장 낮은 것이 첫 번째)
`price`	0..1 가격, 소수 3자리 string
`shares`	해당 가격의 총 수량, 소수 2자리 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 엔드포인트 공통 규약

이 페이지가 도움이 되었나요?