TypeScript SDK
@polytest/sdk 是 PolyTest API 的官方 TypeScript 客户端,可在 Node 20 或更高版本上读取 Polymarket 的历史市场、快照和订单簿。类型定义随包附带,并且没有运行时依赖。
Python 和 Go SDK 已在计划中。在它们发布之前,快速入门会用 curl 和 Python 展示每个请求。
安装
从 npm 安装这个包,并把你的 API 密钥放进 POLYTEST_KEY 环境变量。
npm install @polytest/sdk
export POLYTEST_KEY="pt_live_your_key_here"第一个请求
polytest() 会从 POLYTEST_KEY 读取你的密钥。这个示例列出 BTC 5m 市场,打印其中一个已结算市场的五条快照,然后再次获取这些时刻中的第一个,这次带上双边订单簿。
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() 接受四个选项,每一个都可以省略。
| 选项 | 默认值 | 作用 |
|---|---|---|
| key | process.env.POLYTEST_KEY | 你的 API 密钥,通过 X-API-Key 请求头发送。两端的空格和制表符会被去掉。 |
| origin | https://api.polytest.io | 请求发往的地址。必须使用 https(在 localhost 上也可以用 http),并且不能包含路径。 |
| fetch | globalThis.fetch | 自定义的 fetch 函数。即使它忽略了中止信号,超时依然有效。 |
| timeoutMs | 30000 | 每个请求的时间上限(毫秒),包括读取响应主体的时间。超时的调用会抛出 network。设为 null 可关闭此限制。 |
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。 |
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。
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。 |
| unauthorized | HTTP 401。API 拒绝了该密钥。 |
| trial_exhausted | HTTP 402。某项试用额度已用完。附带 dimension 和 limit。 |
| subscription_inactive | HTTP 403。订阅未处于有效状态。 |
| forbidden | HTTP 403。数据超出你的套餐范围。附带 tier。 |
| rate_limited | HTTP 429。你超出了速率限制。服务器提供 retry_after 时会附带该值。 |
| concurrency_limited | HTTP 429。你同时进行中的请求过多。附带 max_concurrent。 |
| bad_request | HTTP 400,或某个参数在发送前被客户端拒绝。 |
| not_found | HTTP 404。市场不存在,或该时间附近没有快照。 |
| unavailable | HTTP 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 始终属于这种情况,此时请改用你自己的延迟。两个函数本身都不会等待。
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。
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_limit | X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset | limit、remaining 和 reset_unix(秒)。只有三个响应头都是数字时才有值,否则为 null。 |
| trial_remaining_before | X-Trial-Budget-*-Remaining | 试用期间,为本次请求之前剩余的 requests、records 和 bytes。否则为 null。 |
| server_clamp | X-Limit-Clamped | 服务器调低了你的 limit 时,为 requested、applied 和 max。否则为 null。 |
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 模块。
| 使用方式 | 要求 |
|---|---|
| import | Node 20 或更高版本 |
| require() | Node 20.19,或 Node 22.12 及更高版本 |
| 编译为 CommonJS 的 TypeScript | TypeScript 5.8 或更高版本,并设置 "module": "nodenext" |