제휴 안내: 이 글에는 OKX 파트너 링크가 포함되어 있습니다. 해당 링크를 통해 가입·거래하면 운영자에게 수익이 발생할 수 있습니다. 이용자 혜택은 계정·지역·VIP 등급·캠페인에 따라 달라질 수 있으므로 가입 화면과 My Rewards에서 실제 적용 조건을 확인하세요.
핵심 답변: OKX WebSocket은 채널 명세에 따라 Public·Private·Business 서비스와 실거래·Demo 환경을 분리하고, 인증이 필요한 채널에 올바른 서명으로 로그인해야 합니다. 응답을 받을 때마다 N < 30초 타이머를 초기화하고 N초 동안 메시지가 없으면 문자열 ping을 보낸 뒤 pong 응답을 확인합니다. 연결당 시간당 480회 login·subscribe·unsubscribe 합계와 지정 비공개 채널의 서브계정·채널별 30개 연결 제한은 별도로 관리합니다.
API·거래 위험: Secret Key와 Passphrase를 코드, 로그, 화면 캡처 또는 공개 저장소에 남기지 마세요. WebSocket 연결 성공은 주문 전략의 수익이나 체결을 보장하지 않습니다. 재연결 중 중복 주문, 오래된 포지션 상태, 레버리지 확대와 청산이 발생할 수 있으므로 상태 동기화가 끝날 때까지 자동 주문을 중지하고 Demo 환경에서 먼저 검증하세요.
OKX WebSocket 핵심 제한 빠른 표
| 항목 | 조건·확인 사항 |
|---|---|
| 새 연결 요청 | 공식 범위: IP 기준 초당 3회 운영 시 의미: 장애 때 모든 프로세스가 동시에 재연결하지 않도록 백오프와 무작위 지연을 둡니다. |
| login·subscribe·unsubscribe | 공식 범위: 연결당 합계 시간당 480회 운영 시 의미: 재연결 루프에서 같은 구독을 반복 전송하면 한도를 빠르게 소모합니다. |
| 무응답 연결 | 공식 범위: 구독이 없거나 30초 넘게 데이터가 없으면 자동 종료 가능 운영 시 의미: 30초보다 짧은 N초 타이머로 ping·pong을 확인합니다. |
| 특정 비공개 채널 연결 | 공식 범위: 서브계정·채널별 30개 연결 운영 시 의미: Orders·Account·Positions 등 제한 대상 채널을 여러 프로세스가 중복 구독하지 않게 관리합니다. |
| 한 번의 다중 구독 | 공식 범위: 여러 채널 인수의 총 길이 64KB 이하 운영 시 의미: 구독 목록을 무제한으로 한 메시지에 넣지 말고 확인 응답과 실패 항목을 추적합니다. |
위 숫자는 서로 다른 범위입니다. 초당 3회는 IP 기준의 연결 요청, 시간당 480회는 한 연결 안의 login·subscribe·unsubscribe 작업 합계, 30개는 제한 대상 특정 채널별 활성 연결 수입니다. 하나의 숫자를 전체 WebSocket 트래픽 한도로 오해하면 안 됩니다. 주문 전송에는 각 주문 API의 별도 속도 제한도 적용됩니다.
공개·비공개·Business 서비스와 환경 선택
| 환경 | 조건·확인 사항 |
|---|---|
| 실거래 | 서비스: Public 공식 글로벌 엔드포인트 예시: wss://ws.okx.com/ws/v5/public인증: 공개 시세·호가 등은 로그인 불필요 |
| 실거래 | 서비스: Private 공식 글로벌 엔드포인트 예시: wss://ws.okx.com/ws/v5/private인증: 계정·주문·포지션 채널은 로그인 필요 |
| 실거래 | 서비스: Business 공식 글로벌 엔드포인트 예시: wss://ws.okx.com/ws/v5/business인증: 사용 채널의 최신 명세 확인 |
| Demo | 서비스: Public 공식 글로벌 엔드포인트 예시: wss://wspap.okx.com/ws/v5/public인증: Demo 환경과 키를 실거래와 분리 |
| Demo | 서비스: Private 공식 글로벌 엔드포인트 예시: wss://wspap.okx.com/ws/v5/private인증: Demo 전용 API 키로 로그인 |
| Demo | 서비스: Business 공식 글로벌 엔드포인트 예시: wss://wspap.okx.com/ws/v5/business인증: 지원 기능과 채널을 개별 확인 |
공개 채널에는 tickers·호가·마크 가격 등 인증이 필요 없는 데이터가 포함되고, 비공개 채널에는 계정·주문·포지션 등이 포함됩니다. 공개 채널을 받기 위해 비밀키를 보낼 이유가 없습니다. 반대로 Private 주소에 연결만 해놓고 로그인 성공 응답 없이 계정 채널을 구독하면 정상 데이터가 오지 않습니다.
지역 주의: 위 주소는 2026년 10월 24일 글로벌 OKX API 문서에서 확인한 예시입니다. OKX는 계정 등록 지역에 따라 별도 API 도메인과 문서를 사용하도록 안내합니다. 공식 문서는 app.okx.com에 등록한 US·AU 계정은 US·AU 문서와 us.okx.com API 도메인을, my.okx.com에 등록한 EU 계정은 EU 문서와 eea.okx.com API 도메인을 사용하도록 안내합니다. 이 REST API 도메인을 WebSocket 주소로 임의 치환하지 말고 해당 지역 문서의 WebSocket 주소를 확인하세요. 지역 제한을 우회하기 위한 VPN·중복 계정 방법은 이 글에서 다루지 않습니다.
연결부터 준비 완료까지의 안전한 순서
- 환경을 고정합니다. 실거래와 Demo의 설정 파일·API 키·WebSocket 주소를 분리합니다.
- 채널 명세를 확인합니다. Public·Private·Business 중 채널이 지정한 서비스를 선택하고, Private 채널은 인증 조건을 확인합니다. 데이터가 시세라는 이유만으로 모든 채널을 Public 주소로 보내지 않습니다.
- 연결 속도를 제한합니다. IP 기준 초당 3회 연결 한도를 넘지 않도록 중앙 재연결 큐를 둡니다.
- 인증이 필요한 채널에 로그인합니다. Private뿐 아니라 Business의
orders-algo채널도 로그인 필요로 명시되어 있습니다. 서비스 이름만으로 판단하지 말고 채널 명세에 따라 API Key·Passphrase·timestamp·sign으로 login 요청을 보내code: "0"을 확인합니다. - 필요한 채널만 구독합니다. 채널명과 instType·instFamily·instId를 최신 명세에 맞추고 구독 확인 응답을 저장합니다.
- 수신 타이머를 시작합니다. N을 30초보다 짧게 정하고 메시지를 받을 때마다 타이머를 초기화합니다.
- 상태를 동기화합니다. 주문·포지션·잔액 스냅샷과 스트림을 맞춘 뒤에만 봇을 준비 상태로 바꿉니다.
- 종료와 업그레이드 알림을 처리합니다. 연결 끊김이나
64008notice가 오면 새 연결·재인증·재구독·재동기화 순서로 복구합니다.
DISCONNECTED → CONNECTING → AUTHENTICATING
→ SUBSCRIBING → RESYNCING → READY연결 소켓이 열렸다는 사실만으로 주문 가능한 상태라고 판단하지 마세요. 필요한 인증과 구독 확인, 채널 특성에 맞는 현재 상태 조회, 스트림 연결 시점의 누락 데이터 보정을 끝낸 뒤에만 READY로 전환하는 편이 안전합니다.
Private WebSocket 로그인 서명
OKX WebSocket 로그인은 REST 주문 서명과 비슷해 보이지만 입력 형식이 고정되어 있습니다. 공식 문서 기준 timestamp는 초 단위 Unix Epoch 문자열이며, 메서드는 항상 GET, requestPath는 항상 /users/self/verify입니다.
preHash = timestamp + "GET" + "/users/self/verify"
sign = Base64(HMAC_SHA256(preHash, SecretKey))| 필드 | 조건·확인 사항 |
|---|---|
| apiKey | 조건: 해당 환경에서 만든 API Key 자주 생기는 오류: Demo 키와 실거래 키 혼합 |
| passphrase | 조건: 키 생성 때 정한 별도 문자열 자주 생기는 오류: OKX 로그인 비밀번호와 혼동 |
| timestamp | 조건: 초 단위 Unix Epoch 문자열 자주 생기는 오류: 밀리초 값을 그대로 전송하거나 오래된 값을 재사용 |
| sign | 조건: 고정된 GET 경로를 HMAC SHA256 후 Base64 자주 생기는 오류: REST 엔드포인트 경로, 소문자 메서드, Hex 출력 사용 |
로그인 요청은 timestamp 뒤 30초가 지나면 만료됩니다. 서버 시간이 다르면 OKX의 REST 서버 시간 API로 차이를 확인한 뒤 timestamp를 새로 만들어야 합니다. 성공 응답은 event: "login", code: "0"와 connId를 포함하며, 공식 실패 예시는 event: "error", code: "60009", msg: "Login failed."입니다. 60009만으로 원인을 단정하지 말고 환경·시간·Passphrase·서명·키 상태를 순서대로 분리하세요.
키 생성과 최소 권한, IP 허용목록, 14일 비활성 조건은 OKX API 키 생성·보안 가이드에서 확인할 수 있습니다. 로그인 오류 때문에 Secret Key를 로그에 출력하지 말고, 서명 입력 문자열의 길이와 비밀값을 제외한 구성만 제한적으로 기록하세요.
API 키 비활성 조건 주의: OKX 공식 문서는 WebSocket에서는 login 동작만 API 키 사용으로 계산하고, 로그인 뒤의 구독이나 주문은 사용으로 계산하지 않는다고 설명합니다. IP에 연결되지 않은 Trade·Withdraw 권한 키가 14일 비활성 조건의 영향을 받는 경우, 열린 연결에서 데이터나 주문이 오간다는 사실만으로 키 활동이 갱신된다고 가정하지 마세요. IP 허용목록과 최소 권한을 유지하고 Security Center의 키 상태를 확인하세요. Demo Trading API 키는 이 비활성 만료 조건의 예외입니다.
30초 연결 종료를 막는 ping·pong 처리
OKX 문서는 구독이 성립하지 않았거나 30초 넘게 데이터가 푸시되지 않으면 연결이 자동으로 끊길 수 있다고 설명합니다. 해결 방식은 단순한 고정 간격 ping보다 수신 기반 타이머에 가깝습니다.
- 응답 메시지를 받을 때마다 N초 타이머를 다시 시작합니다. N은 30보다 작게 둡니다.
- N초 동안 새 메시지가 없으면 JSON 객체가 아니라 문자열
ping을 보냅니다. - 문자열
pong응답을 기다립니다. - 다음 N초 안에 응답이 없으면 해당 연결을 실패로 표시하고 닫은 뒤 재연결합니다.
활발한 채널은 데이터 자체가 계속 도착하므로 불필요한 ping을 줄일 수 있습니다. 반대로 거래가 적은 상품이나 계정 채널은 무음 구간이 길 수 있어 타이머가 필요합니다. 라이브러리가 자동 WebSocket ping 프레임을 보낸다고 해서 OKX의 문자열 ping·pong 동작까지 자동 지원한다고 가정하지 말고 실제 수신 로그로 확인하세요.
시간당 480회와 채널별 30개 연결 관리
한 연결에서 login·subscribe·unsubscribe 요청의 합계는 시간당 480회로 제한됩니다. 초당 연결 한도와 별개이므로, 연결은 유지되지만 구독 요청만 거부되는 상황도 분리해야 합니다. 애플리케이션이 같은 채널을 이미 구독했는지 상태를 저장하고, 재연결 때 필요한 최종 구독 집합만 한 번 보내세요.
또한 Orders·Account·Positions·Balance and positions·Position risk warning·Account greeks 채널은 서브계정의 특정 채널마다 최대 30개 WebSocket 연결 제한을 받습니다. 같은 연결에서 같은 채널을 여러 인수로 구독해도 해당 채널 연결 수는 한 번으로 계산되지만, Orders와 Account처럼 서로 다른 채널은 각각 계산됩니다. 새 구독 시 channel-conn-count 이벤트의 connCount를 기록하고, channel-conn-count-error가 오면 새 연결을 더 만드는 대신 중복 소비자를 찾으세요.
OKX 문서는 WebSocket을 통한 주문 제출·수정·취소가 이 30개 채널 연결 제한 변경의 영향을 받지 않는다고 설명하지만, 주문 작업 자체의 엔드포인트별 속도 제한은 그대로 존재합니다. REST와 WebSocket의 주문 한도가 공유되는 항목도 있으므로 각 주문 API 명세를 별도로 확인해야 합니다.
구독 성공 응답 이후도 확인: 연결 한도 초과 시 일반 구독 성공 응답 뒤에 channel-conn-count-error가 오며 구독이 종료될 수 있습니다. 공식 문서는 대체로 새 구독을 거부하지만 예외적으로 기존 연결이 해제될 수도 있다고 설명합니다. connId별 구독 상태와 한도 이벤트를 함께 추적하고 ACK 하나만으로 지속 수신을 보장하지 마세요.
재연결 시 데이터 누락과 중복 주문 막기
연결이 끊겼다가 다시 붙는 것보다 더 위험한 문제는 끊긴 구간의 상태를 그대로 믿는 것입니다. 비공개 주문·포지션 스트림을 사용한다면 재연결 직후 자동 주문을 잠시 멈추고 현재 열린 주문, 포지션, 잔액을 다시 조회해 로컬 상태와 대조하세요.
- 재연결은 지수 백오프, 무작위 지연, 최대 대기 상한으로 조절합니다.
- 여러 워커가 한 IP에서 동시에 재연결하지 않도록 단일 조정자를 둡니다.
- login 성공 전 Private 구독을 보내지 않습니다.
- 구독 확인 응답과 채널별 수신 상태를 구분합니다. 주문처럼 변화가 있을 때만 푸시하는 채널은 무음만으로 구독 실패라고 단정하지 않습니다.
- 각 채널이 제공하는 timestamp·sequence·주문 ID 규칙에 맞춰 중복과 공백을 확인합니다.
- 상태 불일치가 남으면 주문 생성·수정·취소를 재개하지 않습니다.
- 응답이 없던 주문은 고유한 client order ID와 주문 조회로 접수 여부를 확인한 뒤 재시도 여부를 결정합니다. 연결 복구만으로 같은 주문을 재전송하지 않습니다.
OKX는 WebSocket 서비스 업그레이드 60초 전에 event: "notice", code: "64008" 알림을 보낼 수 있다고 안내합니다. 이 경우 기존 연결이 끊길 때까지 기다리지 말고 새 연결을 만들고 로그인·구독·상태 동기화를 완료한 뒤 안전하게 전환하세요. 해당 notice는 현재 Public과 Private WebSocket에 지원된다고 명시되어 있습니다.
서명·timestamp·환경 오류가 함께 나타나면 OKX API 50113·50102 오류 해결 가이드를 참고하세요. 자동 주문의 레버리지·청산 구조를 아직 검증하지 않았다면 OKX 선물거래 초보자 가이드를 먼저 읽고 Demo에서 전체 복구 흐름을 시험하는 것이 안전합니다.
주문 채널의 초기 데이터: 공식 Orders 채널 명세는 최초 구독 시 데이터를 푸시하지 않고 새 주문이나 주문 변경이 있을 때만 푸시한다고 명시합니다. 따라서 구독 확인 뒤 기존 미체결 주문이 자동으로 모두 내려올 것이라고 기다리면 안 됩니다. 아래는 AKEYX의 복구 운영안이며 플랫폼이 모든 채널에 동일한 재생 기능을 제공한다는 뜻은 아닙니다.
- 자동 주문을 중지하고 복구 연결에서 로그인·구독 확인을 마친 뒤 들어오는 업데이트를 임시 보관합니다.
- 공식 REST API로 현재 미체결 주문·포지션·잔액을 조회합니다. 열린 주문에 없는 주문은 취소·체결됐을 수 있으므로 주문 상세·이력도 필요한 범위에서 확인합니다.
- 주문 ID, 갱신 시각, 누적 체결량 등을 해당 채널 명세에 맞게 대조하여 중복을 제거합니다. 모든 채널에 동일한 sequence나 초기 스냅샷이 있다고 가정하지 않습니다.
- REST 응답과 보관한 이벤트의 순서가 모호하면 다시 조회해 정합성을 확인합니다. 불일치가 남거나 주문 접수 여부가 불명확하면
READY로 전환하지 않습니다.
증상별 원인과 첫 조치
| 증상 | 조건·확인 사항 |
|---|---|
| 약 30초마다 끊김 | 가능성이 높은 원인: 무음 구간의 ping·pong 미처리 먼저 확인할 증거: 마지막 수신 시각, ping 문자열과 pong 응답 피해야 할 대응: 무한 즉시 재연결 |
| 60009 Login failed | 가능성이 높은 원인: 환경·timestamp·Passphrase·서명 불일치 먼저 확인할 증거: 키 생성 환경, 초 단위 시간, 고정 GET 경로 피해야 할 대응: Secret Key 로그 출력 |
| 구독 확인이 오지 않음 | 가능성이 높은 원인: 서비스·채널·인수 오류 또는 한도 초과 먼저 확인할 증거: Public/Private 주소, error code·msg, 요청 크기 피해야 할 대응: 같은 subscribe 무한 반복 |
| channel-conn-count-error | 가능성이 높은 원인: 제한 대상 채널의 30개 연결 초과 먼저 확인할 증거: 서브계정·채널별 connId 목록 피해야 할 대응: 새 프로세스를 계속 추가 |
| 업그레이드 때 데이터 공백 | 가능성이 높은 원인: 64008 notice 무시 먼저 확인할 증거: notice 수신 시각과 새 연결 준비 시각 피해야 할 대응: 종료 후에야 연결 시작 |
| 재연결 뒤 중복 주문 | 가능성이 높은 원인: 로컬 상태 미동기화·무제한 재시도 먼저 확인할 증거: client order ID, 열린 주문·포지션 스냅샷 피해야 할 대응: READY 전에 자동 주문 재개 |
운영 전 체크리스트
- □ 내 계정 지역과 환경에 맞는 공식 API 문서를 열었는가?
- □ Public·Private·Business 주소와 실거래·Demo 설정을 분리했는가?
- □ IP 기준 초당 3회 연결 요청 한도를 중앙에서 관리하는가?
- □ WebSocket 로그인 timestamp가 초 단위이고 30초 안에 전송되는가?
- □ 비밀키와 Passphrase가 로그·오류 추적 서비스에서 제외되는가?
- □ 연결당 시간당 480회 작업 카운터와 64KB 구독 크기를 감시하는가?
- □ 제한 대상 채널의 서브계정별 connId와 connCount를 기록하는가?
- □ 30초보다 짧은 수신 타이머와 ping·pong 실패 처리가 있는가?
- □ 64008 notice, 네트워크 종료, 인증 실패를 서로 다른 상태로 처리하는가?
- □ 재연결 후 스냅샷·스트림 동기화가 끝날 때까지 주문을 막는가?
계정 방어 설정과 키 유출 대응은 OKX 안전성·계정 보안 가이드도 함께 확인하세요. 연결 안정화와 보안은 별개의 문제이며, 높은 가동률이 위험한 주문을 안전하게 바꾸지는 않습니다.
자주 묻는 질문
시세만 받는데 API 키가 필요한가요?
일반적으로 tickers·호가 같은 공개 채널은 인증이 필요하지 않습니다. 실제 채널 명세의 Public·Business 서비스 주소를 확인하고 비밀키를 보내지 마세요. 계정·주문·포지션 같은 Private 채널은 로그인이 필요합니다.
ping을 30초마다 정확히 보내면 되나요?
공식 안내는 N을 30초보다 작게 정하고, 메시지를 받을 때마다 타이머를 초기화한 뒤 N초 동안 무응답일 때 문자열 ping을 보내는 방식입니다. pong이 다음 N초 안에 오지 않으면 오류 또는 재연결로 처리합니다.
시간당 480회는 시세 메시지 수 제한인가요?
아닙니다. 연결당 login·subscribe·unsubscribe 요청 합계에 적용되는 제한입니다. 서버가 보내는 시세 데이터 건수나 주문 엔드포인트별 속도 제한과는 다른 범위입니다.
30개 연결 제한은 모든 WebSocket에 적용되나요?
아닙니다. 공식 문서에 열거된 Orders·Account·Positions·Balance and positions·Position risk warning·Account greeks 등 특정 비공개 채널을 서브계정·채널별로 계산합니다. 각 채널의 connCount 이벤트를 확인하세요.
Demo에서 잘 되면 실거래도 그대로 연결해도 되나요?
Demo와 실거래는 엔드포인트와 API 키를 분리해야 하며 일부 기능 지원도 다를 수 있습니다. 설정을 복사하더라도 주문 크기·계정 모드·권한·지역 도메인·복구 절차를 실거래 조건으로 다시 검증하세요.
OKDCC를 사용하면 WebSocket 한도가 늘어나나요?
아닙니다. 추천코드는 WebSocket 연결·구독·주문 속도 제한이나 API 안정성과 별개입니다. 수수료 리베이트의 제공 여부와 조건은 자동·무조건 적용이 아니며 계정·지역·VIP·캠페인에 따라 달라질 수 있습니다. 가입 전 화면과 가입 후 My Rewards에서 실제 적용률을 확인하세요.
공식 자료와 검토일
- OKX API V5: API Key Security — WebSocket login만 키 사용으로 계산되는 조건과 14일 비활성 규칙
- OKX API V5: WebSocket Overview — 연결 방식, Public·Private 구분
- OKX API V5: WebSocket Connect — IP당 초당 연결 요청 3회, 연결당 login·subscribe·unsubscribe 합계 시간당 480회, N < 30초 수신 기반 타이머와 문자열 ping·pong
- OKX API V5: Connection Count Limit — 제한 대상 채널, 서브계정·채널별 30개, connCount 이벤트
- OKX API V5: WebSocket Login — 초 단위 timestamp, 고정 서명 경로, 30초 만료, 60009
- OKX API V5: Subscribe — 공개·비공개 채널, 구독 인수와 64KB 조건
- OKX API V5: Notification — 서비스 업그레이드 60초 전 64008 notice
- OKX API V5: Production Trading Services — 실거래 REST·WebSocket 주소
- OKX API V5: Demo Trading Services — Demo 전용 주소·키와 지원 범위
- OKX API V5: Order Channel — 최초 구독 시 초기 데이터 미푸시, 신규·변경 주문 시 업데이트
- OKX API V5: Algo Orders Channel —
orders-algo·/ws/v5/business· login
최종 검토일: 2026년 10월 25일. 연결 주소, 지역 도메인, 채널 목록, 속도·연결 제한과 Demo 지원 기능은 변경될 수 있습니다. 숫자와 엔드포인트는 실행 시점의 내 계정 지역용 OKX 공식 문서를 다시 확인하고, AKEYX의 재연결·상태 동기화 절차는 운영 위험을 줄이기 위한 분석 가이드로 구분해 적용하세요.