Trading and Fees - PolyNode

The SDK trading modules provide a common workflow for wallet setup, CLOB credentials, approvals, order placement, cancellation, and position operations. Polymarket V2 is the default in every current PolyNode SDK.

Trading methods sign messages and can place orders or submit on-chain transactions. Start with a dedicated test wallet, confirm the token ID, price, size, and funder address, and never commit private keys or CLOB credentials.

Install

npm install polynode-sdk@^0.12.2 viem better-sqlite3 \
  @polymarket/clob-client \
  @polymarket/builder-relayer-client \
  @polymarket/builder-signing-sdk

python -m pip install "polynode[trading]>=0.12.2,<0.13"

[dependencies]
polynode = { version = "0.15.2", features = ["trading"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Store credentials outside source control:

export POLYNODE_API_KEY="pn_live_..."
export POLYGON_PRIVATE_KEY="0x..."

Current V2 behavior

You do not need to opt into V2. These are the defaults:

SDK	Default
TypeScript	`exchangeVersion: 'v2'`
Python	`ExchangeVersion.V2`
Rust	`ExchangeVersion::V2`

V2 uses PolyUSD collateral and applies Polymarket protocol fees when an eligible taker order matches. V2 signed orders do not include the legacy feeRateBps, nonce, or taker fields. The SDK omits those fields from the V2 signature and wire payload. The explicit V1 compatibility mode is different: its signed order includes the market fee rate. When V1 is selected, the SDK fetches the current fee and refuses to sign if fee, tick-size, or negative-risk metadata cannot be resolved safely.

Do not copy V1 fields into a V2 order. If you do not have a deliberate legacy requirement, keep the V2 default.

Set up a wallet

ensureReady / ensure_ready is idempotent. It discovers the wallet type, creates or loads CLOB credentials, and completes required setup. For a new wallet it can deploy contracts or submit approvals, so treat it as a state-changing operation.

import { PolyNodeTrader } from 'polynode-sdk';

const trader = new PolyNodeTrader({
  polynodeKey: process.env.POLYNODE_API_KEY!,
  exchangeVersion: 'v2', // Optional: V2 is already the default
});

const ready = await trader.ensureReady(process.env.POLYGON_PRIVATE_KEY!);
console.log({
  wallet: ready.wallet,
  funderAddress: ready.funderAddress,
  approvalsSet: ready.approvalsSet,
});

import os
from polynode.trading import ExchangeVersion, PolyNodeTrader, TraderConfig

trader = PolyNodeTrader(TraderConfig(
    polynode_key=os.environ["POLYNODE_API_KEY"],
    exchange_version=ExchangeVersion.V2,  # Optional: already the default
))

ready = await trader.ensure_ready(os.environ["POLYGON_PRIVATE_KEY"])
print({
    "wallet": ready.wallet,
    "funder_address": ready.funder_address,
    "approvals_set": ready.approvals_set,
})

use polynode::trading::{
    ExchangeVersion, PolyNodeTrader, PrivateKeySigner, TraderConfig,
};

let mut trader = PolyNodeTrader::new(TraderConfig {
    polynode_key: std::env::var("POLYNODE_API_KEY")?,
    exchange_version: ExchangeVersion::V2, // Optional: already the default
    ..Default::default()
})?;

let signer = PrivateKeySigner::from_hex(&std::env::var("POLYGON_PRIVATE_KEY")?)?;
let ready = trader.ensure_ready(Box::new(signer), None).await?;
println!("fund this address: {}", ready.funder_address);

Fund the returned funderAddress / funder_address, not an address guessed from the signing key. The correct funding flow depends on the wallet type. See Deposit wallets, V2 details, and PolyUSD.

Place an order

The following snippets place a real order when run. Replace every placeholder and validate the market first.

const result = await trader.order({
  tokenId: process.env.POLYMARKET_TOKEN_ID!,
  side: 'BUY',
  price: 0.55,
  size: 10,
  type: 'GTC',
  postOnly: true,
});

if (!result.success) throw new Error(result.error ?? 'Order rejected');
console.log(result.orderId);

import os
from polynode.trading import OrderParams

result = await trader.order(OrderParams(
    token_id=os.environ["POLYMARKET_TOKEN_ID"],
    side="BUY",
    price=0.55,
    size=10,
    type="GTC",
    post_only=True,
))

if not result.success:
    raise RuntimeError(result.error or "Order rejected")
print(result.order_id)

use polynode::trading::{OrderParams, OrderSide, OrderType};

let result = trader.order(OrderParams {
    token_id: std::env::var("POLYMARKET_TOKEN_ID")?,
    side: OrderSide::Buy,
    price: 0.55,
    size: 10.0,
    order_type: OrderType::GTC,
    expiration: None,
    post_only: true,
    fee_config: None,
    builder: None,
}).await?;

if !result.success {
    return Err(polynode::Error::Trading(
        result.error.unwrap_or_else(|| "order rejected".into()),
    ));
}
println!("{:?}", result.order_id);

Supported time-in-force values are GTC, GTD, FOK, and FAK. A V2 GTD expiration must include the required safety buffer; the SDK rejects an invalid value before submission.

Cancel and inspect orders

Each SDK supports:

canceling one order;
canceling all active orders;
canceling active orders for a market;
listing open orders;
checking balances and approvals;
reading the local order-attempt history.

const open = await trader.getOpenOrders();
if (open[0]) await trader.cancelOrder(open[0].id);

open_orders = await trader.get_open_orders()
if open_orders:
    await trader.cancel_order(open_orders[0].id)

let open_orders = trader.get_open_orders().await?;
if let Some(order) = open_orders.first() {
    trader.cancel_order(&order.id).await?;
}

Three different fee concepts

Keep these separate in your product and accounting:

Concept	What it means	How it is configured
Polymarket protocol fee	A market fee applied by Polymarket when eligible V2 liquidity matches	Not a signed V2 order field; inspect market metadata for display and budgeting
Builder attribution	Associates eligible volume with a public builder code	`builderCode` / `builder_code`, or the per-order `builder` override
Optional application fee	A fee your application deliberately charges through the SDK fee configuration	`feeConfig` / `fee_config`; disabled unless configured

Builder attribution does not by itself charge the user an application fee. An application fee is enabled only when you explicitly configure it. See Fee escrow before enabling application fees.

Builder attribution

Current V2 orders use a public bytes32 builder code. The SDK supplies PolyNode’s public code by default. You can provide your own code at trader level, override it for one order, or disable the default attribution.

const trader = new PolyNodeTrader({
  polynodeKey: process.env.POLYNODE_API_KEY!,
  builderCode: process.env.POLYMARKET_BUILDER_CODE!,
});

// Per-order override:
await trader.order({ ...order, builder: anotherBuilderCode });

trader = PolyNodeTrader(TraderConfig(
    polynode_key=os.environ["POLYNODE_API_KEY"],
    builder_code=os.environ["POLYMARKET_BUILDER_CODE"],
))

# Per-order override:
await trader.order(OrderParams(**order_values, builder=another_builder_code))

let mut trader = PolyNodeTrader::new(TraderConfig {
    polynode_key: std::env::var("POLYNODE_API_KEY")?,
    builder_code: Some(std::env::var("POLYMARKET_BUILDER_CODE")?),
    ..Default::default()
})?;

// `OrderParams.builder` overrides the config for one order.

Generate and manage builder credentials in your Polymarket builder settings. Builder credentials are secrets; the public builder code is not.

Position operations

The trading modules also expose split, merge, and negative-risk conversion builders or helpers. These are on-chain operations and are distinct from placing a CLOB order. Review Position management before signing or submitting one.

Cleanup

Close the trader to flush and release its local storage:

trader.close();

trader.close()

trader.close();

Next steps

Find a token with V3

Discover markets and token IDs before constructing an order.

Stream a verified book

Use PN1 integrity before making price-sensitive decisions.

V2 migration details

Understand the current exchange and payload differences.

Trading errors

Handle rejected orders and transport failures explicitly.

​Install

​Current V2 behavior

​Set up a wallet

​Place an order

​Cancel and inspect orders

​Three different fee concepts

​Builder attribution

​Position operations

​Cleanup

​Next steps

Find a token with V3

Stream a verified book

V2 migration details

Trading errors

Install

Current V2 behavior

Set up a wallet

Place an order

Cancel and inspect orders

Three different fee concepts

Builder attribution

Position operations

Cleanup

Next steps