주요 콘텐츠로 건너뛰기
AI 튜토리얼

TypeScript로 Polymarket 카피 트레이딩 봇 구축 및 구성

Polymarket CodeX CopyTrading Bot을 구성하고 여러 지갑을 추적하며, 고정 금액 또는 비율 기반 규모를 선택하고, 주문을 시뮬레이션으로 테스트하고, 실거래 실행을 활성화하고, 위험 한도를 적용하고, 로컬 상태를 안전하게 관리하는 방법을 알아보세요.

약 11분 소요
TypeScript로 Polymarket 카피 트레이딩 봇 구축 및 구성

Polymarket CodeX 카피 트레이딩 봇의 기능

Polymarket CodeX 카피 트레이딩 봇은 하나 이상의 팔로우 지갑 활동을 모니터링하고 이에 대응하는 Polymarket 주문을 생성하는 TypeScript 애플리케이션입니다. 공개 Data API를 통해 지갑 활동을 읽고, @polymarket/clob-client-v2를 사용해 Polymarket 중앙 지정가 주문서에서 실시간 거래를 수행합니다.

이 봇은 고정 USD 금액 또는 백분율 기반 주문 규모를 사용해 매수와 매도를 복사할 수 있습니다. 또한 확인된 거래, 생성된 주문, 실행 또는 시뮬레이션된 주문, 대략적인 토큰 포지션을 로컬에 기록합니다.

위험 경고: 이 소프트웨어는 거래용입니다. 수익은 보장되지 않습니다. 항상 먼저 시뮬레이션을 실행하고, 모든 구성 값을 검토한 뒤, 실제 실행을 고려하기 전에 매우 적은 금액을 사용하세요.

주요 기능

  • 여러 팔로우 지갑을 모니터링합니다.
  • 고정 금액 및 백분율 기반 카피 모드를 지원합니다.
  • npm run test를 통한 시뮬레이션 실행을 제공합니다.
  • npm start를 통한 실시간 시장 실행을 제공합니다.
  • 봇이 로컬에서 추적하는 포지션을 사용해 매도 활동을 따라갈 수 있습니다.
  • 최소 주문, 최대 주문, 포지션 및 일일 명목 가치 한도를 적용합니다.
  • FAK 및 FOK 주문 동작을 지원합니다.
  • 팔로우 거래의 체결 가격을 기준으로 선택적 가격 보호를 제공합니다.
  • 상태를 로컬 JSON 파일에 저장합니다.

요구 사항

봇을 구성하기 전에 다음 소프트웨어를 설치하세요.

  • Node.js 버전 20.10 이상.
  • npm.

프로젝트 소스를 가져오고 해당 디렉터리에서 터미널을 연 다음 패키지 종속성을 설치하세요.

npm install

이 봇은 주문 실행에 비베타 @polymarket/clob-client-v2 패키지를 사용하고, 지갑 활동을 폴링할 때 공개 Polymarket Data API를 사용합니다.

실시간 거래 자격 증명 구성

프로젝트의 .env 파일을 생성하거나 편집하세요. CLOB 호스트, Polygon 체인 ID, 서명 유형, 프라이빗 키 및 입금 지갑을 추가하세요.

POLYMARKET_CLOB_HOST=https://clob.polymarket.com
POLYMARKET_CHAIN_ID=137
POLYMARKET_SIGNATURE_TYPE=POLY_1271
POLYMARKET_PRIVATE_KEY=0x...
POLYMARKET_DEPOSIT_WALLET=0x...

실제 프라이빗 키나 자격 증명 파일을 버전 관리 시스템에 커밋하지 마세요. 프라이빗 키와 모든 CLOB 자격 증명을 비밀 정보로 취급하세요.

올바른 서명 유형 선택

POLYMARKET_SIGNATURE_TYPE에는 다음 값을 사용할 수 있습니다.

  • EOA
  • POLY_PROXY
  • POLY_GNOSIS_SAFE
  • POLY_1271

프로젝트 문서에 따르면 POLY_1271은 일반적으로 신규 입금 지갑 사용자에게 적합합니다. 외부 소유 계정을 통해 직접 거래하는 경우에는 EOA를 선택하세요. 이 경우 POLYMARKET_DEPOSIT_WALLET을 생략할 수 있습니다.

기존 L2 자격 증명 사용

봇은 시작할 때 자격 증명을 생성할 수 있습니다. 이 단계를 생략하려면 .env에 기존 L2 자격 증명을 입력하세요.

CLOB_API_KEY=...
CLOB_SECRET=...
CLOB_PASS_PHRASE=...

실시간 실행에는 createAndPostMarketOrder가 사용됩니다. 실시간 거래를 시작하기 전에 거래 지갑에 자금이 있고 필요한 Polymarket 승인이 완료되었는지 확인하세요. 봇은 지갑을 배포하거나 토큰 사용을 자동으로 승인하지 않습니다.

카피 주문 규모 구성

이 애플리케이션은 두 가지 카피 모드를 지원합니다. 봇이 감수할 노출 규모에 맞는 모드를 선택하세요.

고정 모드

고정 모드는 복사된 매수 및 매도 활동에 미리 정해진 USD 금액을 할당합니다.

COPY_MODE=fixed
FIXED_BUY_AMOUNT_USD=5
FIXED_SELL_AMOUNT_USD=5

이 예시에서는 적격 복사 매수와 매도가 설정된 5 US 달러 금액으로 주문됩니다.

백분율 모드

백분율 모드는 팔로우 지갑의 활동을 기준으로 주문 규모를 계산합니다.

COPY_MODE=percentage
COPY_PERCENTAGE=0.10

매수의 경우 봇은 팔로우 거래의 USD 명목 가치 중 설정된 백분율을 복사합니다. 매도의 경우 팔로우 지갑이 매도한 주식 수 중 설정된 백분율을 복사합니다. 매도 수량은 봇의 로컬 상태에서 현재 추적하는 포지션을 초과할 수 없습니다.

예를 들어 0.10은 10%를 의미합니다. 실제 주문은 구성된 위험 제어 조건도 충족해야 합니다.

위험 제어 설정

시뮬레이션 거래나 실시간 거래를 실행하기 전에 .env에서 주문 및 노출 한도를 정의하세요.

MIN_ORDER_USD=1
MAX_ORDER_USD=25
MAX_POSITION_USD_PER_TOKEN=100
DAILY_MAX_NOTIONAL_USD=250
ORDER_TYPE=FAK
PRICE_PROTECTION_BPS=0
  • MIN_ORDER_USD는 허용되는 최소 주문 가치를 설정합니다.
  • MAX_ORDER_USD는 개별 주문의 가치를 제한합니다.
  • MAX_POSITION_USD_PER_TOKEN은 각 토큰의 대략적인 노출을 제한합니다.
  • DAILY_MAX_NOTIONAL_USD는 일일 총 명목 가치 활동을 제한합니다.
  • ORDER_TYPE은 체결 동작을 제어합니다.
  • PRICE_PROTECTION_BPS는 선택적으로 팔로우 체결 가격을 기준으로 실행 가격을 제한합니다.

FAK 및 FOK 주문 이해

ORDER_TYPE=FAK인 경우 주문이 부분적으로 체결될 수 있으며, 체결되지 않은 잔여 수량은 취소됩니다. ORDER_TYPE=FOK인 경우 주문 전체가 체결되어야 하며, 그렇지 않으면 주문이 실패합니다.

부분 실행이 허용되는 경우 FAK가 적합할 수 있습니다. FOK는 더 엄격하지만, 유동성이 충분하지 않을 때 더 많은 주문이 실패할 수 있습니다.

가격 보호 적용

PRICE_PROTECTION_BPS=0이면 CLOB 클라이언트가 시장가 주문에 적용될 최악의 가격을 추정합니다. 0이 아닌 값이 설정되면 봇은 매수 시 팔로우 체결 가격보다 높은 최악 가격 한도를, 매도 시에는 그보다 낮은 한도를 계산합니다.

가격 보호 기능은 허용되는 가격 변동을 제한할 수 있지만, 이 설정을 활성화해도 주문 체결을 보장하지는 않는다고 README에 명시되어 있습니다.

먼저 시뮬레이션 실행

프로젝트의 테스트 명령으로 시작합니다.

npm run test

이 모드는 실제 시장 주문 대신 시뮬레이션 주문을 생성합니다. 이를 사용하면 실제 거래를 즉시 제출하지 않고 지갑 모니터링, 주문 규모 산정, 위험 한도 및 환경 설정을 검증할 수 있습니다.

테스트 중 다음 항목을 확인하세요.

  1. 의도한 지갑이 모니터링되고 있는지 확인합니다.
  2. 매수 및 매도 이벤트가 올바르게 정규화되는지 확인합니다.
  3. 선택한 카피 모드가 예상한 주문 규모를 생성하는지 확인합니다.
  4. 주문이 최소 한도, 최대 한도, 포지션 한도 및 일일 한도를 준수하는지 확인합니다.
  5. 매도 규모가 로컬에서 추적하는 포지션을 초과하지 않는지 확인합니다.
  6. 상태가 ./data/state.json에 기록되는지 확인합니다.

실거래 시작

시뮬레이션 결과, 지갑 자금, 승인, 자격 증명 및 모든 위험 설정을 검토한 후 다음 명령으로 실거래 실행을 시작합니다.

npm start

이 명령은 실제 시장 주문을 활성화합니다. 아주 작은 규모로 시작하고 터미널 출력과 Polymarket 계정을 모두 모니터링하세요. 시뮬레이션 결과가 실제 체결, 유동성 또는 가격 변동과 정확히 일치한다고 가정하지 마세요.

로컬 상태 이해

봇은 다음 위치에 로컬 상태를 저장합니다.

./data/state.json

이 파일은 확인된 거래, 시뮬레이션 또는 실행된 주문, 예상 포지션을 추적합니다. 이미 처리된 활동이 새로운 활동으로 처리되는 것을 방지하고, 매도 추종 로직에 사용 가능한 포지션에 대한 로컬 정보를 제공합니다.

시장 주문은 부분 체결될 수 있으므로 포지션은 근사치일 뿐입니다. 따라서 로컬 상태가 실제 계정 보유량과 달라질 수 있습니다.

고급 운영 팁

포지션 조정 기능 추가

README는 운영 환경에서 주기적인 조정 작업을 추가할 것을 권장합니다. 이 작업은 Data API의 /positions 엔드포인트에 POLYMARKET_DEPOSIT_WALLET을 사용해 요청하고, 반환된 포지션을 로컬 상태와 비교해야 합니다.

부분 체결, 주문 실패, 수동 거래, 재시작 또는 봇 외부에서 수행된 활동이 발생한 후에는 특히 중요합니다.

상태 파일 보호

업그레이드나 운영 변경 전에 ./data/state.json을 백업하세요. 봇이 실행 중일 때는 파일을 편집하지 마세요. 이 파일은 확인된 활동과 예상 포지션을 기록하므로 삭제하거나 손상시키면 중복 감지와 매도 규모 산정에 영향을 줄 수 있습니다.

보수적인 한도 사용

낮은 MAX_ORDER_USD, MAX_POSITION_USD_PER_TOKEN 및 DAILY_MAX_NOTIONAL_USD 값으로 시작하세요. 현실적인 시장 환경에서 봇을 관찰한 후에만 값을 높이세요. 위험 한도는 노출을 제한하지만 체결, 유동성, 시장 또는 소프트웨어 위험을 없애지는 않습니다.

관련 소스 파일 검토

저장소는 설정, 폴링, 전략, 실행 및 상태 관련 책임을 다음과 같이 분리합니다.

  • src/config.ts는 환경 변수 파싱과 안전성 검사를 처리합니다.
  • src/index.ts에는 기본 폴링 루프가 포함되어 있습니다.
  • src/polymarket/dataApi.ts는 공개 Data API 조회를 수행합니다.
  • src/watchers/walletWatcher.ts는 여러 지갑의 활동을 폴링합니다.
  • src/polymarket/tradeParser.ts는 활동 이벤트를 정규화합니다.
  • src/strategy/copyStrategy.ts는 고정 및 백분율 기반 규모 산정을 구현합니다.
  • src/strategy/riskManager.ts는 주문, 일일 및 포지션 한도를 적용합니다.
  • src/polymarket/orderExecutor.ts는 시뮬레이션 및 실거래 실행을 처리합니다.
  • src/storage/stateStore.ts는 로컬 JSON 상태를 관리합니다.

실거래 배포 전에 이러한 파일을 검토하면 유용합니다. 특히 폴링 동작, 안전성 검사, 이벤트 정규화 또는 주문 규모 산정 방식을 이해해야 하는 경우에 그렇습니다.

결론

Polymarket CodeX CopyTrading Bot은 여러 지갑을 모니터링하고 고정 또는 백분율 기반 규모 산정을 사용해 조건에 맞는 매수 및 매도를 복사하는 TypeScript 워크플로를 제공합니다. 자격 증명을 신중하게 설정하고, 보수적인 위험 한도를 적용하며, npm run test를 통해 동작을 검증하고, 실거래에 npm start를 사용하기 전에 로컬 포지션을 조정하세요.