PolyOrderbooks MCP Server

Claude, Cursor, and 기타 모든 MCP 클라이언트를 위한 과거 Polymarket 주음장 깊이(order book depth) — 결제된 결과가 척부된 1초 해상도의 완전한 L2 매·매도 호가 레더 등을 의미합니다.

Polymarket의 자체 API는 가격 기록을 잘 제공합니다. 그러나 어떤 단위로도 주문장 깊이를 보관하지 않습니다 — /book은 현재 상태만 반환하며 이를 저장하는 곳은 없습니다. 이 서버는 실시간으로 포착된 깊이를 노출하는데, 이것은 사후에는 되살릴 수 없는 부분입니다.

설치

설치할 것 없습니다. MCP 클라이언트 구성에 추가하면 npx로 실행됩니다.

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "polyorderbooks": {
      "command": "npx",
      "args": ["-y", "@polyorderbooks/mcp-server"],
      "env": { "POLYORDERBOOKS_API_KEY": "pob_..." }
    }
  }
}

Cursor — .cursor/mcp.json, 같은 형식입니다.

구성 파일을 편집한 후 클라이언트를 다시 시작하세요. MCP 서버는 실행 시에 시작됩니다.

Related MCP server: polymarket-mcp-server

API 키 발급

1. polyorderbooks.com/signup에서 가입하세요. 신용 카드는 필요하지 않습니다.

2. 대시보드를 열어 키를 만드세요. pob_ 뒤에 긴 무작위 문자열이 붙은 형태입니다.

3. 위 예시와 같이 MCP 클라이언트 구성 파일의 env 블록에 넣으세요.

무료 Starter 플랜은 유료 플랜과 동일한 1초 간격으로 조회합니다. 유료 플랜이 추가하는 것은 더 긴 기록 보존 기간과 더 높은 요청 허용량이지, 더 정밀한 데이터가 아닙니다. 무엇이든 지불하기 전에 실제 질문에 답할 수 있을 정도로 Starter로 충분합니다.

get_usage 도구를 호출하여 설정한 키의 플랜, 한도, 남은 허용량을 확인할 수 있습니다.

환경 변수

이 변수들은 에이 아닌 MCP 클라인언트 구서에 지정하레요. 클라인언트는 서버를 하위 프세스로 시행하며 인터랙티브 셸 환경을 그 서버에 전달하지 않으므로 .zshrc에서 export한 키는 서버에 보이지 않습니다.

도구

카탈로그는 시리즈 → 이벤트 → 마켓 순서입니다. search_series로 특정 종류의 마켓을 찾고, search_events로 함께 결제되는 세트를 찾고, search_markets로 특정 마켓 하나를 찾습니다.

데이터를 해석하기 전에 알아야 할 것들

마켓이 결제되면서 호가서는 한쪽으로 쏠립니다. 5bp 마켓의 마지막 1분에는 스냅샷의 76%가 매수 또는 매도 한쪽이 비어 있습니다 — 아무도 지는 결과를 제공하지 않는 것입니다. 이것은 데이터 누락이 아니라 실제 마켓의 행동이며, 양쪽 호가서가 존재한다는 가정에 기반한 분석을 깨뜨립니다.

계약 기간이 모든 것을 바꿔 놓습니다. 4시간 계약은 0.5%의 시간에만 한쪽으로 편중되고, 5분 계약은 17%입니다. 한쪽 계약에서 얻은 결론은 다른 쪽으로 이전되지 않습니다.

응답은 빠르게 커집니다. 1초 간격으로 1시간을 조회 요청하면 토큰당 3,600개 버킺이고, 마켓 하나에는 토크객이 두 개 있습닉니다. 시간대를좁거나 해한 상도를 낮고, 반환된 next_cursor로 페이지를 나누세요.

예시 프롬프트

어제 결제된 BTC 5분 마켓들을 찾아 결제 전 마지막 2분 안에 오더북 깊이가 어떻게 바뀌었는직 보여줘.

이 마켓의 경우, 마감 5초 전에 실제 레더 기준으로 buy 100주를 사려면 그 순간의 미드 포인트와 대비해 얼마의 비용이 들었을까?

지난 하루 동안 5분, 15분, 4시간 BTC 계약의 스프레드 와 유동성을 비교해줘.

두 번째 프롬프트가 바로 L2 데이터의 요점입니다. 가격 시퀸스는 시장이 어디에 있었는지는 알려주지만, 실제로 얼마에 매매할 수 있었는지는 레더만이 알려줍니다.

다른 Polymarket MCP 서버와의 차이점

이미 좋은 서버 여러 개가 있습니다 — kukapay/polymarkets-predictions-mcp, demwick/polymarkets-agent-mcp, PaulieB14/graph-polymarkets-mcp. 이들은 Polymarket의 자존 Gamma 및 CLOB API를 잘 핑하여 사용합니다.

차이는 노력의 문제가 아니라 구조적입니다. Polymarket의 /book 끝점은 현재 상태만 반환할 뿐 아무 곳도 저장하지 않기 때문에, 그 API를 만든 어떤 서버도 과거 호가 레더를 제공할 수 없습니다. 그 반면 이 서버는 실시간으로 캡처된 아카이브를 읽어옵니다.

거래하거나 밀리 배당률을 보고 싶다면 그들의 서버를 사용하세요. 그 부분은 더 잘 다루니까. 이 서버는 특정 과거 시점에 호가서가 어떠했는지에 대한 질문을 다룰 때 사용하세요.

문제 해결

• "POLYORDERBOOKS_API_KEY is not set" — 키가 없습니다. 호가서는 셸이 아닌 클라이언트 구성의 env` 블록에 있어야 합니다. 자세한 것은 환경 변수를 참고하세요.

• Authentication failed — 키가 서버에 도이 했지만 API가 이를 거부했습니다. 키는 pob_로 시작합니다. 터미널에서 붙여넣었을 때 마지막 줄바이나 의도하지 않은 따옴표가 있는지 확이하세요. 이상이 않으면 get_usage를 찾조해 키가 관성되어 있는지 확인하세요.

• 응답이 잘리거나 결과가 느린 경우 — 1초 간격으로 1시간을 한 번에 가져히면 토큐당 3,600개 버킷이 됩니이다. 그리고 각 마켓에는 두 개의 토큐이 있습니다. 기간을 줄이거나, 보다 더 큰 resolution: "1m" 같은 해上도 옵션을 사용하세요. 그런 뒤 next_cursor 로 계속 습니다.

• 빌 호가 레더 — 결제 시기가 가까워질 때 예상되는 현상입니다. 위의 한쪽 호가서(오더 북)에 있는 주 부분을 보세요.

공개 데이터

805개의 종료된 마켓, 3가지 계약 기간에 걸쳐 세로 기록한 897,192 스냅샷이 CC BY 4.0 라이선스와 DOI를 달아 공개되어 있습니다. 회원 가입 안 해도 됩니다:

doi.org/10.5281/zenodo.22084114

위 속성을 직접 확인해본 뒤 이 데이터를 활용하면 됩니다.

개발

npm install
npm run build
POLYORDERBOOKS_API_KEY=pob_... npm run dev

이 서버는 stdio를 사용합니다. MCP 클라이언트 없이 테스트하려면 표준 입력으로 JSON-RPC 요청을 보내세요 — initialize, 다음 tools/list, 다음 tools/call.

링크

• polyorderbooks.com — API

• docs.polyorderbooks.com — 참고 문서

• Python client — pip install polyorderbooks

• 무료 BTC 샘플 — 하나의 마켓, 가입 없이

라이선스

MIT. Polymarket과는 제휴, 보증 또는 관련이 없습니다.