Start Trading - Polymarket Documentation

Complete connection setup first. We’ll arrange test pUSD, credentials and approvals during onboarding.

Configure Your Integration

API
TypeScript
Python

NEX is a drop-in replacement for the CLOB API.

Switch the Base URL

Environment	Base URL
Production	`https://clob.polymarket.com`
NEX Sandbox	`https://nex.preprod.defi.euw2.polymarket.sh`

Keep your existing routes, payloads and response handling.

Use Sandbox Signing and Credentials

Sign for Polygon Amoy (80002) using the Amoy exchange contracts configured during onboarding. Authenticate with your sandbox trading credentials. Use an EOA or Deposit Wallet; Safe and Proxy Wallets are unavailable. EOAs need Amoy POL for their own approval transactions.

Check the API

curl -i https://nex.preprod.defi.euw2.polymarket.sh/health

Expect HTTP 200.

Use the latest stable release of every Polymarket SDK in your stack, including separate trading and relayer packages. Set NEX_CLOB_URL to https://nex.preprod.defi.euw2.polymarket.sh. You’ll also need an Amoy RPC URL and your sandbox signer’s private key.This example uses your signer’s address (EOA) as the trading account on Amoy.

The sandbox supports EOAs and Deposit Wallets; Safe and Proxy Wallets are unavailable. EOAs need Amoy POL for their own approval transactions. Use your Deposit Wallet address for funding if you trade through one.

Update the SDK

Requires Node.js 24 or later.

npm install @polymarket/client@latest viem

Create the Client

Set GAMMA_CLIENT_ID and GAMMA_CLIENT_SECRET to the Gamma credentials sent after approval.

import { createSecureClient, forkEnvironmentConfig } from "@polymarket/client";
import { privateKey } from "@polymarket/client/viem";
import { http } from "viem";
import { polygonAmoy } from "viem/chains";

const rpcUrl = process.env.AMOY_RPC_URL!;
const signer = privateKey(process.env.POLYMARKET_PRIVATE_KEY, {
  chain: polygonAmoy,
  transport: http(rpcUrl),
});

const amoy = forkEnvironmentConfig({
  name: "amoy",
  chainId: polygonAmoy.id,
  rpc: rpcUrl,
  clob: { rest: process.env.NEX_CLOB_URL! },
  gamma: {
    rest: "https://gamma-api-preprod.polymarket.dev",
    headers: {
      "x-client-id": process.env.GAMMA_CLIENT_ID!,
      "x-client-secret": process.env.GAMMA_CLIENT_SECRET!,
    },
  },
});

const client = await createSecureClient({
  signer,
  wallet: await signer.getAddress(),
  environment: amoy,
});

See the TypeScript SDK guide for the rest of the client API.

Update the SDK

Requires Python 3.11 or later.

python -m pip install --upgrade polymarket-client eth-account httpx

Create the Client

Amoy currently uses the SDK team’s internal environment helper. Run this setup inside your existing async application.

import os
from dataclasses import replace

from eth_account import Account
from polymarket import AsyncSecureClient
from polymarket._internal.environment import PRODUCTION_CONFIG, create_environment

private_key = os.environ["POLYMARKET_PRIVATE_KEY"]
eoa_address = Account.from_key(private_key).address

amoy = create_environment(
    name="amoy",
    config=replace(
        PRODUCTION_CONFIG,
        chain_id=80002,
        rpc_url=os.environ["AMOY_RPC_URL"],
        clob_url=os.environ["NEX_CLOB_URL"].rstrip("/"),
        gamma_url="https://gamma-api-preprod.polymarket.dev",
        exchange_v3="0xe3333700cA9d93003F00f0F71f8515005F6c00Aa",
        position_manager="0x006F54F7f9A22e0000CC2AB60031000000ae9fEF",
    ),
)

client = await AsyncSecureClient.create(
    private_key=private_key,
    wallet=eoa_address,
    environment=amoy,
)

For synchronous code, import SecureClient instead and call SecureClient.create without await.

See the Python SDK guide for the rest of the client API.

Legacy Clients

Set NEX_CLOB_URL to the NEX base URL above. These examples use an EOA; complete your existing authentication flow before trading. For a Deposit Wallet, retain its signing configuration.

TypeScript
Python
Rust

@polymarket/clob-client-v2 is deprecated. Prefer @polymarket/client for new integrations.

npm install @polymarket/clob-client-v2@latest

Use your existing signer, configured for Amoy:

import { Chain, ClobClient } from "@polymarket/clob-client-v2";

const client = new ClobClient({
  host: process.env.NEX_CLOB_URL!,
  chain: Chain.AMOY,
  signer,
});

py-clob-client-v2 is deprecated. Prefer polymarket-client for new integrations.

python -m pip install --upgrade py-clob-client-v2

import os
from py_clob_client_v2 import ClobClient

client = ClobClient(
    host=os.environ["NEX_CLOB_URL"],
    chain_id=80002,
    key=os.environ["POLYMARKET_PRIVATE_KEY"],
)

The Rust CLOB SDK remains supported. The unified Rust SDK is in progress.

cargo add polymarket_client_sdk_v2 --features clob

use polymarket_client_sdk_v2::clob::{Client, Config};

let host = std::env::var("NEX_CLOB_URL")?;
let client = Client::new(&host, Config::default())?;

This creates an unauthenticated client. Configure your trading signer for Amoy (80002) and continue with your existing authentication flow.

See the SDK migration guide to move an existing TypeScript or Python integration to the unified SDK.

Find a Market

Choose an outcome from a sandbox market, then read its order book.

API
TypeScript
Python

Use the Gamma credentials we sent privately to list sandbox markets:

curl --fail-with-body -G \
  "https://gamma-api-preprod.polymarket.dev/markets" \
  --header "x-client-id: $GAMMA_CLIENT_ID" \
  --header "x-client-secret: $GAMMA_CLIENT_SECRET" \
  --data-urlencode "closed=false" \
  --data-urlencode "limit=5"

Choose an outcome from the response. Use its position ID for Polymarket V2 or its token ID for CTF. Set NEX_ASSET_ID to that identifier, then read its book:

curl --fail-with-body -G \
  "https://nex.preprod.defi.euw2.polymarket.sh/book" \
  --data-urlencode "token_id=$NEX_ASSET_ID"

See List Markets and Get Order Book for response schemas.

Call listMarkets() to find Polymarket Protocol V2 markets with the Gamma credentials configured above.

import { ProtocolVersion } from "@polymarket/client";

const pages = client.listMarkets({
  closed: false,
  version: ProtocolVersion.V2,
  pageSize: 5,
});
const page = await pages.firstPage();

for (const market of page.items) {
  console.log(market.id, market.question, market.version);
}

Select YES in a market accepting orders, then call fetchOrderBook() with its position ID:

const market = page.items.find((market) => market.state.acceptingOrders);
if (!market) throw new Error("None of these markets is accepting orders.");

const assetId = market.outcomes.yes.positionId;
if (!assetId) throw new Error("No trading identifier for this outcome.");

const book = await client.fetchOrderBook({ assetId });
console.log(book.tickSize, book.minOrderSize);

The Python SDK cannot yet attach Gamma’s sandbox headers. Fetch Polymarket Protocol V2 market data with HTTPX using the Gamma credentials sent after approval, then parse the binary markets with the SDK’s Market model:

import json

import httpx
from polymarket import Market

async with httpx.AsyncClient() as gamma:
    response = await gamma.get(
        "https://gamma-api-preprod.polymarket.dev/markets/keyset",
        headers={
            "x-client-id": os.environ["GAMMA_CLIENT_ID"],
            "x-client-secret": os.environ["GAMMA_CLIENT_SECRET"],
        },
        params=[
            ("closed", "false"),
            ("version", "v2"),
            ("limit", "5"),
        ],
    )
    response.raise_for_status()
    markets = []
    for item in response.json()["markets"]:
        outcomes = item.get("outcomes") or []
        if isinstance(outcomes, str):
            outcomes = json.loads(outcomes)
        if len(outcomes) == 2:
            markets.append(Market.parse_response(item))

for market in markets:
    print(market.id, market.question, market.version)

Select YES in a market accepting orders and read its book with get_order_book():

market = next((market for market in markets if market.state.accepting_orders), None)
if market is None:
    raise ValueError("None of these markets is accepting orders.")

asset_id = market.outcomes.yes.position_id
if asset_id is None:
    raise ValueError("No trading identifier for this outcome.")

book = await client.get_order_book(asset_id=asset_id)
print(book.tick_size, book.min_order_size)

Place and Track an Order

Place a small limit order, read it back, then cancel the remaining quantity. A resting order can fill before you cancel it.

API
TypeScript
Python

Use your sandbox credentials and the Amoy signing configuration validated during onboarding.

Place an Order

Submit a small limit order. Follow the market’s tick size and minimum order size. See Post a New Order.

Read It Back

Fetch the order by ID.

Cancel the Remaining Quantity

See Manage Orders for cancellation requests.

Use the authenticated client, assetId and book from the steps above. The example uses the book’s minimum size and a buy price of one tick.

Place an Order

import { OrderSide } from "@polymarket/client";

const result = await client.placeLimitOrder({
  assetId,
  side: OrderSide.BUY,
  price: book.tickSize,
  size: book.minOrderSize,
  postOnly: true,
});

if (!result.ok) throw new Error(result.message);
console.log(result.orderId);

Read It Back

const order = await client.fetchOrder({ orderId: result.orderId });
console.log(order.status);

Cancel the Remaining Quantity

const cancellation = await client.cancelOrder({ orderId: result.orderId });
console.log(cancellation.canceled, cancellation.notCanceled);

Use the authenticated client, asset_id and book from the steps above. The example uses the book’s minimum size and a buy price of one tick.

Place an Order

result = await client.place_limit_order(
    asset_id=asset_id,
    side="BUY",
    price=book.tick_size,
    size=book.min_order_size,
    post_only=True,
)

if not result.ok:
    raise RuntimeError(result.message)
print(result.order_id)

Read It Back

order = await client.get_order(order_id=result.order_id)
print(order.status)

Cancel the Remaining Quantity

cancellation = await client.cancel_order(order_id=result.order_id)
print(cancellation.canceled, cancellation.not_canceled)

Order reads return open orders. If it fills before you read it back, follow updates on the user feed. A match happens before settlement; follow settlement before checking your position.