> ## Documentation Index
> Fetch the complete documentation index at: https://polymarketcn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Polymarket 永續合約 API 教學【2026】Perps 行情端點、下單簽名、SDK 範例與 WebSocket 訂閱

> Polymarket Perps API 完整教學：公開行情端點（合約列表、盤口、K 線、資金費率）免鑑權直接 curl；下單、撤單、調槓桿要走 EIP-712 代理簽名；附 TypeScript 與 Python SDK 範例、WebSocket 頻道清單、常見錯誤碼與風控建議。

Polymarket 2026 年 9 月上線的永續合約（Perps）用的是一套獨立的 API，和事件合約的 CLOB、Gamma 完全分開：不同的網域、不同的鑑權方式、不同的抵押品（pUSD）。這篇把公開行情、鑑權、下單、帳戶查詢和 WebSocket 一次講完，所有端點都是 2026 年 10 月實測可用的。

如果你還不熟悉永續合約的槓桿、資金費率和強平規則，先看[永續合約教程](/trading/polymarket-perps)，這篇只講程式接入。

<Callout type="info">
  基礎網址：REST `https://api.perpetuals.polymarket.com/v1`，WebSocket `wss://ws.perpetuals.polymarket.com/v1/ws`。公開行情不需要任何 key，帳戶和交易操作需要代理簽名。
</Callout>

<Warning>
  **地區限制**：美國、加拿大、古巴、伊朗、北韓、敘利亞、克里米亞、頓內茨克、盧甘斯克不允許下單。官方文件明確寫了 builder 有責任在送單前確認用戶所在地，自己寫機器人或給別人用的工具都要注意。
</Warning>

## 公開行情端點（免鑑權）

| 端點 | 用途 | 主要參數 |
| - | - | - |
| `GET /v1/info/instruments` | 全部合約清單：代號、最高槓桿、風險分級、最小名目、強平費率 | `instrument_id`（可選，查已下架合約） |
| `GET /v1/info/tickers` | 行情快照：指數價、標記價、最新成交價、中間價、未平倉量、資金費率 | `instrument_id`（可選） |
| `GET /v1/info/book` | 訂單簿深度 | `instrument_id`、`depth`（10/100/500/1000） |
| `GET /v1/info/klines` | K 線 OHLCV，單次最多 1000 根 | `instrument_id`、`interval`、`start_timestamp` |
| `GET /v1/info/mark-history` | 標記價歷史，最細 1 秒 | 同上 |
| `GET /v1/info/trades` | 最近公開成交，單次最多 100 筆 | `instrument_id` |
| `GET /v1/info/funding` | 歷史資金費率，單次最多 100 筆 | `instrument_id` |

時間戳全部是 Unix 毫秒。先拿合約清單，拿到 `instrument_id` 再查其他東西：

```bash theme={null}
# 全部合約（截至 2026-10 共 88 個）
curl "https://api.perpetuals.polymarket.com/v1/info/instruments"

# BTC 的訂單簿（instrument_id=1 是 BTC-USD）
curl -G "https://api.perpetuals.polymarket.com/v1/info/book" \
  --data-urlencode "instrument_id=1" \
  --data-urlencode "depth=100"

# 1 分鐘 K 線
curl -G "https://api.perpetuals.polymarket.com/v1/info/klines" \
  --data-urlencode "instrument_id=1" \
  --data-urlencode "interval=1m" \
  --data-urlencode "start_timestamp=1766120400000"

# 歷史資金費率
curl -G "https://api.perpetuals.polymarket.com/v1/info/funding" \
  --data-urlencode "instrument_id=1"
```

### 合約清單欄位怎麼讀

`instruments` 回傳的每個物件裡最常用的欄位：

| 欄位 | 意思 |
| - | - |
| `instrument_id` | 下單和查詢都用這個 ID |
| `symbol` / `display_symbol` | 代號，例如 `BTC-USD`；`NAS100-USD` 的顯示代號是 `US100-USD` |
| `category` | `crypto`、`equity`、`index`、`commodity` |
| `max_leverage` | 最高槓桿，BTC/ETH/SP500/NAS100 目前 50 |
| `risk_tiers` | 倉位名目分級：`lower_bound` 以上的名目適用更低的 `max_leverage` |
| `min_notional` | 最小單筆名目，目前全部是 10 美元 |
| `max_market_notional` / `max_limit_notional` | 市價單與限價單的單筆名目上限 |
| `liquidation_fee` | 強平費率，目前全部 0.005（0.5%） |
| `isolated_only` | `true` 代表該市場只能逐倉 |
| `price_decimals` / `quantity_decimals` | 價格與數量的小數位，下單超過位數會被拒 |
| `funding_interval` | 資金費結算週期，目前全部 `1h` |
| `close_only` | `true` 時只能減倉 |

用 Python 把清單整理成表格，順便算出每個市場的維持保證金率（MMR = 0.5 ÷ 最高槓桿）：

```python theme={null}
import requests

rows = requests.get("https://api.perpetuals.polymarket.com/v1/info/instruments", timeout=10).json()
for r in sorted(rows, key=lambda x: (x["category"], x["symbol"])):
    mmr = 0.5 / r["max_leverage"]
    print(f'{r["category"]:10} {r["symbol"]:14} 槓桿 {r["max_leverage"]:>2}x  MMR {mmr:.2%}  強平費 {float(r["liquidation_fee"]):.1%}')
```

## 鑑權：代理簽名怎麼運作

Perps 的鑑權分三層，理解了這個，SDK 在做什麼就一目了然：

| 金鑰 | 作用 |
| - | - |
| Polymarket 帳戶簽名者（你的主錢包私鑰） | 只簽一次 `CreateProxy`，授權一把代理金鑰 |
| 代理簽名者（程式自己生成的一對新金鑰） | 之後所有下單、撤單、調槓桿都用它簽 |
| 代理密鑰（`secret`，API 回傳） | 放在 header 裡做私有查詢和 WebSocket 鑑權 |

流程是：本地生成代理金鑰對 → 用主錢包對 EIP-712 的 `CreateProxy` 簽名（domain：`name` Polymarket、`version` 1、`chainId` 137）→ `POST /v1/account/proxy` → 拿到 `secret`。之後私有讀取用這兩個 header：

```
polymarket-proxy: <代理地址>
polymarket-secret: <代理密鑰>
```

每個簽名請求都要帶毫秒級的 `ts` 和隨機 `salt`，而且要和 typed data 裡的值一致。本機時間和伺服器差太多會被拒，建議先打一次 `GET /v1/info/time` 對時。代理憑證預設一週有效，過期要重新建立。

主錢包私鑰只用來簽一次授權，之後可以離線保存。這是 Perps 比事件合約 CLOB 更安全的設計，交易機器人跑在伺服器上也只持有代理金鑰。

## 用官方 SDK 下第一筆單

官方 SDK 把上面的鑑權全包了：TypeScript 用 `@polymarket/client` 搭 `viem`，Python 用 `polymarket-client`。下面四步走完就是一筆完整交易。

### 1. 建立 client 並打開 Perps session

```typescript theme={null}
import { createSecureClient, privateKey } from "@polymarket/client";

const client = await createSecureClient({
  wallet: process.env.POLYMARKET_WALLET_ADDRESS!,   // 你在 polymarket.com 的帳戶錢包地址
  signer: privateKey(process.env.PRIVATE_KEY!),     // 該帳戶的簽名私鑰
});
const session = await client.openPerpsSession({ label: "my-bot" });
```

```python theme={null}
import os
from polymarket_client import AsyncSecureClient

client = await AsyncSecureClient.create(
    private_key=os.environ["PRIVATE_KEY"],
    wallet=os.environ["POLYMARKET_WALLET_ADDRESS"],
)
session = await client.open_perps_session(label="my-bot")
```

`session.credentials` 可以存起來，下次用 `openPerpsSession({ credentials })` 直接恢復，不用每次重新簽 `CreateProxy`。

### 2. 把 pUSD 轉入 Perps 帳戶

Perps 帳戶和事件合約帳戶是分開記帳的，要先從 Polymarket 錢包轉 pUSD 進去，最低 10 pUSD。SDK 裡是兩個呼叫：

```typescript theme={null}
await client.setupTradingApprovals();          // 一次性授權
const deposit = await client.depositToPerps({ amount: 10_000_000n }); // 10 pUSD，單位是 6 位小數的最小單位
await deposit.wait();                           // 等鏈上確認，Perps 入帳會再晚幾秒
```

### 3. 設定槓桿和保證金模式

```typescript theme={null}
await session.updateLeverage({
  instrumentId: 1,        // BTC-USD
  leverage: 5,
  crossMargin: false,     // false = 逐倉，true = 全倉
});
```

對應的 REST 端點是 `PATCH /v1/trade/leverage`，欄位 `iid`、`lev`、`cross`。兩個限制要記住：槓桿預設是該市場的最高值，不改就是滿槓桿；切換逐倉和全倉時，該市場必須沒有持倉也沒有掛單。

### 4. 下單、撤單、平倉

```typescript theme={null}
import { OrderSide, PerpsTimeInForce } from "@polymarket/client";

// 掛一張限價買單
const order = await session.placeOrder({
  instrumentId: 1,
  side: OrderSide.BUY,
  price: "65000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.GTC,
  postOnly: true,          // 只做 Maker，會吃單就拒絕
});

// 撤單
await session.cancelOrder({ orderId: order.id });

// 平倉：反方向、全數量、reduce-only
const portfolio = await session.fetchPortfolio();
const pos = portfolio.positions.find(p => p.instrumentId === 1);
if (pos) {
  await session.placeOrder({
    instrumentId: 1,
    side: pos.size > 0 ? OrderSide.SELL : OrderSide.BUY,
    quantity: Math.abs(pos.size).toString(),
    timeInForce: PerpsTimeInForce.IOC,
    reduceOnly: true,
  });
}
```

```python theme={null}
result = await session.place_order(
    instrument_id=1,
    side="BUY",
    price="65000",
    quantity="0.01",
    time_in_force="gtc",
    post_only=True,
)
await session.cancel_order(order_id=result.id)
```

直接打 REST 的話，下單是 `POST /v1/trade/orders`，請求體是一個 `op`，`type` 為 `createOrders`，單筆訂單欄位用縮寫：

| 欄位 | 意思 |
| - | - |
| `iid` | instrument\_id |
| `buy` | `true` 買 / `false` 賣 |
| `p` | 價格，pUSD 每單位，小數位不能超過 `price_decimals` |
| `qty` | 數量，小數位不能超過 `quantity_decimals` |
| `tif` | `gtc` / `ioc` / `fok` |
| `po` | post-only，只對 GTC 有效 |
| `ro` | reduce-only，只減倉不開新倉 |
| `c` | 自訂訂單 ID，32 位小寫十六進位 |

整個 `op` 要先用 MessagePack 編碼、做 keccak256，再以 EIP-712 的 `Op` 類型簽名。這一段手寫很容易錯，除非有特殊需求，用 SDK。

### 訂單狀態一覽

| 狀態 | 意思 |
| - | - |
| `open` | GTC 掛在簿上 |
| `filled` | 完全成交 |
| `ioc_no_fill` / `ioc_expired` | IOC 沒有成交或只部分成交後取消 |
| `fok_unfilled` | FOK 無法全部成交，整張取消 |
| `post_only_rejected` | 掛 post-only 但會吃單，被拒 |
| `stp_cancelled` | 自成交保護觸發，你的掛單被取消 |
| `reduce_only_invalid` / `reduce_only_expired` | reduce-only 單會增加或反轉倉位，被拒 |
| `order_in_flight` | 前一筆還在處理，稍後重試（SDK 只對這個狀態自動重試） |

自成交保護預設開啟且不能關，模式是取消掛單方（CancelMaker）。同一個人的多個帳戶如果被 Polymarket 歸為同一實體，互相成交也會被擋。

## 帳戶端點（需鑑權）

| 端點 | 回傳 |
| - | - |
| `GET /v1/account/portfolio` | 持倉、保證金、可提領額、是否在強平中 |
| `GET /v1/account/balances` | 各資產抵押品餘額 |
| `GET /v1/account/open-orders` | 掛單（可帶 `instrument_id`） |
| `GET /v1/account/orders` | 已提交訂單的最新狀態 |
| `GET /v1/account/fills` | 成交明細、手續費、損益，分頁 |
| `GET /v1/account/funding` | 資金費收付記錄 |
| `GET /v1/account/deposits` / `withdrawals` | 出入金記錄 |
| `GET /v1/account/equity` / `pnl` | 權益與損益曲線 |
| `GET /v1/account/stats` | 近 7 日成交量與 Maker 占比 |

`portfolio` 裡每個持倉有 `size`（正數多、負數空）、`entryPrice`、`liquidationPrice`、`leverage`、`cross`、`initialMargin`、`maintenanceMargin`、`unrealizedPnl`、`cumulativeFunding`。寫風控用 `liquidationPrice` 和 `margin.totalMaintenanceMargin` 就夠。

提領用 `POST /v1/account/withdraw`，但要滿足保留規則：帳戶必須留下未平倉名目 10% 的抵押品，所以 `withdrawable` 常常小於可用來開倉的餘額。

## WebSocket 即時行情

連上 `wss://ws.perpetuals.polymarket.com/v1/ws` 後送訂閱訊息：

```json theme={null}
{ "id": 1, "req": "sub", "chs": ["bbo::1", "trades::1", "tickers::all"] }
```

| 頻道 | 內容 |
| - | - |
| `bbo::<id>` | 最佳買賣價 |
| `book::<id>` | 訂單簿深度 |
| `trades::<id>` | 公開成交，每筆帶 `settlement` 旗標 |
| `tickers::<id>` 或 `tickers::all` | 標記價、指數價、資金費率、下次結算時間 |
| `statistics::<id>` 或 `statistics::all` | 24 小時成交量、開盤價 |
| `klines::<id>::<interval>` | K 線，interval 支援 1s、1m、5m、15m、30m、1h、4h、6h、12h、1d、1w |

退訂把 `req` 改成 `unsub`。私有頻道（訂單、成交、帳戶狀態）要先送鑑權幀：

```json theme={null}
{ "id": 1, "req": "post", "op": { "type": "auth", "args": { "proxy": "<代理地址>", "secret": "<代理密鑰>" } } }
```

資金費率不是獨立頻道，從 `tickers` 裡讀。想看資金費壓力怎麼累積，可以持續記錄 `tickers` 推送的即時溢價樣本，官方每 5 秒取樣一次。

## 手續費與強平怎麼算進程式裡

* 手續費按名目收：`abs(價格 × 數量) × 費率`。新帳戶 Taker 0.04%、Maker 0.0125%，按近 30 日成交量分級，每天 UTC 重算。費率不要寫死，從 `instruments` 和帳戶 `fee_tier` 讀。
* 強平時每筆成交多收 `liquidation_fee`（0.5%）。
* 維持保證金率 `MMR = 0.5 / max_leverage`，看的是市場的最高槓桿，不是你設的槓桿。
* 送單前的保證金檢查用最壞情況名目：`max(|持倉 + 未成交買單|, |持倉 − 未成交賣單|)`。掛了很多單的帳戶，明明餘額夠也可能被拒，原因在這。
* 風險分級 `risk_tiers` 只影響開倉保證金，不影響維持保證金。要開大倉位，先把 `leverage` 調低。

## 常見問題

**Q: 可以沙盒測試嗎？**
A: 目前沒有測試網。先用最小名目 10 美元、1x 到 2x 槓桿走一遍流程。

**Q: 和事件合約 CLOB 的憑證通用嗎？**
A: 不通用。CLOB 用的是 API key + L2 簽名，Perps 用代理簽名，網域也不同。兩邊可以在同一個程式裡並行，各自鑑權。

**Q: 帳戶是綁在哪個地址上？**
A: 綁在簽 `createProxy` 的 EOA 基礎地址，不是 Safe 智能錢包地址。查餘額、找客服都報 EOA 地址。

**Q: 一個帳戶能開幾個代理？**
A: 可以開多個，用 `label` 區分（例如一個做市、一個風控）。撤銷用帳戶管理端點。

**Q: 有速率限制嗎？**
A: 文件沒有公布具體數字，但強平時的平倉單有按帳戶的速率限制。自己的程式建議加退避重試，看到 `order_in_flight` 等一下再送。

<Callout type="tip">
  程式跑起來之前先去網頁版開一筆小單，看一眼強平價怎麼跳。[前往 Polymarket](https://polymarket.com?via=asia) 開戶入金後，永續合約和事件合約共用同一筆 pUSD。
</Callout>

## 延伸閱讀

<CardGroup cols={2}>
  <Card title="永續合約教程（網頁版操作）" icon="arrow-trend-up" href="/trading/polymarket-perps">
    槓桿、資金費率、強平規則，先懂規則再寫程式
  </Card>

  <Card title="API 開發者總覽" icon="code" href="/api-tutorial/overview">
    CLOB、Gamma、Data API 與 Perps API 怎麼分工
  </Card>

  <Card title="事件合約第一筆訂單" icon="rocket" href="/api-tutorial/first-order">
    py-clob-client 與 TypeScript SDK 下單範例
  </Card>

  <Card title="速率限制" icon="gauge" href="/api-tutorial/rate-limits">
    各 API 的限流規則與退避策略
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.