TypeScript SDK

@polytest/sdk는 PolyTest API의 공식 TypeScript 클라이언트입니다. Node 20 이상에서 Polymarket의 과거 마켓, 스냅샷, 오더북을 읽습니다. 타입 정의가 패키지에 함께 들어 있으며, 런타임 의존성은 없습니다.

Python 및 Go SDK는 계획되어 있습니다. 출시 전까지는 빠른 시작에 각 요청이 curl과 Python으로 나와 있습니다.

설치

npm에서 패키지를 설치하고, API 키를 POLYTEST_KEY 환경 변수에 넣으세요.

Terminal
npm install @polytest/sdk
export POLYTEST_KEY="pt_live_your_key_here"

패키지는 npm에, 소스 코드는 GitHub에 있습니다.

첫 요청

polytest()는 POLYTEST_KEY에서 키를 읽습니다. 이 예시는 BTC 5m 마켓 목록을 가져와 결과가 확정된 마켓 하나의 스냅샷 5개를 출력한 다음, 그중 첫 번째 순간을 양쪽 오더북과 함께 다시 가져옵니다.

TypeScript
import { polytest } from "@polytest/sdk"

const api = polytest() // reads POLYTEST_KEY

// The newest BTC 5m markets, then the first one that has resolved
const markets = await api.markets({ market_type: "5m", coin: "btc", limit: 10 })
const market = markets.items.find((m) => m.winner !== null)
if (!market) throw new Error("No resolved market on this page")
console.log(market.slug, market.winner)

// Its first five snapshots
const page = await api.snapshots(market.market_id, { limit: 5 })
for (const shot of page.items) {
  console.log(shot.time, shot.price_up, shot.price_down)
}

// The first moment again, now with both order books
const [first] = page.items
if (first) {
  const { snapshot } = await api.snapshotAt(market.market_id, {
    timestamp: first.time,
    include_orderbook: true,
  })
  console.log(snapshot.orderbook_up?.bids, snapshot.orderbook_up?.asks)
}

클라이언트 설정

polytest()는 네 가지 옵션을 받습니다. 어느 옵션이든 생략할 수 있습니다.

옵션기본값설명
keyprocess.env.POLYTEST_KEYX-API-Key로 전송되는 API 키입니다. 앞뒤의 공백과 탭은 제거됩니다.
originhttps://api.polytest.io요청을 보낼 대상입니다. https를 사용해야 하며(localhost에서는 http도 가능), 경로를 포함할 수 없습니다.
fetchglobalThis.fetch사용자 지정 fetch 함수입니다. 이 함수가 중단 신호를 무시해도 타임아웃은 그대로 적용됩니다.
timeoutMs30000요청당 제한 시간(밀리초)이며, 본문을 받는 시간까지 포함합니다. 시간을 넘긴 호출은 network 오류를 던집니다. null이면 제한이 꺼집니다.
TypeScript
import { polytest } from "@polytest/sdk"

const api = polytest({
  key: "pt_live_your_key_here",
  timeoutMs: 10_000,
})

health()는 키 없이도 동작합니다. 키가 설정되지 않은 경우 나머지 모든 메서드는 아무것도 보내기 전에 종류가 config인 PolyTestFailure를 던집니다.

클라이언트는 리디렉션을 따르지 않으므로, 키는 설정한 origin으로만 전송됩니다. 3xx 응답을 받으면 http 오류를 던집니다.

메서드

모든 메서드는 Promise를 반환하며, 모든 결과에는 meta가 포함됩니다(응답 meta 참고).

메서드필드반환값
health()status(ok 또는 degraded)와 timestamp. 키를 보내지 않습니다.
limits()플랜의 한도: tier, rate_limits, concurrency, data_access, api_keys, trial_budget.
markets(query)market_type, coin?, limit?, offset?, start_time?, end_time?최신순으로 정렬된 마켓 한 페이지.
market(ref)market_id | slugmarket_id 또는 slug로 지정한 마켓 하나.
snapshots(market_id, query?)limit?, offset?, start_time?, end_time?, include_orderbook?오래된 순으로 정렬된 스냅샷 한 페이지.
snapshotAt(market_id, query)timestamp, include_orderbook?timestamp에 가장 가까운 스냅샷(앞뒤 최대 2초).
  • market_type은 5m, 15m, 1hr, 4hr, 24hr 중 하나입니다. 이 목록은 MARKET_TYPES로 export됩니다.
  • coin은 btc, eth, sol처럼 소문자로 쓰세요. 생략하면 서버가 btc 마켓을 반환합니다.
  • start_time, end_time, timestamp는 ISO 8601 형식을 받습니다. 시간대가 없는 시각은 UTC로 해석되며, T 대신 공백을 써도 됩니다.
  • 인수는 요청 전에 검사됩니다. 잘못된 인수가 있으면 bad_request 오류를 던지고 아무것도 전송하지 않습니다. null을 넣으면 오류가 발생하므로, 선택 필드를 쓰지 않으려면 아예 생략하세요.

페이지

markets와 snapshots는 페이지를 반환합니다. 행은 items에 있고, stop은 뒤에 행이 더 있는지 알려줍니다. page.next()는 다음 페이지를 가져오며, 다음 페이지가 없으면 null을 반환합니다.

stop의미next()
morenextOffset에서 다음 페이지가 이어집니다.다음 페이지를 가져옵니다.
end마지막 페이지입니다.요청 없이 null을 반환합니다.
tier_window플랜에 포함된 데이터의 끝에 도달했습니다.요청 없이 null을 반환합니다.
snapshot_offset_cap순회가 스냅샷 offset 상한인 100000에 도달했습니다.요청 없이 null을 반환합니다.
TypeScript
import { polytest, type Page, type Snapshot } from "@polytest/sdk"

const api = polytest()
const marketId = "1496946"

let page: Page<Snapshot> | null = await api.snapshots(marketId, { limit: 500 })
let rows = 0
while (page) {
  rows += page.items.length
  if (page.stop !== "more") console.log(rows, "rows, stopped by", page.stop)
  page = await page.next()
}

클라이언트가 읽을 수 없는 행은 items에서 제외되고 skipped에 집계됩니다. 다음 offset에는 이런 행도 계산되므로, 건너뛴 행 때문에 순회가 일찍 끝나지는 않습니다.

total은 서버의 추정값입니다. stop이 more가 아닌 값이 될 때까지 계속 페이지를 넘기세요.

스냅샷 offset이 100000을 넘으면 요청 전에 bad_request 오류를 던집니다. 긴 마켓에서 더 뒤쪽 데이터를 읽으려면 start_time과 end_time으로 범위를 좁히세요.

오더북

snapshots 또는 snapshotAt에 include_orderbook: true를 전달하세요. 그러면 각 스냅샷에 orderbook_up과 orderbook_down이 포함되고, 각 오더북에는 bids와 asks가 있습니다.

TypeScript
import { polytest } from "@polytest/sdk"

const api = polytest()
const marketId = "1496946"

const page = await api.snapshots(marketId, { limit: 100, include_orderbook: true })
for (const shot of page.items) {
  if (shot.orderbook_up_invalid) continue // the client could not read this book
  for (const { price, size } of shot.orderbook_up?.asks ?? []) {
    console.log(shot.time, price, size)
  }
}

각 호가 단계는 price와 size를 가진 객체입니다. API가 [price, size] 쌍으로 보내는 경우에도 마찬가지입니다. depth 같은 추가 오더북 필드는 그대로 유지됩니다.

클라이언트가 읽을 수 없는 오더북은 null로 반환되며, orderbook_up_invalid 또는 orderbook_down_invalid가 true로 설정됩니다. 이 플래그 없이 null인 오더북은 원래 없었던 것입니다. 어느 경우든 스냅샷의 나머지 부분은 유지됩니다.

리터럴 true를 넘기면 행의 타입은 SnapshotWithBooks가 됩니다. boolean 변수를 넘기면 Snapshot 또는 SnapshotWithBooks가 됩니다.

오류와 재시도

메서드는 PolyTestFailure를 던집니다. error.failure.kind로 분기하세요. error.status는 HTTP 상태 코드이고, error.meta는 응답 meta이며, 응답이 도착하지 않았으면 null입니다.

종류발생 조건
config잘못된 옵션 또는 키 누락. 요청을 보내기 전에 발생합니다.
network응답이 도착하지 않았습니다. 연결에 실패했거나 요청 시간이 초과되었습니다. 원래 오류는 error.cause에 있습니다.
unauthorizedHTTP 401. API가 키를 거부했습니다.
trial_exhaustedHTTP 402. 체험 사용 한도 중 하나가 소진되었습니다. dimension과 limit이 포함됩니다.
subscription_inactiveHTTP 403. 구독이 활성 상태가 아닙니다.
forbiddenHTTP 403. 플랜에 포함되지 않은 데이터입니다. tier가 포함됩니다.
rate_limitedHTTP 429. 요청 한도를 초과했습니다. 서버가 보낸 경우 retry_after가 포함됩니다.
concurrency_limitedHTTP 429. 동시에 진행 중인 요청이 너무 많습니다. max_concurrent가 포함됩니다.
bad_requestHTTP 400, 또는 클라이언트가 전송 전에 거부한 인수.
not_foundHTTP 404. 해당 마켓이 없거나, 그 시각 근처에 스냅샷이 없습니다.
unavailableHTTP 502 또는 503. retry_after가 포함될 수 있습니다.
server그 밖의 모든 5xx, 또는 클라이언트가 읽지 못한 200 응답 본문.
http리디렉션을 포함한 그 밖의 모든 응답.

isRetryable(error)는 rate_limited, concurrency_limited, unavailable, network, HTTP 5xx로 인한 server, 408 또는 425로 인한 http에 대해 true를 반환합니다. SDK 요청은 모두 GET이므로 다시 보내도 안전합니다.

retryDelayMs(error)는 대기 시간을 밀리초 단위로 반환하며, 최대 1시간입니다. 서버가 retry_after를 보냈다면 그 값을 사용합니다. retry_after가 없는 rate_limited라면 요청 한도가 초기화될 때까지의 시간을 사용합니다. 그 밖의 경우에는 null을 반환하며 concurrency_limited는 항상 여기에 해당하므로, 이때는 직접 정한 지연 시간을 사용하세요. 두 함수 모두 실제로 대기하지는 않습니다.

TypeScript
import { polytest, isRetryable, retryDelayMs, PolyTestFailure } from "@polytest/sdk"

const api = polytest()

async function marketBySlug(slug: string) {
  try {
    return await api.market({ slug })
  } catch (error) {
    if (error instanceof PolyTestFailure && error.failure.kind === "not_found") return null
    if (!isRetryable(error)) throw error
    await new Promise((resolve) => setTimeout(resolve, retryDelayMs(error) ?? 1000))
    return api.market({ slug })
  }
}

const market = await marketBySlug("btc-updown-5m-1772689200")
console.log(market?.winner)

요청 취소

모든 메서드는 signal을 담은 선택적 마지막 인수를 받으며, page.next()도 마찬가지입니다. 신호가 중단되면 호출은 fetch와 마찬가지로 signal.reason으로 거부됩니다. 이 값은 PolyTestFailure가 아니며, isRetryable은 이 값에 대해 false를 반환합니다.

TypeScript
import { polytest } from "@polytest/sdk"

const api = polytest()
const controller = new AbortController()
setTimeout(() => controller.abort(), 5_000)

const page = await api.markets({ market_type: "15m" }, { signal: controller.signal })
const nextPage = await page.next({ signal: controller.signal })

timeoutMs는 신호와 함께 계속 동작합니다. 먼저 발생한 쪽이 호출을 끝내며, 타임아웃이면 network 오류를 던집니다.

응답 meta

모든 결과에는 meta가 있습니다. HTTP 응답으로 만들어진 실패도 같은 객체를 error.meta에 담고 있으므로, 429 응답에서도 요청 한도를 확인할 수 있습니다.

필드헤더내용
rate_limitX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Resetlimit, remaining, reset_unix(초). 세 헤더가 모두 숫자인 경우가 아니면 null입니다.
trial_remaining_beforeX-Trial-Budget-*-Remaining체험 기간에는 이 요청 전에 남아 있던 requests, records, bytes입니다. 그 외에는 null입니다.
server_clampX-Limit-Clamped서버가 limit을 낮춘 경우 requested, applied, max입니다. 그 외에는 null입니다.
TypeScript
import { polytest } from "@polytest/sdk"

const api = polytest()
const page = await api.markets({ market_type: "5m", limit: 100 })

console.log(page.meta.rate_limit?.remaining) // requests left in this window
console.log(page.meta.server_clamp) // null unless the server lowered limit

런타임

이 패키지는 ES 모듈입니다.

사용 방식요구 사항
importNode 20 이상
require()Node 20.19, 또는 Node 22.12 이상
CommonJS로 컴파일한 TypeScriptTypeScript 5.8 이상, "module": "nodenext" 설정