예측 시장은 API를 구축하는 데 있어 기술적으로 가장 까다로운 영역 중 하나입니다. 만기가 있는 금융 상품, 실시간으로 가격이 책정되는 확률, 복잡한 자본 관계를 가진 다중 결과 이벤트, 그리고 UI를 클릭하는 사람과 차익 거래 전략을 실행하는 자동화된 트레이딩 봇을 모두 포함하는 사용자 기반을 다루고 있기 때문입니다. 모든 설계 결정은 즉시 스트레스 테스트를 받습니다.
현재 거래량 기준 세계 최대 예측 시장 플랫폼인 Polymarket은 이러한 이유로 연구할 가치가 있는 API 생태계를 구축했습니다. 이는 단순히 데이터베이스 위에 CRUD API를 구축한 것이 아닙니다. 개방성과 보안, 실시간 데이터와 기록 데이터, 전통적인 금융 패턴과 암호화폐 기반의 기본 요소 사이의 근본적인 긴장을 다루는 신중하게 계층화된 아키텍처입니다.
그들이 구축한 방식에서 추출할 만한 여덟 가지 디자인 패턴은 다음과 같습니다.
패턴 1: 도메인 분리 API 계층
Polymarket은 각각 명확한 도메인을 가진 세 가지 개별 API를 노출합니다.
- 감마 API (
gamma-api.polymarket.com) — 시장 탐색, 이벤트, 태그, 검색 - CLOB API (
clob.polymarket.com) — 주문장 데이터, 가격 책정, 주문 제출 - 데이터 API (
data-api.polymarket.com) — 사용자 포지션, 거래, 분석, 리더보드
이것은 단순한 명명 규칙이 아닙니다. 각 API는 다른 인증 요구 사항, 다른 업데이트 주기, 그리고 다른 소비자 프로필을 가지고 있습니다. 감마 API는 전적으로 공개되어 있으며 탐색 및 검색에 최적화되어 있습니다. CLOB API는 공개 엔드포인트(누구나 주문장을 읽을 수 있음)와 인증된 엔드포인트(거래에는 자격 증명이 필요함)를 모두 가지고 있습니다. 데이터 API는 공개되어 있지만 지갑 주소 기반입니다. 사용자 주소로 포지션을 쿼리합니다.
여기서의 디자인 교훈은 엔티티별이 아닌 도메인별로 분리하는 것이 더 일관된 API를 생성한다는 것입니다. 순진한 접근 방식은 /markets, /orders, /users를 모두 한 지붕 아래에 두게 될 것입니다. 대신 Polymarket은 "이 API는 무엇을 위한 것인가?"라고 묻고 그 질문을 중심으로 구축합니다. 검색은 거래와 다른 접근 패턴을 가지고 있습니다. 거래는 분석과 다른 지연 시간 요구 사항을 가지고 있습니다. 각각에 고유한 기본 URL을 부여함으로써 각각 독립적으로 진화하고, 확장하고, 인증할 수 있습니다.
패턴 2: 공개 우선 데이터 접근
가격, 주문장, 이벤트 메타데이터, 과거 거래 등 시장 데이터에 대한 모든 것은 완전히 공개되어 있습니다.
curl "https://gamma-api.polymarket.com/events?limit=5"
API 키가 없습니다. OAuth도 없습니다. 읽기 엔드포인트에는 속도 제한이 없습니다. 데이터를 얻을 수 있습니다.
이는 대부분의 금융 플랫폼이 하지 않는 의도적인 선택입니다. 전통적인 거래소는 시장 데이터를 수익원으로 보호합니다. Polymarket은 이를 인프라로 취급합니다. 더 많은 사람이 데이터를 읽고 구축할수록 시장은 더 유동적이고 유용해집니다. 이는 API에 적용된 공공재 논리입니다.
API 설계자에게 실질적인 결과는 주목할 만합니다. 인증을 일률적으로 적용하기보다는 읽기 접근과 쓰기 접근을 일류 관심사로 분리하는 것이 데이터 소비가 데이터 생산보다 훨씬 많은 플랫폼에서는 거의 항상 올바른 선택입니다. 사용자가 자격 증명 없이 시장 가격을 읽을 수 있다면, 잠재 고객의 95%에게서 마찰을 제거한 것입니다. 마찰은 실제로 중요한 시점, 즉 실제 주문을 제출하려는 시점에만 추가됩니다.
패턴 3: 실제 신뢰를 반영하는 2단계 인증
거래 엔드포인트는 인증을 요구하지만, Polymarket의 인증 모델은 대부분의 API 설계자가 이전에 보지 못했던 구조를 가지고 있습니다. 서로 다른 목적을 가진 두 가지 수준입니다.
L1 인증은 사용자의 개인 키에서 EIP-712 서명을 사용합니다. 이는 지갑 소유권을 증명합니다. API 자격 증명을 파생하기 위해 정확히 한 번(또는 드물게) 사용합니다.
// L1: 개인 키를 사용하여 API 자격 증명 파생
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
L2 인증은 파생된 자격 증명을 사용하여 HMAC-SHA256을 사용합니다. 이는 모든 거래 요청에 첨부하는 것입니다.
// 모든 거래 요청에 대한 L2 헤더
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
핵심은 서로 다른 작업이 서로 다른 보안 절차를 필요로 한다는 것입니다. API 키를 생성하려면 지갑 제어를 증명해야 합니다. 이는 개인 키에서 암호화 서명을 요구해야 하는 고위험 작업입니다. 그러나 일단 신뢰가 구축되면, 일상적인 거래 요청은 모든 호출에 개인 키로 다시 서명할 필요가 없습니다. L2 자격 증명은 L1 신원에 여전히 연결되어 있으면서도 고빈도 사용에 충분히 가볍습니다.
이 패턴은 암호화폐를 넘어 잘 적용됩니다. "당신이 이 사람임을 증명하세요"(L1, 가장 강력한 자격 증명으로 드물게 수행됨)와 "이 요청이 당신에게서 왔음을 증명하세요"(L2, 세션 자격 증명으로 지속적으로 수행됨)의 차이로 생각할 수 있습니다. 대부분의 웹 앱은 이러한 것들을 하나의 인증 흐름으로 통합하여 보안 미묘함을 잃습니다.
패턴 4: API 호출이 아닌 서명된 메시지로서의 주문
이것이 예측 시장이 기존 API 설계와 가장 크게 달라지는 지점입니다. Polymarket에서 주문을 제출할 때, 단순히 서버로 데이터를 보내는 것이 아니라 강제 가능한 금융 약정인 암호화 서명된 메시지를 생성하는 것입니다.
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
내부적으로 SDK는 EIP-712 형식화된 데이터 구조를 구성하고, 개인 키로 서명한 다음, 서명을 주문과 함께 제출합니다. 매칭 엔진은 오프체인에서 작동하지만, 거래가 매칭되면 해당 서명을 사용하여 Polygon을 통해 온체인에서 정산됩니다. 운영자는 거래를 조작하거나 자금을 이동할 수 없습니다. 서명된 메시지는 권한 부여입니다.
이것은 "API 호출"이 의미하는 바의 의미론을 바꿉니다. 일반적으로 엔드포인트에 제출하는 것은 "나를 대신하여 이것을 해주세요"를 의미합니다. 여기서는 주문을 제출하는 것은 "여기에 이 거래를 승인하는 서명된 문서가 있습니다"를 의미합니다. API는 결정을 내리는 중개자가 아니라 암호화 방식으로 자체 인증되는 메시지를 전달하는 중계기입니다.
암호화폐 분야 외부의 API 설계자에게 주는 교훈은 이것입니다. 전송 계층 자격 증명에 전적으로 의존하는 대신 페이로드 자체가 권한을 전달할 수 있을 때, 부인 방지 및 검증 가능성을 무료로 얻을 수 있습니다. 금융 시스템, 법률 문서 및 고위험 작업은 모두 이 패턴의 후보입니다.
패턴 5: 데이터 모델의 명시적 온톨로지
Polymarket은 이벤트(Events)와 시장(Markets)이라는 두 가지 객체를 중심으로 데이터를 구조화합니다. 이 구분은 중요합니다.
이벤트는 질문입니다. "2026년 펜실베이니아 주 미국 상원 선거에서 누가 이길 것인가?" 제목, 카테고리, 해결 날짜를 가집니다. 시장은 해당 이벤트 내에서 특정 거래 가능한 이진 결과입니다. "Bob Casey가 이길 것인가?" 하나의 이벤트는 여러 시장을 포함할 수 있습니다.
{
"id": "501",
"title": "2026 Pennsylvania Senate Race",
"negRisk": true,
"markets": [
{ "id": "2301", "question": "Will Bob Casey win?", "outcomePrices": "[\"0.42\", \"0.58\"]" },
{ "id": "2302", "question": "Will Dave McCormick win?", "outcomePrices": "[\"0.35\", \"0.65\"]" },
{ "id": "2303", "question": "Will a third candidate win?", "outcomePrices": "[\"0.23\", \"0.77\"]" }
]
}
이것은 명시적 온톨로지입니다. API는 단순히 데이터를 저장하는 것이 아니라 엔티티 간의 개념적 관계를 인코딩합니다. 가격은 인덱스 위치가 바인딩 규칙인 병렬 배열로 표시됩니다. outcomes[0]은 outcomePrices[0]에 해당합니다. 이벤트 수준의 negRisk 플래그는 그 안의 시장들이 독립적인 시장에는 존재하지 않는 자본 관계를 가지고 있음을 나타냅니다.
대부분의 API는 이러한 관계를 평면화합니다. Polymarket은 시스템 작동 방식에 중요하기 때문에 이들을 표면화합니다. 자동 거래자를 구축하고 있는데 negRisk: true를 놓친다면, 잘못된 포지션 모델을 구성하고 잠재적으로 돈을 잃을 수 있습니다. API 디자인은 개념적 구조를 가시적으로 만들어, 이를 생략하는 것이 의식적인 선택이지 암묵적인 기본값이 아니게 합니다.
패턴 6: NegRisk — 일류 관심사로서의 자본 관계
이벤트의 negRisk 플래그는 Polymarket의 가장 흥미로운 API 디자인 패턴 중 하나인, 금융 등가성을 프로그래밍 가능하게 만드는 것을 가리킵니다.
표준 다중 결과 이벤트에서는 각 시장이 독립적입니다. 그러나 정확히 하나의 결과만 이길 수 있는 NegRisk 이벤트에서는 포지션 간에 수학적 관계가 존재합니다.
결과 A에 대한 1개의 '아니요' 토큰 ≡ 다른 모든 결과에 대한 1개의 '예' 토큰
이것은 단순히 수학이 아닙니다. 스마트 계약에 구현되어 API를 통해 표면화됩니다. 펜실베이니아 상원 선거에서 "기타"에 대한 '아니요' 포지션을 보유할 때 이를 변환할 수 있습니다.
| 이전 | 이후 |
|---|---|
| 1× 아니요 (기타) | 1× 예 (Casey) + 1× 예 (McCormick) |
API는 이것을 명시합니다. 시장 객체에 negRisk: true가 있고, 이 시장을 거래할 때 주문 옵션에 negRisk: true가 필요합니다. 잘못하면 주문이 거부되거나 잘못 정산될 수 있습니다.
여기서의 디자인 패턴은 도메인 불변성을 문서 각주로 남기지 않고 유형화된 API 필드로 인코딩하는 것입니다. NegRisk 플래그는 편리해서 존재하는 것이 아니라, 생략하면 잘못된 동작을 초래하기 때문에 존재합니다. 도메인에 엄격한 제약(하나의 결과만 이길 수 있음, 포지션에 전환 등가성이 있음)이 있다면, 이러한 제약은 문서에만 있는 것이 아니라 API 표면에 나타나야 합니다.
패턴 7: 시장 상태로서의 동적 틱 크기
대부분의 금융 API는 틱 크기를 정적 구성으로 취급합니다. Polymarket은 더 흥미로운 일을 합니다. 틱 크기는 시장 가격에 따라 동적으로 변하며, API는 이를 실시간 이벤트 스트림으로 노출합니다.
시장의 가격이 극단(0.96 이상 또는 0.04 미만)에 접근하면 최소 틱 크기는 0.01에서 0.001로 좁아집니다.
{
"event_type": "tick_size_change",
"asset_id": "65818619657...",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
이유는 직관적입니다. 극단적인 확률에서 1센트 틱은 25%의 움직임(0.04에서 0.03으로)을 나타냅니다. 이는 의미 있는 가격 발견에는 너무 거칩니다. 극단에 가까울수록 더 미세한 틱은 시장이 97%로 반올림하는 대신 97.3%와 같은 확률을 표현할 수 있도록 합니다.
이것이 API 디자인 선택으로서 주목할 만한 점은 틱 크기가 한 번만 가져오는 매개변수가 아니라는 것입니다. 이는 변하고 추적되어야 하는 상태입니다. WebSocket은 tick_size_change 이벤트를 정확히 노출하여 클라이언트가 현재 시장 상태와 일관되게 주문 구성 로직을 유지할 수 있도록 합니다. 틱 크기를 하드코딩하고 이 이벤트를 놓치면 주문이 거부될 것입니다.
이는 더 광범위한 원칙을 반영합니다. 금융 시스템을 위한 API 디자인은 상태를 일류 개념으로 받아들여야 합니다. 시장 매개변수는 정적이지 않습니다. 해결 규칙은 변경됩니다. 결과는 명확해집니다. API는 이러한 상태 전환을 명시적으로 전달해야 하며, 클라이언트가 거부된 요청을 통해 이를 발견하도록 내버려 두어서는 안 됩니다.
패턴 8: 서로 다른 소비자 프로필을 위한 두 가지 WebSocket 계층
Polymarket은 두 개의 별도 WebSocket 시스템을 운영하며, 그 이유를 이해하면 사용자 세분화에 대한 패턴을 알 수 있습니다.
시장 채널 (wss://ws-subscriptions-clob.polymarket.com/ws/market)은 거래 소비자를 위해 구축되었습니다. 토큰 ID로 구독하고, 주문장 스냅샷, 가격 변동, 거래 실행, 틱 크기 변경을 수신합니다. 모든 것은 자산 ID에 맞춰져 있으며 저지연 주문 구성에 최적화되어 있습니다.
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
실시간 데이터 소켓 (wss://ws-live-data.polymarket.com)은 완전히 다른 프로필을 위해 구축되었습니다. 댓글, Binance 및 Chainlink의 암호화폐 가격, 주식 가격, 소셜 상호작용 이벤트를 스트리밍합니다. 주제별로 구독합니다.
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
이 두 시스템은 근본적으로 다른 요구 사항을 가진 사용자에게 서비스를 제공합니다. 시장 조성자는 마이크로초 단위로 관련 있는 주문장 델타가 필요합니다. "지금 Polymarket에서 무슨 일이 일어나고 있는지"를 보여주는 UI는 댓글 피드와 소셜 활동이 필요합니다. 이들을 결합하면 거래 등급의 지연 시간 요구 사항으로 소셜 피드를 과도하게 설계하거나, 소셜 등급의 신뢰성 가정으로 주문장 피드를 과소하게 설계하게 됩니다.
교훈은 간단하지만 종종 무시됩니다. 실시간 소비자들이 의미 있게 다른 지연 시간 허용 오차, 데이터 볼륨, 실패 모드를 가질 때, 그들에게 별도의 인프라를 제공하세요. 여러 목적을 제공하려고 하는 공유 WebSocket 엔드포인트는 복잡성 면에서 최고 공통 분모로, 성능 면에서 최저 공통 분모로 수렴하는 경향이 있습니다.
이러한 패턴들의 공통점
Polymarket의 API 디자인은 특정 철학을 반영합니다. API는 도메인의 실제 구조를 추상화하지 않고 가시적으로 만들어야 한다는 것입니다.
3계층 아키텍처는 실제 도메인 경계에 매핑됩니다. 공개 우선 접근 방식은 예측 시장 가치가 작동하는 방식을 반영합니다. 2단계 인증은 신원을 증명하는 것과 행동을 승인하는 것 사이의 실제 차이를 반영합니다. 서명된 메시지로서의 주문은 비수탁 보증을 인코딩합니다. 이벤트/시장 계층 구조와 NegRisk 플래그는 그렇지 않으면 보이지 않을 관계를 노출합니다. 동적 틱 크기는 클라이언트 상태를 시장 상태와 일관되게 유지합니다. 별도의 WebSocket 계층은 별도의 사용자에게 서비스를 제공합니다.
대부분의 API 디자인 조언은 인체공학에 중점을 둡니다. 호출하기 쉽고, 명명법이 일관되며, 오류 처리가 예측 가능하도록 만드세요. Polymarket의 API는 이 모든 것을 수행합니다. 그러나 더 흥미로운 선택은 도메인에 대한 충실도에 관한 것입니다. 도메인이 의미 있는 구분을 가질 때, API는 이를 표면에 드러냅니다. 도메인이 제약을 가질 때, API는 이를 강제합니다. 도메인이 변하는 상태를 가질 때, API는 이를 방송합니다.
그 결과는 소비자에게 더 많은 것을 요구하지만, 올바르게 사용하면 거래하는 시스템을 실제로 이해하게 되는 API입니다. 이는 우연이 아닙니다. 가격이 정보를 반영하는 것이 핵심인 예측 시장에서, 시장의 구조를 이해하도록 강요하는 API는 정확히 제 역할을 하고 있는 것입니다.