Trading - Polymarket Documentation

Trading workflows require an authenticated session.

Perps trading changes account exposure on an instrument. An order expresses what the account wants to do, but exposure only changes when the order fills. An accepted order can rest on the book before it fills. Use order state to track accepted, resting, modified, canceled, or rejected orders. Use fills and portfolio state to confirm any exposure change.

Start an Authenticated Session

Open an authenticated session before reading private account state or submitting trading commands. See Authenticated Sessions for the full setup flow.

TypeScript
Python
API

Create a SecureClient.

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

const client = await createSecureClient({
  wallet: process.env.POLYMARKET_WALLET_ADDRESS!,
  signer: privateKey(process.env.PRIVATE_KEY!),
});

Open the Perps session.

const session = await client.openPerpsSession();

Create an AsyncSecureClient.

import os

from polymarket import AsyncSecureClient

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

Open the Perps session.

session = await client.open_perps_session()

Use proxy credentials for private reads and signed trading commands.

polymarket-proxy: <proxy_address>
polymarket-secret: <proxy_secret>

Prepare a Trade

Start by identifying the Perps instrument you want to trade. Instruments define the market and include the constraints used later when building an order.

TypeScript
Python
API

Fetch instruments and select the market you want to trade.

const instruments = await client.fetchPerpsInstruments();
const instrument = instruments.find((item) => item.symbol === "BTC-PERP");

if (!instrument) {
  throw new Error("Instrument not found");
}

Keep the selected instrument available for the next steps.

Fetch instruments and select the market you want to trade.

instruments = await client.fetch_perps_instruments()
instrument = next((item for item in instruments if item.symbol == "BTC-PERP"), None)

if instrument is None:
    raise RuntimeError("Instrument not found")

Keep the selected instrument available for the next steps.

Fetch instruments and select the market you want to trade.

curl "https://api.perpetuals.polymarket.com/v1/info/instruments"

The response is a list of instruments.

[
  {
    "instrument_id": 1,
    "instrument_type": "perpetual",
    "category": "crypto",
    "symbol": "BTC-PERP",
    "base_asset": "BTC",
    "quote_asset": "USD",
    "funding_interval": "1h",
    "quantity_decimals": 4,
    "price_decimals": 2,
    "price_bounds": "0.1",
    "liquidation_fee": "0.01",
    "max_order_count": 200,
    "min_notional": "1",
    "max_market_notional": "100000",
    "max_limit_notional": "1000000",
    "max_leverage": 10,
    "risk_tiers": [{ "lower_bound": "0", "max_leverage": 10 }]
  }
]

Keep the selected instrument for the next steps.

Choose Direction and Size

Before placing an order, decide whether it should open new exposure, increase existing exposure, reduce exposure, or close the position. The effect of a buy or sell depends on the current position.

Current position	Buy order	Sell order
No position	Opens long	Opens short
Long	Increases long	Reduces or closes long
Short	Reduces or closes short	Increases short

To close a position, submit an order in the opposite direction for the current open position size.

TypeScript
Python
API

Read the portfolio when the order decision depends on current exposure.

const portfolio = await session.fetchPortfolio();
const position = portfolio.positions.find(
  (item) => item.instrumentId === instrument.id,
);

Positive position.size means the account is long. Negative position.size means the account is short. No matching position means the account has no open exposure for that instrument.

Read the portfolio when the order decision depends on current exposure.

portfolio = await session.fetch_portfolio()
position = next(
    (item for item in portfolio.positions if item.instrument_id == instrument.id),
    None,
)

Positive position.size means the account is long. Negative position.size means the account is short. No matching position means the account has no open exposure for that instrument.

Read the portfolio when the order decision depends on current exposure.

curl "https://api.perpetuals.polymarket.com/v1/account/portfolio" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>"

The response includes current positions.

{
  "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
}

Positive positions[].size means the account is long. Negative positions[].size means the account is short. No matching position means the account has no open exposure for that instrument.

Place Orders

Place an order when the account is ready to express buy or sell intent. Use an explicit limit price when you need price protection. Use immediate-or-cancel execution when the order should fill immediately or cancel any unfilled quantity.

TypeScript
Python
API

Choose a Price

Fetch a ticker when you need a lightweight current-price reference. Fetch the book when the order price depends on spread, depth, or top-of-book liquidity.

const ticker = await client.fetchPerpsTicker({ instrumentId: instrument.id });
const book = await client.fetchPerpsBook({ instrumentId: instrument.id });

Set price as pUSD per quantity unit, rounded to instrument.priceDecimals.

Build the Order

Create the order request from the direction, price, quantity, and execution behavior you chose. This example submits an immediate-or-cancel (IOC) buy order for 0.01 BTC-PERP at 65000 pUSD per quantity unit.

import {
  OrderSide,
  PerpsTimeInForce,
  type PlacePerpsOrderRequest,
} from "@polymarket/client";

const request: PlacePerpsOrderRequest = {
  instrumentId: instrument.id,
  side: OrderSide.BUY,
  price: "65000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.IOC,
};

side sets direction based on how you intend to open, increase, reduce, or close the position.
price is the price you chose in the first step, in pUSD per quantity unit.
quantity is the number of quantity units. Use no more than instrument.quantityDecimals decimal places.

Use clientOrderId when your integration needs its own identifier for tracking or canceling the order.

const request: PlacePerpsOrderRequest = {
  instrumentId: instrument.id,
  side: OrderSide.BUY,
  price: "65000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.IOC,
  clientOrderId: "7f9e4a2b6c8d0e1f1234567890abcdef",
};

Submit the Order

Submit the request with placeOrder. It resolves with the matching private order update after the order is accepted.

const order = await session.placeOrder(request);

Use the returned order to track whether the order filled, expired, canceled, or remains on the book.

type PerpsOrder = {
  id: PerpsOrderId;
  instrumentId: PerpsInstrumentId;
  side: OrderSide;
  price: string;
  quantity: string;
  timeInForce: PerpsTimeInForce;
  postOnly: boolean;
  status: PerpsOrderStatus;
  restingQuantity: string;
  filledQuantity: string;
  createdTimestamp: number;
  updatedTimestamp: number;
  clientOrderId?: string;
  tpSl?: PerpsTpSlOrderFields;
};

For an IOC order, status can be one of these values.

Status	Description
`PerpsOrderStatus.Filled`	The order fully filled.
`PerpsOrderStatus.IocNoFill`	The order did not fill.
`PerpsOrderStatus.IocExpired`	The order filled partially and the remainder canceled.
`PerpsOrderStatus.StpCancelled`	The order would have matched your own resting order, so it canceled.

Choose a Price

Fetch a ticker when you need a lightweight current-price reference. Fetch the book when the order price depends on spread, depth, or top-of-book liquidity.

ticker = await client.fetch_perps_ticker(instrument_id=instrument.id)
book = await client.fetch_perps_book(instrument_id=instrument.id)

Set price as pUSD per quantity unit, rounded to instrument.price_decimals.

Build the Order

request = {
    "instrument_id": instrument.id,
    "side": "BUY",
    "price": "65000",
    "quantity": "0.01",
    "time_in_force": "ioc",
}

side sets direction based on how you intend to open, increase, reduce, or close the position.
price is the price you chose in the first step, in pUSD per quantity unit.
quantity is the number of quantity units. Use no more than instrument.quantity_decimals decimal places.

Use client_order_id when your integration needs its own identifier for tracking or canceling the order.

request = {
    "instrument_id": instrument.id,
    "side": "BUY",
    "price": "65000",
    "quantity": "0.01",
    "time_in_force": "ioc",
    "client_order_id": "7f9e4a2b6c8d0e1f1234567890abcdef",
}

Submit the Order

Submit the request with place_order. It resolves with the matching private order update after the order is accepted.

result = await session.place_order(**request)
# result.order: PerpsOrder

Use result.order to track whether the order filled, expired, canceled, or remains on the book.

Example

{
  "id": 1234567890,
  "instrument_id": 1,
  "side": "BUY",
  "price": "65000",
  "quantity": "0.01",
  "time_in_force": "ioc",
  "post_only": false,
  "status": "filled",
  "resting_quantity": "0",
  "filled_quantity": "0.01",
  "created_at": 1767000010000,
  "updated_at": 1767000010500,
  "client_order_id": "7f9e4a2b6c8d0e1f1234567890abcdef"
}

For an IOC order, result.order.status can be one of these values.

Status	Description
`filled`	The order fully filled.
`ioc_no_fill`	The order did not fill.
`ioc_expired`	The order filled partially and the remainder canceled.
`stp_cancelled`	The order would have matched your own resting order, so it canceled.

Choose a Price

Fetch current market data when the order price depends on live prices or available liquidity.

curl -G "https://api.perpetuals.polymarket.com/v1/info/tickers" \
  --data-urlencode "instrument_id=1"

curl -G "https://api.perpetuals.polymarket.com/v1/info/book" \
  --data-urlencode "instrument_id=1" \
  --data-urlencode "depth=100"

Use tickers for a lightweight current-price reference. Use the book when the order price depends on spread, depth, or top-of-book liquidity.Set price as pUSD per quantity unit, rounded to the instrument’s price_decimals.

Build the Order Operation

Create a createOrders operation from the direction, price, quantity, and execution behavior you chose. This example submits an immediate-or-cancel (ioc) buy order for 0.01 BTC-PERP at 65000 pUSD per quantity unit.

Concept	Field	Notes
Instrument	`iid`	Instrument identifier.
Direction	`buy`	`true` buys, `false` sells.
Price	`p`	Price chosen in the first step.
Quantity	`qty`	Number of quantity units, with no more than `quantity_decimals` decimal places.
Time in force	`tif`	Use `ioc` for this basic order.
Client order ID	`c`	Optional identifier your integration can use to track or cancel the order. Must be a 32-character lowercase hex value.

{
  "type": "createOrders",
  "args": [
    {
      "iid": 1,
      "buy": true,
      "p": "65000",
      "qty": "0.01",
      "tif": "ioc",
      "c": "7f9e4a2b6c8d0e1f1234567890abcdef"
    }
  ]
}

Create the Operation Hash

Create the operation hash from the compact signable representation of the order operation. For createOrders, the compact operation is:

["createOrders", [[iid, buy, p, qty, tif, po, ro, c, tr]]];

Omit undefined array entries from the compact operation, then MessagePack-encode it and hash the encoded bytes with keccak256.The example below uses @msgpack/msgpack and Viem.

import { encode } from "@msgpack/msgpack";
import { keccak256 } from "viem";

const signableOperation = [
  "createOrders",
  [
    [
      1,
      true,
      "65000",
      "0.01",
      "ioc",
      false,
      undefined,
      "7f9e4a2b6c8d0e1f1234567890abcdef",
      undefined,
    ].filter((value) => value !== undefined),
  ],
] as const;

const opHash = keccak256(encode(signableOperation));

Create Order Typed Data

Create an EIP-712 Op typed-data payload.

{
  "domain": {
    "name": "Polymarket",
    "version": "1",
    "chainId": 137
  },
  "primaryType": "Op",
  "types": {
    "Op": [
      { "name": "data", "type": "bytes32" },
      { "name": "salt", "type": "uint64" },
      { "name": "ts", "type": "uint64" }
    ]
  },
  "message": {
    "data": "<op_hash>",
    "salt": 234567890,
    "ts": 1767000010000
  }
}

Field	Value
`data`	Operation hash from the previous step.
`salt`	Random integer generated for this signed request.
`ts`	Current Unix timestamp in milliseconds.

Sign Order Typed Data

Sign the Op typed data with the proxy signer private key. The example below uses Viem.

Viem

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("<proxy_private_key>");

const signature = await account.signTypedData({
  domain: {
    name: "Polymarket",
    version: "1",
    chainId: 137,
  },
  primaryType: "Op",
  types: {
    Op: [
      { name: "data", type: "bytes32" },
      { name: "salt", type: "uint64" },
      { name: "ts", type: "uint64" },
    ],
  },
  message: {
    data: opHash,
    salt: 234567890,
    ts: 1767000010000,
  },
});

Submit the Order

Submit the signed request to POST /v1/trade/orders.

curl -X POST "https://api.perpetuals.polymarket.com/v1/trade/orders" \
  -H "content-type: application/json" \
  -d '{
    "op": {
      "type": "createOrders",
      "args": [
        {
          "iid": 1,
          "buy": true,
          "p": "65000",
          "qty": "0.01",
          "tif": "ioc",
          "c": "7f9e4a2b6c8d0e1f1234567890abcdef"
        }
      ]
    },
    "sig": "<signature>",
    "salt": 234567890,
    "ts": 1767000010000
  }'

The response confirms whether the order request was accepted. Read the order state separately to see whether it filled, expired, or rests on the book.

[
  {
    "status": "ok",
    "oid": 1234567890,
    "coid": "7f9e4a2b6c8d0e1f1234567890abcdef"
  }
]

On success, keep oid as the order ID. If you supplied c, the response also echoes it as coid.

Read the Order State

Fetch the order snapshot by order_id or client_order_id to see whether the order filled, expired, or canceled after acceptance.

curl -G "https://api.perpetuals.polymarket.com/v1/account/orders" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>" \
  --data-urlencode "order_id=1234567890"

Use the order state fields to reconcile fill quantity, resting quantity, and status.

Field	Meaning
`order_id`	Order ID returned as `oid` in the acknowledgement.
`instrument_id`	Instrument identifier.
`buy`	`true` for buy orders, `false` for sell orders.
`price`	pUSD price per quantity unit.
`quantity`	Original order quantity.
`tif`	Time in force.
`post_only`	Whether the order was post-only.
`ro`	Whether the order was reduce-only.
`status`	Latest known order status.
`resting_quantity`	Quantity still resting on the book.
`filled_quantity`	Quantity that has filled.
`created_timestamp`	Creation timestamp in milliseconds.
`updated_timestamp`	Last update timestamp in milliseconds.
`client_order_id`	Client order ID, present when supplied in the request.

If the order snapshot is not available immediately, retry the read or listen to the private orders WebSocket channel for live updates.

[
  {
    "order_id": 1234567890,
    "instrument_id": 1,
    "buy": true,
    "price": "65000",
    "quantity": "0.01",
    "tif": "ioc",
    "post_only": false,
    "ro": false,
    "status": "filled",
    "resting_quantity": "0",
    "filled_quantity": "0.01",
    "created_timestamp": 1767000010000,
    "updated_timestamp": 1767000010500,
    "client_order_id": "7f9e4a2b6c8d0e1f1234567890abcdef"
  }
]

After this ioc order resolves, status is one of these values.

Status	Description
`filled`	The order fully filled.
`ioc_no_fill`	The order did not fill.
`ioc_expired`	The order filled partially and the remainder canceled.
`stp_cancelled`	The order would have matched your own resting order, so it canceled.

Take Profit & Stop Loss

Use take-profit and stop-loss (TP/SL) orders to place conditional exits for a position. A take-profit order exits when price moves in your favor. A stop-loss order exits when price moves against you.

How Triggers Work

TP/SL orders watch the mark price, not the last traded price. A trigger fires when the mark price touches the trigger price, then submits a reduce-only order to close exposure.

Position	Take-profit fires when	Stop-loss fires when
Long	Mark rises to trigger	Mark falls to trigger
Short	Mark falls to trigger	Mark rises to trigger

For a long position, take-profit triggers usually sit above the current mark and stop-loss triggers usually sit below it. For a short position, the directions are reversed.

Market and Limit Closes

Choose how the exit should execute after the trigger fires.

Close Type	What Happens	Available For
Market	The exit executes immediately against available liquidity.	Bracket orders and positions
Limit	The exit places a limit order and can remain open until it fills.	Bracket orders only

Place a Bracket Order

A bracket order submits one entry order with up to one take-profit and one stop-loss trigger. The triggers stay dormant until the entry fills in full. If the entry is canceled, rejected, or only partially filled, the triggers are canceled too. A bracket protects the completed entry, not a partial fill.

You cannot attach TP/SL triggers to an order that is already resting on the book. To protect a position from an existing order, wait for the fill and then protect the position.

TypeScript
Python
API

Place a GTC entry order with take-profit and stop-loss triggers.

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

const result = await session.placeOrder({
  instrumentId: instrument.id,
  side: OrderSide.BUY,
  price: "65000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.GTC,
  takeProfit: {
    triggerPrice: "70000",
  },
  stopLoss: {
    triggerPrice: "62000",
  },
});

const entryOrderId = result.order.id;
const takeProfitOrderId = result.tpSl.takeProfit?.orderId;
const stopLossOrderId = result.tpSl.stopLoss?.orderId;

result.order is the entry order. result.tpSl contains the order IDs for the conditional exits that were accepted with the entry order.

Output: PlacePerpsOrderWithTpSlResult

{
  "order": {
    "id": 1234567890,
    "instrumentId": 1,
    "side": "BUY",
    "price": "65000",
    "quantity": "0.01",
    "timeInForce": "gtc",
    "postOnly": false,
    "status": "open",
    "restingQuantity": "0.01",
    "filledQuantity": "0",
    "createdTimestamp": 1767000010000,
    "updatedTimestamp": 1767000010500
  },
  "tpSl": {
    "takeProfit": { "orderId": 1234567891 },
    "stopLoss": { "orderId": 1234567892 }
  }
}

Add limitPrice to a trigger when the exit should place a limit order at trigger time.

const result = await session.placeOrder({
  instrumentId: instrument.id,
  side: OrderSide.BUY,
  price: "65000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.GTC,
  stopLoss: {
    triggerPrice: "62000",
    limitPrice: "61900",
  },
});

Place a GTC entry order with take-profit and stop-loss triggers.

from polymarket import PerpsTpSlTrigger

result = await session.place_order(
    instrument_id=instrument.id,
    side="BUY",
    price="65000",
    quantity="0.01",
    time_in_force="gtc",
    take_profit=PerpsTpSlTrigger(trigger_price="70000"),
    stop_loss=PerpsTpSlTrigger(trigger_price="62000"),
)

# result.order.id: PerpsOrderId
# result.tp_sl.take_profit.order_id: PerpsOrderId
# result.tp_sl.stop_loss.order_id: PerpsOrderId

result.order is the entry order. result.tp_sl contains the order IDs for the conditional exits that were accepted with the entry order.

Output: PerpsOrderPlacement

{
  "order": {
    "id": 1234567890,
    "instrument_id": 1,
    "side": "BUY",
    "price": "65000",
    "quantity": "0.01",
    "time_in_force": "gtc",
    "post_only": false,
    "status": "open",
    "resting_quantity": "0.01",
    "filled_quantity": "0",
    "created_at": 1767000010000,
    "updated_at": 1767000010500
  },
  "tp_sl": {
    "take_profit": { "order_id": 1234567891 },
    "stop_loss": { "order_id": 1234567892 }
  }
}

Add limit_price to a trigger when the exit should place a limit order at trigger time.

result = await session.place_order(
    instrument_id=instrument.id,
    side="BUY",
    price="65000",
    quantity="0.01",
    time_in_force="gtc",
    stop_loss=PerpsTpSlTrigger(
        trigger_price="62000",
        limit_price="61900",
    ),
)

Submit the entry order and its TP/SL children in one createOrders operation with grp set to "order".

{
  "type": "createOrders",
  "grp": "order",
  "args": [
    {
      "iid": 1,
      "buy": true,
      "p": "65000",
      "qty": "0.01",
      "tif": "gtc",
      "c": "7f9e4a2b6c8d0e1f1234567890abcdef"
    },
    {
      "iid": 1,
      "buy": false,
      "qty": "0.01",
      "ro": true,
      "tr": {
        "market": true,
        "trp": "70000",
        "tpsl": "tp"
      }
    },
    {
      "iid": 1,
      "buy": false,
      "qty": "0.01",
      "ro": true,
      "tr": {
        "market": true,
        "trp": "62000",
        "tpsl": "sl"
      }
    }
  ]
}

Use the same signing flow as Place Orders. For hashing, sign the compact operation, not the structured JSON body. The TP/SL group is the third compact element:

["createOrders", [entryOrder, takeProfitOrder, stopLossOrder], "order"];

Then submit the signed request to POST /v1/trade/orders.

curl -X POST "https://api.perpetuals.polymarket.com/v1/trade/orders" \
  -H "content-type: application/json" \
  -d '{
    "op": {
      "type": "createOrders",
      "grp": "order",
      "args": [
        {
          "iid": 1,
          "buy": true,
          "p": "65000",
          "qty": "0.01",
          "tif": "gtc",
          "c": "7f9e4a2b6c8d0e1f1234567890abcdef"
        },
        {
          "iid": 1,
          "buy": false,
          "qty": "0.01",
          "ro": true,
          "tr": {
            "market": true,
            "trp": "70000",
            "tpsl": "tp"
          }
        },
        {
          "iid": 1,
          "buy": false,
          "qty": "0.01",
          "ro": true,
          "tr": {
            "market": true,
            "trp": "62000",
            "tpsl": "sl"
          }
        }
      ]
    },
    "sig": "<signature>",
    "salt": 234567890,
    "ts": 1767000010000
  }'

The response returns one acknowledgement per submitted order.

[
  {
    "status": "ok",
    "oid": 1234567890,
    "coid": "7f9e4a2b6c8d0e1f1234567890abcdef"
  },
  { "status": "ok", "oid": 1234567891 },
  { "status": "ok", "oid": 1234567892 }
]

Set market to true for market-style trigger execution. For limit trigger execution, omit market and set p on the TP/SL child order.

Protect an Existing Position

Add TP/SL orders to a position that is already open. Position TP/SL closes the full position at trigger time, so it does not use a fixed quantity. Position TP/SL has a few placement rules:

The account must already hold a position in the instrument.
The account can have at most one position take-profit and one position stop-loss per instrument.
When the trigger fires, the exit submits immediately. Position TP/SL does not support limit prices.
A position trigger is rejected if the current mark has already crossed it, because it would fire immediately.

TypeScript
Python
API

Place TP/SL orders for the full current position.

const result = await session.placePositionTpSl({
  instrumentId: instrument.id,
  takeProfit: {
    triggerPrice: "70000",
  },
  stopLoss: {
    triggerPrice: "62000",
  },
});

const takeProfitOrderId = result.tpSl.takeProfit?.orderId;
const stopLossOrderId = result.tpSl.stopLoss?.orderId;

placePositionTpSl sizes the exit at trigger time, so you do not pass a position side or quantity.

Place TP/SL orders for the full current position.

from polymarket import PerpsPositionTpSlTrigger

result = await session.place_position_tp_sl(
    instrument_id=instrument.id,
    take_profit=PerpsPositionTpSlTrigger(trigger_price="70000"),
    stop_loss=PerpsPositionTpSlTrigger(trigger_price="62000"),
)

# result.take_profit.order_id: PerpsOrderId
# result.stop_loss.order_id: PerpsOrderId

place_position_tp_sl sizes the exit at trigger time, so you do not pass a position side or quantity.

Submit position-scoped TP/SL orders with grp set to "position". Use qty: "0" so the engine sizes the exit at trigger time.Set buy to the side that closes the position: false for a long position and true for a short position.

{
  "type": "createOrders",
  "grp": "position",
  "args": [
    {
      "iid": 1,
      "buy": false,
      "qty": "0",
      "ro": true,
      "tr": {
        "market": true,
        "trp": "70000",
        "tpsl": "tp"
      }
    },
    {
      "iid": 1,
      "buy": false,
      "qty": "0",
      "ro": true,
      "tr": {
        "market": true,
        "trp": "62000",
        "tpsl": "sl"
      }
    }
  ]
}

Sign the compact operation, not the structured JSON body. The TP/SL group is the third compact element:

["createOrders", [takeProfitOrder, stopLossOrder], "position"];

Submit the signed request to POST /v1/trade/orders and keep the returned order IDs for reconciliation.

Update or Cancel TP/SL

TP/SL orders cannot be modified in place. To change a trigger price or execution type, cancel the old trigger and create a replacement.

For position TP/SL, cancel the old trigger before creating another trigger of the same kind for the instrument.
For a bracket whose entry is still resting, cancel the entry and place a new bracket with the updated triggers.
For a bracket whose entry already filled, cancel the armed trigger and create position TP/SL as the replacement.

Cancel-then-create is not atomic. Between the cancel and the replacement, the position may be unprotected.

Configure Order Behavior

So far, we have used immediate-or-cancel orders. Next, we’ll look at how to control whether an order rests, fills immediately, or only adds liquidity.

Good-Til-Canceled Orders

Use good-til-canceled orders when the order can rest on the book until it fills or you cancel it.

TypeScript
Python
API

Set timeInForce to GTC.

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

const order = await session.placeOrder({
  instrumentId: instrument.id,
  side: OrderSide.BUY,
  price: "65000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.GTC,
});

For a GTC order, order.status can be one of these values.

Status	Meaning
`PerpsOrderStatus.Open`	The order is resting on the book.
`PerpsOrderStatus.Filled`	The order fully filled before resting.
`PerpsOrderStatus.StpCancelled`	The order would have matched your own resting order, so it canceled.

If a GTC order partially fills and rests, inspect filledQuantity and restingQuantity on the returned order.

Set time_in_force to gtc.

result = await session.place_order(
    instrument_id=instrument.id,
    side="BUY",
    price="65000",
    quantity="0.01",
    time_in_force="gtc",
)

# result.order: PerpsOrder

For a GTC order, result.order.status can be one of these values.

Status	Meaning
`open`	The order is resting on the book.
`filled`	The order fully filled before resting.
`stp_cancelled`	The order would have matched your own resting order, so it canceled.

If a GTC order partially fills and rests, inspect result.order.filled_quantity and result.order.resting_quantity.

Set tif to "gtc".

{
  "type": "createOrders",
  "args": [
    {
      "iid": 1,
      "buy": true,
      "p": "65000",
      "qty": "0.01",
      "tif": "gtc"
    }
  ]
}

After the order is accepted, read order state from GET /v1/account/orders or the private orders WebSocket channel. For a gtc order, status can be one of these values.

Status	Meaning
`open`	The order is resting on the book.
`filled`	The order fully filled before resting.
`stp_cancelled`	The order would have matched your own resting order, so it canceled.

If a gtc order partially fills and rests, inspect filled_quantity and resting_quantity.

Post-Only Orders

A post-only order is a special type of good-til-canceled order that only adds liquidity. If it would cross the book and take liquidity, it is rejected instead.

TypeScript
Python
API

Set postOnly: true on a GTC order.

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

const order = await session.placeOrder({
  instrumentId: instrument.id,
  side: OrderSide.BUY,
  price: "65000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.GTC,
  postOnly: true,
});

For a post-only order, order.status can be one of these values.

Status	Meaning
`PerpsOrderStatus.Open`	The order was accepted and added to the book.
`PerpsOrderStatus.PostOnlyRejected`	The order would have crossed the book and taken liquidity.

Set post_only=True on a GTC order.

result = await session.place_order(
    instrument_id=instrument.id,
    side="BUY",
    price="65000",
    quantity="0.01",
    time_in_force="gtc",
    post_only=True,
)

# result.order: PerpsOrder

For a post-only order, result.order.status can be one of these values.

Status	Meaning
`open`	The order was accepted and added to the book.
`post_only_rejected`	The order would have crossed the book and taken liquidity.

Set po: true on a gtc order.

{
  "type": "createOrders",
  "args": [
    {
      "iid": 1,
      "buy": true,
      "p": "65000",
      "qty": "0.01",
      "tif": "gtc",
      "po": true
    }
  ]
}

For a post-only order, status can be one of these values.

Status	Meaning
`open`	The order was accepted and added to the book.
`post_only_rejected`	The order would have crossed the book and taken liquidity.

Fill-Or-Kill Orders

Use fill-or-kill orders when the full quantity must fill immediately or cancel. These orders do not rest on the book.

TypeScript
Python
API

Set timeInForce to FOK.

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

const order = await session.placeOrder({
  instrumentId: instrument.id,
  side: OrderSide.BUY,
  price: "65000",
  quantity: "0.01",
  timeInForce: PerpsTimeInForce.FOK,
});

For a FOK order, order.status can be one of these values.

Status	Meaning
`PerpsOrderStatus.Filled`	The full order quantity filled immediately.
`PerpsOrderStatus.FokUnfilled`	The full order quantity could not fill immediately, so it canceled.
`PerpsOrderStatus.StpCancelled`	The order would have matched your own resting order, so it canceled.

Set time_in_force to fok.

result = await session.place_order(
    instrument_id=instrument.id,
    side="BUY",
    price="65000",
    quantity="0.01",
    time_in_force="fok",
)

# result.order: PerpsOrder

For a FOK order, result.order.status can be one of these values.

Status	Meaning
`filled`	The full order quantity filled immediately.
`fok_unfilled`	The full order quantity could not fill immediately, so it canceled.
`stp_cancelled`	The order would have matched your own resting order, so it canceled.

Set tif to "fok".

{
  "type": "createOrders",
  "args": [
    {
      "iid": 1,
      "buy": true,
      "p": "65000",
      "qty": "0.01",
      "tif": "fok"
    }
  ]
}

For a fok order, status can be one of these values.

Status	Meaning
`filled`	The full order quantity filled immediately.
`fok_unfilled`	The full order quantity could not fill immediately, so it canceled.
`stp_cancelled`	The order would have matched your own resting order, so it canceled.

Cancel Resting Orders

Cancel resting orders when they are stale, conflict with updated strategy, or should no longer remain on the book. Canceling a resting order does not close any filled position.

TypeScript
Python
API

Cancel stale orders by order ID or by client order ID.

const result = await session.cancelOrder({
  orderId: order.id,
});

Use result.status to confirm whether the cancel request was accepted.

Status	Meaning
`ok`	The cancel command was accepted.
`err`	The cancel command was not accepted.

Canceling a working order removes it from the book.

Cancel stale orders by order ID or by client order ID.

result = await session.cancel_order(order_id=order.id)
# result: PerpsCancelOrderResult

Use result.status to confirm whether the cancel request was accepted.

Status	Meaning
`ok`	The cancel command was accepted.
`err`	The cancel command was not accepted.

Canceling a working order removes it from the book.

Cancel by order ID with DELETE /v1/trade/orders.

curl -X DELETE "https://api.perpetuals.polymarket.com/v1/trade/orders" \
  -H "content-type: application/json" \
  -d '{
    "op": {
      "type": "cancelOrders",
      "args": [1234567890]
    },
    "sig": "<cancel_signature>",
    "salt": 234567892,
    "ts": 1767000030000
  }'

Cancel by client order ID with DELETE /v1/trade/orders-coid.

curl -X DELETE "https://api.perpetuals.polymarket.com/v1/trade/orders-coid" \
  -H "content-type: application/json" \
  -d '{
    "op": {
      "type": "cancelOrdersCOID",
      "args": ["7f9e4a2b6c8d0e1f1234567890abcdef"]
    },
    "sig": "<cancel_signature>",
    "salt": 234567893,
    "ts": 1767000040000
  }'

The response contains one cancel result per requested order.

[
  {
    "status": "ok",
    "oid": 1234567890
  }
]

Close a Position

Closing a position is a new order in the opposite direction of the open position. Use the full open position size to close. Use a smaller quantity to reduce instead. Mark close orders reduce-only so they cannot flip the account into new exposure if position state changes before execution. Reduce-only is a safeguard, not a sizing shortcut. You still choose the quantity: use the full position size to close or a smaller quantity to reduce. If the order would increase exposure, flip the position, or exceed the remaining closeable size, it is rejected.

Current Position	Reduce-Only Buy	Reduce-Only Sell
Long	Rejected	Reduces or closes
Short	Reduces or closes	Rejected
No position	Rejected	Rejected

The remaining closeable size accounts for other resting reduce-only orders on the same instrument.

TypeScript
Python
API

Find the current position by market symbol and parse its decimal size.

import Big from "big.js";

const portfolio = await session.fetchPortfolio();
const position = portfolio.positions.find((item) => item.symbol === "BTC-PERP");

if (!position) {
  throw new Error("No open BTC-PERP position");
}

const size = new Big(position.size);

Close a long position by selling the full size, or close a short position by buying the absolute position size.

import {
  OrderSide,
  PerpsOrderStatus,
  PerpsTimeInForce,
} from "@polymarket/client";

if (size.gt(0)) {
  const order = await session.placeOrder({
    instrumentId: instrument.id,
    side: OrderSide.SELL,
    quantity: position.size,
    timeInForce: PerpsTimeInForce.IOC,
    reduceOnly: true,
  });

  if (order.status === PerpsOrderStatus.Filled) {
    // The position is fully closed.
  }
}

These examples use an IOC order with no price and only treat the close as complete when order.status is PerpsOrderStatus.Filled. Include a price when you want to limit execution, or use FOK or GTC when the close should follow a different order behavior.For reduce-only orders, also handle these statuses.

Status	Meaning
`PerpsOrderStatus.ReduceOnlyInvalid`	The order would not reduce the remaining closeable position.
`PerpsOrderStatus.ReduceOnlyExpired`	A resting reduce-only order was canceled after the position fully closed.

Find the current position by market symbol and inspect its decimal size.

portfolio = await session.fetch_portfolio()
position = next((item for item in portfolio.positions if item.symbol == "BTC-PERP"), None)

if position is None:
    raise RuntimeError("No open BTC-PERP position")

# position: PerpsPosition
# position.size: Decimal

Close a long position by selling the full size, or close a short position by buying the absolute position size.

if position.size > 0:
    result = await session.place_order(
        instrument_id=instrument.id,
        side="SELL",
        quantity=position.size,
        time_in_force="ioc",
        reduce_only=True,
    )

    if result.order.status == "filled":
        # The position is fully closed.
        pass

These examples use an IOC order with no price and only treat the close as complete when result.order.status is filled. Include a price when you want to limit execution, or use FOK or GTC when the close should follow a different order behavior.For reduce-only orders, also handle these statuses.

Status	Meaning
`reduce_only_invalid`	The order would not reduce the remaining closeable position.
`reduce_only_expired`	A resting reduce-only order was canceled after the position fully closed.

Fetch the portfolio and inspect the position size for the instrument.

curl "https://api.perpetuals.polymarket.com/v1/account/portfolio" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>"

Use the sign of positions[].size to determine the closing side. A positive size is a long position. A negative size is a short position.

Position excerpt

{
  "positions": [
    {
      "instrument_id": 1,
      "symbol": "BTC-PERP",
      "size": "0.01"
    },
    {
      "instrument_id": 2,
      "symbol": "ETH-PERP",
      "size": "-0.5"
    }
  ]
}

Submit a createOrders operation in the opposite direction for the full size and set ro: true so the order cannot increase or flip exposure.

Current `positions[].size`	Closing order `buy`	Closing order `qty`	Closing order `ro`
Positive	`false`	Current position size.	`true`
Negative	`true`	Absolute position size.	`true`

Closing can use ioc, gtc, or fok depending on the execution behavior you want.For reduce-only orders, status can include these values.

Status	Meaning
`reduce_only_invalid`	The order would not reduce the remaining closeable position.
`reduce_only_expired`	A resting reduce-only order was canceled after the position fully closed.

Update Leverage

Leverage controls how much notional exposure a position can carry relative to its margin. Cross margin uses available account collateral for the position; non-cross margin keeps the position isolated. Validate leverage against instrument.maxLeverage and the current instrument.riskTiers before submitting the change.

TypeScript
Python
API

Read Current Configuration

Read the current account configuration before changing leverage.

const [config] = await session.fetchAccountConfig({
  instrumentId: instrument.id,
});

config includes the current leverage and margin mode for the instrument.

Update Leverage

Update leverage and whether the position uses cross margin. The result confirms the effective leverage configuration after the update.

const result = await session.updateLeverage({
  instrumentId: instrument.id,
  leverage: 5,
  crossMargin: false,
});

The result includes the effective leverage configuration after the update.

Example Result

{
  "status": "ok",
  "instrumentId": 1,
  "leverage": 5,
  "crossMargin": false
}

Read Current Configuration

Read the current account configuration before changing leverage.

configs = await session.fetch_account_config(
    instrument_id=instrument.id,
)
# configs[0]: PerpsAccountConfig

Each config includes the current leverage and margin mode for the instrument.

Update Leverage

Update leverage and whether the position uses cross margin. The result confirms the effective leverage configuration after the update.

result = await session.update_leverage(
    instrument_id=instrument.id,
    leverage=5,
    cross_margin=False,
)
# result: PerpsUpdateLeverageResult

The result includes the effective leverage configuration after the update.

Example Result

{
  "status": "ok",
  "instrument_id": 1,
  "leverage": 5,
  "cross_margin": false
}

Read Current Configuration

Read the current account configuration before changing leverage.

curl -G "https://api.perpetuals.polymarket.com/v1/account/config" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>" \
  --data-urlencode "instrument_id=1"

The account config includes the current leverage and margin mode for the instrument.

Build the Leverage Operation

Create an updateLeverage operation with the instrument ID, leverage, and margin mode.

{
  "type": "updateLeverage",
  "args": {
    "iid": 1,
    "lev": 5,
    "cross": false
  }
}

Create the Operation Hash

Create the operation hash from the compact signable representation of the operation.

["updateLeverage", [iid, lev, cross]];

Omit undefined array entries from the compact operation, then MessagePack-encode it and hash the encoded bytes with keccak256.

import { encode } from "@msgpack/msgpack";
import { keccak256 } from "viem";

const signableOperation = ["updateLeverage", [1, 5, false]] as const;

const opHash = keccak256(encode(signableOperation));

Sign Leverage Typed Data

Create and sign an EIP-712 Op typed-data payload with the proxy signer private key.

Viem

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("<proxy_private_key>");

const signature = await account.signTypedData({
  domain: {
    name: "Polymarket",
    version: "1",
    chainId: 137,
  },
  primaryType: "Op",
  types: {
    Op: [
      { name: "data", type: "bytes32" },
      { name: "salt", type: "uint64" },
      { name: "ts", type: "uint64" },
    ],
  },
  message: {
    data: opHash,
    salt: 234567894,
    ts: 1767000050000,
  },
});

Submit the Update

Submit the signed request to PATCH /v1/trade/leverage.

curl -X PATCH "https://api.perpetuals.polymarket.com/v1/trade/leverage" \
  -H "content-type: application/json" \
  -d '{
    "op": {
      "type": "updateLeverage",
      "args": {
        "iid": 1,
        "lev": 5,
        "cross": false
      }
    },
    "sig": "<leverage_signature>",
    "salt": 234567894,
    "ts": 1767000050000
  }'

Read the Confirmed Result

The response confirms the effective leverage configuration after the update, or returns an error if the update is rejected.

{
  "status": "ok",
  "instrument_id": 1,
  "leverage": 5,
  "cross": false
}

Reconcile Trade State

Keep local trading state in sync by starting from a local snapshot, applying live updates, and reconciling again whenever the session tells you state may have been missed. TP/SL orders appear alongside regular orders in open-order and order-history reads. Track their lifecycle in addition to the position and fills they protect.

Lifecycle State	Meaning
Dormant	Waiting for a bracket entry order to fill in full.
Armed	Watching the mark price for the trigger.
Triggered	Fired and submitted the closing order.
Canceled	Removed by you, by parent cancellation, or by auto-cancel.
Cleared	Removed because the protected position closed or changed sides.

TypeScript
Python
API

Fetch a Startup Snapshot

Fetch a snapshot when the session starts.

async function fetchTradingSnapshot() {
  const [balances, openOrders, orders, fills, portfolio] = await Promise.all([
    session.fetchBalances(),
    session.fetchOpenOrders({ instrumentId: instrument.id }),
    session.fetchOrders({ instrumentId: instrument.id }),
    session.listFills().firstPage(),
    session.fetchPortfolio(),
  ]);

  return { balances, openOrders, orders, fills, portfolio };
}

let snapshot = await fetchTradingSnapshot();

Apply Live Events

Then apply trading live events while the session is open.

for await (const event of session) {
  switch (event.type) {
    case "balance": {
      // event.payload: PerpsBalance
      break;
    }

    case "order": {
      // event.payload: PerpsOrder
      break;
    }

    case "fill": {
      // event.payload: PerpsAccountFill
      break;
    }

    case "portfolio": {
      // event.payload.positions contains current exposure.
      break;
    }

    case "tpsl": {
      // event.payload: PerpsTpSlUpdateEvent["payload"]
      break;
    }
  }
}

Reconcile on Resync

When event.type is "resync", use account reads as the first step to reconcile local state before applying more local assumptions.

if (event.type === "resync") {
  snapshot = await fetchTradingSnapshot();
}

Fetch a Startup Snapshot

Fetch a snapshot when the session starts.

import asyncio


async def fetch_trading_snapshot():
    balances, open_orders, orders, fills, portfolio = await asyncio.gather(
        session.fetch_balances(),
        session.fetch_open_orders(instrument_id=instrument.id),
        session.fetch_orders(instrument_id=instrument.id),
        session.list_fills().first_page(),
        session.fetch_portfolio(),
    )

    return {
        "balances": balances,
        "open_orders": open_orders,
        "orders": orders,
        "fills": fills,
        "portfolio": portfolio,
    }


snapshot = await fetch_trading_snapshot()

Apply Live Events

Then apply trading live events while the session is open.

async for event in session:
    if event.type == "balance":
        # event.payload: PerpsBalance
        pass
    elif event.type == "order":
        # event.payload: PerpsOrder
        pass
    elif event.type == "fill":
        # event.payload: PerpsFill
        pass
    elif event.type == "portfolio":
        # event.payload.positions contains current exposure.
        pass
    elif event.type == "tpsl":
        # event.payload: PerpsTpSlUpdate
        pass

Reconcile on Resync

When event.type is "resync", use account reads as the first step to reconcile local state before applying more local assumptions.

if event.type == "resync":
    snapshot = await fetch_trading_snapshot()

Fetch a Startup Snapshot

Use account reads to build the local startup snapshot.

curl "https://api.perpetuals.polymarket.com/v1/account/balances" \
  -H "polymarket-proxy: <proxy_address>" \
  -H "polymarket-secret: <proxy_secret>"

Apply Live Events

Then use the authenticated WebSocket session for live updates. Private WebSocket frames can include balances, orders, fills, portfolio, and TP/SL updates. See Authenticated Sessions for the session lifecycle.

{
  "ch": "balances",
  "data": {
    "asset": "pUSD",
    "balance": "1000",
    "value": "1000"
  },
  "sq": 1,
  "ts": 1767000010000
}

Detect Sequence Gaps

Track the sq sequence number for each channel. If a sequence number is skipped or the connection reconnects, repeat the account reads above before relying on local state.

Trading Fees

Use the fee schedule when you need to display or account for maker and taker trading fees. Fee rates are decimal strings, so "0.0002" means 0.02%.

TypeScript
Python
API

Fetch the current Perps fee schedule.

const fees = await client.fetchPerpsFees();
// fees: PerpsFeeScheduleEntry[]

Each fee entry contains the market category and its maker and taker fee rates.

type PerpsFeeScheduleEntry = {
  category: PerpsInstrumentCategory;
  makerFeeRate: DecimalString;
  takerFeeRate: DecimalString;
};

makerFeeRate applies when an order adds liquidity, such as a resting or post-only order. takerFeeRate applies when an order removes liquidity, such as an immediately filled IOC order.

Fetch the current Perps fee schedule.

fees = await client.fetch_perps_fees()
# fees: tuple[PerpsFeeScheduleEntry, ...]

Each fee entry contains the market category and its maker and taker fee rates.maker_fee_rate applies when an order adds liquidity, such as a resting or post-only order. taker_fee_rate applies when an order removes liquidity, such as an immediately filled IOC order.

Fetch the current Perps fee schedule.

curl "https://api.perpetuals.polymarket.com/v1/info/fees"

The response contains fee entries with maker and taker fee rates.

{
  "fee_schedule": [
    {
      "instrument_type": "perpetual",
      "category": "crypto",
      "maker_fee_rate": "-0.00005",
      "taker_fee_rate": "0.0002"
    }
  ]
}

maker_fee_rate applies when an order adds liquidity, such as a resting or post-only order. taker_fee_rate applies when an order removes liquidity, such as an immediately filled ioc order.

​Start an Authenticated Session

​Prepare a Trade

​Choose Direction and Size

​Place Orders

​Take Profit & Stop Loss

​How Triggers Work

​Market and Limit Closes

​Place a Bracket Order

​Protect an Existing Position

​Update or Cancel TP/SL

​Configure Order Behavior

​Good-Til-Canceled Orders

​Post-Only Orders

​Fill-Or-Kill Orders

​Cancel Resting Orders

​Close a Position

​Update Leverage

​Reconcile Trade State

​Trading Fees

Start an Authenticated Session

Prepare a Trade

Choose Direction and Size

Place Orders

Take Profit & Stop Loss

How Triggers Work

Market and Limit Closes

Place a Bracket Order

Protect an Existing Position

Update or Cancel TP/SL

Configure Order Behavior

Good-Til-Canceled Orders

Post-Only Orders

Fill-Or-Kill Orders

Cancel Resting Orders

Close a Position

Update Leverage

Reconcile Trade State

Trading Fees