polymarket_api文档_概览

Documentation Index

Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt

Use this file to discover all available pages before exploring further.

简介

Polymarket API 概览

Polymarket API 提供对全球最大预测市场的编程访问。平台由三个独立的 API 组成，各自处理不同的领域。

API

**`https://gamma-api.polymarket.com`**

复制代码

市场、事件、标签、系列、评论、体育、搜索和公开个人资料。这是发现和浏览市场数据的主要 API。

**`https://data-api.polymarket.com`**

复制代码

用户持仓、交易、活动、持有者数据、未平仓合约、排行榜和 Builder 分析。

**`https://clob.polymarket.com`**

复制代码

订单簿数据、价格、中间价、价差和价格历史。同时处理下单、撤单和其他交易操作。交易端点需要[身份验证](/api-reference/authentication)。

另有一个独立的 **Bridge API**（`https://bridge.polymarket.com`）处理充值和提现。Bridge 不由 Polymarket 直接运营，而是 fun.xyz 服务的代理。

身份验证

Gamma API 和 Data API 完全公开------不需要身份验证。

CLOB API 同时包含公开端点（订单簿、价格）和需要验证的端点（订单管理）。详情请参阅身份验证。

下一步

了解如何为交易端点验证请求。官方 TypeScript、Python 和 Rust 库。 > ## Documentation Index > Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt > Use this file to discover all available pages before exploring further.

身份验证

如何对 CLOB API 请求进行身份验证

CLOB API 使用两级身份验证：**L1（私钥）**和 L2（API Key）。两种方式都可以通过 CLOB 客户端或 REST API 完成。

公开 vs 需要验证

**Gamma API**、**Data API** 和 CLOB 读取端点（订单簿、价格、价差）不需要身份验证。 CLOB 交易端点（下单、撤单、心跳）需要全部 5 个 `POLY_*` L2 HTTP header。

两级身份验证模型

CLOB 使用两级身份验证：L1（私钥）和 L2（API Key）。两种方式都可以通过 CLOB 客户端或 REST API 完成。

L1 身份验证 - 私钥

L1 身份验证使用钱包的私钥签署一个 EIP-712 消息，用于请求头。它证明了对私钥的所有权和控制权。私钥始终由用户控制，所有交易活动都是非托管的。

用于：

创建 API 凭证
派生现有的 API 凭证
本地签署和创建用户订单

L2 身份验证 - API 凭证

L2 使用从 L1 身份验证生成的 API 凭证（apiKey、secret、passphrase）。这些仅用于验证发送到 CLOB API 的请求。请求使用 HMAC-SHA256 签名。

用于：

取消或获取用户的活跃订单
检查用户的余额和授权
提交用户签名的订单

即使使用了 L2 身份验证 header，创建用户订单的方法仍然需要用户签署订单 payload。

获取 API 凭证

在发送需要验证的请求之前，你需要使用 L1 身份验证获取 API 凭证。

使用 SDK - 推荐

```typescript theme={null} import { ClobClient } from "@polymarket/clob-client-v2"; import { createWalletClient, http } from "viem"; import { privateKeyToAccount } from "viem/accounts";

复制代码

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const signer = createWalletClient({ account, transport: http() });

const client = new ClobClient({
  host: "https://clob.polymarket.com",
  chain: 137, // Polygon mainnet
  signer,
});

// Creates new credentials or derives existing ones
const credentials = await client.createOrDeriveApiKey();

console.log(credentials);
// {
//   key: "550e8400-e29b-41d4-a716-446655440000",
//   secret: "base64EncodedSecretString",
//   passphrase: "randomPassphraseString"
// }
```

```python theme={null} from py_clob_client_v2 import ClobClient import os

复制代码

client = ClobClient(
    host="https://clob.polymarket.com",
    chain_id=137,  # Polygon mainnet
    key=os.getenv("PRIVATE_KEY")
)

# Creates new credentials or derives existing ones
credentials = client.create_or_derive_api_key()

print(credentials)
# {
#     "apiKey": "550e8400-e29b-41d4-a716-446655440000",
#     "secret": "base64EncodedSecretString",
#     "passphrase": "randomPassphraseString"
# }
```

\*\*永远不要将私钥提交到版本控制系统。\*\*请始终使用环境变量或安全的密钥管理系统。

使用 REST API

虽然我们强烈建议使用提供的客户端来处理签名和身份验证，但以下内容适用于选择不使用 Python 或 TypeScript 客户端的开发者。

创建 API 凭证

bash 复制代码

POST https://clob.polymarket.com/auth/api-key

派生 API 凭证

bash 复制代码

GET https://clob.polymarket.com/auth/derive-api-key

所需的 L1 header：

Header	说明
`POLY_ADDRESS`	Polygon 签名者地址
`POLY_SIGNATURE`	CLOB EIP-712 签名
`POLY_TIMESTAMP`	当前 UNIX 时间戳
`POLY_NONCE`	Nonce（默认值: 0）

POLY_SIGNATURE 通过签署以下 EIP-712 结构生成：
```typescript TypeScript theme={null} const domain = { name: "ClobAuthDomain", version: "1", chainId: chainId, // Polygon Chain ID 137 };

复制代码

const types = {
  ClobAuth: [
    { name: "address", type: "address" },
    { name: "timestamp", type: "string" },
    { name: "nonce", type: "uint256" },
    { name: "message", type: "string" },
  ],
};

const value = {
  address: signingAddress, // The Signing address
  timestamp: ts,            // The CLOB API server timestamp
  nonce: nonce,             // The nonce used
  message: "This message attests that I control the given wallet",
};

const sig = await signer._signTypedData(domain, types, value);
```

```python Python theme={null}
domain = {
    "name": "ClobAuthDomain",
    "version": "1",
    "chainId": chainId,  # Polygon Chain ID 137
}

types = {
    "ClobAuth": [
        {"name": "address", "type": "address"},
        {"name": "timestamp", "type": "string"},
        {"name": "nonce", "type": "uint256"},
        {"name": "message", "type": "string"},
    ]
}

value = {
    "address": signingAddress,  # The signing address
    "timestamp": ts,            # The CLOB API server timestamp
    "nonce": nonce,             # The nonce used
    "message": "This message attests that I control the given wallet",
}

sig = signer.sign_typed_data(domain, types, value)
```

参考实现：

响应：

json 复制代码

{
  "apiKey": "550e8400-e29b-41d4-a716-446655440000",
  "secret": "base64EncodedSecretString",
  "passphrase": "randomPassphraseString"
}

L2 身份验证需要这三个值。

所有交易端点需要以下 5 个 header：

Header	说明
`POLY_ADDRESS`	Polygon 签名者地址
`POLY_SIGNATURE`	请求的 HMAC 签名
`POLY_TIMESTAMP`	当前 UNIX 时间戳
`POLY_API_KEY`	用户的 API `apiKey` 值
`POLY_PASSPHRASE`	用户的 API `passphrase` 值

L2 的 POLY_SIGNATURE 是使用用户 API 凭证的 secret 值创建的 HMAC-SHA256 签名。参考实现可在 TypeScript 和 Python 客户端中找到。

CLOB 客户端 - L2

```typescript theme={null} import { ClobClient, Side } from "@polymarket/clob-client-v2"; import { createWalletClient, http } from "viem"; import { privateKeyToAccount } from "viem/accounts";

复制代码

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const signer = createWalletClient({ account, transport: http() });

const client = new ClobClient({
  host: "https://clob.polymarket.com",
  chain: 137,
  signer,
  creds: apiCreds, // Generated from L1 auth, API credentials enable L2 methods
  signatureType: 1, // signatureType explained below
  funderAddress, // funder explained below
});

// Now you can trade!
const order = await client.createAndPostOrder(
  { tokenID: "123456", price: 0.65, size: 100, side: Side.BUY },
  { tickSize: "0.01", negRisk: false }
);
```

```python theme={null} from py_clob_client_v2 import ClobClient, OrderArgs, PartialCreateOrderOptions from py_clob_client_v2.order_builder.constants import BUY import os

复制代码

client = ClobClient(
    host="https://clob.polymarket.com",
    chain_id=137,
    key=os.getenv("PRIVATE_KEY"),
    creds=api_creds,  # Generated from L1 auth, API credentials enable L2 methods
    signature_type=1,  # signatureType explained below
    funder=os.getenv("FUNDER_ADDRESS") # funder explained below
)

# Now you can trade!
order = client.create_and_post_order(
    OrderArgs(token_id="123456", price=0.65, size=100, side=BUY),
    options=PartialCreateOrderOptions(tick_size="0.01", neg_risk=False),
)
```

即使使用了 L2 身份验证 header，创建用户订单的方法仍然需要用户签署订单 payload。

签名类型和 Funder

初始化 L2 客户端时，你必须指定钱包的 signatureType 和持有资金的 funder 地址：

签名类型	值	说明
EOA	`0`	标准 Ethereum 钱包（MetaMask）。Funder 即 EOA 地址，需要 POL 来支付链上交易的 gas 费。
POLY_PROXY	`1`	现有的 Polymarket 代理钱包流程，常用于通过 Magic Link 邮箱/Google 登录的用户。
GNOSIS_SAFE	`2`	现有的 Gnosis Safe 钱包流程。已有 Safe 用户可以继续使用此类型。
POLY_1271	`3`	面向新 API 用户的 Deposit Wallet 流程。Funder 是 Deposit Wallet 地址，订单通过 ERC-1271 进行验证。

新 API 用户应使用 `POLY_1271` 配合 Deposit Wallet。现有的 Safe 和 Proxy 用户不受影响，可以继续使用原有的 funder 地址和签名类型。详见 [Deposit Wallet 指南](/trading/deposit-wallets)。

安全最佳实践

将私钥存储在环境变量或安全的密钥管理系统中。永远不要将它们提交到版本控制系统。

复制代码

```bash theme={null}
# .env (never commit this file)
PRIVATE_KEY=0x...
```

永远不要在客户端代码中暴露你的 API secret。所有需要身份验证的请求都应从你的后端发起。

故障排除

你的钱包私钥不正确或格式不对。

复制代码

**解决方案：**

* 验证你的私钥是有效的十六进制字符串（以 "0x" 开头）
* 确保你使用的是目标地址对应的正确密钥
* 检查密钥是否具有正确的权限

你提供的 nonce 已被用于创建 API key。

复制代码

**解决方案：**

* 使用相同的 nonce 调用 `deriveApiKey()` 来获取现有凭证
* 或使用不同的 nonce 调用 `createApiKey()`

你的 funder 地址不正确或与你的钱包不匹配。

复制代码

\*\*解决方案：\*\*在 [polymarket.com/settings](https://polymarket.com/settings) 查看你的 Polymarket 个人资料地址。

如果地址不存在或用户从未登录过 Polymarket.com，请先部署地址，然后再创建 L2 身份验证。

很遗憾，没有 nonce 就无法恢复丢失的 API 凭证。你需要创建新的凭证：

复制代码

```typescript theme={null}
// Create fresh credentials with a new nonce
const newCreds = await client.createApiKey();
// Save the nonce this time!
```

下一步

了解如何创建和提交订单。按地区检查交易可用性。 > ## Documentation Index > Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt > Use this file to discover all available pages before exploring further.

速率限制

所有 Polymarket 端点的 API 速率限制

所有 API 速率限制通过 Cloudflare 的限流系统执行。当你超过任何端点的限制时，请求会被限流（延迟/排队），而非立即拒绝。限制基于滑动时间窗口重置。

通用

端点	限制
通用速率限制	15,000 req / 10s
健康检查（`/ok`）	100 req / 10s

Gamma API

Base URL: https://gamma-api.polymarket.com

端点	限制
通用	4,000 req / 10s
`/events`	500 req / 10s
`/markets`	300 req / 10s
`/markets` + `/events` 列表	900 req / 10s
`/comments`	200 req / 10s
`/tags`	200 req / 10s
`/public-search`	350 req / 10s

Data API

Base URL: https://data-api.polymarket.com

端点	限制
通用	1,000 req / 10s
`/trades`	200 req / 10s
`/positions`	150 req / 10s
`/closed-positions`	150 req / 10s
健康检查（`/ok`）	100 req / 10s

CLOB API

Base URL: https://clob.polymarket.com

通用

端点	限制
通用	9,000 req / 10s
`GET` balance allowance	200 req / 10s
`UPDATE` balance allowance	50 req / 10s

市场数据

端点	限制
`/book`	1,500 req / 10s
`/books`	500 req / 10s
`/price`	1,500 req / 10s
`/prices`	500 req / 10s
`/midpoint`	1,500 req / 10s
`/midpoints`	500 req / 10s
`/prices-history`	1,000 req / 10s
Market tick size	200 req / 10s

账本

端点	限制
`/trades`, `/orders`, `/notifications`, `/order`	900 req / 10s
`/data/orders`	500 req / 10s
`/data/trades`	500 req / 10s
`/notifications`	125 req / 10s

身份验证

端点	限制
API key 端点	100 req / 10s

交易

交易端点同时有突发限制（允许短期峰值）和持续限制（较长期的平均值）。

端点	突发限制	持续限制
`POST /order`	5,000 req / 10s	48,000 req / 10 min
`DELETE /order`	5,000 req / 10s	48,000 req / 10 min
`POST /orders`	1,500 req / 10s	21,000 req / 10 min
`DELETE /orders`	1,000 req / 10s	15,000 req / 10 min
`DELETE /cancel-all`	250 req / 10s	6,000 req / 10 min
`DELETE /cancel-market-orders`	1,500 req / 10s	21,000 req / 10 min

其他

端点	限制
Relayer `/submit`	25 req / 1 min
User PNL API	200 req / 10s

下一步

了解如何对交易请求进行身份验证。官方 TypeScript、Python 和 Rust 库。 > ## Documentation Index > Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt > Use this file to discover all available pages before exploring further.

客户端与 SDK

与 Polymarket 交互的官方开源库

Polymarket 提供 TypeScript、Python 和 Rust 的官方开源客户端。三者都支持完整的 CLOB API，包括市场数据、订单管理和身份验证。

安装

```bash TypeScript theme={null} npm install @polymarket/clob-client-v2 viem ```

bash 复制代码

pip install py-clob-client-v2

bash 复制代码

cargo add polymarket_client_sdk_v2 --features clob

快速示例

```typescript TypeScript theme={null} import { ClobClient } from "@polymarket/clob-client-v2";

const client = new ClobClient({

host: "https://clob.polymarket.com",

chain: 137,

signer,

creds: apiCreds,

});

const markets = await client.getMarkets();

复制代码

```python Python theme={null}
from py_clob_client_v2 import ClobClient

client = ClobClient(
    "https://clob.polymarket.com",
    key=private_key,
    chain_id=137,
    creds=api_creds,
)

markets = client.get_markets()

源代码

语言	包	仓库
TypeScript	`@polymarket/clob-client-v2`	github.com/Polymarket/clob-client-v2
Python	`py-clob-client-v2`	github.com/Polymarket/py-clob-client-v2
Rust	`polymarket_client_sdk_v2`	github.com/Polymarket/rs-clob-client-v2

每个仓库的 /examples 目录中包含可运行的示例。

Relayer SDK

对于使用代理钱包的免 Gas 交易，Relayer 客户端负责通过 Polymarket 的 relayer 提交交易：

语言	包	仓库
TypeScript	`@polymarket/builder-relayer-client`	github.com/Polymarket/builder-relayer-client
Python	`py-builder-relayer-client`	github.com/Polymarket/py-builder-relayer-client

下一步

设置客户端并下你的第一笔订单。了解 L1/L2 身份验证和 API 凭证。

polymarket_api文档_概览

Documentation Index

简介

API

身份验证

下一步

身份验证

公开 vs 需要验证

两级身份验证模型

L1 身份验证 - 私钥

L2 身份验证 - API 凭证

获取 API 凭证

使用 SDK - 推荐

使用 REST API

L2 身份验证 Header

CLOB 客户端 - L2

签名类型和 Funder

安全最佳实践

故障排除

下一步

速率限制

通用

Gamma API

Data API

CLOB API

通用

市场数据

账本

身份验证

交易

其他

下一步

客户端与 SDK

安装

快速示例

源代码

Relayer SDK

下一步