폴리마켓 API 오류: 흔한 오류 전부 해결(2026, CLOB V2)

API · 문제 해결

대부분의 폴리마켓 API 오류는 원인도 한 줄, 해결도 한 줄이지만 그 답이 GitHub 이슈 곳곳에 흩어져 있습니다. 이 페이지는 개발자들이 CLOB V2 / pUSD에서 실제로 마주치는 오류를 원인, 최소 재현, Python과 Rust 해결책과 함께 모았습니다. 아래에 오류를 붙여 넣으면 해당 항목으로 바로 이동합니다.

order_version_mismatch

원인. V1 형식의 주문(옛 EIP-712 Exchange 도메인 버전 "1", 레거시 필드)에 서명하여 V2 거래소(도메인 버전 "2")에 보냈습니다. 2026년 4월 28일 주문 구조체가 바뀌었습니다. 서명 구조체에서 nonce, feeRateBps, taker, expiration이 제거되고 timestamp, metadata, builder가 추가되었습니다. 거의 언제나 아직 V1 클라이언트를 import하고 있다는 뜻입니다.

해결. V2 SDK로 전환하세요. V2 구조체를 대신 만들고 서명해 줍니다.

pip install py-clob-client-v2          # V1 py-clob-client (0.34.x) is archived
from py_clob_client_v2 import ClobClient
client.create_and_post_order(order_args)   # signs the V2 struct, domain "2"

// Cargo.toml: polymarket_client_sdk_v2 = "0.5"   (official, repo rs-clob-client-v2)
use polymarket_client_sdk_v2::ClobClient;

관련: invalid signature, v1 → v2 마이그레이션.

not enough balance / allowance

원인. V2에서는 자금 지갑이 담보와 지분 토큰을 옮길 수 있도록 V2 거래소 컨트랙트를 승인해야 하며, 담보는 USDC.e가 아니라 pUSD여야 합니다. 매수에는 pUSD 허용량이, 매도에는 CTF(ERC-1155) 승인이 필요합니다. 둘 중 하나라도 없으면 이 오류가 반환됩니다.

해결. (1) USDC.e를 pUSD로 래핑한 다음, (2) pUSD와 조건부 토큰을 세 개의 V2 컨트랙트에 승인하세요:

웹사이트 사용자는 한 번 승인하면 자동으로 래핑되고, API 전용 트레이더는 CollateralOnramp.wrap()(0x93070a847efEf7F70739046A929D47a521F5B8ee)을 직접 호출합니다.

maker address not allowed, please use the deposit wallet flow

원인. POLY_1271 입금 지갑(서명 유형 3)으로 서명하고 있습니다. 2026년 6월 기준 Python(py-clob-client-v2)과 TypeScript(@polymarket/clob-client-v2) 클라이언트에는 미해결 버그가 있어 L1 인증이 API 키를 입금 지갑이 아닌 EOA에 묶고, 거래소가 주문을 거부합니다.

해결. 오늘날 입금 지갑(유형 3) 거래에는 EIP-1271 서명을 올바르게 감싸는 공식 Rust 클라이언트를 사용하세요:

// Rust - authentication_builder().funder(deposit_wallet).signature_type(SignatureType::Poly1271)

Rust 없이 하는 임시방편: 이메일/Magic으로 가입하고 Magic 지갑 키를 내보낸 뒤 signature_type = POLY_PROXY(유형 1)를 사용하세요. 동작하지만 봇 여러 개로 확장하기는 어렵습니다. 이 버그는 계속 바뀌고 있습니다 - 수정 여부는 폴리마켓 이슈 #70(Python)과 #65(TS)를 다시 확인하세요.

the order signer address has to be the address of the API KEY

원인. 주문에 서명한 지갑이 API 키가 파생된 지갑과 일치하지 않거나, 올바른 funder/서명 유형을 전달하지 않았습니다. 서명 키가 자금 보유 주소와 다른 프록시나 Gnosis-Safe 지갑에서 흔합니다.

해결. 서명에 사용하는 것과 동일한 지갑으로 API 키를 파생하고, 개인 키와 funder 주소를 올바른 signature_type과 함께 전달하세요(1 = 이메일/Magic 프록시, 2 = Gnosis Safe, 3 = 입금 지갑).

invalid signature

원인. 보통 다음 중 하나입니다: (a) 잘못된 EIP-712 도메인에 서명 - V2 Exchange 도메인 버전은 "2"입니다(L1 ClobAuth 도메인은 "1" 유지); (b) 기기와 서버 간 시계 오차 > 약 60초; (c) V1 클라이언트(order_version_mismatch 참고).

해결. V2 SDK를 사용해 도메인/구조체를 올바르게 맞추고, 시계를 동기화하세요(NTP).

401 / invalid api key / PolyApiException

원인. L2 자격 증명(API 키/시크릿/패스프레이즈)이 없거나 잘못되었거나, 아예 생성하지 않았습니다. 시장 데이터 읽기는 키가 필요 없으며, 이 오류는 인증이 필요한 호출(주문, 내 포지션)에만 영향을 줍니다.

해결. API 자격 증명을 생성하거나 파생한 뒤, 인증이 필요한 요청에 세 값을 모두 전달하세요:

# client.create_or_derive_api_key()  -> api_key, api_secret, api_passphrase

INVALID_ORDER_MIN_TICK_SIZE

원인. 가격이 시장의 틱 사이즈(흔히 0.01, 때로는 0.001)의 배수가 아닙니다.

해결. 시장의 틱 사이즈(GET /tick-size)를 가져와 서명 전에 가격을 그 단위로 반올림하세요.

FOK_ORDER_NOT_FILLED

원인. Fill-Or-Kill 주문이 현재 호가창에 쌓인 유동성에 대해 지정한 가격으로 전량 체결되지 못해 취소되었습니다(이는 FOK가 의도대로 동작한 것이지 실패가 아닙니다).

해결. 먼저 호가창을 읽고 가용 깊이에 맞춰 수량을 정하거나, 가격을 넓히거나, FOK 대신 GTC/FAK를 사용하세요.

invalid amounts (decimals)

원인. 수량은 소수 자릿수를 지켜야 합니다. 메이커 수량은 소수점 2자리, 테이커 수량은 소수점 4자리까지입니다. 그 이상의 정밀도는 거부됩니다.

해결. 서명 전에 반올림/양자화하고, V2 SDK가 가격 × 수량으로 금액을 계산하게 하세요.

Size lower than the minimum: 5

원인. 최소 지분 수량(5) 미만인 주문은 거부됩니다.

해결. 주문 수량을 5지분 이상으로 늘리세요.

429 / throttled

원인. 슬라이딩 윈도 요청 한도를 초과했습니다. V2 한도는 높고(CLOB 10초당 약 9,000; /book,/price 10초당 1,500; Gamma 10초당 4,000; Data 10초당 1,000) 한도를 넘긴 요청은 완전히 거부되지 않고 지연/대기 처리되지만, 그래도 클라이언트 측 리미터를 두는 것이 현명합니다.

해결. 토큰 버킷 리미터와 429에 대한 지수 백오프를 추가하세요.

다음: 인증과 지갑 · CLOB API 참고 자료 · API 빠른 시작.