하나의 연결로, 실시간 배당을.

01 API 키 준비

관리자가 고객사를 등록하고 API 키를 발급합니다. 키에 지정된 종목, 경기 전·라이브 범위와 최대 동시 연결 수가 실제 구독에 적용됩니다.

인증 헤더 설정

헤더 이름은 X-API-Key, 값은 발급받은 bc_live_... 키 원문입니다. 아래의 발급받은_API_키 부분을 실제 키로 바꿔 입력하세요. 서버 WebSocket 클라이언트는 연결을 열 때 이 헤더를 전달합니다.

X-API-Key: 발급받은_API_키

헤더를 직접 입력하는 클라이언트에서도 이름에 X-API-Key, 값에 키 원문을 설정한 뒤 연결하세요. Python·Node.js·PHP의 설정 위치는 아래 언어별 탭에서 확인할 수 있습니다.

서버 실행 전 API_KEY 설정

Python·Node.js·PHP 예제는 현재 프로세스의 API_KEY 환경변수를 읽습니다. 사용하는 터미널에서 아래 명령을 실행한 뒤 같은 터미널에서 예제를 실행하세요.

Windows PowerShell

$env:API_KEY = "발급받은_API_키"

Linux·macOS (bash / zsh)

export API_KEY="발급받은_API_키"

브라우저는 애플리케이션이 전달한 apiKey로 첫 인증 메시지를 보냅니다. 자세한 방법은 브라우저 탭을 확인하세요.

02 WebSocket 구독

다음 주소는 축구 라이브 목록 배당 구독 예시입니다. 운영 환경에서는 배포된 서비스의 wss:// 주소를 사용합니다.

wss://odds-flow.com/ws?snapshot=true&phase=live&sport_id=1

event_id를 생략하면 상시 수집하는 목록용 승패 계열 배당을 받습니다. 원본이 제공하는 연장 포함 유형도 목록에 포함됩니다. 경기의 전체 상세 마켓을 받으려면 event_id에 목록에서 확인한 경기 ID를 지정하세요.

wss://odds-flow.com/ws?snapshot=true&phase=live&sport_id=1&event_id=경기ID

상세 요청 시 해당 경기의 원본 구독을 시작하고 초기 수집을 완료한 뒤 데이터를 보냅니다. 같은 경기를 요청한 고객은 원본 구독 하나를 공유합니다. 첫 요청에는 수집 대기 시간이 있으며, 기본 대기 한도는 45초입니다. 마지막 요청이 끝난 뒤 기본 30초 동안 구독을 유지한 후 해제합니다. 상세 구독 전의 상세배당 변동 이력은 제공되지 않습니다.

03 언어별 연동 예제

python -m pip install websockets

additional_headers={"X-API-Key": os.environ["API_KEY"]}

import asyncio, json, os
from websockets.asyncio.client import connect

async def main():
    async with connect(
        "wss://odds-flow.com/ws?snapshot=true&phase=live&sport_id=1",
        additional_headers={"X-API-Key": os.environ["API_KEY"]},
        max_size=4 * 1024 * 1024,
    ) as ws:
        async for message in ws:
            payload = json.loads(message)
            # snapshot_end까지 초기 목록을 모은 뒤 변경분을 반영합니다.
            print(payload)

asyncio.run(main())

python subscribe.py

04 메시지와 연결 복구

연결이 끊기면 마지막으로 처리한 odds.id 또는 heartbeat.id를 since에 지정하세요. snapshot_end.resume_after는 초기 목록 완료 후 사용할 수 있습니다. 중복 변경은 (source, phase, event_id, market_id, selection_id)와 change_id로 구분합니다.

wss://odds-flow.com/ws?phase=live&sport_id=1&since=메시지ID

• 상태가 active인 선택지만 활성 배당으로 사용합니다. suspended는 중지, removed는 삭제 상태입니다.
• 초기 목록 전송 도중 종료되면 미완료 목록을 적용하지 말고 다시 받아야 합니다.
• API 키 폐기, 만료 또는 고객사 이용 중지 시 연결이 제한됩니다.
• 스냅샷과 배당 변경의 중복은 정상이며 change_id가 더 큰 상태를 유지합니다.

05 수신 데이터와 필드 설명

WebSocket으로 받은 문자열을 JSON으로 읽은 뒤 최상위 type으로 메시지를 구분합니다. 아래 JSON과 값은 형식 설명을 위한 가상 예시입니다.

메시지 공통 필드

초기 목록은 items 배열, 실시간 변경은 data 객체로 전달됩니다. data 안의 type은 변경 종류를 나타내며 최상위 type과 구분해서 읽습니다.

배당 데이터: odds.data / snapshot.items[]

배당 한 건은 한 경기의 마켓에 속한 선택지 하나입니다. 실시간 odds.data는 그 선택지의 현재 전체 값입니다. 초기 snapshot.items의 각 항목도 같은 기본 필드를 사용하며, 변경 메시지 전용 type과 outbox_id는 포함하지 않습니다.

{
  "type": "odds",
  "id": "1793145601000-0",
  "data": {
    "source": "x10x10s",
    "phase": "live",
    "event_id": "example-event-1",
    "sport_id": "1",
    "sport_name": "Football",
    "region_name": "예시 지역",
    "league_id": "example-league-1",
    "league_name": "예시 리그",
    "home_team": "예시 홈팀",
    "away_team": "예시 원정팀",
    "start_time": "2026-10-27T23:00:00Z",
    "market_id": "example-market-1",
    "market_name": "Match Result",
    "market_type": "P1XP2",
    "line": null,
    "selection_id": "example-selection-home",
    "selection_name": "W1",
    "odds": "2.20",
    "status": "active",
    "received_at": "2026-10-28T00:00:01Z",
    "source_updated_at": null,
    "change_id": 102,
    "changed_at": "2026-10-28T00:00:01Z",
    "type": "odds.changed",
    "outbox_id": 501
  }
}

선택지는 (source, phase, event_id, market_id, selection_id)로 식별합니다. 같은 키가 다시 오면 해당 선택지를 갱신하고 status가 active인 선택지만 활성 배당으로 사용하세요. odds는 소수 정밀도를 보존하는 문자열이며 값이 없을 때는 null입니다.

경기 상태: 스코어·시간·통계·타임라인

include_game_state=true를 지정하면 game_state_snapshot과 game_state도 같은 WebSocket으로 받습니다. 기본값은 false입니다.

wss://odds-flow.com/ws?snapshot=true&phase=live&sport_id=1&include_game_state=true

{
  "type": "game_state",
  "id": "1793145602000-0",
  "data": {
    "source": "x10x10s",
    "phase": "live",
    "event_id": "example-event-1",
    "sport_id": "1",
    "sport_name": "Football",
    "region_name": "예시 지역",
    "league_id": "example-league-1",
    "league_name": "예시 리그",
    "home_team": "예시 홈팀",
    "away_team": "예시 원정팀",
    "start_time": "2026-10-27T23:00:00Z",
    "score": {
      "home": "1",
      "away": "0"
    },
    "clock": {
      "time": "54",
      "state": "set2"
    },
    "info": {
      "score1": "1",
      "score2": "0",
      "current_game_time": "54",
      "current_game_state": "set2"
    },
    "stats": {},
    "live_events": [],
    "status": "active",
    "received_at": "2026-10-28T00:00:02Z",
    "change_id": 202,
    "changed_at": "2026-10-28T00:00:02Z",
    "type": "game.state_changed",
    "outbox_id": 502
  }
}

경기 상태는 (source, phase, event_id)로 식별합니다. game_state.data 전체를 교체하여 빈 live_events나 null 점수도 반영하세요. clock.time의 단위와 clock.state의 코드는 종목과 원본에 따라 달라지므로 원문 그대로 해석합니다. info·stats·live_events의 내부 키와 값도 종목마다 다르며, 타임라인의 type_id를 임의의 골·카드 이름으로 변환하지 않습니다.

경기 상태를 함께 받는 경우 Python의 max_size와 Node.js의 maxPayload를 8 * 1024 * 1024로 설정하세요. 배당 전용 구독에서 경기 상태 포함 구독으로 바꿀 때는 since를 생략하고 snapshot=true로 초기 목록을 다시 받습니다.

초기 목록·인증·연결 복구 JSON

snapshot=true로 처음 연결하면 snapshot_start → game_state_snapshot(선택) → snapshot → snapshot_end 순서로 받습니다. 중간 목록 메시지는 여러 번 오거나 데이터가 없으면 생략될 수 있습니다. snapshot_end를 받은 뒤 모아 둔 초기 목록을 적용하세요.

{
  "type": "auth_required",
  "timeoutMs": 5000
}

{
  "type": "snapshot_start",
  "resume_after": "1793145600000-0"
}

{
  "type": "game_state_snapshot",
  "items": [
    {
      "source": "x10x10s",
      "phase": "live",
      "event_id": "example-event-1",
      "sport_id": "1",
      "sport_name": "Football",
      "region_name": "예시 지역",
      "league_id": "example-league-1",
      "league_name": "예시 리그",
      "home_team": "예시 홈팀",
      "away_team": "예시 원정팀",
      "start_time": "2026-10-27T23:00:00Z",
      "score": {
        "home": "1",
        "away": "0"
      },
      "clock": {
        "time": "53",
        "state": "set2"
      },
      "info": {
        "score1": "1",
        "score2": "0",
        "current_game_time": "53",
        "current_game_state": "set2"
      },
      "stats": {},
      "live_events": [],
      "status": "active",
      "received_at": "2026-10-28T00:00:00Z",
      "change_id": 201,
      "changed_at": "2026-10-28T00:00:00Z"
    }
  ]
}

{
  "type": "snapshot",
  "items": [
    {
      "source": "x10x10s",
      "phase": "live",
      "event_id": "example-event-1",
      "sport_id": "1",
      "sport_name": "Football",
      "region_name": "예시 지역",
      "league_id": "example-league-1",
      "league_name": "예시 리그",
      "home_team": "예시 홈팀",
      "away_team": "예시 원정팀",
      "start_time": "2026-10-27T23:00:00Z",
      "market_id": "example-market-1",
      "market_name": "Match Result",
      "market_type": "P1XP2",
      "line": null,
      "selection_id": "example-selection-home",
      "selection_name": "W1",
      "odds": "2.15",
      "status": "active",
      "received_at": "2026-10-28T00:00:00Z",
      "source_updated_at": null,
      "change_id": 101,
      "changed_at": "2026-10-28T00:00:00Z"
    }
  ]
}

{
  "type": "snapshot_end",
  "resume_after": "1793145600000-0",
  "count": 1,
  "game_count": 1
}

{
  "type": "heartbeat",
  "id": "1793145602000-0"
}

{
  "type": "reset_required",
  "reason": "cursor_unavailable",
  "requested_id": "1793145500000-0",
  "resume_after": "1793145602000-0",
  "snapshot_url": "/api/v1/odds",
  "websocket_snapshot": "/ws?snapshot=true&include_game_state=true"
}

auth_required는 헤더 인증이 없는 연결에서만 받습니다. 인증 후에는 별도의 성공 메시지 없이 초기 목록 또는 변경분이 시작됩니다. heartbeat는 현재 커서를 알려 주는 서버 메시지이며 응답 JSON을 보내지 않습니다. 구독 조건을 바꾸려면 연결 주소의 파라미터를 바꿔 다시 연결하세요.

재접속에는 마지막으로 처리한 odds.id, game_state.id 또는 heartbeat.id를 since로 전달합니다. snapshot_end.resume_after도 초기 목록 완료 후 사용할 수 있습니다. id는 재개 커서이고 change_id는 레코드의 변경 버전입니다. 목록 배당·상세배당·경기 상태의 change_id는 각각의 구독 범위와 종류 안에서 비교합니다. 상세 수집이 해제된 뒤 재시작하면 이전 커서로 이어받는 대신 reset_required에 따라 새 초기 목록을 받아야 할 수 있습니다.

reset_required를 받으면 미완료 초기 목록을 버리고 기존 종목·경기·phase·include_game_state 조건을 유지한 채 since 없이 snapshot=true로 다시 연결하세요. snapshot_url은 배당 REST 조회 경로이고, 경기 상태까지 다시 받으려면 websocket_snapshot 경로로 연결합니다. 필요한 구독 조건은 다시 붙여야 합니다.

연결 종료 코드

인증 실패나 서비스 오류는 별도의 error JSON 대신 WebSocket 종료 이벤트의 code와 reason으로 전달됩니다. 지원하지 않는 구독 파라미터나 잘못된 값은 연결 성립 전에 HTTP 400으로 거절될 수 있습니다.

06 종목 ID

⚽축구1

🏀농구3

🏐배구5

🏒아이스하키2

⚾야구11

🎾테니스4

리그 오브 레전드77

도타 276

07 애니메이션 연동

기본 경기장 화면을 제공하는 iframe 위젯과 직접 데이터를 받는 애니메이션 WebSocket을 지원합니다. 배당·스코어·타임라인을 받는 /ws?include_game_state=true와 구분되는 별도 피드입니다.

목록에서 확인한 실제 경기 ID와 종목 ID를 사용하고 키에 live·해당 종목 권한을 허용하세요. 모든 경기에 애니메이션이 제공되는 것은 아니며 원본에 없는 좌표·점수는 생성하지 않습니다.

POST https://odds-flow.com/api/v1/animation/widget-sessions

// 고객사의 인증을 통과한 서버 요청에서 호출하세요.
// API_KEY는 고객사 서버의 환경변수이며 브라우저로 반환하지 않습니다.
export async function createAnimationWidget(eventId, sportId, parentOrigin) {
  const apiKey = process.env.API_KEY;
  if (!apiKey) throw new Error("API_KEY 환경변수를 설정하세요.");

  const response = await fetch("https://odds-flow.com/api/v1/animation/widget-sessions", {
    method: "POST",
    headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({
      eventId, sportId, parentOrigin, ttlSeconds: 900,
    }),
    cache: "no-store",
    signal: AbortSignal.timeout(10_000),
  });
  if (!response.ok) throw new Error("위젯 발급 실패: HTTP " + response.status);
  const widget = await response.json();
  // 고객사 서버의 응답도 Cache-Control: no-store로 전달하세요.
  return { iframeUrl: widget.iframeUrl, expiresAt: widget.expiresAt };
}

// eventId: 목록에서 확인한 실제 경기 ID 문자열
// sportId: 해당 경기의 종목 ID 숫자
// parentOrigin: 위젯을 삽입할 고객 페이지의 정확한 Origin
// 예: https://customer.example (경로·쿼리 제외)

<iframe
  src="서버 응답의 iframeUrl을 그대로 입력"
  title="실시간 경기 애니메이션"
  width="100%"
  height="520"
  loading="lazy"
  referrerpolicy="no-referrer"
  style="border:0"
></iframe>

연결 주소와 수신 메시지

아래 주소의 EVENT_ID를 실제 경기 ID로 바꾸세요. 애니메이션 주소는 event_id와 sport_id만 받으며 phase·snapshot·since는 사용하지 않습니다.

wss://odds-flow.com/animation/ws?event_id=EVENT_ID&sport_id=1

animation_snapshot과 animation_update의 data는 서버에서 병합한 전체 현재 상태입니다. 이전 객체와 패치를 합치는 대신 data와 events를 교체하세요. score·clock·ball 등이 null이면 대기 상태를 표시합니다.

아래 JSON은 형식 예시이며 실시간 경기 값이 아닙니다. auth_required는 헤더 인증이 없는 연결에서만 받으며, 인증 성공 후 authenticated와 상태·데이터 메시지가 전달됩니다.

{"type":"auth_required","timeoutMs":5000}
{"type":"authenticated","eventId":"실제_경기_ID","sportId":1,"expiresAt":null}
{"type":"animation_snapshot","eventId":"실제_경기_ID","sportId":1,"receivedAt":"2026-10-28T00:00:00Z","sequence":1,"data":{"homeTeam":"홈팀","awayTeam":"원정팀","score":null,"clock":null,"period":null,"ball":null,"possession":null,"events":[]}}
{"type":"animation_status","eventId":"실제_경기_ID","sportId":1,"receivedAt":"2026-10-28T00:00:01Z","status":"unavailable","message":"이 경기의 애니메이션 데이터가 제공되지 않습니다."}

재연결·상태·접근 제한

• sequence는 숫자가 있을 때 같은 연결에서 순서·중복을 확인하는 값입니다. 배당 id와 다르며 since 재생에 사용할 수 없습니다. 새 연결에서는 비교값을 초기화하고 다시 인증해 최신 캐시를 받습니다.
• connecting은 연결 준비, stale은 최근 상태 확인·연결 복구, unavailable은 해당 경기의 데이터 미제공 상태입니다. unavailable도 정상적인 제공 상태로 화면에 안내하세요.
• 배당과 애니메이션 시청 연결은 키의 최대 WebSocket 연결 수를 공유합니다. 키 중지·폐기·만료, 고객사 중지, 권한·허용 IP 제한은 1008, 수신 지연·동시 처리 한도는 1013, 서비스 오류는 1011로 종료될 수 있습니다.
• IP 제한 키는 위젯 발급 서버와 실제 브라우저 시청자의 접속 IP를 각각 허용해야 합니다. 초기 위젯 메타데이터 조회만으로 실시간 피드를 받을 수는 없습니다.
• 1011·1013이나 네트워크 단절 후에는 간격을 늘려 재연결하고, 1008은 키·IP·종목·live 권한과 위젯 만료를 확인한 뒤 다시 연결하세요.