Introduction

Welcome to Polymarket's docs! Here developers can find all the information they need for interacting with Polymarket. This includes documentation on market discovery, resolution, trading etc. Whether you are an academic researcher a market maker or an indy developer, this documentation should provide you what you need to get started. All the code you find linked here and on our GitHub is open source and free to use. If you have any questions please join our discord and direct your questions to the #devs channel.

CLOB API

Introduction

Welcome to the Polymarket Order Book API! In this documentation you will find overviews, explanations, examples and annotations that aim to make interacting with the order book a breeze. In this section we will provide a general overview of the Polymarket Order Book and the purpose of the API before diving deep into the API and clients in following sections.

System

Polymarket's Order Book, also referred to as the "CLOB" (Central Limit Order Book) or "BLOB" (Binary Limit Order Book), is hybrid-decentralized wherein there is an operator that provides off-chain matching/ordering/execution services while settlement happens on-chain, non-custodially according to instructions provided by users in the form of signed order messages. This decentralized exchange model provides users with a powerful, non-custodial exchange experience.

Underlying the exchange system is a custom Exchange contract that facilitates atomic swaps (settlement) between binary Outcome Tokens (both CTF ERC1155 assets and ERC20 PToken assets) and a collateral asset (ERC20) according to signed limit orders. The Exchange contract is purpose built for binary markets (instruments that allow collateral to be split into positions and conversely positions to be merged into collateral with the two positions ultimately being settled to a price equal to 1). This allows "unification" of order books such that orders for a position and its complement can be matched. Explicitly, the Exchange allows for matching operations that include a mint/merge operation which allows orders for complementary outcome tokens to be crossed.

Orders are represented as signed typed structured data (EIP712). When orders are matched, one side is considered the maker and the other side is considered the taker. The relationship is always either one to one or many to one (maker to taker) and any price improvement is captured by the taker. The Operator is responsible for matching, ordering, and submitting matched trades to the underlying blockchain network for execution. As such, order placement and canellation can happen immediately off-chain while only the settlement action must occur on-chain.

API

The Polymarket Order Book API is a set of endpoints that allow market makers, traders, and other Polymarket users to programmatically create and manage orders for markets via access to the API provided by the operator.

Orders for any amount can be created and listed, or fetched and read from the order book for a given market. The API also provides data on all available markets, market prices, and order history through REST and WSS endpoints.

Security

Polymarket's Exchange contract has been audited by Chainsecurity you can find the audit report here.

The operator has no special privileges outside of ordering, this means that the only actions you must trust them with is enforcing correct ordering, not censoring and removing cancellations (orders can also be cancelled on-chain if operator is not trusted). If the operator is not doing any of these activities fairly a user can simply stop interacting with the operator. The operator is never able to set prices for users, or execute any trade on the user's behalf outside of the signed limit orders the user creates.

Fees

Schedule

Subject to change

Overview

Fees are levied in the output asset (proceeds). Fees for binary options with a complementary relationship (ie A + A' = C) must be symmetric to preserve market integrity. Symmetric means that someone selling 100 shares of A @ $0.99 should pay the same fee value as someone buying 100 A' @ $0.01. An intuition for this requires understanding that minting/merging a complementary token set for collateral can happen at any time. Fees are thus implemented in the following manner.

If buying (ie receiving A or A'), the fee is levied on the proceed tokens. If selling (ie receiving C), the fee is levied on the proceed collateral. The base fee rate (baseFeeRate) is signed into the order struct. The base fee rate corresponds to % the fee rate paid by traders when the price of the two tokens is equal (ie $0.50 and $0.50). Moving away from a centered price, the following formulas are used to calculate the fees making sure to maintain symmetry.

Case 1: If selling outcome tokens (base) for collateral (quote):

$$ feeQuote = baseRate * \min(price, 1-price) * size $$

Case 2: If buying outcome tokens (base) with collateral (quote):

$$ feeBase = baseRate * \min(price, 1-price) * \frac{size}{price} $$

Additional Resources

• Exchange contract source code
• Exchange contract documentation

Deployments

The Exchange contract is deployed at the following addresses:

Status

https://status-clob.polymarket.com/

Clients

Installation

npm i -s @polymarket/clob-client

yarn add @polymarket/clob-client

pip install py-clob-client

Polymarket has implemented reference clients that allow programmatic use of the API below:

• clob-client (Typescript)
• py-clob-client (Python)

Initialization

from py_clob_client.client import ClobClient

host: str = ""
key: str = ""
chain_id: int = 1
client = ClobClient(host, key=key, chain_id=chain_id)

import { ClobClient } from "polymarket/clob-client";

const clobClient = new ClobClient(
  host as string,
  (await wallet.getChainId()) as number,
  wallet as ethers.Wallet | ethers.providers.JsonRpcSigner
);

Order Utils

Polymarket has implemented utility libraries to programmatically sign and generate orders:

• clob-order-utils (Typescript)
• python-order-utils (Python)
• go-order-utils (Golang)

Endpoints

REST

Used for all CLOB REST endpoints, denoted {clob-endpoint}.

https://clob.polymarket.com/

Websocket

Used for all CLOB WSS endpoints, denoted {wss-channel}.

wss://ws-subscriptions-clob.polymarket.com/ws/

Authentication

There are two levels of authentication to be considered when using Polymarket's CLOB. All signing can be handled directly by the client libraries.

L1: Private Key Authentication

The highest level of authentication is via an account's Polygon private key. The private key remains in control of a user's funds and as such all trading is non-custodial. The operator never has control over users' funds.

Private key authentication is required for the following operations:

• Placing an order (for signing the order)
• Creating or revoking API keys

L1 Header

The POLY_SIGNATURE is generated by signing the following EIP712 struct:

const domain = {
  name: "ClobAuthDomain",
  version: "1",
  chainId: chainId, // Polygon ChainID 137
};

const types = {
  ClobAuth: [
    { name: "address", type: "address" },
    { name: "timestamp", type: "string" },
    { name: "nonce", type: "uint256" },
    { name: "message", type: "string" },
  ],
};
const value = {
  address: signingAddress, // the Signing address
  timestamp: ts, // The CLOB API server timestamp
  nonce: nonce, // The nonce used
  message: "This message attests that I control the given wallet", // A static message indicating that the user controls the wallet
};
const sig = await signer._signTypedData(domain, types, value);

Implementations exist in the Typescript and Python clients

L2: API Key Authentication

The next level of authentication consists of the API key, secret and passphrase which are used solely to authenticate API requests made to Polymarket's CLOB. This includes operations such as posting/canceling orders or retrieving an account's orders and fills.

When a user on-boards via POST /auth/api-key, the server will use the signature as a seed to deterministically generate credentials. An API credential includes three fields:

key: UUID identifying the credentials.

secret: Secret string used to generate HMACs, not sent with requests.

passphrase: Secret string sent with each request, used to encrypt/decrypt the secret in our DB, and never stored in our DB.

All requests which are not signed by a private key (/auth/api-key) and which are made to private endpoints require an API key signature.

L2 Header

Create API Key

Create new API key credentials for a user.

HTTP Request

POST {clob-endpoint}/auth/api-key

const creds = await clobClient.createApiKey(); // nonce defaults to 0

creds = client.create_api_key()

The above request returns a JSON structured like this:

{
  "apiKey": "xxxxxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
  "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
  "passphrase": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Derive API Key

Derive an existing API key for an address and nonce.

HTTP Request

GET {clob-endpoint}/auth/derive-api-key

const creds = await clobClient.deriveApiKey(); // nonce defaults to 0

creds = client.derive_api_key() ## nonce defaults to 0

The above request returns JSON structured like this:

{
  "apiKey": "xxxxxxxxx-xxxxx-xxxxxx-xxxx-xxxxxxxxxxxx",
  "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
  "passphrase": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Get API Keys

Get all api keys associated with a Polygon address.

HTTP Request

GET {clob-endpoint}/auth/api-keys

const apiKeys = await clobClient.getApiKeys();

api_keys = client.get_api_keys()

The above command returns a JSON structured like this:

{
  "apiKeys": [ "xxxxxxxxx-xxxxx-xxxxxx-xxxx-xxxxxxxxxxxx", ... ]
}

Delete API Key

Deletes API used to authenticate the request.

HTTP Request

DELETE {clob-endpoint}/auth/api-key

const resp = await clobClient.deleteApiKey();
console.log(resp);

resp = clob_client.delete_api_key()
print(resp)

If successful, the above command returns an "OK" string value:

"OK"

Orders

Overview

All orders are expressed as limit orders (can be marketable). The underlying order primitive must be in the form expected and executable by the on-chain binary limit order protocol contract. Preparing such an order is quite involved (structuring, hashing, signing), thus Polymarket suggests using the open source typescript, python and golang libraries.

Allowances

To place an order, allowances must be set by the funder address for the specified maker asset for the Exchange contract. When buying, this means the funder must have set a USDC allowance greater than or equal to the spending amount. When selling, the funder must have set an allowance for the conditional token tht is greater than or equal to the selling amount. This allows the Exchange contract to execute settlement according to the signed order instructions created by a user and matched by the operator.

Signature Types

Polymarket's CLOB supports 3 signature types. Orders must identify what signature type they use. The available typescript and python clients abstract the complexity of signing and preparing orders with the following signature types by allowing a funder address and signer type to be specified on initialization. The supported signature types are:

Validity Checks

Orders are continually monitored to make sure they remain valid. Specifically, this includes continually tracking underlying balances, allowances and on-chain order cancellations. Any maker that is caught intentionally abusing these checks (which are essentially real time) will be blacklisted.

Additionally, there are rails on order placement in a market. Specifically, you can only place orders that sum to less than or equal to your available balance for each market. For example if you have 500 USDC in your funding wallet, you can place one order to buy 1000 YES in marketA @ $.50, then any additional buy orders to that market will be rejected since your entire balance is reserved for the first (and only) buy order. More explicitly the max size you can place for an order is:

$$ maxOrderSize = underlyingAssetBalance - \sum(orderSize - orderFillAmount) $$

Create and Place an Order

Create and place an order using the Polymarket CLOB API clients. All orders are represented as "limit" orders, but "market" orders are enabled by allowing marketable limit orders, which are executed on input at the best price available. Thus to place a market order, simply ensure your price is marketable against current resting limit orders.

HTTP Request

POST {clob-endpoint}/order

// GTC Order example
//
import { Side, OrderType } from "@polymarket/clob-client";

async function main() {
  // Create a buy order for 100 YES for 0.50c
  // YES: 16678291189211314787145083999015737376658799626183230671758641503291735614088
  const order = await clobClient.createOrder({
    tokenID:
      "16678291189211314787145083999015737376658799626183230671758641503291735614088",
    price: 0.5,
    side: Side.BUY,
    size: 100,
    feeRateBps: 100,
    nonce: 1,
  });
  console.log("Created Order", order);

  // Send it to the server

  // GTC Order
  const resp = await clobClient.postOrder(order, OrderType.GTC);
  console.log(resp);
}

main();

// GTD Order example
//
import { Side, OrderType } from "@polymarket/clob-client";

async function main() {
  // Create a buy order for 100 YES for 0.50c that expires in 1 minute
  // YES: 16678291189211314787145083999015737376658799626183230671758641503291735614088

  const oneMinute = parseInt(
    ((new Date().getTime() + 60 * 1000 + 10 * 1000) / 1000).toString()
  );

  const order = await clobClient.createOrder({
    tokenID:
      "16678291189211314787145083999015737376658799626183230671758641503291735614088",
    price: 0.5,
    side: Side.BUY,
    size: 100,
    feeRateBps: 100,
    nonce: 1,
    expiration: oneMinute,
  });
  console.log("Created Order", order);

  // Send it to the server

  // GTD Order
  const resp = await clobClient.postOrder(order, OrderType.GTD);
  console.log(resp);
}

main();

// FOK Order example
//
import { Side, OrderType } from "@polymarket/clob-client";

async function main() {
  // Create a buy order for 100 YES for 0.50c that expires in 1 minute
  // YES: 16678291189211314787145083999015737376658799626183230671758641503291735614088

  const oneMinute = parseInt(
    ((new Date().getTime() + 60 * 1000 + 10 * 1000) / 1000).toString()
  );

  const marketOrder = await clobClient.createMarketBuyOrder({
    tokenID:
      "16678291189211314787145083999015737376658799626183230671758641503291735614088",
    amount: 100,
    feeRateBps: 0,
    nonce: 0,
    price: 0.5,
  });
  console.log("Created Order", order);

  // Send it to the server

  // FOK Order
  const resp = await clobClient.postOrder(order, OrderType.FOK);
  console.log(resp);
}

main();

## GTC Order
#
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY

## Create and sign a limit order buying 100 YES tokens for 0.50c each
order_args = OrderArgs(
    price=0.50,
    size=100.0,
    side=BUY,
    token_id="16678291189211314787145083999015737376658799626183230671758641503291735614088",
)
signed_order = client.create_order(order_args)

## GTC Order
resp = client.post_order(signed_order, OrderType.GTC)
print(resp)

## GTD Order
#
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY

## Create and sign a limit order buying 100 YES tokens for 0.50c each
order_args = OrderArgs(
    price=0.50,
    size=100.0,
    side=BUY,
    token_id="16678291189211314787145083999015737376658799626183230671758641503291735614088",
    expiration="100000000000"
)
signed_order = client.create_order(order_args)

## GTD Order
resp = client.post_order(signed_order, OrderType.GTD)
print(resp)

Request Payload Parameters

An Order object is of the form:

Order types:

• FOK: A 'Fill-Or-Kill' order is an market order to buy shares that must be executed immediately in its entirety; otherwise, the entire order will be cancelled.
• GTC: A 'Good-Til-Cancelled' order is a limit order that is active until it is fulfilled or cancelled.
• GTD: A 'Good-Til-Day' order is a type of order that is active until its specified date (UTC seconds timestamp), unless it has already been fulfilled or cancelled

Response Format

Insert Errors/Messages

If the errorMsg field of the response object from placement is not an empty string the order was not able to be immediately placed. This might be because of a delay or because of a failure. If the success is not true then there was an issue placing the order. The following errors/messages are possible.

Insert Statuses

When placing an order, a status field is included. This status field provides additional information regarding the order's state as a result of the placement. Possible values include:

Get Order

Get single order by id.

HTTP Request

GET {clob-endpoint}/order

async function main() {
  const order = await clobClient.getOrder(
    "0xb816482a5187a3d3db49cbaf6fe3ddf24f53e6c712b5a4bf5e01d0ec7b11dabc"
  );
  console.log(order);
}

main();

order = clob_client.get_order("0xb816482a5187a3d3db49cbaf6fe3ddf24f53e6c712b5a4bf5e01d0ec7b11dabc")
print(order)

Request Parameters

Response Format

An OpenOrder object is of the form:

Check if an order is scoring

Returns a boolean value where it is indicated if an order is scoring or not.

HTTP Request

GET {clob-endpoint}/order-scoring?order_id={...}

async function main() {
  const scoring = await clobClient.isOrderScoring({
    orderId: "0x...",
  });
  console.log(scoring);
}

main();

scoring = client.is_order_scoring(
    OrderScoringParams(
        orderId="0x..."
    )
)
print(scoring)

Request Parameters

Response Format

An OrderScoring object is of the form:

Check if some orders are scoring

Returns a a dictionary with boolean value where it is indicated if an order is scoring or not.

HTTP Request

GET {clob-endpoint}/ordesr-scoring?order_ids=[...]

async function main() {
  const scoring = await clobClient.areOrdersScoring({
    orderIds: ["0x..."],
  });
  console.log(scoring);
}

main();

scoring = client.are_orders_scoring(
    OrdersScoringParams(
        orderIds=["0x..."]
    )
)
print(scoring)

Request Parameters

Response Format

An OrdersScoring object is a dictionary that indicates order by order if it scores:

{
  "0x0": true,
  "0x1": false
}

Get Active Orders

Get active order(s) for a specific owner and market.

HTTP Request

GET {clob-endpoint}/orders

async function main() {
  const resp = await clobClient.getOpenOrders({
    market:
      "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
    owner: creds.key,
  });
  console.log(resp);
  console.log(`Done!`);
}

main();

from py_clob_client.clob_types import FilterParams

resp = client.get_orders(
    FilterParams(
        market="0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
    )
)
print(resp)
print("Done!")

Request Parameters

Response Format

Cancel an Order

Cancel an order.

HTTP Request

DELETE {clob-endpoint}/order

async function main() {
  // Send it to the server
  const resp = await clobClient.cancelOrder({
    orderID:
      "0x38a73eed1e6d177545e9ab027abddfb7e08dbe975fa777123b1752d203d6ac88",
  });
  console.log(resp);
  console.log(`Done!`);
}
main();

resp = client.cancel(order_id="0x38a73eed1e6d177545e9ab027abddfb7e08dbe975fa777123b1752d203d6ac88")
print(resp)

Request Payload Parameters

Response Format

Cancel orders

Cancel many orders.

HTTP Request

DELETE {clob-endpoint}/orders

async function main() {
  // Send it to the server
  const resp = await clobClient.cancelOrders([
    "0x38a73eed1e6d177545e9ab027abddfb7e08dbe975fa777123b1752d203d6ac88",
    "0xaaaa...",
  ]);
  console.log(resp);
  console.log(`Done!`);
}
main();

resp = client.cancel_orders(["0x38a73eed1e6d177545e9ab027abddfb7e08dbe975fa777123b1752d203d6ac88", "0xaaaa..."])
print(resp)

Request Payload Parameters

Response Format

Cancel All Orders

Cancel all open orders posted by a user.

HTTP Request

DELETE {clob-endpoint}/cancel-all

async function main() {
  const resp = await clobClient.cancelAll();
  console.log(resp);
  console.log(`Done!`);
}

main();

resp = client.cancel_all()
print(resp)
print("Done!")

Response Format

Cancel orders from market

Cancel orders from market.

HTTP Request

DELETE {clob-endpoint}/cancel-market-orders

async function main() {
  // Send it to the server
  const resp = await clobClient.cancelMarketOrders({
    market:
      "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
    asset_id:
      "1343197538147866997676250008839231694243646439454152539053893078719042421992",
  });
  console.log(resp);
  console.log(`Done!`);
}
main();

resp = client.cancel_market_orders(market="0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af", asset_id="1343197538147866997676250008839231694243646439454152539053893078719042421992")
print(resp)

Request Payload Parameters

Response Format

Trades

Overview

All historical trades can be fetched via the Polymarket CLOB REST API. A trade is initiated by a "taker" who creates a marketable limit order. This limit order can be matched against one or more resting limit orders on the associated book. A trade can be in various states as described below. Note in some cases (due to gas limitations) the execution of a "trade" must be broken into multiple transactions in which case separate trade entities will be returned. To make these trade entires associable, there is a bucket_index field, a market_order field and a match_time field. Trades that have been broken into multiple trade objects can be reconciled by combining trade objects with the same market_order, match_time and incrementing bucket_indexs into a top level "trade" client side.

Statuses

Get Trades

Get trades for the authenticated user based on the provided filters.

HTTP Request

GET {clob-endpoint}/trades

async function main() {
  const trades = await clobClient.getTrades({
    market:
      "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
    maker: await wallet.getAddress(),
    limit: 10,
  });
  console.log(`trades: `);
  console.log(trades);
}

main();

from py_clob_client.clob_types import FilterParams

resp = client.get_trades(
    FilterParams(
        limit=1,
        maker=client.get_address(),
        market="0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
    )
)
print(resp)
print("Done!")

Request Parameters

Response Format

A Trade object is of the form:

A MakerOrder object is of the form:

Markets

Get Markets

Get available CLOB markets (paginated).

HTTP Request

GET {clob-endpoint}/markets?next_cursor={next_cursor}

async function main() {
  const markets = await clobClient.getMarkets("");
  console.log(`markets: `);
  console.log(markets);
}

main();

resp = client.get_markets(next_cursor = "")
print(resp)
print("Done!")

Request Parameters

Response Format

A Market object is of the form:

Where the Token object is of the form:

Where the Rewards object is of the form:

Get Sampling Markets

Get available CLOB markets that have rewards enabled.

HTTP Request

GET {clob-endpoint}/sampling-markets?next_cursor={next_cursor}

async function main() {
  const markets = await clobClient.getSamplingMarkets("");
  console.log(`markets: `);
  console.log(markets);
}

main();

resp = client.get_sampling_markets(next_cursor = "")
print(resp)
print("Done!")

Response Format

Get Simplified Markets

Get available CLOB markets expresed in a reduced schema.

HTTP Request

GET {clob-endpoint}/simplified-markets?next_cursor={next_cursor}

async function main() {
  const markets = await clobClient.getSimplifiedMarkets("");
  console.log(`markets: `);
  console.log(markets);
}

main();

resp = client.get_simplified_markets(next_cursor = "")
print(resp)
print("Done!")

Response Format

A SimplifiedMarket object is of the form:

Get Sampling Simplified Markets

Get available CLOB markets expresed in a reduced schema that have rewards enabled.

HTTP Request

GET {clob-endpoint}/sampling-simplified-markets?next_cursor={next_cursor}

async function main() {
  const markets = await clobClient.getSamplingSimplifiedMarkets("");
  console.log(`markets: `);
  console.log(markets);
}

main();

resp = client.get_sampling_simplified_markets(next_cursor = "")
print(resp)
print("Done!")

Response Format

Get Market

Get a single CLOB market.

async function main() {
  const market = await clobClient.getMarket("condition_id");
  console.log(`market: `);
  console.log(market);
}

main();

resp = client.get_market(condition_id = "...")
print(resp)
print("Done!")

HTTP Request

GET {clob-endpoint}/markets/{condition_id}

Response Format

Prices and Books

Get Book

Get a level 2 order book summary for a market.

HTTP Request

GET {clob-endpoint}/book

async function main() {
  const resp = await clobClient.getOrderBook(
    "16678291189211314787145083999015737376658799626183230671758641503291735614088"
  );
  console.log(resp);
}
main();

print(
    client.get_order_book(
        "16678291189211314787145083999015737376658799626183230671758641503291735614088"
    )
)

Request Parameters

Response Format

A Level object is of the form:

Get Price

Get the price for a market (best bid or best ask).

HTTP Request

GET {clob-endpoint}/price

async function main() {
  const YES_TOKEN_ID =
    "16678291189211314787145083999015737376658799626183230671758641503291735614088";
  const NO_TOKEN_ID =
    "1343197538147866997676250008839231694243646439454152539053893078719042421992";

  clobClient
    .getPrice(YES_TOKEN_ID, "buy")
    .then((price: any) => console.log("YES", "BUY", price));
  clobClient
    .getPrice(YES_TOKEN_ID, "sell")
    .then((price: any) => console.log("YES", "SELL", price));
  clobClient
    .getPrice(NO_TOKEN_ID, "buy")
    .then((price: any) => console.log("NO", "BUY", price));
  clobClient
    .getPrice(NO_TOKEN_ID, "sell")
    .then((price: any) => console.log("NO", "SELL", price));
}
main();

print(
    client.get_price(
        token_id="16678291189211314787145083999015737376658799626183230671758641503291735614088", side="buy
    )
)

Request Payload Parameters

Response

{"price": ".513"}

Get Midpoint

Get the midpoint price for a market (halfway between best bid or best ask).

HTTP Request

GET {clob-endpoint}/midpoint

async function main() {
  const resp = client.getMidpoint(
    (tokenID =
      "16678291189211314787145083999015737376658799626183230671758641503291735614088")
  );
  console.log(resp);
}
main();

resp = client.get_midpoint(
    "16678291189211314787145083999015737376658799626183230671758641503291735614088"
)
print(resp)
print("Done!")

Request Payload Parameters

Response

{'mid': '0.55'}

Websocket API

Overview

The Polymarket CLOP API provides websocket (wss) channels through which clients can get pushed updates. These endpoints allow clients to maintain almost real-time views of their orders, their trades and markets in general. There are two available channels user and market.

Subscription

To subscribe send a message including the following authenticating and intent information upon opening the connection.

where the auth field is of type Auth which has the form described in the WSS Authentication section below.

WSS Authentication

User Channel

Authenticated channel for updates related to user activities (orders, trades), filtered for authenticated user (by apiKey).

SUBSCRIBE {wss-channel} user

trade Message

{
  "asset_id": "1343197538147866997676250008839231694243646439454152539053893078719042421992",
  "event_type": "trade",
  "id": "28c4d2eb-bbea-40e7-a9f0-b2fdb56b2c2e",
  "last_update": "1672290701",
  "maker_orders": [
    {
      "asset_id": "1343197538147866997676250008839231694243646439454152539053893078719042421992",
      "matched_amount": "10",
      "order_id": "0xff354cd7ca7539dfa9c28d90943ab5779a4eac34b9b37a757d7b32bdfb11790b",
      "outcome": "YES",
      "owner": "9180014b-33c8-9240-a14b-bdca11c0a465",
      "price": "0.57"
    }
  ],
  "market": "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
  "matchtime": "1672290701",
  "outcome": "YES",
  "owner": "9180014b-33c8-9240-a14b-bdca11c0a465",
  "price": "0.57",
  "side": "BUY",
  "size": "10",
  "status": "MATCHED",
  "taker_order_id": "0x06bc63e346ed4ceddce9efd6b3af37c8f8f440c92fe7da6b2d0f9e4ccbc50c42",
  "time": "1672290701",
  "trade_owner": "9180014b-33c8-9240-a14b-bdca11c0a465",
  "type": "TRADE"
}

Emitted when:

• when a market order is matched (”MATCHED”)
• when a limit order for a user is included in a trade (”MATCHED”)
• subsequent status changes for trade (”MINED”, “CONFIRMED”, “RETRYING”, “FAILED”)

Structure:

Where a MakerOrder object is of the form:

order Message

{
  "asset_id": "1343197538147866997676250008839231694243646439454152539053893078719042421992",
  "associate_trades": null,
  "event_type": "order",
  "id": "0xff354cd7ca7539dfa9c28d90943ab5779a4eac34b9b37a757d7b32bdfb11790b",
  "market": "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
  "order_owner": "9180014b-33c8-9240-a14b-bdca11c0a465",
  "original_size": "10",
  "outcome": "YES",
  "owner": "9180014b-33c8-9240-a14b-bdca11c0a465",
  "price": "0.57",
  "side": "SELL",
  "size_matched": "0",
  "time": "1672290687",
  "type": "PLACEMENT"
}

Emitted when:

• When an order is placed (PLACEMENT)
• When an order is updated (some of it is matched) (UPDATE)
• When an order is cancelled (CANCELLATION)

Structure:

Market Channel

Public channel for updates related to market updates (level 2 price data).

SUBSCRIBE {wss-channel} market

book Message

{
  "event_type": "book",
  "asset_id": "65818619657568813474341868652308942079804919287380422192892211131408793125422",
  "market": "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
  "buys": [
    { "price": ".48", "size": "30" },
    { "price": ".49", "size": "20" },
    { "price": ".50", "size": "15" }
  ],
  "sells": [
    { "price": ".52", "size": "25" },
    { "price": ".53", "size": "60" },
    { "price": ".54", "size": "10" }
  ]
}

Emitted When:

• First subscribed to market/
• When there is a trade that affects the book

Structure:

Where a OrderSummary object is of the form:

price_change Message

{
"event_type": "price_change",
"asset_id": "65818619657568813474341868652308942079804919287380422192892211131408793125422",\
"market": "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
"price": "0.51",
"size": "10.0",
"side": "buy",
"time": "1666716712",
}

Emitted When:

• A new order is placed
• An order is cancelled

Structure:

Subgraph

Overview

Polymarket has written and open sourced a subgraph that provides, via a GraphQL query interface, useful aggregate calculations and event indexing for things like trade, volume, user position, market and liquidity data. The subgraph updates in real time as blocks are mined, and is reorg-aware. The subgraph underlies the primary Polymarket.com interface, providing positional data, activity history and more. The subgraph can be hosted by anyone but is also hosted and made publicly available by a 3rd party provider, Goldsky.

Source

The Polymaket subgraph is entirely open source and can be found on the Polymarket Github.

Polymarket/polymarket-subgraph

Note: The available models/schemas can be found in the schema.graphql file.

Hosted Version

The hosted version and accompany GraphQL playground can be found at:

[POLYGON] https://api.goldsky.io/c/polymarket/gn/subgraphs/name/2f21c18c

[MUMBAI] https://api.goldsky.io/c/polymarket/gn/subgraphs/name/master-mumbai

Resolution

All market resolution is completely decentralized. A majority of markets on Polymarket are resolved via UMA's optimistic oracle, the rest (some price markets) are resoled via Pyth.

UMA

Overview

Polymarket leverages UMA's Optimistic Oracle (OO) to resolve arbitrary questions, permissionlessly. From UMA's docs:

"UMA's Optimistic Oracle allows contracts to quickly request and receive data information. The Optimistic Oracle acts as a generalized escalation game between contracts that initiate a price request and UMA's dispute resolution system known as the Data Verification Mechanism (DVM). Prices proposed by the Optimistic Oracle will not be sent to the DVM unless it is disputed. If a dispute is raised, a request is sent to the DVM. All contracts built on UMA use the DVM as a backstop to resolve disputes. Disputes sent to the DVM will be resolved within a few days - after UMA tokenholders vote on what the correct outcome should have been."

To allow CTF markets to be resolved via the OO, Polymarket developed a custom adapter contract called UmaCtfAdapter that provides a way for the two contract systems to interface.

Clarifications

Recent versions (v2+) of the UmaCtfAdapter also include a bulletin board feature that allows market creators to issue "clarifications". Questions that allow updates will include the sentence in their ancillary data:

"Updates made by the question creator via the bulletin board at 0x6A9D222616C90FcA5754cd1333cFD9b7fb6a4F74 as described by https://polygonscan.com/tx/0xa14f01b115c4913624fc3f508f960f4dea252758e73c28f5f07f8e19d7bca066 should be considered”

Where the transaction referenced includes a message outlining what should and shouldn't be considered. In summary, only clarifications that do not impact the question's intent should be considered.

Resolution Process

Actions:

• Initialize - Binary CTF markets are initialized via the UmaCtfAdapter's initialize() function. This stores the question parameters on the contract, prepares the question on the CTF and requests a price for a question from the OO. It returns a CTF questionID that is also used as reference on the UmaCtfAdapter. The caller provides:
  1. ancillaryData - data used to resolve a question (ie the question + description)
  2. rewardToken - ERC20 token address used for payment of rewards and fees
  3. reward - Reward amount offered to a successful proposer. The caller must have set allowance so that the contract can pull this reward in.
  4. proposalBond - Bond required to be posted by OO proposers/disputers. If 0, the default OO bond is used.
  5. liveness - UMA liveness period in seconds. If 0, the default liveness period is used.
• Propose Price - Anyone can then propose a price to the question on the OO. To do this they must post the proposalBond. The liveness period begins after a price is proposed.
• Dispute - Anyone that disagrees with the proposed price has the opportunity to dispute the price by posting a counter bond via the OO, this price proposal will now be escalated to the DVM for a voter-wide vote.

Possible Flows:

When the first proposed price is disputed for a questionId on the adapter, a callback is made that resets the questionId, making a new request to the OO (the reward is returned before the callback is made and posted as the reward for this new proposal). This means a second proposal is required for a questionId to resolve, and correspondingly a second dispute is required for it to go to the DVM. The thinking behind here is it doubles the cost of a potential griefing vector (two disputes are required versus just one) and also allows fat-fingered (incorrect) first price proposals to not delay resolution. As such we have the following possible resolution flows:

• Initialize (CTFAdaptor) -> Propose (OO) -> Resolve (CTFAdaptor)
• Initialize (CTFAdaptor) -> Propose (OO) -> Challenge (OO) -> Propose (OO) -> Resolve (CTFAdaptor)
• Initialize (CTFAdaptor) -> Propose (OO) -> Challenge (OO) -> Propose (OO) -> Challenge (CtfAdapter) -> Resolve (CTFAdaptor)

Deployed Addresses

v3.0.0

v2.0.0

v1.0.0

Additional Resources

• Audit
• Source Code
• UMA Documentation
• UMA Oracle Portal

Pyth

Coming soon

Rewards

Polymarket provides incentives aimed at catalyzing the supply and demand side of the marketplace. Specifically there is a public liquidity rewards program as well as one-ff public pnl/volume competitions.

Liquidity Rewards Program

Overview

By posting resting limit orders, liquidity providers (makers) are automatically eligible for Polymarket's incentive program. The overall goal of this program is to catalyze a healthy, liquid marketplace. We can further define this as creating incentives that:

• Catalyze liquidity across all markets
• Encourage liquidity throughout a market’s entire lifecycle
• Motivate passive, balanced quoting tight to a market’s mid point
• Encourages trading activity
• Discourages blatantly exploitative behaviors

This program is heavily inspired by dYdX's liquidity provider rewards which you can read more about here. In fact, the incentive methodology is essentially a copy of dYdX’s successful methodology but with some adjustments including specific adaptations for binary contract markets with distinct books, no staking mechanic a slightly modified order utility-relative to depth function and reward amounts isolated per market. Rewards are distributed directly to maker's addresses weekly (for the latest ended epoch) on Fridays at midnight ET.

Methodology

Polymarket liquidity providers will be rewarded based on a formula that rewards participation in markets (complementary consideration), boosts two-sided depth (single-sided orders still score), and spread (vs. mid-market, adjusted for the size cutoff*). Each market will configure a max spread and min size cutoff within which orders are considered. The amount of rewards earned is determined by the relative share of each participant’s $Q_{epoch}$ in each market multiplied by the rewards available for that market.

Equation 1:

$$S(v,s)= (\frac{v-s}{v})^2 \cdot b$$

Equation 2:

$$Q_{one}= S(v,Spread_{m_1}) \cdot BidSize_{m_1} + S(v,Spread_{m_2}) \cdot BidSize_{m_2} + \dots $$ $$ + S(v, Spread_{m^\prime_1}) \cdot AskSize_{m^\prime_1} + S(v, Spread_{m^\prime_2}) \cdot AskSize_{m^\prime_2}$$

Equation 3:

$$Q_{two}= S(v,Spread_{m_1}) \cdot AskSize_{m_1} + S(v,Spread_{m_2}) \cdot AskSize_{m_2} + \dots $$ $$ + S(v, Spread_{m^\prime_1}) \cdot BidSize_{m^\prime_1} + S(v, Spread_{m^\prime_2}) \cdot BidSize_{m^\prime_2}$$

Equation 4:

Equation 4a:

If midpoint is in range [0.10,0.90] allow single sided liq to score:

$$Q_{\min} = \max(\min({Q_{one}, Q_{two}}), \max(Q_{one}/c, Q_{two}/c))$$

Equation 4b:

If midpoint is in either range [0,0.10) or (.90,1.0] require liq to be double sided to score:

$$Q_{\min} = \min({Q_{one}, Q_{two}})$$

Equation 5:

$$Q_{normal} = \frac{Q_{min}}{\sum_{n=1}^{N}{(Q_{min})_n}}$$

Equation 6:

$$Q_{epoch} = \sum_{u=1}^{10,080}{(Q_{normal})_u}$$

Equation 7:

$$Q_{final}=\frac{Q_{epoch}}{\sum_{n=1}^{N}{(Q_{epoch})_n}}$$

* The adjusted midpoint is a size-cutoff adjusted interpretation of a traditional midpoint ((best_bid+best_ask)/2) which is calculated using the equation (best_bid_min_shares_adjusted + best_ask_min_shares_adjusted)/2 where the best_bid_min_shares_adjusted is the price level at which the cumulative size of open bids, at or better than that level is greater than or equal to the min shares requirement and the best_ask_min_shares_adjusted is the price level at which the cumulative size of open asks, at or better than that level is greater than or equal to the min shares requirement.

Market Configurations

Both min_incentive_size and max_incentive_spread can be fetched alongside full market objects cia both the CLOB API and Markets API. Reward allocations for an epoch can be fetched via the Markets API.

Leaderboard Competitions

coming soon

Conditional Tokens Framework

Overview

All outcomes on Polymarket are tokenized on the Polygon network. Specifically, Polymarket outcome shares are binary outcomes (ie “YES” and “NO”) represented using Gnosis’ Conditional Token Framework (CTF). They are distinct ERC1155 tokens related to a parent condition and backed by some collateral. More technically, the binary outcome tokens are referred to as “positionIds” in Gnosis’s documentation. “PositionIds” are derived from a collateral token and distinct “collectionIds”. “CollectionIds” are derived from a “parentCollectionId”, (always bytes32(0) in our case) a “conditionId”, and a unique “indexSet”. The “indexSet” is a 256 bit array denoting which outcome slots are in an outcome collection; it must be a nonempty proper subset of a condition’s outcome slots. In the binary case, which we are interested in, there are two “indexSets”, one for the first outcome and one for the second. The first outcome’s “indexSet” is 0b01 == 1 and the second’s is 0b10 == 2. The parent “conditionId” (shared by both “collectionIds” and therefore “positionIds”) is derived from a “questionId” (a hash of the UMA ancillary data), an “oracle” address (the UMA adapter V2) and an “outcomeSlotCount” (always 2 in the binary case). The steps for calculating the ERC1155 token ids (positionIds) is as follows:

1. Get the conditionId
   1. Function:
      1. getConditionId(oracle, questionId, outcomeSlotCount)
   2. Inputs:
      1. oracle: address - UMA adapter V2
      2. questionId: bytes32 - hash of the UMA ancillary data
      3. outcomeSlotCount: uint - 2 for binary markets
2. Get the two collectionIds
   1. Function:
      1. getCollectionId(parentCollectionId, conditionId, indexSet)
   2. Inputs:
      1. parentCollectionId: bytes32 - bytes32(0)
      2. conditionId: bytes32 - the conditionId derived from (1)
      3. indexSet: uint - 1 (0b01) for the first and 2 (0b10) for the second.
3. Get the two positionIds
   1. Function:
      1. getPositionId(collateralToken, collectionId)
   2. Inputs:
      1. collateralToken: IERC20 - address of ERC20 token collateral (USDC)
      2. collectionId: bytes32 - the two collectionIds derived from (3)

Leveraging the relations above, specifically “conditionIds” → “positionIds” the Gnosis CTF contract allows for “splitting” and “merging” full outcome sets. We explore these actions and provide code examples below.

Split

At any time, after a condition has been prepared on the CTF contract (via prepareCondition), it is possible to "split" collateral into a full (position) set. In other words, one unit USDC can be split into 1 YES unit and 1 NO unit. If splitting from the collateral, the CTF contract will attempt to transfer amount collateral from the message sender to itself. If successful, amount stake will be minted in the split target positions. If any of the transfers, mints, or burns fail, the transaction will revert. The transaction will also revert if the given partition is trivial, invalid, or refers to more slots than the condition is prepared with. This operation happens via the splitPosition() function on the CTF contract with the following parameters:

• collateralToken: IERC20 - The address of the positions' backing collateral token.
• parentCollectionId: bytes32 - The ID of the outcome collections common to the position being split and the split target positions. Null in Polymarket case.
• conditionId: bytes32 - The ID of the condition to split on.
• partition: uint[] - An array of disjoint index sets representing a nontrivial partition of the outcome slots of the given condition. E.g. A|B and C but not A|B and B|C (is not disjoint). Each element's a number which, together with the condition, represents the outcome collection. E.g. 0b110 is A|B, 0b010 is B, etc. In the Polymarket case 1,2.
• amount - The amount of collateral or stake to split. Also the number of full sets to receive.

Merge

In addition to splitting collateral for a full set, the inverse can also happen; a full set can be "merged" for collateral. This operation can again happen at any time after a condition has been prepared on the CTF contract. One unit of each position in a full set is burned in return for 1 collateral unit. This operation happens via the mergePosition() function on the CTF contract with the following parameters:

• collateralToken: IERC20 - The address of the positions' backing collateral token.
• parentCollectionId: bytes32 - The ID of the outcome collections common to the position being merged and the merge target positions. Null in Polymarket case.
• conditionId: bytes32 - The ID of the condition to merge on.
• partition: uint[] - An array of disjoint index sets representing a nontrivial partition of the outcome slots of the given condition. E.g. A|B and C but not A|B and B|C (is not disjoint). Each element's a number which, together with the condition, represents the outcome collection. E.g. 0b110 is A|B, 0b010 is B, etc. In the Polymarket case 1,2.
• amount - The number of full sets to merge. Also the amount of collateral to receive.

Redeem

One a condition has had it's payouts reported (ie by the UmaCTFAdapter calling reportPayouts on the CTF contract), users with shares in the winning outcome can redeem them for the underlying collateral. Specifically, users can call the redeemPositions function on the CTF contract which will burn all valuable conditional tokens in return for collateral according to the reported payout vector. This function has the following parameters:

• collateralToken: IERC20 - The address of the positions' backing collateral token.
• parentCollectionId: bytes32 - The ID of the outcome collections common to the position being redeemed. Null in Polymarket case.
• conditionId: bytes32 - The ID of the condition to redeem.
• indexSets: uint[] - An array of disjoint index sets representing a nontrivial partition of the outcome slots of the given condition. E.g. A|B and C but not A|B and B|C (is not disjoint). Each element's a number which, together with the condition, represents the outcome collection. E.g. 0b110 is A|B, 0b010 is B, etc. In the Polymarket case 1,2.

Deployment

The CTF contract is deployed (and verified) at the following addresses:

Resources

• Source Code
• Audits
• Gnosis CTF Technical Documentation
• Gist For positionId Calculation

FPMMs

Overview

Underlying all markets, and providing for an alternative trading mechanism to the central limit order book (CLOB) are fixed product market makers (FPMMs). These FPMMs are deployed upon market creation using a factory contract. As such, each market has a unique FPMM deployment/address. The addresses and associations of these deployments are indexed in the subgraph and made available via the Gamma API. The contracts themselves are also self-descriptive. As the name suggests, FPMMs implement a fixed (ie "constant") product scoring rule wherein the product of the tokens in the pool (ie the liquidity) is held constant. By maintaining this invariant, the price of a trade is calculated. Importantly, the tokens in the pool are outcome shares. Anyone can provide liquidity to the contract, and in return get ERC20 tokens representing their share of the liquidity pool. When users trade against the pool they pay a configured fee, in collateral, which is reserved proportionally for liquidity providers. When a trader buys shares from a pool, their collateral is split into the underlying conditional tokens, the token they are buying is kept and the rest are sold to the pool for more of the token they are buying. When selling, the user is actually trading the token for equal amounts of the other tokens in the pool (in the binary case just one other outcome token) and then the full sets are merged for collateral. The source implementation of the fixed product was developed by Gnosis.

Add Liquidity

Liquidity providers can provide liquidity to the pool in the form of collateral via addFunding(). The function has the following parameters:

• addedFunds: uint - The amount of collateral to add to the pool in return for tokens representing their share of the pool and fees.
• distributionHint: uint[] - Array indicating the ratios of outcome tokens for initial liquidity. This can only be provided by the first liquidity provider in the pool. [1,1] in the 50/50 starting case.

Note: this is not front-run protected so should be used with a contract that enforces some protection against front running.

Remove Liquidity

At any time, liquidity providers can remove liquidity from a pool they are providing to via removeFunding() with the parameter:

• sharesToBurn: uint - The number of liquidity shares to burn. The underlying conditional tokens are returned to the liquidity provider along with any earned fees (in collateral).

Buy

Traders can buy outcome tokens from the pool via the buy() function with the following parameters:

• investmentAmount: uint - The amount of collateral to spend.
• outcomeIndex: uint - The index of the outcome to purchase.
• minOutcomeTokensToBuy: unit - The minimum amount of tokens you expect to receive.

Sell

Traders can sell outcome tokens to the pool via the sell() function with the following parameters:

• returnAmount: uint - The amount of collateral to get back.
• outcomeIndex: uint - The index of the outcome to sell.
• maxOutcomeTokensToSell: uint - The maximum number of outcome tokens to sell to get the returnAmount of collateral.

Deployments

FPMM Factory Deployments

Resources

• Source Code
• Audit

Proxy Wallets

Overview

When a user first uses Polymarket.com to trade they are prompted to create a wallet. When they do this, a 1 of 1 multisig is deployed to Polygon which is controlled/owned by the accessing EOA (either MetaMask wallet or MagicLink wallet). This proxy wallet is where all the user's positions (ERC1155) and USDC (ERC20) are held. Using proxy wallets allows Polymarket to provide an improved UX where multi-step transactions can be executed atomically and transactions can be relayed by relayers on the gas station network. If you are a developer looking to programmatically access positions you accumulated via the Polymarket.com interface, you can either continue using the smart contract wallet by executing transactions through it from the owner account, or you can transfer these assets to a new address using the owner account.

Deployments

Each user has their own proxy wallet (and thus proxy wallet address) but the factories are available at the following deployed addresses on the Polygon network.