Polymarket Relayer Client Tutorial

이 가이드는 TypeScript에서 Polymarket Relayer Client를 사용해 가스리스 흐름을 구축하는 방법을 보여줍니다: 지갑 배포, ERC-20 승인 처리, CTF의 split/merge/redeem 작업, 그리고 CLOB에 대한 주문 배치. 가스리스 통합으로 실제 동작하는 솔루션을 만들려면 Polymarket Relayer Client가 개발자가 먼저 사용할 SDK입니다.

주요 요점

Polymarket Relayer Client는 지갑 배포, 승인, CTF 작업 및 Polymarket Relayer를 통한 주문 배치를 처리하는 TypeScript 및 Python SDK를 제공합니다.
Polymarket 거래는 최종 사용자에게 가스리스입니다: Relayer가 가스를 후원하고 지갑 배포와 승인 절차를 추상화합니다.
일반적인 흐름은: 지갑 온보딩 → 승인 확인/요청 → complete set을 mint하는 split → 주문 생성(리밋 또는 FAK) → 결제 후 merge/redeem 입니다.
항상 결제 및 정산 리스크를 설계에 반영하세요: UMA 분쟁, 부분 체결/슬리피지, 시간 지연 등이 실제로 발생할 수 있습니다.

이 가이드는 누구를 위한가

당신은 Polymarket의 CLOB에 주문을 넣고 CTF와 상호작용하는 통합, 봇 또는 UI 컴포넌트를 만드는 개발자입니다. TypeScript, EVM 지갑(MetaMask, Rabby 등)과 기본적인 web3 개념에 익숙해야 합니다.

SDK가 다루는 내용 개요

지갑 온보딩: 첫 사용 시 Proxy 지갑을 배포하거나 사용 가능한 Gnosis Safe 사용.
pUSD 및 split/merge에 사용되는 다른 토큰들에 대한 ERC-20 승인 관리.
CTF 작업: outcome 토큰(ERC-1155)의 split, merge, redeem.
Relayer를 통한 CLOB에 대한 주문 배치 및 취소.
Builder로 활동할 때의 빌더 귀속 헤더 처리(Builder Program 문서 참조).

참고: Polymarket는 Polygon(chain ID 137)을 사용하며 거래의 결제 자산은 pUSD(Polymarket의 래핑된 USDC)입니다. 모든 사용자 트랜잭션은 Relayer를 통해 가스리스로 처리됩니다.

설치 및 첫 단계

TypeScript 패키지와 표준 web3 프로바이더 패키지를 설치하세요. 정확한 패키지 이름은 버전별로 다를 수 있습니다; 아래 예시는 Relayer SDK에서 일반적으로 사용하는 정식 임포트 경로를 사용합니다. 프로젝트의 패키지 이름이 다르면 SDK README를 확인하세요.

Shell

npm install @polymarket/relayer-client ethers

기본 초기화 (TypeScript)

import { RelayerClient } from '@polymarket/relayer-client';
import { ethers } from 'ethers';

// 브라우저에 노출된 지갑 프로바이더 사용 (MetaMask, Rabby 등)
const provider = new ethers.providers.Web3Provider((window as any).ethereum);
const signer = provider.getSigner();

const relayer = new RelayerClient({
  signer,
  network: 'polygon', // Polymarket는 Polygon에서 운영됩니다 (chainId 137)
});

위 예제에 대한 주: RelayerClient 생성자와 옵션 객체는 예시용입니다. 정확한 생성자 시그니처와 사용 가능한 옵션은 SDK README를 확인하세요.

온보딩: 지갑 배포와 승인

Polymarket는 미리 배포된 Gnosis Safe와 첫 트랜잭션에서 자동 배포되는 Proxy 지갑 두 가지 모델을 지원합니다. Relayer SDK는 두 흐름을 모두 처리하며 배포 가스를 후원합니다.

UX에서 구현해야 할 일반적인 온보딩 단계:

사용자가 이미 Proxy 또는 Safe를 가지고 있는지 감지합니다. 없으면 SDK의 deploy-on-first-use 헬퍼를 호출하세요.
사용자가 지갑에 pUSD를 보유하고 있는지 확인하세요. 없으면 브리지나 입금 방법을 안내하세요(Polymarket의 자금 조달 가이드 참조).
pUSD에 대한 ERC-20 승인 상태를 확인하고 필요하면 Relayer를 통한 가스리스 승인을 요청하세요.

예시: 승인 확인 및 요청 (TypeScript)

// 의사코드 — SDK 메서드에 맞게 조정하세요
const pUsdAddress = '0x...'; // SDK 상수 사용 권장
const allowance = await relayer.checkAllowance(pUsdAddress);
if (allowance.lt(requiredAmount)) {
  await relayer.requestApproval(pUsdAddress, requiredAmount);
}

Relayer가 가스를 후원하기 때문에 승인 호출은 사용자가 직접 온체인 가스 트랜잭션에 서명하는 대신 Relayer를 통해 전송됩니다.

CTF 흐름: split, merge, redeem

Conditional Token Framework(CTF)는 Polymarket가 결과를 ERC-1155 토큰으로 나타내는 방식입니다. complete set을 구매하려는 전형적인 순서는 다음과 같습니다:

split: pUSD를 소각하고 outcome 토큰의 complete set을 mint
거래 후, merge: 남은 outcome 토큰을 공통 포지션으로 변환
redeem: 해상도 후, 승리한 outcome 토큰을 각각 $1.00로 소각하여 수령

예시 split (TypeScript)

// Relayer SDK 사용 의사코드
const conditionId = '0x...';
const amount = ethers.utils.parseUnits('1.0', 6); // pUSD는 6자리 소수
await relayer.split(conditionId, amount);

SDK는 필요한 승인과 Relayer 제출을 처리합니다. split 후 사용자의 Proxy 또는 Safe에 ERC-1155 outcome 토큰을 받게 됩니다.

CLOB에 주문하기

CLOB는 주문 배치와 오더북 조회를 제공합니다. Relayer Client는 주문 배치를 Relayer를 통해 라우팅하며, Builder로 활동할 경우 빌더 귀속 헤더를 처리합니다.

중요한 주문 유형:

리밋 주문: 오더북에 게시되어 메이커로 남을 수 있음(메이커 수수료는 0).
마켓 주문(FAK): SDK는 즉시 체결되거나 취소되는 FAK 주문 생성 헬퍼를 제공합니다.

예시: FAK 마켓 주문 생성 (TypeScript)

// 개념적 예시
const instrumentId = 'POLY_MARKET_INSTRUMENT_ID';
const side = 'buy';
const size = ethers.utils.parseUnits('10', 6);

const result = await relayer.createMarketOrder({
  instrumentId,
  side,
  size,
  slippageTolerance: 0.01, // 1% 슬리피지 보호
});

console.log('fill result', result);

Builder로 운영하는 경우 SDK 요구사항에 따라 귀속 헤더나 빌더 자격 증명을 포함하세요. Builder Program은 계층별 Relayer 한도와 보상을 제공합니다; 자격 증명은 https://polymarket.com/settings 에서 얻으세요.

마켓 데이터 조회 및 WebSocket

트레이딩이 아닌 읽기 작업에는 Polymarket의 공개 REST 및 WebSocket 서피스를 사용하세요:

Gamma API: https://gamma-api.polymarket.com (markets, events)
Data API: https://data-api.polymarket.com (positions, trades, open interest)
CLOB API: https://clob.polymarket.com (오더북 및 주문 배치 API)
Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market — 실시간 북 업데이트

마켓 WS 피드를 구독할 때 custom_feature_enabled: true를 요청하면 best_bid_ask 이벤트를 받을 수 있으며, 연결당 500개 상품으로 구독을 제한하세요.

오류 처리 및 흔한 함정

부분 체결: 마켓 주문(FAK)은 부분 체결될 수 있습니다. 항상 결과를 점검하고 남은 수량을 처리하세요.
슬리피지: 공격적인 마켓 주문에는 슬리피지 제한을 적용하세요. SDK는 마켓 헬퍼에 슬리피지 설정을 제공하는 경우가 많습니다.
결제 및 정산 타이밍: UMA 분쟁은 정산을 일시 중단할 수 있습니다. UI와 회계는 redeem이 완료될 때까지 미결제 자금을 반영하도록 설계하세요.
틱 사이즈 변경: 틱 사이즈는 가격 극단 근처에서 $0.01에서 $0.001로 이동합니다; tick_size_change WebSocket 이벤트를 처리하세요.

테스트 전략

엔드투엔드 샌드박스: 전체 온보딩을 실행해 보세요 — Proxy 지갑 배포, 승인 요청, split, 주문 배치, merge/redeem.
래퍼 함수 단위 테스트: relayer 메서드를 모킹하여 올바른 승인 및 split 순서를 검증하세요.
레이트 리밋 인식: Gamma /markets는 레이트 리밋이 있습니다(예: /markets는 300 req / 10 s). 조회를 배치하고 캐시하세요.

이것이 트레이딩 또는 봇 로직에 미치는 영향

Polymarket Relayer Client를 사용하면 최종 사용자의 가스를 관리할 필요가 없고 Proxy 배포와 승인을 자동화해 온보딩이 단순해집니다. 봇의 경우 전략과 마켓 데이터에 집중할 수 있으며, SDK는 split/merge와 주문 흐름의 통합 표면을 줄여줍니다. 다만 슬리피지, 부분 체결, 오라클 분쟁과 같은 실행 외 리스크는 여전히 처리해야 합니다.

참조 및 다음 단계

Polymarket API 기본 URL: Gamma (https://gamma-api.polymarket.com), Data (https://data-api.polymarket.com), CLOB (https://clob.polymarket.com)
Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market
Builder Program 세부사항 및 자격 증명: https://polymarket.com/settings

마감 메모: Polymarket는 Relayer를 통해 가스를 후원하며 일반적인 지갑 및 CTF 워크플로를 간소화하는 TypeScript 및 Python SDK를 제공합니다. Polymarket Relayer Client는 CLOB와 CTF와 상호작용하는 가스리스 통합을 구축하는 권장 경로입니다.

자주 묻는 질문

Polymarket Relayer Client란 무엇인가요?

Polymarket Relayer Client는 사용자의 트랜잭션을 Polymarket의 Relayer를 통해 라우팅하는 SDK(TypeScript 및 Python)로, 지갑 배포, ERC-20 승인, CTF 작업 및 주문 배치를 처리하여 최종 사용자가 가스리스 거래를 경험하도록 합니다.

사용자가 거래하려면 여전히 pUSD가 필요합니까?

예. Polymarket의 결제 자산은 pUSD(래핑된 USDC)입니다. Relayer가 가스를 후원하지만 split 작업과 주문 배치를 위해 사용자는 pUSD를 보유해야 합니다.

Relayer Client를 통해 Builder로 활동할 수 있나요?

예. Builder Program은 제3자가 귀속 헤더와 함께 주문을 라우팅하고 빌더 수수료를 받을 수 있게 합니다. 자격 증명은 https://polymarket.com/settings 에서 얻고 SDK에서 요구하는 빌더 헤더를 포함하세요.

Relayer Client가 승인 및 지갑 배포를 자동으로 처리하나요?

SDK는 첫 사용 시 자동 Proxy 지갑 배포 헬퍼와 Relayer를 통한 가스리스 ERC-20 승인 요청 헬퍼를 제공하여 온보딩을 단순화합니다.

실시간 오더북 업데이트는 어디서 볼 수 있나요?

Market WebSocket wss://ws-subscriptions-clob.polymarket.com/ws/market 에 구독하세요. best_bid_ask 이벤트를 받으려면 custom_feature_enabled: true를 요청하고 500개 상품 구독 제한을 유의하세요.

교육용 자료입니다. 재무, 법률 또는 세금 조언이 아닙니다. Polymarket은 귀하의 관할 구역에서 사용 불가할 수 있습니다.

Polymarket Relayer Client 사용법 튜토리얼