> ## 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 教程概覽

> Polymarket API 使用指南：官方文檔入口、行情與下單接口說明、籤名與風控要點，幫助開發者用 API 自動化交易。

想用程序化方式在 Polymarket 上做量化或自動下單？本篇整理了 Polymarket API 的文檔入口、交易流程和風控要點，幫助你快速接入。

<Callout type="success">
  還沒有帳號？[點擊這裡註冊 Polymarket](https://polymarket.com/?r=2026VIP) 並完成入金，才能用錢包私鑰為訂單籤名、實際成交。
</Callout>

<Warning>
  **法律合規提醒**：在使用 Polymarket 服務或 API 前，請確認您所在地區的法律規定。Polymarket 目前不支援比利時、法國、新加坡、泰國、中國大陸等地區，政策可能隨時變化。
</Warning>

## Polymarket API 是什麼？

Polymarket 的 API 主要分為兩類：

* **行情/公共數據接口**：獲取市場列表、事件信息、訂單簿、成交歷史等，不需要鑑權。
* **交易接口（CLOB）**：下單、撤單、查詢帳戶和倉位，需要用錢包私鑰對訂單進行籤名。

## API 文檔結構

Polymarket 提供了完整的 API 文檔，包括以下主要部分：

### 開發者快速開始

* **快速開始指南**：了解如何設置開發環境
* **第一筆訂單**：學習如何下第一筆訂單
* **術語表**：理解關鍵概念和術語
* **速率限制**：了解 API 調用限制
* **端點列表**：查看所有可用的 API 端點

### 中央限價訂單簿 (CLOB)

CLOB 是 Polymarket 的核心交易系統，提供：

* 訂單管理（創建、取消、查詢）
* 市場數據獲取
* 歷史交易數據
* 認證和籤名機制

### WebSocket 實時數據

通過 WebSocket 連接獲取：

* 實時市場數據更新
* 訂單簿變化
* 用戶訂單狀態更新

### Gamma API

Gamma 是 Polymarket 的市場數據 API，提供：

* 市場信息查詢
* 事件數據
* 評論和社交數據
* 用戶資料

### 其他功能

* **橋接和兌換**：跨鏈資產轉移
* **條件代幣框架**：理解 Polymarket 的代幣機制
* **流動性獎勵**：獲取流動性挖礦信息
* **負風險市場**：特殊市場類型

## 使用 API 交易的前提

* 已[註冊 Polymarket 帳戶](https://polymarket.com/?r=2026VIP)並完成必要的合規要求。
* 錢包裡有可用的 USDC（或支援的代幣）且在支援的網絡上。
* 擁有可用於籤名的私鑰（不要把私鑰洩露給前端頁面或無信任方）。
* 熟悉訂單參數（價格、數量、方向、過期時間）以及最小下單限制。

## 快速上手流程

<Steps>
  <Step title="1. 查看行情">
    通過公共接口獲取市場與訂單簿，例如請求市場列表、盤口深度和近期成交。
  </Step>

  <Step title="2. 選擇合約與方向">
    明確要交易的市場 ID / tokenId，確定 buy 或 sell，設置價格和數量。
  </Step>

  <Step title="3. 構建訂單並籤名">
    按文檔要求生成訂單 JSON，包含 tokenId、價格、數量、方向、過期時間等欄位，用錢包私鑰籤名。
  </Step>

  <Step title="4. 提交訂單">
    將籤名後的訂單通過交易接口（通常是 POST /orders）發送到 CLOB，等待撮合。
  </Step>

  <Step title="5. 查詢狀態與撤單">
    通過查詢接口獲取訂單狀態、成交明細；需要時調用撤單接口取消未成交部分。
  </Step>
</Steps>

## 核心接口（按需求）

* **市場與事件列表**：按分類、時間或流動性過濾市場，拿到 tokenId、outcome、到期時間等。
* **訂單簿 / 行情快照**：查看 Bid/Ask 隊列、最佳買賣價、深度。
* **歷史成交（trades）**：獲取最近成交價與成交量，用於計算滑點和預期成本。
* **下單（POST /orders）**：提交籤名訂單；常見欄位包括 tokenId、price、size、side、expiration、signature、walletAddress。
* **撤單（DELETE /orders/{id}）**：取消未成交或部分成交的訂單。
* **帳戶/餘額**：查詢可用餘額、持倉與保證金需求，確保下單時餘額充足。
* **WebSocket 訂閱**：訂閱市場價格變動、訂單簿更新和個人訂單狀態，降低輪詢成本。

## 示例：獲取行情並提交買單

以下示例僅為結構參考，具體欄位名與響應格式以官方文檔為準。

**1）獲取市場列表（公共接口）**

```bash theme={null}
curl "https://clob.polymarket.com/markets?limit=5"
```

**2）構建並籤名訂單（偽代碼）**

```javascript theme={null}
const order = {
  tokenId: "<目标市场的 tokenId>",
  price: 0.55,        // 你願意出的價格，單位 USD
  size: 50,           // 想買的數量
  side: "buy",        // buy 或 sell
  expiration: Date.now() + 5 * 60 * 1000
};

// 使用本地錢包私鑰籤名（請使用官方 SDK 或 ethers.js 完成籤名）
const signature = signOrder(order, privateKey);
```

**3）提交訂單（交易接口）**

```bash theme={null}
curl -X POST "https://clob.polymarket.com/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "tokenId": "<tokenId>",
      "price": 0.55,
      "size": 50,
      "side": "buy",
      "expiration": 1728000000
    },
    "signature": "<签名结果>",
    "walletAddress": "<你的钱包地址>"
  }'
```

收到響應後，記錄訂單 ID，便於後續查詢狀態或撤單。

## 籤名與安全要點

* 在後端或安全的執行環境中完成籤名，不要在公開前端暴露私鑰。
* 設置合理的過期時間，避免長期懸掛的訂單被誤成交。
* 下單前檢查餘額與最小下單限制，防止被系統拒單。
* 使用 WebSocket 監聽訂單狀態，及時撤單或調整價格，降低滑點。

## 常見問題

### Q: API 需要申請 Key 嗎？

A: 公共數據通常無需 Key；交易需要用錢包私鑰對訂單籤名並提交。若未來有速率限制或額外鑑權要求，以官方文檔公告為準。

### Q: 測試環境是否可用？

A: Polymarket 主要在主網環境提供真實交易。若官方開放測試網或沙盒，會在文檔中說明；實盤下單前可先用小額訂單驗證流程。

### Q: 費用如何計算？

A: 手續費與網絡費用因市場和網絡而異，詳見文檔的 Fees 章節。常用網絡（如 Polygon）費用相對最低。

## 下一步

<CardGroup cols={2}>
  <Card title="第一筆訂單" icon="rocket" href="/api-tutorial/first-order">
    學習如何使用 Python 或 TypeScript 下第一筆訂單
  </Card>

  <Card title="CLOB 介紹" icon="book" href="/api-tutorial/clob/introduction">
    深入了解 Polymarket 的中央限價訂單簿
  </Card>

  <Card title="速率限制" icon="gauge" href="/api-tutorial/rate-limits">
    了解 API 調用的速率限制
  </Card>

  <Card title="官方文檔" icon="globe" href="https://docs.polymarket.com">
    訪問 Polymarket 官方英文文檔
  </Card>
</CardGroup>