Bybit 트레이딩 봇 구축 방법: 개발자를 위한 기술 가이드

Bybit API 아키텍처 개요

1. Bybit의 REST 및 WebSocket API는 각 엔드포인트가 특정 가중치 계층에 속하는 엄격한 속도 제한 프레임워크에서 작동합니다. 티커 및 주문장 쿼리와 같은 퍼블릭 엔드포인트는 호출당 1단위를 소비하는 반면, 주문 배치 또는 위치 수정과 같은 프라이빗 엔드포인트는 페이로드 복잡성에 따라 3~10단위의 가중치를 전달합니다.

2. 인증은 비밀 키, 타임스탬프 및 정규화된 요청 문자열을 사용하여 생성된 HMAC-SHA256 서명에 의존합니다. 임시값 정렬 또는 서명 만료 기간(최대 30초)이 일치하지 않으면 즉시 401 무단 응답이 트리거됩니다.

3. v5 API는 현물, 역영구, 선형 무기한 및 옵션 시장 전반에 걸쳐 통합 마진 모드 지원을 도입합니다. 이를 위해서는 모호한 라우팅 오류를 방지하기 위해 모든 요청 헤더에 카테고리 매개변수를 명시적으로 지정해야 합니다.

4. 비공개 채널을 구독하기 전에 필수 인증 핸드셰이크를 통해 WebSocket 연결을 설정해야 합니다. 연결 후 10초 이내에 인증 패킷을 보내지 못하면 강제 종료됩니다.

5. 생성, 부분 채우기, 전체 채우기, 취소 및 거부를 포함한 주문 수명주기 이벤트는 주문, 실행 및 위치와 같은 고유한 주제 아래 별도의 스트림을 통해 발생하므로 주제별로 독립적인 구독 관리가 필요합니다.

핵심 통합 구성요소

1. ccxt.bybit 커넥터는 X-RateLimit-Remaining 헤더를 구문 분석하고 임계값이 할당된 할당량의 20% 미만으로 떨어지면 후속 요청을 동적으로 조절하여 자동 속도 제한 적응을 처리합니다.

2. 마진 모드 전환 논리는 exchange_instance_service.ts 모듈에 상주하며, 이는 최종 사용자에게 원시 API 호출을 노출하지 않고 격리 구성과 교차 마진 구성 간의 원자 상태 전환을 시행합니다.

3. 주문장 깊이 스냅샷은 orderBookL2_25 WebSocket 스트림을 통해 검색되어 각 업데이트 페이로드에 포함된 마이크로초 수준의 정밀 타임스탬프와 함께 가격별로 정렬된 입찰/요청 수준을 제공합니다.

4. 위치 동기화는 델타 기반 조정을 사용합니다. 봇은 모든 위치 업데이트 이벤트에서 반환된 서버 측 위치 버전 번호와 로컬 캐시 체크섬을 비교하여 전체 상태를 다시 로드하지 않고도 불일치를 감지하고 해결합니다.

5. 거래 실행 검증은 제출 전 매개변수 삭제, 응답 후 상태 코드 확인, 실행 스트림 상관관계를 통한 채우기 후 확인 등 세 가지 계층에서 이루어지므로 확인되지 않은 주문이 모호한 상태로 남아 있지 않도록 보장합니다.

전략 실행 메커니즘

1. Bybit의 선형 영구 계약을 기반으로 구축된 추세 추종 전략은 GET /v5/market/candles 를 통해 가져온 캔들 데이터에서 직접 EMA(9) 및 EMA(21) 값을 계산하며 간격 분해능은 최대 1분까지 구성 가능합니다.

2. 손절매 및 이익 실현 수준은 부분으로 설정된 tpSlMode 매개변수를 사용하여 진입 주문과 함께 원자적으로 제출되므로 실시간 ATR(14) 계산을 기반으로 추적 손절매를 동적으로 조정할 수 있습니다.

3. 펀딩 비율 차익거래 로직은 여러 기호에 걸쳐 GET /v5/market/funding/history 엔드포인트를 동시에 모니터링하여 절대 자금 차이가 3회 연속 간격에 걸쳐 0.025%를 초과하는 경우에만 헤지 포지션을 트리거합니다.

4. 청산 위험 평가는 walletBalance 스트림의 실시간 계좌 자산 업데이트를 오픈 포지션 명목 가치와 통합하여 200밀리초마다 마진 비율을 계산합니다.

5. 시간 가중 평균 가격(TWAP) 실행은 대규모 주문을 구성 가능한 간격으로 고정된 크기의 하위 주문으로 분할합니다. 각 하위 주문의 가격은 현재 중간 가격과 지난 5초 주문장 깊이에서 계산된 슬리피지 버퍼를 더한 값에서 파생됩니다.

오류 처리 및 복구 프로토콜

1. 네트워크 연결 끊김 감지는 이중 계층 모니터링을 사용합니다. 즉, 모든 활성 WebSocket 연결에서 15초마다 애플리케이션 수준 핑/퐁 하트비트 검증과 결합된 OS 수준의 TCP 연결 유지 시간 초과입니다.

2. 실패한 주문 제출은 분산된 봇 인스턴스 전체에 걸쳐 동기화된 재시도를 방지하기 위해 지터가 적용되어 최대 5번의 시도로 제한된 기하급수적 백오프 재시도 시퀀스를 트리거합니다.

3. 유효하지 않은 서명 오류가 발생하면 즉시 재인증 흐름이 시작되고, 60초 내에 반복 실패가 3회를 초과하는 경우 캐시된 자격 증명을 삭제하고 새 API 키를 강제로 다시 생성합니다.

4. 주문장 비동기화는 REST GET /v5/market/orderbook을 통해 전체 스냅샷을 요청한 후 후속 WebSocket 업데이트에서 증분 델타 패치를 적용하여 수정됩니다.

5. 포지션 불일치 복구는 격리 마진 계정의 경우 POST /v5/position/reset-isolation 또는 교차 마진 시나리오의 경우 POST /v5/position/set-leverage를 통해 강제 포지션 재설정을 호출하여 일관된 상태 정렬을 복원합니다.

보안 구성 표준

1. API 키 권한은 거래소 수준에서 시행됩니다. 거래 키에는 주문 관리 및 포지션 관리가 활성화되어 있어야 하며, 읽기 전용 키에는 계정 정보 액세스만 필요합니다.

2. 프로덕션 배포에는 IP 화이트리스트 작성이 필수입니다. 사전 승인된 CIDR 범위 외부에서 발생하는 모든 요청은 유효한 서명에 관계없이 즉시 403 Forbidden 응답을 받습니다.

3. 비밀 키는 24시간마다 순환되는 프로세스별 임시 키와 함께 AES-256-GCM을 사용하여 암호화되어 저장되므로 메모리 덤프가 손상되더라도 장기간 노출이 방지됩니다.

4. 모든 아웃바운드 HTTP 요청에는 5000밀리초로 설정된 X-BAPI-RECV-WINDOW 헤더가 포함되어 있으며, 재생 공격 벡터를 완화하기 위해 이 임계값을 초과하여 지연된 모든 서버 응답을 거부합니다.

5. 2단계 인증 우회 토큰은 로컬로 유지되지 않습니다. 초기 설정 중에 요청 시 생성되고 API 등록 성공 후 즉시 삭제됩니다.

자주 묻는 질문

Q1: Bybit에서 현물거래와 파생상품 거래에 동일한 API 키를 사용할 수 있나요? 예. 하지만 생성 중에 키에 두 범주 모두에 대한 권한이 명시적으로 부여되어야 합니다. 스팟 전용 키를 사용하여 파생 상품 엔드포인트에 액세스하려고 하면 오류 코드 10003이 반환됩니다.

Q2: Bybit는 서로 다른 거래 쌍에서 중복된 주문 ID를 어떻게 처리합니까? 각 주문 ID의 범위는 해당 기호로 지정됩니다. 동일한 클라이언트 주문 ID는 충돌 없이 BTCUSDT와 ETHUSDT에 동시에 존재할 수 있지만 충돌 감지는 동일한 거래 쌍 컨텍스트 내에서 엄격하게 적용됩니다.

Q3: 내 봇이 유효하지 않은 레버리지 설정으로 주문을 제출하면 어떻게 되나요? API는 오류 코드 30083으로 이를 거부하고 응답 본문에 정확한 허용 레버리지 범위를 포함하므로 수동 개입 없이 즉각적인 수정이 가능합니다.

Q4: 대량 주문을 하기 전에 현재 시장 유동성을 프로그래밍 방식으로 확인할 수 있는 방법이 있습니까? 예. GET /v5/market/tickers 엔드포인트는 장부 유동성 볼륨을 나타내는 bidSize 및 AskSize 필드를 반환하는 반면, GET /v5/market/orderbook은 지정된 가격 수준에서 누적 심도를 제공합니다.