Polymarket

https://docs.polymarket.com
Admin
Polymarket is the world's largest prediction market where users can buy and sell shares representing...
Tokens:477,346
Snippets:2,653
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Get Trades API Request Examples

Source: https://docs.polymarket.com/cn/api-reference/endpoints/clob/get-data-trades

Examples of how to authenticate and request trade data using various programming languages.

```bash
curl --request GET \
  --url https://clob.polymarket.com/data/trades \
  --header 'POLY_ADDRESS: <api-key>' \
  --header 'POLY_API_KEY: <api-key>' \
  --header 'POLY_PASSPHRASE: <api-key>' \
  --header 'POLY_SIGNATURE: <api-key>' \
  --header 'POLY_TIMESTAMP: <api-key>'
```

```python
import requests  
  
url = "https://clob.polymarket.com/data/trades"  
  
headers = {  
    "POLY_API_KEY": "<api-key>",  
    "POLY_ADDRESS": "<api-key>",  
    "POLY_SIGNATURE": "<api-key>",  
    "POLY_PASSPHRASE": "<api-key>",  
    "POLY_TIMESTAMP": "<api-key>"  
}  
  
response = requests.get(url, headers=headers)  
  
print(response.text)
```

```javascript
const options = {  
  method: 'GET',  
  headers: {  
    POLY_API_KEY: '<api-key>',  
    POLY_ADDRESS: '<api-key>',  
    POLY_SIGNATURE: '<api-key>',  
    POLY_PASSPHRASE: '<api-key>',  
    POLY_TIMESTAMP: '<api-key>'  
  }  
};  
  
fetch('https://clob.polymarket.com/data/trades', options)  
  .then(res => res.json())  
  .then(res => console.log(res))  
  .catch(err => console.error(err));
```

```php
<?php  
  
$curl = curl_init();  
  
curl_setopt_array($curl, [  
  CURLOPT_URL => "https://clob.polymarket.com/data/trades",  
  CURLOPT_RETURNTRANSFER => true,  
  CURLOPT_ENCODING => "",  
  CURLOPT_MAXREDIRS => 10,  
  CURLOPT_TIMEOUT => 30,  
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  
  CURLOPT_CUSTOMREQUEST => "GET",  
  CURLOPT_HTTPHEADER => [  
    "POLY_ADDRESS: <api-key>",  
    "POLY_API_KEY: <api-key>",  
    "POLY_PASSPHRASE: <api-key>",  
    "POLY_SIGNATURE: <api-key>",  
    "POLY_TIMESTAMP: <api-key>"  
  ],  
]);  
  
$response = curl_exec($curl);  
$err = curl_error($curl);  
  
curl_close($curl);  
  
if ($err) {  
  echo "cURL Error #:" . $err;  
} else {  
  echo $response;  
}
```

```go
package main  
  
import (  
	"fmt"  
	"net/http"  
	"io"  
)  
  
func main() {  
  
	url := "https://clob.polymarket.com/data/trades"  
  
	req, _ := http.NewRequest("GET", url, nil)  
  
	req.Header.Add("POLY_API_KEY", "<api-key>")  
	req.Header.Add("POLY_ADDRESS", "<api-key>")  
	req.Header.Add("POLY_SIGNATURE", "<api-key>")  
	req.Header.Add("POLY_PASSPHRASE", "<api-key>")  
	req.Header.Add("POLY_TIMESTAMP", "<api-key>")  
  
	res, _ := http.DefaultClient.Do(req)  
  
	defer res.Body.Close()  
	body, _ := io.ReadAll(res.Body)  
  
	fmt.Println(string(body))  
  
}
```

```java
HttpResponse<String> response = Unirest.get("https://clob.polymarket.com/data/trades")  
  .header("POLY_API_KEY", "<api-key>")  
  .header("POLY_ADDRESS", "<api-key>")  
  .header("POLY_SIGNATURE", "<api-key>")  
  .header("POLY_PASSPHRASE", "<api-key>")  
  .header("POLY_TIMESTAMP", "<api-key>")  
  .asString();
```

```ruby
require 'uri'  
require 'net/http'  
  
url = URI("https://clob.polymarket.com/data/trades")  
  
http = Net::HTTP.new(url.host, url.port)  
http.use_ssl = true  
  
request = Net::HTTP::Get.new(url)  
request["POLY_API_KEY"] = '<api-key>'  
request["POLY_ADDRESS"] = '<api-key>'  
request["POLY_SIGNATURE"] = '<api-key>'  
request["POLY_PASSPHRASE"] = '<api-key>'  
request["POLY_TIMESTAMP"] = '<api-key>'  
  
response = http.request(request)  
puts response.read_body
```

--------------------------------

### Install Polymarket Client

Source: https://docs.polymarket.com/perps/place-your-first-trade

Install the required Python package using poetry.

```bash
poetry add polymarket-client
```

--------------------------------

### Install Python SDK

Source: https://docs.polymarket.com/perps/place-your-first-trade

Install the Unified Python SDK using uv or pip.

```bash
uv add polymarket-client
```

```bash
pip install polymarket-client
```

--------------------------------

### MarketPrices Data Examples

Source: https://docs.polymarket.com/market-data/market-details

Example JSON structures for market metrics and prices.

```json
{
  "metrics": {
    "liquidity": "150248.32",
    "volume24hr": "5842.3"
  },
  "prices": {
    "lastTradePrice": "0.085",
    "bestBid": "0.08",
    "bestAsk": "0.09",
    "spread": "0.01",
    "oneDayPriceChange": "-0.003"
  }
}
```

```json
{
  "metrics": {
    "liquidity": "150248.32",
    "volume_24hr": "5842.3"
  },
  "prices": {
    "last_trade_price": "0.085",
    "best_bid": "0.08",
    "best_ask": "0.09",
    "spread": "0.01",
    "one_day_price_change": "-0.003"
  }
}
```

--------------------------------

### Portfolio Response Examples

Source: https://docs.polymarket.com/perps/account-management

JSON examples representing the portfolio data structure returned by the API.

```json
{
  "positions": [
    {
      "instrumentId": 1,
      "symbol": "BTC-PERP",
      "size": "0.01",
      "entryPrice": "65000",
      "leverage": 5,
      "cross": false,
      "initialMargin": "130",
      "maintenanceMargin": "65",
      "positionValue": "650",
      "liquidationPrice": "52000",
      "unrealizedPnl": "0",
      "returnOnEquity": "0",
      "cumulativeFunding": "0"
    }
  ],
  "margin": {
    "totalAccountValue": "1000",
    "totalInitialMargin": "130",
    "totalMaintenanceMargin": "65",
    "totalPositionValue": "650"
  },
  "withdrawable": "870",
  "inLiquidation": false,
  "timestamp": 1767000000000
}
```

```json
{
  "positions": [
    {
      "instrument_id": 1,
      "symbol": "BTC-PERP",
      "size": "0.01",
      "entry_price": "65000",
      "leverage": 5,
      "cross": false,
      "initial_margin": "130",
      "maintenance_margin": "65",
      "position_value": "650",
      "liquidation_price": "52000",
      "unrealized_pnl": "0",
      "return_on_equity": "0",
      "cumulative_funding": "0"
    }
  ],
  "margin": {
    "total_account_value": "1000",
    "total_initial_margin": "130",
    "total_maintenance_margin": "65",
    "total_position_value": "650"
  },
  "withdrawable": "870",
  "in_liquidation": false,
  "timestamp": 1767000000000
}
```

--------------------------------

### Simplify Gasless Setup

Source: https://docs.polymarket.com/changelog/sdks

Gasless setup helpers are deprecated; proceed directly to setting up trading approvals after client creation.

```diff
-const ready = await secureClient.isGaslessReady();
-
-if (!ready) {
-  secureClient = await secureClient.setupGaslessWallet();
-}
-
 await secureClient.setupTradingApprovals();
```

--------------------------------

### Initialize Public Clients

Source: https://docs.polymarket.com/getting-started/python

Demonstrates initializing async and sync public clients to list markets.

```python
from polymarket import AsyncPublicClient


async with AsyncPublicClient() as client:
    pages = client.list_markets(closed=False)
    first_page = await pages.first_page()
```

```python
from polymarket import PublicClient


with PublicClient() as client:
    pages = client.list_markets(closed=False)
    first_page = pages.first_page()
```

--------------------------------

### OpenAPI Specification for Get Order Book

Source: https://docs.polymarket.com/api-reference/market-data/get-order-book

Defines the /book GET endpoint, including required parameters, response schemas, and example payloads for successful and error states.

```yaml
openapi: 3.1.0
info:
  title: Polymarket CLOB API
  description: Polymarket CLOB API Reference
  license:
    name: MIT
    identifier: MIT
  version: 1.0.0
servers:
  - url: https://clob.polymarket.com
    description: Production CLOB API
  - url: https://clob-staging.polymarket.com
    description: Staging CLOB API
security: []
tags:
  - name: Trade
    description: Trade endpoints
  - name: Markets
    description: Market data endpoints
  - name: Account
    description: Account and authentication endpoints
  - name: Notifications
    description: User notification endpoints
  - name: Rewards
    description: Rewards and earnings endpoints
  - name: Rebates
    description: Maker rebate endpoints
paths:
  /book:
    get:
      tags:
        - Market Data
      summary: Get order book
      description: |
        Retrieves the order book summary for a specific token ID.
        Includes bids, asks, market details, and last trade price.
      operationId: getBook
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved order book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBookSummary'
              example:
                market: '0x1234567890123456789012345678901234567890'
                asset_id: 0xabc123def456...
                timestamp: '1234567890'
                hash: a1b2c3d4e5f6...
                bids:
                  - price: '0.45'
                    size: '100'
                  - price: '0.44'
                    size: '200'
                asks:
                  - price: '0.46'
                    size: '150'
                  - price: '0.47'
                    size: '250'
                min_order_size: '1'
                tick_size: '0.01'
                neg_risk: false
                last_trade_price: '0.45'
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - No orderbook exists for the requested token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: No orderbook exists for the requested token id
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: error getting the orderbook
      security: []
components:
  schemas:
    OrderBookSummary:
      type: object
      required:
        - market
        - asset_id
        - timestamp
        - hash
        - bids
        - asks
        - min_order_size
        - tick_size
        - neg_risk
        - last_trade_price
      properties:
        market:
          type: string
          description: Market condition ID
          example: '0x1234567890123456789012345678901234567890'
        asset_id:
          type: string
          description: Token ID (asset ID)
          example: 0xabc123def456...
        timestamp:
          type: string
          description: Timestamp of the order book snapshot
          example: '1234567890'
        hash:
          type: string
          description: Hash of the order book summary
          example: a1b2c3d4e5f6...
        bids:
          type: array
          description: List of bid orders (sorted by price descending)
          items:
            $ref: '#/components/schemas/OrderSummary'
        asks:
          type: array
          description: List of ask orders (sorted by price ascending)
          items:
            $ref: '#/components/schemas/OrderSummary'
        min_order_size:
          type: string
          description: Minimum order size
          example: '1'
        tick_size:
          type: string
          description: Minimum price increment (tick size)
          example: '0.01'
        neg_risk:
          type: boolean
          description: Whether negative risk is enabled for this market
          example: false
        last_trade_price:
          type: string
          description: Last trade price
          example: '0.45'
```

--------------------------------

### GET /v1/info/trades

Source: https://docs.polymarket.com/api-reference/get-recent-trades

Retrieves public trades for a specified instrument. Supports optional filtering by start and end timestamps.

```APIDOC
## GET /v1/info/trades

### Description
Get public trades for an instrument. Maximum of 100 entries returned per request.

### Method
GET

### Endpoint
/v1/info/trades

### Parameters
#### Query Parameters
- **instrument_id** (integer) - Required - Instrument ID
- **start_timestamp** (integer) - Optional - Start timestamp in milliseconds
- **end_timestamp** (integer) - Optional - End timestamp in milliseconds

### Response
#### Success Response (200)
- **data** (array) - Public trades for the instrument
- **more** (boolean) - More data available
```

--------------------------------

### Install Unified SDK Dependencies

Source: https://docs.polymarket.com/getting-started/migrate-from-previous-sdks

Remove legacy packages and install the unified SDK along with a wallet library like viem.

```bash
npm uninstall @polymarket/clob-client-v2 @polymarket/builder-relayer-client @polymarket/builder-signing-sdk
npm install @polymarket/client@latest viem
```

```bash
pnpm remove @polymarket/clob-client-v2 @polymarket/builder-relayer-client @polymarket/builder-signing-sdk
pnpm add @polymarket/client@latest viem
```

```bash
yarn remove @polymarket/clob-client-v2 @polymarket/builder-relayer-client @polymarket/builder-signing-sdk
yarn add @polymarket/client@latest viem
```

```bash
bun remove @polymarket/clob-client-v2 @polymarket/builder-relayer-client @polymarket/builder-signing-sdk
bun add @polymarket/client@latest viem
```

--------------------------------

### Initialize Client and Place Order

Source: https://docs.polymarket.com/getting-started/migrate-from-previous-sdks

Demonstrates client authentication using a private key and placing a limit order.

```rust
#[tokio::main]
    async fn main() -> anyhow::Result<()> {
        let host = "https://clob-v2.polymarket.com";
        let signer = LocalSigner::from_str(&std::env::var(PRIVATE_KEY_VAR)?)?
            .with_chain_id(Some(POLYGON));
        let deposit_wallet = Address::from_str(&std::env::var("DEPOSIT_WALLET")?)?;

        let client = Client::new(host, Config::default())?
            .authentication_builder(&signer)
            .funder(deposit_wallet)
            .signature_type(SignatureType::Poly1271)
            .authenticate()
            .await?;

        client
            .update_balance_allowance(
                UpdateBalanceAllowanceRequest::builder()
                    .asset_type(AssetType::Collateral)
                    .build(),
            )
            .await?;

        let response = client
            .limit_order()
            .token_id(U256::from_str(&std::env::var("TOKEN_ID")?)?)
            .side(Side::Buy)
            .price(Decimal::from_str("0.40")?)
            .size(Decimal::from_str("100")?)
            .order_type(OrderType::GTC)
            .build_sign_and_post(&signer)
            .await?;

        println!("order_id={} status={}", response.order_id, response.status);
        Ok(())
    }
```

--------------------------------

### Get Single Order by ID API Requests

Source: https://docs.polymarket.com/cn/api-reference/endpoints/clob/get-data-order-orderid

Examples of how to fetch order details using various programming languages and tools.

```bash
curl --request GET \
  --url https://clob.polymarket.com/data/order/{orderID} \
  --header 'POLY_ADDRESS: <api-key>' \
  --header 'POLY_API_KEY: <api-key>' \
  --header 'POLY_PASSPHRASE: <api-key>' \
  --header 'POLY_SIGNATURE: <api-key>' \
  --header 'POLY_TIMESTAMP: <api-key>'
```

```python
import requests  
  
url = "https://clob.polymarket.com/data/order/{orderID}"  
  
headers = {  
    "POLY_API_KEY": "<api-key>",  
    "POLY_ADDRESS": "<api-key>",  
    "POLY_SIGNATURE": "<api-key>",  
    "POLY_PASSPHRASE": "<api-key>",  
    "POLY_TIMESTAMP": "<api-key>"  
}  
  
response = requests.get(url, headers=headers)  
  
print(response.text)
```

```javascript
const options = {  
  method: 'GET',  
  headers: {  
    POLY_API_KEY: '<api-key>',  
    POLY_ADDRESS: '<api-key>',  
    POLY_SIGNATURE: '<api-key>',  
    POLY_PASSPHRASE: '<api-key>',  
    POLY_TIMESTAMP: '<api-key>'  
  }  
};  
  
fetch('https://clob.polymarket.com/data/order/{orderID}', options)  
  .then(res => res.json())  
  .then(res => console.log(res))  
  .catch(err => console.error(err));
```

```php
<?php  
  
$curl = curl_init();  
  
curl_setopt_array($curl, [  
  CURLOPT_URL => "https://clob.polymarket.com/data/order/{orderID}",  
  CURLOPT_RETURNTRANSFER => true,  
  CURLOPT_ENCODING => "",  
  CURLOPT_MAXREDIRS => 10,  
  CURLOPT_TIMEOUT => 30,  
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  
  CURLOPT_CUSTOMREQUEST => "GET",  
  CURLOPT_HTTPHEADER => [  
    "POLY_ADDRESS: <api-key>",  
    "POLY_API_KEY: <api-key>",  
    "POLY_PASSPHRASE: <api-key>",  
    "POLY_SIGNATURE: <api-key>",  
    "POLY_TIMESTAMP: <api-key>"  
  ],  
]);  
  
$response = curl_exec($curl);  
$err = curl_error($curl);  
  
curl_close($curl);  
  
if ($err) {  
  echo "cURL Error #:" . $err;  
} else {  
  echo $response;  
}
```

```go
package main  
  
import (  
	"fmt"  
	"net/http"  
	"io"  
)  
  
func main() {  
  
	url := "https://clob.polymarket.com/data/order/{orderID}"  
  
	req, _ := http.NewRequest("GET", url, nil)  
  
	req.Header.Add("POLY_API_KEY", "<api-key>")  
	req.Header.Add("POLY_ADDRESS", "<api-key>")  
	req.Header.Add("POLY_SIGNATURE", "<api-key>")  
	req.Header.Add("POLY_PASSPHRASE", "<api-key>")  
	req.Header.Add("POLY_TIMESTAMP", "<api-key>")  
  
	res, _ := http.DefaultClient.Do(req)  
  
	defer res.Body.Close()  
	body, _ := io.ReadAll(res.Body)  
  
	fmt.Println(string(body))  
  
}
```

```java
HttpResponse<String> response = Unirest.get("https://clob.polymarket.com/data/order/{orderID}")  
  .header("POLY_API_KEY", "<api-key>")  
  .header("POLY_ADDRESS", "<api-key>")  
  .header("POLY_SIGNATURE", "<api-key>")  
  .header("POLY_PASSPHRASE", "<api-key>")  
  .header("POLY_TIMESTAMP", "<api-key>")  
  .asString();
```

```ruby
require 'uri'  
require 'net/http'  
  
url = URI("https://clob.polymarket.com/data/order/{orderID}")  
  
http = Net::HTTP.new(url.host, url.port)  
http.use_ssl = true  
  
request = Net::HTTP::Get.new(url)  
request["POLY_API_KEY"] = '<api-key>'  
request["POLY_ADDRESS"] = '<api-key>'  
request["POLY_SIGNATURE"] = '<api-key>'  
request["POLY_PASSPHRASE"] = '<api-key>'  
request["POLY_TIMESTAMP"] = '<api-key>'  
  
response = http.request(request)  
puts response.read_body
```

--------------------------------

### OpenAPI Specification for Get Last Trade Prices

Source: https://docs.polymarket.com/api-reference/market-data/get-last-trade-prices-request-body

The OpenAPI definition for the /last-trades-prices POST endpoint, including request body schema and response examples.

```yaml
openapi: 3.1.0
info:
  title: Polymarket CLOB API
  description: Polymarket CLOB API Reference
  license:
    name: MIT
    identifier: MIT
  version: 1.0.0
servers:
  - url: https://clob.polymarket.com
    description: Production CLOB API
  - url: https://clob-staging.polymarket.com
    description: Staging CLOB API
security: []
tags:
  - name: Trade
    description: Trade endpoints
  - name: Markets
    description: Market data endpoints
  - name: Account
    description: Account and authentication endpoints
  - name: Notifications
    description: User notification endpoints
  - name: Rewards
    description: Rewards and earnings endpoints
  - name: Rebates
    description: Maker rebate endpoints
paths:
  /last-trades-prices:
    post:
      tags:
        - Market Data
      summary: Get last trade prices (request body)
      description: |
        Retrieves last trade prices for multiple token IDs using a request body.
        Maximum 500 token IDs can be requested per call.
      operationId: getLastTradesPricesPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BookRequest'
            example:
              - token_id: 0xabc123def456...
              - token_id: 0xdef456abc123...
      responses:
        '200':
          description: Successfully retrieved last trade prices
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - token_id
                    - price
                    - side
                  properties:
                    token_id:
                      type: string
                      description: Token ID (asset ID)
                      example: 0xabc123def456...
                    price:
                      type: string
                      description: Last trade price
                      example: '0.45'
                    side:
                      type: string
                      description: Last trade side (BUY or SELL)
                      enum:
                        - BUY
                        - SELL
                      example: BUY
              example:
                - token_id: 0xabc123def456...
                  price: '0.45'
                  side: BUY
                - token_id: 0xdef456abc123...
                  price: '0.52'
                  side: SELL
        '400':
          description: Bad request - Invalid payload or exceeds limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid payload
                exceeds_limit:
                  summary: Payload exceeds limit
                  value:
                    error: Payload exceeds the limit
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
      security: []
components:
  schemas:
    BookRequest:
      type: object
      required:
        - token_id
      properties:
        token_id:
          type: string
          description: Token ID (asset ID)
          example: 0xabc123def456...
        side:
          type: string
          description: Order side (optional, not used for midpoint calculation)
          enum:
            - BUY
            - SELL
          example: BUY
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Machine-readable error code, when provided
        retry_after_seconds:
          type: integer
          description: Number of seconds to wait before retrying, when provided
```

--------------------------------

### Install Privy Adapter

Source: https://docs.polymarket.com/getting-started/typescript

Install the Privy adapter and server SDK to enable Privy wallet integration.

```bash
npm install @polymarket/client@latest @privy-io/node
```

```bash
bun add @polymarket/client@latest @privy-io/node
```

```bash
pnpm add @polymarket/client@latest @privy-io/node
```

```bash
yarn add @polymarket/client@latest @privy-io/node
```

--------------------------------

### Get Instruments

Source: https://docs.polymarket.com/llms.txt

Get all instruments.

```APIDOC
## GET /get-instruments

### Description
Get all instruments.
```

--------------------------------

### GET spread

Source: https://docs.polymarket.com/resources/error-codes

Error codes for the GET spread endpoint.

```APIDOC
## GET spread

### Response
#### Error Responses
- **400 Bad Request**: Invalid token id (The token_id parameter is missing or invalid)
- **404 Not Found**: No orderbook exists for the requested token id
```

--------------------------------

### Install Viem Adapter

Source: https://docs.polymarket.com/getting-started/typescript

Install the necessary packages to use the Viem adapter with the Polymarket SDK.

```bash
npm install @polymarket/client@latest viem
```

```bash
bun add @polymarket/client@latest viem
```

```bash
pnpm add @polymarket/client@latest viem
```

```bash
yarn add @polymarket/client@latest viem
```

--------------------------------

### GET midpoint

Source: https://docs.polymarket.com/resources/error-codes

Error codes for the GET midpoint endpoint.

```APIDOC
## GET midpoint

### Response
#### Error Responses
- **400 Bad Request**: Invalid token id (The token_id parameter is missing or invalid)
- **404 Not Found**: No orderbook exists for the requested token id
```

--------------------------------

### Install the Polymarket SDK

Source: https://docs.polymarket.com/getting-started/typescript

Install the latest version of the SDK using your preferred package manager.

```bash
npm install @polymarket/client@latest
```

```bash
bun add @polymarket/client@latest
```

```bash
pnpm add @polymarket/client@latest
```

```bash
yarn add @polymarket/client@latest
```

--------------------------------

### GET price

Source: https://docs.polymarket.com/resources/error-codes

Error codes for the GET price endpoint.

```APIDOC
## GET price

### Response
#### Error Responses
- **400 Bad Request**: Invalid token id (The token_id parameter is missing or invalid)
- **400 Bad Request**: Invalid side (The side parameter must be BUY or SELL)
- **404 Not Found**: No orderbook exists for the requested token id
```

--------------------------------

### Get Statistics

Source: https://docs.polymarket.com/llms.txt

Get last 24-hour statistics for all instruments.

```APIDOC
## GET /get-statistics

### Description
Get last 24-hour statistics for all instruments.
```

--------------------------------

### Install Beta SDK

Source: https://docs.polymarket.com/changelog/sdks

Install the unified TypeScript SDK beta package using pnpm.

```bash
pnpm add @polymarket/client@beta
```

--------------------------------

### OpenAPI Specification for Get User Earnings

Source: https://docs.polymarket.com/cn/api-reference/endpoints/clob/get-rewards-user

定义了获取用户指定日期收益的 GET 请求参数、响应结构及错误处理。

```yaml
openapi: 3.1.0
info:
  title: Polymarket CLOB API
  description: Polymarket CLOB API Reference
  license:
    name: MIT
    identifier: MIT
  version: 1.0.0
servers:
  - url: https://clob.polymarket.com
    description: Production CLOB API
  - url: https://clob-staging.polymarket.com
    description: Staging CLOB API
security: []
tags:
  - name: Trade
    description: Trade endpoints
  - name: Markets
    description: Market data endpoints
  - name: Account
    description: Account and authentication endpoints
  - name: Notifications
    description: User notification endpoints
  - name: Rewards
    description: Rewards and earnings endpoints
  - name: Rebates
    description: Maker rebate endpoints
paths:
  /rewards/user:
    get:
      tags:
        - Rewards
      summary: Get earnings for user by date
      description: >
        Returns an array of user earnings per market for a provided day.


        Requires CLOB L2 Auth headers.


        Results are paginated (100 items per page). Use next_cursor to fetch
        subsequent pages.

        A next_cursor value of "LTE=" indicates the last page.
      operationId: getEarningsForUserForDay
      parameters:
        - name: date
          in: query
          description: Date in YYYY-MM-DD format
          required: true
          schema:
            type: string
            format: date
          example: '2024-03-26'
        - name: signature_type
          in: query
          description: |
            Signature type for address derivation (required for API KEY auth):
            - 0: EOA
            - 1: POLY_PROXY
            - 2: POLY_GNOSIS_SAFE
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
        - name: maker_address
          in: query
          description: Maker address to query earnings for
          required: false
          schema:
            type: string
          example: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
        - name: sponsored
          in: query
          description: If true, returns sponsored-only earnings
          required: false
          schema:
            type: boolean
            default: false
        - name: next_cursor
          in: query
          description: Pagination cursor from previous response
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved user earnings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUserEarnings'
              example:
                limit: 100
                count: 1
                next_cursor: LTE=
                data:
                  - date: '2024-03-26T00:00:00Z'
                    condition_id: >-
                      0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
                    asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                    maker_address: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
                    earnings: 0.237519
                    asset_rate: 1
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_date:
                  summary: Invalid date format
                  value:
                    error: 'Invalid date (format: YYYY-MM-DD)'
                invalid_signature_type:
                  summary: Invalid signature type
                  value:
                    error: Invalid signature_type
                invalid_maker_address:
                  summary: Invalid maker address
                  value:
                    error: Invalid maker_address
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
      security:
        - polyApiKey: []
```

--------------------------------

### Install Polymarket SDK Beta

Source: https://docs.polymarket.com/changelog/sdks

Command to install the unified Python SDK using the uv package manager.

```bash
uv add polymarket-client
```

--------------------------------

### PerpsAccountStats JSON Example

Source: https://docs.polymarket.com/perps/account-management

Example JSON response for account statistics.

```json
{
  "volume7d": "5000000",
  "takerVolume7d": "3500000",
  "makerVolume7d": "1500000",
  "accountMakerShare7d": "0.35",
  "entityMakerShare7d": "0.40",
  "entityId": 42,
  "entityName": "desk"
}
```

--------------------------------

### Initializing Secure Clients

Source: https://docs.polymarket.com/getting-started/python

Create an authenticated client using a private key from environment variables for trading or account access.

```python
import os

from polymarket import AsyncSecureClient


async with await AsyncSecureClient.create(
    private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
) as client:
    ...
```

```python
import os

from polymarket import SecureClient


with SecureClient.create(
    private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
) as client:
    ...
```

--------------------------------

### client.setupTradingApprovals()

Source: https://docs.polymarket.com/perps/fund-your-account

Sets up the necessary approvals for Perps collateral deposits. The SDK will automatically skip this step if approvals are already complete.

```APIDOC
### Method
`client.setupTradingApprovals()`

### Description
Configures the required blockchain approvals to allow the Perps contract to move pUSD collateral from the user's wallet.
```

--------------------------------

### RelayerTransaction Schema Example

Source: https://docs.polymarket.com/cn/api-reference/endpoints/relayer/get-transactions

Example values for the RelayerTransaction object fields.

```yaml
transactionID: 0190b317-a1d3-7bec-9b91-eeb6dcd3a620
transactionHash: '0x38cbfbeae8fffa4e2b187ee5978d3ee9cafc53af0363ed90a35b7ea9016535d8'
from: '0x6e0c80c90ea6c15917308f820eac91ce2724b5b5'
to: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174'
proxyAddress: '0x6d8c4e9adf5748af82dabe2c6225207770d6b4fa'
data: 0x...
nonce: '60'
value: ''
signature: >-
  0x01a060c734d7bdf4adde50c4a7e574036b1f8b12890911bdd1c1cfdcd77502381b89fa8a47c36f62a0b9f1cdfee7b260fd8108536db9f6b2089c02637e7de9fc20
state: STATE_CONFIRMED
type: SAFE
owner: '0x6e0c80c90ea6c15917308f820eac91ce2724b5b5'
metadata: ''
createdAt: '2024-07-14T21:13:08.819782Z'
updatedAt: '2024-07-14T21:13:46.576639Z'
```

--------------------------------

### SubmitResponse Schema Example

Source: https://docs.polymarket.com/cn/api-reference/endpoints/relayer/post-submit

Example values for the SubmitResponse object fields.

```yaml
SubmitResponse:
  type: object
  properties:
    transactionID:
      type: string
      description: Unique identifier for the submitted transaction
      example: 0190b317-a1d3-7bec-9b91-eeb6dcd3a620
    state:
      type: string
      description: Current state of the transaction
      example: STATE_NEW
```

--------------------------------

### Create Public Client Comparison

Source: https://docs.polymarket.com/getting-started/migrate-from-previous-sdks

Simplifies public client initialization by removing the need for manual URL and chain ID configuration.

```python
from py_clob_client_v2.client import ClobClient

client = ClobClient("https://clob.polymarket.com", chain_id=137)
```

```python
from polymarket import AsyncPublicClient

client = AsyncPublicClient()
```

--------------------------------

### SignatureParams Schema Example

Source: https://docs.polymarket.com/cn/api-reference/endpoints/relayer/post-submit

Example values for the SignatureParams object fields.

```yaml
SignatureParams:
  type: object
  properties:
    gasPrice:
      type: string
      description: Gas price
      example: '0'
    operation:
      type: string
      description: Operation type
      example: '0'
    safeTxnGas:
      type: string
      description: Safe transaction gas
      example: '0'
    baseGas:
      type: string
      description: Base gas
      example: '0'
    gasToken:
      $ref: '#/components/schemas/Address'
      description: Gas token address
      example: '0x0000000000000000000000000000000000000000'
    refundReceiver:
      $ref: '#/components/schemas/Address'
      description: Refund receiver address
      example: '0x0000000000000000000000000000000000000000'
```

--------------------------------

### Create SecureClient with Viem Private Key

Source: https://docs.polymarket.com/getting-started/typescript

Initialize the client using a private key directly via the Viem adapter.

```ts
import { createSecureClient } from "@polymarket/client";
import { privateKey } from "@polymarket/client/viem";

const client = await createSecureClient({
  signer: privateKey(process.env.POLYMARKET_PRIVATE_KEY),
});
```

--------------------------------

### Install Unified SDK

Source: https://docs.polymarket.com/getting-started/migrate-from-previous-sdks

Commands to remove legacy packages and install the new unified SDK using various package managers.

```bash
uv remove py-clob-client-v2 py-builder-relayer-client py-builder-signing-sdk
uv add polymarket-client
```

```bash
pip uninstall -y py-clob-client-v2 py-builder-relayer-client py-builder-signing-sdk
pip install polymarket-client
```

```bash
poetry remove py-clob-client-v2 py-builder-relayer-client py-builder-signing-sdk
poetry add polymarket-client
```

--------------------------------

### SubmitRequest Schema Example

Source: https://docs.polymarket.com/cn/api-reference/endpoints/relayer/post-submit

Example values for the SubmitRequest object fields.

```yaml
Address:
  type: string
  description: Ethereum address (0x-prefixed, 40 hex chars)
  pattern: ^0x[a-fA-F0-9]{40}$
  example: '0x6e0c80c90ea6c15917308F820Eac91Ce2724B5b5'
SubmitRequest:
  type: object
  required:
    - from
    - to
    - proxyWallet
    - data
    - nonce
    - signature
    - signatureParams
    - type
  properties:
    from:
      $ref: '#/components/schemas/Address'
      description: Signer address
    to:
      $ref: '#/components/schemas/Address'
      description: Target contract address
    proxyWallet:
      $ref: '#/components/schemas/Address'
      description: User's Polymarket proxy wallet address
    data:
      type: string
      description: Encoded transaction data (0x-prefixed hex string)
      example: 0x...
    nonce:
      type: string
      description: Transaction nonce
      example: '60'
    signature:
      type: string
      description: Transaction signature (0x-prefixed hex string)
      example: >-
        0x01a060c734d7bdf4adde50c4a7e574036b1f8b12890911bdd1c1cfdcd77502381b89fa8a47c36f62a0b9f1cdfee7b260fd8108536db9f6b2089c02637e7de9fc20
    signatureParams:
      $ref: '#/components/schemas/SignatureParams'
    type:
      type: string
      description: Transaction type
      enum:
        - SAFE
        - PROXY
      example: SAFE
```

--------------------------------

### Reward Amount Example

Source: https://docs.polymarket.com/api-reference/get-account-rewards

Example value for a reward amount string.

```yaml
example: '127.50344'
```

--------------------------------

### Initialize EOA Client in Python

Source: https://docs.polymarket.com/trading/wallets-auth

Configure the AsyncSecureClient using environment variables for the private key and wallet address.

```python
import os

from polymarket import AsyncSecureClient

client = await AsyncSecureClient.create(
    private_key=os.environ["SIGNER_PRIVATE_KEY"],
    wallet=os.environ["POLYMARKET_SIGNER_ADDRESS"],
);
```

--------------------------------

### Install TypeScript SDK

Source: https://docs.polymarket.com/perps/place-your-first-trade

Install the Unified TypeScript SDK and Viem using your preferred package manager.

```bash
pnpm add @polymarket/client@latest viem
```

```bash
npm install @polymarket/client@latest viem
```

```bash
yarn add @polymarket/client@latest viem
```

--------------------------------

### Reward Pool Example

Source: https://docs.polymarket.com/api-reference/get-account-rewards

Example value for a configured reward pool.

```yaml
example: '1000'
```

--------------------------------

### Set Up Trading Approvals

Source: https://docs.polymarket.com/perps/fund-your-account

Configure necessary approvals for collateral deposits; the SDK automatically skips already completed work.

```python
await client.setup_trading_approvals()
```

--------------------------------

### Error Identifier Example

Source: https://docs.polymarket.com/api-reference/get-account-rewards

Example of a machine-readable error identifier string.

```yaml
example: insufficient_margin
```

--------------------------------

### Remove Gasless Setup Helpers

Source: https://docs.polymarket.com/changelog/sdks

Illustrates the removal of deprecated gasless readiness checks and setup calls.

```diff
-ready = await secure_client.is_gasless_ready()
-
-if not ready:
-    secure_client = await secure_client.setup_gasless_wallet()
-
 await secure_client.setup_trading_approvals()
```

--------------------------------

### ClobTrade JSON Example

Source: https://docs.polymarket.com/trading/manage-orders

Example JSON response for a CLOB trade object.

```json
{
  "items": [
    {
      "id": "TRADE_ID",
      "condition_id": "0x747dc809fb79e1b05be09c42d6179459a58de2ef3e40f02484a4e1260f741f75",
      "token_id": "107505882767731489358349912513945399560393482969656700824895970500493757150417",
      "owner": "9180014b-33c8-9240-a14b-bdca11c0a465",
      "maker_address": "0x1234567890123456789012345678901234567890",
      "taker_order_id": "0xff354cd7ca7539dfa9c28d90943ab5779a4eac34b9b37a757d7b32bdfb11790b",
      "side": "BUY",
      "trader_side": "TAKER",
      "price": "0.52",
      "size": "10",
      "outcome": "Yes",
      "status": "TRADE_STATUS_MATCHED",
      "fee_rate_bps": "0",
      "bucket_index": 0,
      "transaction_hash": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd",
      "maker_orders": [],
      "matched_at": "2026-06-01T12:00:05Z",
      "updated_at": "2026-06-01T12:00:05Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}
```

--------------------------------

### Initialize AsyncPublicClient

Source: https://docs.polymarket.com/getting-started/python

Create an asynchronous client instance to access public Polymarket data.

```python
from polymarket import AsyncPublicClient


async with AsyncPublicClient() as client:
    ...
```

--------------------------------

### UserOrderEvent JSON Example

Source: https://docs.polymarket.com/trading/realtime-order-updates

Example JSON payload for a user order event.

```json
{
  "topic": "user",
  "type": "order",
  "payload": {
    "id": "<order_id>",
    "owner": "<clob_api_key>",
    "market": "<condition_id>",
    "token_id": "<token_id>",
    "side": "BUY",
    "original_size": "10",
    "size_matched": "0",
    "price": "0.52",
    "outcome": "Yes",
    "order_event_type": "PLACEMENT",
    "status": "LIVE",
    "timestamp": "2026-06-29T17:15:57.257000Z"
  }
}
```

--------------------------------

### CryptoPricesChainlinkEvent Example

Source: https://docs.polymarket.com/market-data/realtime-data

Example JSON payload for a Chainlink crypto price update.

```json
{
  "topic": "prices.crypto.chainlink",
  "type": "update",
  "timestamp": "2026-06-29T17:15:57.257000Z",
  "payload": {
    "symbol": "eth/usd",
    "timestamp": 1782753357213,
    "value": "3420.15"
  }
}
```

--------------------------------

### Create a Secure Client (Python)

Source: https://docs.polymarket.com/perps/fund-your-account

Initialize an AsyncSecureClient for the wallet. Use either a Relayer API key for existing wallets or a Builder API key for programmatic wallet creation.

```python
import os

from polymarket import AsyncSecureClient, RelayerApiKey

client = await AsyncSecureClient.create(
    private_key=os.environ["PRIVATE_KEY"],
    wallet=os.environ["POLYMARKET_WALLET_ADDRESS"],
    api_key=RelayerApiKey(
        key=os.environ["RELAYER_API_KEY"],
        address=os.environ["RELAYER_API_KEY_ADDRESS"],
    ),
)
```

```python
import os

from polymarket import AsyncSecureClient, BuilderApiKey
```

--------------------------------

### PerpsBalance JSON Example

Source: https://docs.polymarket.com/perps/account-management

Example JSON response structure for account balances.

```json
[
  {
    "asset": "pUSD",
    "balance": "1000",
    "value": "1000"
  }
]
```

--------------------------------

### Create an AsyncSecureClient in Python

Source: https://docs.polymarket.com/perps/authenticated-sessions

Initializes an AsyncSecureClient using environment variables for credentials.

```python
import os

from polymarket import AsyncSecureClient

client = await AsyncSecureClient.create(
    private_key=os.environ["PRIVATE_KEY"],
    wallet=os.environ["POLYMARKET_WALLET_ADDRESS"],
)
```
Tokens:
Raw