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 市场,打印其中一个已结算市场的五条快照,然后再次获取这些时刻中的第一个,这次带上双边订单簿。

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_KEY你的 API 密钥,通过 X-API-Key 请求头发送。两端的空格和制表符会被去掉。
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(参见响应元数据)。

方法字段返回值
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 | slug单个市场,按 market_id 或 slug 查找。
snapshots(market_id, query?)limit?, offset?, start_time?, end_time?, include_orderbook?一页快照,最早的在前。
snapshotAt(market_id, query)timestamp, include_orderbook?最接近 timestamp 的快照,前后最多相差两秒。
  • market_type 取值为 5m、15m、1hr、4hr 或 24hr。这个列表以 MARKET_TYPES 导出。
  • 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()
more下一页从 nextOffset 开始。获取下一页。
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。传入布尔变量时,类型为 Snapshot 或 SnapshotWithBooks。

错误与重试

方法会抛出 PolyTestFailure。请根据 error.failure.kind 分别处理。error.status 是 HTTP 状态码,error.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其他任何响应,包括重定向。

对于 rate_limited、concurrency_limited、unavailable 和 network,由 HTTP 5xx 引起的 server,以及由 408 或 425 引起的 http,isRetryable(error) 都返回 true。SDK 的每个请求都是 GET,因此重复发送是安全的。

retryDelayMs(error) 返回应等待的毫秒数,上限为一小时。如果服务器发送了 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() 也是如此。信号中止时,调用会以 signal.reason 拒绝(reject),与 fetch 的行为相同。该值不是 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。根据 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"