API · 참고 자료
폴리마켓 시장 데이터를 읽는 데는 키가 필요 없습니다. 주문을 넣거나 취소하려면 두 겹의 인증이 필요합니다. API 자격 증명을 만드는 L1 지갑 서명(EIP-712), 그리고 인증이 필요한 모든 요청에 붙는 L2 HMAC 서명입니다. 이 페이지는 두 가지 모두와 함께, 대부분의 인증 오류를 일으키는 두 요소인 네 가지 서명 유형과 funder 주소를 다룹니다.
한눈에 보기
- 읽기(Gamma, Data, 공개 CLOB) - 인증 불필요.
- L1 - 지갑이 EIP-712 메시지(ClobAuth 도메인 버전
"1")에 서명하여 API 자격 증명을 생성 또는 파생합니다. - L2 - 각 주문 요청은
api_key/api_secret/api_passphrase의 HMAC으로 서명됩니다.
API 자격 증명 생성 또는 파생(L1)
지갑이 한 번 서명하여 결정론적인 API 자격 증명 세트를 발급(또는 재파생)합니다. V2 SDK를 사용하세요.
V1 py-clob-client(0.34.x)는 보관 처리되어 동작하지 않습니다.
from py_clob_client_v2 import ClobClient # pip install py-clob-client-v2
# L1: your wallet signs to derive API credentials
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY)
creds = client.create_or_derive_api_key() # api_key, api_secret, api_passphrase
# L1 + L2: rebuild the client WITH creds for authenticated calls (no set_api_creds in v2)
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY, creds=creds)// polymarket_client_sdk_v2 - official Rust client (repo rs-clob-client-v2)
use polymarket_client_sdk_v2::clob::{Client, Config};
use polymarket_client_sdk_v2::clob::types::SignatureType;
let client = Client::new("https://clob.polymarket.com", Config::default())?
.authentication_builder(&signer)
.funder(deposit_wallet) // deposit wallets work in Rust today
.signature_type(SignatureType::Poly1271)
.authenticate().await?;세 값은 비밀(환경 변수)로 저장하세요. 시장 데이터 읽기에는 절대 필요하지 않습니다.
서명 유형(0-3)
서명 유형은 주문 서명이 자금을 보유한 지갑(funder)에 어떻게 대응되는지를 거래소에 알려줍니다. 계정이 생성된 방식에 맞는 유형을 고르세요.
| 유형 | 이름 | 사용 시점 |
|---|---|---|
| 0 | EOA | 서명과 자금 보유를 모두 하는 일반 지갑(예: MetaMask). |
| 1 | POLY_PROXY | 이메일 / Magic.link 가입 - 프록시 지갑이 자금을 보유하고, 사용자 키가 그 지갑을 대신해 서명합니다. |
| 2 | POLY_GNOSIS_SAFE | Gnosis Safe가 자금을 보유하고, 서명 키가 그것을 대신해 서명합니다. |
| 3 | POLY_1271 | 입금 지갑(EIP-1271 스마트 컨트랙트 서명). |
서명 키가 자금 보유 주소와 다를 때(유형 1-3)는 개인 키와 funder 주소를
모두 전달해야 합니다.
입금 지갑(유형 3) - 현재는 Rust를 사용하세요. 2026년 6월 기준 Python
(
py-clob-client-v2)과 TypeScript(@polymarket/clob-client-v2) 클라이언트에는
미해결 버그가 있습니다. L1 인증이 API 키를 입금 지갑이 아닌 EOA에 묶어서 주문이
거부됩니다("maker address not allowed, please use the deposit wallet flow"). 공식
Rust 클라이언트는 EIP-1271 입금 지갑 서명을 올바르게 처리합니다. Rust를 쓰지 않는 임시방편:
이메일/Magic 계정을 사용하고 signature_type = POLY_PROXY(유형 1)로 서명하세요. 수정 여부는
폴리마켓 이슈 #70(Python) / #65(TS)를 다시 확인하세요.요청 서명(L2)
인증이 필요한 각 요청에는 API 시크릿과 요청 메서드, 경로, 본문, 타임스탬프로 만든 HMAC 서명이 실립니다. V2 SDK가 이 헤더들을 대신 만들어 줍니다. 올바르게 유지해야 할 두 가지:
- 시계 - 약 60초를 넘는 오차가 있으면 서명이 거부됩니다. NTP로 동기화하세요.
- 도메인 - L2/ClobAuth EIP-712 도메인 버전은
"1"로 유지되고, V2 Exchange(주문) 도메인만"2"로 바뀌었습니다. V1 클라이언트는 잘못된 주문 도메인에 서명해 실패합니다 - order_version_mismatch 참고.
키 보안
- 개인 키나 API 시크릿을 절대 하드코딩하지 마세요. 환경 변수를 사용하고, 커밋하지 마세요.
- 가능하면 서명 키와 funder 주소를 평소 쓰는 지갑과 분리해 두세요.
- 읽기 전용 봇은 자격 증명이 전혀 필요 없습니다. 거기서 시작하세요.
다음: CLOB API: 주문 넣기 · 인증 오류 해결 · v1 → v2 마이그레이션.
