Entropy의 Hyperliquid HIP-3 마켓을 거래하는 안전한 Python 자동매매 클라이언트를 구현해줘.
목표는 단순히 주문이 한 번 들어가는 코드가 아니라, 장시간 실행해도 중복 주문·타임아웃·부분 체결·역포지션 사고를 방지하
는 fail-closed 구조다.
[기본 규칙]
- 공식 Hyperliquid Python SDK와 공식 API 문서만 사용한다.
- 기본 네임스페이스:
dex = "io"
coin = "io:ANTH"
- coin은 환경변수 ENTROPY_COIN으로 변경할 수 있게 하되, 코드에서 검토된 io:* 페어 allowlist를 적용한다.
- 메인 지갑 개인키는 절대 사용하지 않는다.
- 주문 서명은 전용 API Wallet/Agent Wallet만 사용한다.
- 계정·잔고·포지션·주문 조회에는 Agent 주소가 아니라 마스터 또는 서브계정 주소를 사용한다.
- 키는 코드, 명령행 인수, 로그, Git에 남기지 않는다. 권한 0600인 별도 파일이나 환경변수에서만 읽는다.
- DRY_RUN을 기본값으로 설정한다. 별도의 명시적 LIVE 플래그 없이는 주문·취소·청산 요청을 보내지 않는다.
[시장 데이터]
1. POST /info에 다음 요청을 보내 io 마켓 메타데이터를 조회한다.
{"type":"metaAndAssetCtxs","dex":"io"}
2. 선택한 coin이 universe에 실제로 존재하는지 확인한다.
3. szDecimals, maxLeverage, isolated 여부, mark price를 검증한다.
4. 다음 요청으로 주문장을 조회한다.
{"type":"l2Book","coin":"io:ANTH"}
5. 실시간 BBO는 WebSocket l2Book 구독으로 받고, REST는 시작 시 검증과 주기적인 상태 조정에 사용한다.
6. WebSocket 주문장이 일정 시간 이상 stale이면 신규 주문을 중단하고 봇이 생성한 기존 주문만 취소한다.
[Agent Wallet]
- 전용 Agent 개인키에서 derived address를 계산한다.
- 계정에 등록된 Agent 목록을 조회해 이름, 주소, 만료 시간을 검증한다.
- Agent가 등록되지 않았거나 주소가 다르거나 곧 만료되면 즉시 종료한다.
- userDexAbstraction 값은 관측 로그만 남기고 무조건적인 거래 허용 조건으로 오판하지 않는다.
- Agent는 서명만 담당하고, 모든 계정 조회에는 ENTROPY_ACCOUNT_ADDRESS를 사용한다.
[주문 규칙]
- 주문 수량은 달러가 아니라 ANTH 단위로 입력한다.
- 모든 메이커 주문은 tif="Alo"로 제출한다.
- ALO 주문이 즉시 체결될 가격이면 테이커 주문으로 바꾸지 말고 거부된 것으로 처리한다.
- 가격과 수량은 거래소 tick size와 szDecimals에 맞게 반올림한다.
- 최소 주문 금액과 사용 가능한 USDC를 시작 전에 검증한다.
- 매수·매도 주문마다 고유한 16-byte CLOID를 생성한다.
- CLOID에는 이 봇이 만든 주문임을 식별할 수 있는 고정 태그를 포함한다.
- 열린 주문 중 태그가 없거나 다른 프로그램이 만든 선택 페어 주문이 발견되면 신규 주문을 중단한다.
- 봇이 생성한 주문만 정확한 CLOID로 조회하고 취소한다.
- 부분 체결된 주문을 재호가할 때 최초 수량이 아니라 거래소가 보고한 remaining size를 사용한다.
- 포지션 한도 바로 전부터 재고를 악화시키는 방향의 주문을 중단하고, 포지션을 줄이는 방향만 유지한다.
[타임아웃과 상태 조정]
주문이나 취소 요청이 타임아웃됐다고 같은 요청을 다시 전송하지 않는다. 이미 거래소에 접수됐을 수 있다.
반드시 다음 순서로 조정한다.
1. CLOID 상태 조회
2. 열린 주문 조회
3. 주문 이력 조회
4. 체결 내역 조회
5. 실제 포지션 조회
상태가 확인된 경우에만 다음 동작을 진행한다. 끝까지 불확실하면 해당 CLOID를 uncertain 상태로 기록하고 모든 추가
mutation을 중단한다.
취소 요청 역시 한 번만 전송한다. REST가 잠시 예전 상태를 반환할 수 있으므로 짧은 read polling으로 취소 여부를 확인하되
취소 mutation 자체는 재전송하지 않는다.
[포지션 청산]
- 설정된 주문 크기가 아니라 거래소가 보고한 실제 signed position size를 사용한다.
- 청산 수량은 abs(position)으로 계산한다.
- 반드시 reduce_only=True를 적용한다.
- 청산 주문에도 새로운 CLOID를 부여한다.
- 응답, CLOID 상태, 체결 내역, 최종 포지션을 확인한다.
- 포지션 0을 확인하지 못했다고 무작정 청산 주문을 다시 보내지 않는다.
- 반대 방향의 신규 포지션이 열릴 가능성이 있으면 fail-closed한다.
[운영 안전장치]
- SIGTERM/SIGINT 수신 시 봇 주문을 정리하고 종료한다.
- 상태 파일을 원자적으로 저장한다.
- 마지막 WebSocket 수신 시간, 포지션, 열린 주문, uncertain CLOID 수를 기록한다.
- 로그에 개인키, 전체 서명값, 인증정보를 출력하지 않는다.
- 프로세스가 비정상 종료됐을 때 봇 태그 주문을 정리하는 watchdog 또는 systemd 종료 훅을 제공한다.
- 기존 서버나 라이브 봇이 있다면 먼저 읽기 전용으로 조사하고 충돌 여부를 확인한다. 다른 봇을 수정하거나 재시작하지 않
는다.
[산출물]
- entropy_mm.py
- test_entropy_mm.py
- requirements.txt
- .env.example
- README.md
- systemd service 예시
- 주문 정리용 watchdog 예시
.env.example에는 실제 값 대신 아래 변수명만 넣는다.
ENTROPY_ACCOUNT_ADDRESS=
ENTROPY_AGENT_SECRET_FILE=
ENTROPY_COIN=io:ANTH
ENTROPY_DRY_RUN=1
ENTROPY_ORDER_SIZE=
ENTROPY_MAX_POSITION=
ENTROPY_REFRESH_SECONDS=
ENTROPY_REPRICE_BPS=
ENTROPY_MAX_BOOK_AGE_SECONDS=
ENTROPY_STATE_FILE=
[검증 순서]
1. unit test와 Python compile
2. 키 없이 공개 metaAndAssetCtxs 및 l2Book preflight
3. DRY_RUN에서 WebSocket BBO와 주문 가격 계산 확인
4. Agent 등록 주소·만료·잔고 읽기 확인
5. 사용자의 별도 LIVE 승인 후에만 최소 수량의 먼 가격 ALO 1건 제출
6. 해당 CLOID가 resting 상태인지 확인
7. 동일 CLOID로 취소
8. 열린 주문 0과 포지션 0 확인
9. 결과와 남은 위험을 과장 없이 보고
각 단계에서 실제 API 응답 구조를 확인하고 구현해라. 문서와 SDK가 다르면 추측하지 말고 공식 SDK 소스와 실제 읽기 전용
응답을 기준으로 조정해라.
공식 참고 문서: API Wallet
(https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets), Order Types
(https://hyperliquid.gitbook.io/hyperliquid-docs/trading/order-types), Exchange API
(https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint).
entropy tier3 코드 (수수료 60%페이백)
현재 페어는 앤스로픽과 샌디스크 뿐인데 bps는 앤스로픽이 더 나았으니 참고하세요
