gavindiaz/PolymarketDocumentation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Polymarket documentation (2026-02-19)

Browse Source 
- Added new documentation URLs from llms.txt index
- Updated TARGET.md with 244 total documentation pages
- Scraped new pages for trading, concepts, and API reference sections
- Updated changelog and new index pages
This commit is contained in:
AI Agent
2026-02-19 14:31:02 +01:00
parent 81f77eff3c
commit b2a29fe51f
250 changed files with 33306 additions and 9659 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/quickstart/first-order.md
+170 -245
View File
@@ -2,301 +2,226 @@
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Placing Your First Order
# Quickstart
> Set up authentication and submit your first trade
> Place your first order on Polymarket
This guide walks you through placing an order on Polymarket using your own wallet.
This guide walks you through placing an order on Polymarket end-to-end.
***
<Steps>
<Step title="Install the SDK">
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client ethers@5
```
## Installation
```bash Python theme={null}
pip install py-clob-client
```
</CodeGroup>
</Step>
<CodeGroup>
```bash TypeScript theme={null}
npm install @polymarket/clob-client ethers@5
```
<Step title="Set Up Your Client">
Derive your API credentials and initialize the trading client. This example uses an EOA wallet (type `0`) — your wallet pays its own gas and acts as the funder:
```bash Python theme={null}
pip install py-clob-client
```
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers"; // v5.8.0
```bash Rust theme={null}
cargo add polymarket-client-sdk
```
</CodeGroup>
const HOST = "https://clob.polymarket.com";
const CHAIN_ID = 137; // Polygon mainnet
const signer = new Wallet(process.env.PRIVATE_KEY);
***
// Derive API credentials
const tempClient = new ClobClient(HOST, CHAIN_ID, signer);
const apiCreds = await tempClient.createOrDeriveApiKey();
## Step 1: Initialize Client with Private Key
// Initialize trading client
const client = new ClobClient(
HOST,
CHAIN_ID,
signer,
apiCreds,
0, // EOA
signer.address,
);
```
<CodeGroup>
```typescript TypeScript theme={null}
import { ClobClient } from "@polymarket/clob-client";
import { Wallet } from "ethers"; // v5.8.0
```python Python theme={null}
from py_clob_client.client import ClobClient
import os
const HOST = "https://clob.polymarket.com";
const CHAIN_ID = 137; // Polygon mainnet
const signer = new Wallet(process.env.PRIVATE_KEY);
host = "https://clob.polymarket.com"
chain_id = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
const client = new ClobClient(HOST, CHAIN_ID, signer);
```
# Derive API credentials
temp_client = ClobClient(host, key=private_key, chain_id=chain_id)
api_creds = temp_client.create_or_derive_api_creds()
```python Python theme={null}
from py_clob_client.client import ClobClient
import os
# Initialize trading client
client = ClobClient(
host,
key=private_key,
chain_id=chain_id,
creds=api_creds,
signature_type=0, # EOA
funder="YOUR_WALLET_ADDRESS"
)
```
</CodeGroup>
host = "https://clob.polymarket.com"
chain_id = 137 # Polygon mainnet
private_key = os.getenv("PRIVATE_KEY")
<Note>
If you have a Polymarket.com account, your funds are in a proxy wallet — use
signature type `1` or `2` instead. See [Signature
Types](/trading/overview#signature-types) for details.
</Note>
client = ClobClient(host, key=private_key, chain_id=chain_id)
```
</CodeGroup>
<Warning>
Before trading, your funder address needs **USDC.e** (for buying outcome
tokens) and **POL** (for gas, if using EOA type `0`). Proxy wallet users
(types `1` and `2`) can use Polymarket's gasless relayer instead.
</Warning>
</Step>
***
<Step title="Place an Order">
Get a token ID from the [Markets API](/market-data/fetching-markets), then create and submit your order:
## Step 2: Derive User API Credentials
<CodeGroup>
```typescript TypeScript theme={null}
import { Side, OrderType } from "@polymarket/clob-client";
Your private key is used once to derive API credentials. These credentials authenticate all subsequent requests.
const response = await client.createAndPostOrder(
{
tokenID: "YOUR_TOKEN_ID",
price: 0.5,
size: 10,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false, // Set to true for multi-outcome markets
},
OrderType.GTC,
);
<CodeGroup>
```typescript TypeScript theme={null}
// Get existing API key, or create one if none exists
const userApiCreds = await client.createOrDeriveApiKey();
console.log("Order ID:", response.orderID);
console.log("Status:", response.status);
```
console.log("API Key:", userApiCreds.apiKey);
console.log("Secret:", userApiCreds.secret);
console.log("Passphrase:", userApiCreds.passphrase);
```
```python Python theme={null}
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY
```python Python theme={null}
# Get existing API key, or create one if none exists
user_api_creds = client.create_or_derive_api_creds()
response = client.create_and_post_order(
OrderArgs(
token_id="YOUR_TOKEN_ID",
price=0.50,
size=10,
side=BUY,
),
options={
"tick_size": "0.01",
"neg_risk": False, # Set to True for multi-outcome markets
},
order_type=OrderType.GTC
)
print("API Key:", user_api_creds["apiKey"])
print("Secret:", user_api_creds["secret"])
print("Passphrase:", user_api_creds["passphrase"])
```
</CodeGroup>
print("Order ID:", response["orderID"])
print("Status:", response["status"])
```
</CodeGroup>
***
<Tip>
Look up a market's `tickSize` and `negRisk` values using the SDK's
`getTickSize()` and `getNegRisk()` methods, or from the market object returned
by the API.
</Tip>
</Step>
## Step 3: Configure Signature Type and Funder
<Step title="Check Your Orders">
<CodeGroup>
```typescript TypeScript theme={null}
// View all open orders
const openOrders = await client.getOpenOrders();
console.log(`You have ${openOrders.length} open orders`);
Before reinitializing the client, determine your **signature type** and **funder address**:
// View your trade history
const trades = await client.getTrades();
console.log(`You've made ${trades.length} trades`);
| How do you want to trade? | Type | Value | Funder Address |
| ----------------------------------------------------------------------------------------- | ------------ | ----- | ------------------------- |
| I want to use an EOA wallet. It holds USDCe and position tokens, and I'll pay my own gas. | EOA | `0` | Your EOA wallet address |
| I want to trade through my Polymarket.com account (Magic Link email/Google login). | POLY\_PROXY | `1` | Your proxy wallet address |
| I want to trade through my Polymarket.com account (browser wallet connection). | GNOSIS\_SAFE | `2` | Your proxy wallet address |
// Cancel an order
await client.cancelOrder(response.orderID);
```
<Note>
If you have a Polymarket.com account, your funds are in a proxy wallet (visible in the profile dropdown). Use type 1 or 2. Type 0 is for standalone EOA wallets only.
</Note>
```python Python theme={null}
# View all open orders
open_orders = client.get_orders()
print(f"You have {len(open_orders)} open orders")
***
# View your trade history
trades = client.get_trades()
print(f"You've made {len(trades)} trades")
## Step 4: Reinitialize with Full Authentication
<CodeGroup>
```typescript TypeScript theme={null}
// Choose based on your wallet type (see table above)
const SIGNATURE_TYPE = 0; // EOA example
const FUNDER_ADDRESS = signer.address; // For EOA, funder is your wallet
const client = new ClobClient(
HOST,
CHAIN_ID,
signer,
userApiCreds,
SIGNATURE_TYPE,
FUNDER_ADDRESS
);
```
```python Python theme={null}
# Choose based on your wallet type (see table above)
signature_type = 0 # EOA example
funder_address = "YOUR_WALLET_ADDRESS" # For EOA, funder is your wallet
client = ClobClient(
host,
key=private_key,
chain_id=chain_id,
creds=user_api_creds,
signature_type=signature_type,
funder=funder_address
)
```
</CodeGroup>
<Warning>
**Do not use Builder API credentials in place of User API credentials!** Builder credentials are for order attribution, not user authentication. See [Builder Order Attribution](/developers/builders/order-attribution).
</Warning>
***
## Step 5: Place an Order
Now you're ready to trade! First, get a token ID from the [Gamma API](/developers/gamma-markets-api/get-markets).
<CodeGroup>
```typescript TypeScript theme={null}
import { Side, OrderType } from "@polymarket/clob-client";
// Get market info first
const market = await client.getMarket("TOKEN_ID");
const response = await client.createAndPostOrder(
{
tokenID: "TOKEN_ID",
price: 0.50, // Price per share ($0.50)
size: 10, // Number of shares
side: Side.BUY, // BUY or SELL
},
{
tickSize: market.tickSize,
negRisk: market.negRisk, // true for multi-outcome events
},
OrderType.GTC // Good-Til-Cancelled
);
console.log("Order ID:", response.orderID);
console.log("Status:", response.status);
```
```python Python theme={null}
from py_clob_client.clob_types import OrderArgs, OrderType
from py_clob_client.order_builder.constants import BUY
# Get market info first
market = client.get_market("TOKEN_ID")
response = client.create_and_post_order(
OrderArgs(
token_id="TOKEN_ID",
price=0.50, # Price per share ($0.50)
size=10, # Number of shares
side=BUY, # BUY or SELL
),
options={
"tick_size": market["tickSize"],
"neg_risk": market["negRisk"], # True for multi-outcome events
},
order_type=OrderType.GTC # Good-Til-Cancelled
)
print("Order ID:", response["orderID"])
print("Status:", response["status"])
```
</CodeGroup>
***
## Step 6: Check Your Orders
<CodeGroup>
```typescript TypeScript theme={null}
// View all open orders
const openOrders = await client.getOpenOrders();
console.log(`You have ${openOrders.length} open orders`);
// View your trade history
const trades = await client.getTrades();
console.log(`You've made ${trades.length} trades`);
// Cancel an order
await client.cancelOrder(response.orderID);
```
```python Python theme={null}
# View all open orders
open_orders = trading_client.get_open_orders()
print(f"You have {len(open_orders)} open orders")
# View your trade history
trades = trading_client.get_trades()
print(f"You've made {len(trades)} trades")
# Cancel an order
trading_client.cancel_order(response["orderID"])
```
</CodeGroup>
# Cancel an order
client.cancel(order_id=response["orderID"])
```
</CodeGroup>
</Step>
</Steps>
***
## Troubleshooting
<AccordionGroup>
<Accordion title="Invalid Signature / L2 Auth Not Available">
Wrong private key, signature type, or funder address for the derived User API credentials.
<Accordion title="L2_AUTH_NOT_AVAILABLE / Invalid Signature">
Wrong private key, signature type, or funder address for the derived API credentials.
Double check the following values when creating User API credentials via `createOrDeriveApiKey()`:
* Do not use Builder API credentials in place of User API credentials
* Check `signatureType` matches your account type (0, 1, or 2)
* Check that `signatureType` matches your account type (`0`, `1`, or `2`)
* Ensure `funder` is correct for your wallet type
* Re-derive credentials with `createOrDeriveApiKey()` if unsure
</Accordion>
<Accordion title="Unauthorized / Invalid API Key">
Wrong API key, secret, or passphrase.
<Accordion title="Order rejected: insufficient balance">
Your funder address doesn't have enough tokens:
Re-derive credentials with `createOrDeriveApiKey()` and update your config.
* **BUY orders**: need USDC.e in your funder address
* **SELL orders**: need outcome tokens in your funder address
* Ensure you have more USDC.e than what's committed in open orders
</Accordion>
<Accordion title="Not Enough Balance / Allowance">
Either not enough USDCe / position tokens in your funder address, or you lack approvals to spend your tokens.
<Accordion title="Order rejected: insufficient allowance">
You need to approve the Exchange contract to spend your tokens. This is
typically done through the Polymarket UI on your first trade, or using the CTF
contract's `setApprovalForAll()` method.
</Accordion>
* Deposit USDCe to your funder address.
* Ensure you have more USDCe than what's committed in open orders.
* Check that you've set all necessary token approvals.
<Accordion title="What's my funder address?">
Your funder address is the wallet where your funds are held:
* **EOA (type 0)**: Your wallet address directly
* **Proxy wallet (type 1 or 2)**: Go to [polymarket.com/settings](https://polymarket.com/settings) and look for the wallet address in the profile dropdown
If the proxy wallet doesn't exist, log into Polymarket.com first (it's deployed on first login).
</Accordion>
<Accordion title="Blocked by Cloudflare / Geoblock">
You're trying to place a trade from a restricted region.
See [Geographic Restrictions](/developers/CLOB/geoblock) for details.
You're trying to place a trade from a restricted region. See [Geographic Restrictions](/api-reference/geoblock) for details.
</Accordion>
</AccordionGroup>
***
## Adding Builder API Credentials
## Next Steps
If you're building an app that routes orders for your users, you can add builder credentials to get attribution on the [Builder Leaderboard](https://builders.polymarket.com/):
<CardGroup cols={2}>
<Card title="Create Orders" icon="plus" href="/trading/orders/create">
Order types, tick sizes, and error handling
</Card>
```typescript TypeScript theme={null}
import { BuilderConfig, BuilderApiKeyCreds } from "@polymarket/builder-signing-sdk";
const builderCreds: BuilderApiKeyCreds = {
key: process.env.POLY_BUILDER_API_KEY!,
secret: process.env.POLY_BUILDER_SECRET!,
passphrase: process.env.POLY_BUILDER_PASSPHRASE!,
};
const builderConfig = new BuilderConfig({ localBuilderCreds: builderCreds });
// Add builderConfig as the last parameter
const client = new ClobClient(
HOST,
CHAIN_ID,
signer,
userApiCreds,
signatureType,
funderAddress,
undefined,
false,
builderConfig
);
```
<Info>
Builder credentials are **separate** from user credentials. You use your builder
credentials to tag orders, but each user still needs their own L2 credentials to trade.
</Info>
<Card title="Full Builder Guide" icon="hammer" href="/developers/builders/order-attribution">
Complete documentation for order attribution and gasless transactions
</Card>
<Card title="Order Attribution" icon="tag" href="/trading/orders/attribution">
Attribute orders to your builder account for volume credit
</Card>
</CardGroup>