Trading & Orders

Overview

The OrderClient handles order creation, EIP-712 signing, and order management. It supports Good-Til-Cancelled (GTC), Fill-And-Kill (FAK), and Fill-or-Kill (FOK) orders.

Prerequisites

Before placing orders, you need four components:

import asyncio
import os
from eth_account import Account
from limitless_sdk.api import HttpClient
from limitless_sdk import HMACCredentials
from limitless_sdk.markets import MarketFetcher
from limitless_sdk.orders import OrderClient
from limitless_sdk.types import Side, OrderType

# Authenticate with a scoped API token (token ID + secret)
http_client = HttpClient(
    hmac_credentials=HMACCredentials(
        token_id=os.environ["LMTS_TOKEN_ID"],
        secret=os.environ["LMTS_TOKEN_SECRET"],
    ),
)
account = Account.from_key("0xYOUR_PRIVATE_KEY")
market_fetcher = MarketFetcher(http_client)
order_client = OrderClient(http_client, account)

Component	Purpose
`HttpClient`	Authenticated HTTP client for API requests
`Account`	eth-account wallet for EIP-712 order signing
`MarketFetcher`	Fetches market data and caches venue addresses
`OrderClient`	Creates, signs, and submits orders

The OrderClient constructor automatically fetches your user profile data (userData) from the API. This is used to populate the ownerId field on submitted orders.

Wallet-mode preflight. Accepting the one-time “choose your trading wallet” prompt in the app enables 1-click (smart wallet) trading on your Limitless profile. Once that mode is set, self-signed orders are rejected with Signer does not match - you should use embedded address for smart wallet. Switch the profile to EOA trading mode first: see Trading wallet mode.

Token approvals

Before your first trade on a given venue, you must approve the exchange contracts to spend your tokens. This is a one-time on-chain setup per venue.

Standard CLOB
NegRisk

For standard CLOB markets, approve USDC and Conditional Tokens to the exchange contract:

from web3 import Web3

w3 = Web3(Web3.HTTPProvider("https://mainnet.base.org"))

USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
CT_ADDRESS = "0xC9c98965297Bc527861c898329Ee280632B76e18"  # Conditional Token framework address

market = await market_fetcher.get_market("your-market-slug")
exchange = market.venue.exchange

# Approve USDC for BUY orders
usdc_contract = w3.eth.contract(
    address=Web3.to_checksum_address(USDC_ADDRESS),
    abi=[{
        "name": "approve",
        "type": "function",
        "inputs": [
            {"name": "spender", "type": "address"},
            {"name": "amount", "type": "uint256"},
        ],
        "outputs": [{"name": "", "type": "bool"}],
    }],
)
tx = usdc_contract.functions.approve(
    Web3.to_checksum_address(exchange),
    2**256 - 1,  # max approval
).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
})
signed = w3.eth.account.sign_transaction(tx, account.key)
w3.eth.send_raw_transaction(signed.raw_transaction)

# Approve Conditional Tokens for SELL orders
ct_contract = w3.eth.contract(
    address=Web3.to_checksum_address(CT_ADDRESS),
    abi=[{
        "name": "setApprovalForAll",
        "type": "function",
        "inputs": [
            {"name": "operator", "type": "address"},
            {"name": "approved", "type": "bool"},
        ],
        "outputs": [],
    }],
)
tx = ct_contract.functions.setApprovalForAll(
    Web3.to_checksum_address(exchange),
    True,
).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
})
signed = w3.eth.account.sign_transaction(tx, account.key)
w3.eth.send_raw_transaction(signed.raw_transaction)

For NegRisk markets, you must additionally approve the adapter contract:

market = await market_fetcher.get_market("your-negrisk-slug")
exchange = market.venue.exchange
adapter = market.venue.adapter

# 1. Approve USDC to the exchange (same as CLOB)
# ... (see Standard CLOB tab)

# 2. Approve Conditional Tokens to the exchange
# ... (see Standard CLOB tab)

# 3. Approve Conditional Tokens to the adapter (NegRisk only)
tx = ct_contract.functions.setApprovalForAll(
    Web3.to_checksum_address(adapter),
    True,
).build_transaction({
    "from": account.address,
    "nonce": w3.eth.get_transaction_count(account.address),
})
signed = w3.eth.account.sign_transaction(tx, account.key)
w3.eth.send_raw_transaction(signed.raw_transaction)

Approvals are on-chain transactions that cost gas. You only need to perform them once per venue. Use venue.exchange for both CLOB and NegRisk, and additionally venue.adapter for NegRisk markets.

GTC orders (Good-Til-Cancelled)

GTC orders remain on the orderbook until filled or explicitly cancelled. Specify price (in dollars) and size (number of shares):

market = await market_fetcher.get_market("btc-above-100k-march-2025")

result = await order_client.create_order(
    token_id=market.tokens.yes,
    price=0.65,
    size=10.0,
    side=Side.BUY,
    order_type=OrderType.GTC,
    market_slug="btc-above-100k-march-2025",
)
print("Order placed:", result)

Post-only GTC order

Use post_only=True to ensure your order is never filled immediately as a taker. If the order would cross the spread (i.e., match against existing orders), it is rejected instead. This guarantees you always receive maker fees.

result = await order_client.create_order(
    token_id=market.tokens.yes,
    price=0.65,
    size=10.0,
    side=Side.BUY,
    order_type=OrderType.GTC,
    market_slug="btc-above-100k-march-2025",
    post_only=True,
)

Parameter	Type	Description
`token_id`	`str`	Token ID from `market.tokens.yes` or `market.tokens.no`
`price`	`float`	Price per share in dollars (0.01 to 0.99)
`size`	`float`	Number of shares to buy or sell
`side`	`Side`	`Side.BUY` or `Side.SELL`
`order_type`	`OrderType`	`OrderType.GTC`
`market_slug`	`str`	Market slug for venue lookup
`post_only`	`bool`	Optional. When `True`, rejects the order if it would immediately match. Default `False`.

Self-trade prevention

Pass stp_policy to control what happens when your incoming order would match your own resting order on the same token. It is a top-level request field — not part of the EIP-712 signed order — and applies to any order type. Omit it to keep the server default, cancel_maker.

result = await order_client.create_order(
    token_id=market.tokens.yes,
    price=0.65,
    size=10.0,
    side=Side.BUY,
    order_type=OrderType.GTC,
    market_slug="btc-above-100k-march-2025",
    stp_policy="cancel_maker",  # "cancel_maker" | "cancel_taker" | "cancel_both"
)

Value	Result
`cancel_maker`	Default. Cancels your conflicting resting order and continues with the incoming order.
`cancel_taker`	Rejects the incoming order before it self-trades.
`cancel_both`	Cancels your conflicting resting order and rejects the incoming order.

The create-order response carries an execution object with the outcome:

execution = result.execution
if execution.settlement_status == "CANCELED" and execution.reason == "STP_TAKER_REJECTED":
    print("Order rejected by self-trade prevention")
elif execution.stp_maker_cancels:
    print("Cancelled own resting orders:", execution.stp_maker_cancels)

`execution` field	Type	Description
`settlement_status`	`str`	`CANCELED` when a `cancel_taker` / `cancel_both` order is rejected.
`reason`	`str \| None`	`STP_TAKER_REJECTED` when the incoming order was rejected.
`stp_maker_cancels`	`list[str] \| None`	Resting order ids cancelled by `cancel_maker` / `cancel_both`.

Self-trade prevention blocks same-profile matches on the same token only. Orders on a different token of the same profile are unaffected. The wire field is always stpPolicy, regardless of the SDK.

FAK orders (Fill-And-Kill)

FAK orders use the same price and size inputs as GTC, but they only consume immediately available liquidity and cancel any unmatched remainder. post_only is not supported for FAK orders.

response = await order_client.create_order(
    token_id=market.tokens.yes,
    price=0.45,
    size=10.0,
    side=Side.BUY,
    order_type=OrderType.FAK,
    market_slug="btc-above-100k-march-2025",
)

if response.maker_matches:
    print(f"FAK order matched immediately with {len(response.maker_matches)} fill(s)")
else:
    print("FAK remainder was cancelled.")

Parameter	Type	Description
`token_id`	`str`	Token ID from `market.tokens.yes` or `market.tokens.no`
`price`	`float`	Price per share in dollars (0.01 to 0.99)
`size`	`float`	Number of shares to buy or sell
`side`	`Side`	`Side.BUY` or `Side.SELL`
`order_type`	`OrderType`	`OrderType.FAK`
`market_slug`	`str`	Market slug for venue lookup

FOK orders (Fill-or-Kill)

FOK orders execute immediately and fully, or are rejected entirely. Instead of price and size, you specify maker_amount:

FOK BUY
FOK SELL

When buying, maker_amount is the total USDC you want to spend. The exchange fills as many shares as possible at the best available price:

result = await order_client.create_order(
    token_id=market.tokens.yes,
    maker_amount=10.0,  # spend 10 USDC
    side=Side.BUY,
    order_type=OrderType.FOK,
    market_slug="btc-above-100k-march-2025",
)

When selling, maker_amount is the number of shares to sell. The exchange returns USDC at the best available price:

result = await order_client.create_order(
    token_id=market.tokens.yes,
    maker_amount=10.0,  # sell 10 shares
    side=Side.SELL,
    order_type=OrderType.FOK,
    market_slug="btc-above-100k-march-2025",
)

AMM trading

CLOB orders trade against the orderbook. AMM (FPMM) markets trade against a pool, and the SDK exposes them through client.partner_amm. The service calls POST /amm/allowances/check, POST /amm/allowances/approve, POST /amm/buy, and POST /amm/sell on behalf of a partner server wallet. Use it when the market is an AMM market and you want the server to hold custody, sign the trade, and pay gas. See AMM Trading (Server Wallets) for the underlying endpoints and market model.

Requirements

Authenticate with an HMAC API token that holds both the trading and delegated_signing scopes, or pass a per-call Privy identity_token. Legacy x-api-key credentials are rejected.
The trade runs against a server-wallet sub-account. Set on_behalf_of to the sub-account profile ID, or omit it to trade from the authenticated profile.
Amounts are positive integer strings in the collateral token’s base units (for USDC: "1000000" = 1 USDC). Never pass floats.
slippage_bps is optional and ranges from 0 to 1000. The server default is 100 (1%).
outcome_index is 0 for YES and 1 for NO.

One-time approval per wallet and market

BUY and SELL approvals are independent and set up once per wallet and market. buy and sell do not preflight allowances themselves. Confirm the allowance first. ensure_allowance runs check_allowance, submits approve_allowance at most once when missing, then polls the check until confirmed is true. Tune the poll with interval (default 2 seconds) and max_attempts (default 30).

from limitless_sdk import Client, HMACCredentials, AmmAllowanceParams

client = Client(
    hmac_credentials=HMACCredentials(
        token_id=os.environ["LMTS_TOKEN_ID"],
        secret=os.environ["LMTS_TOKEN_SECRET"],
    ),
)

market_slug = "btc-100k-weekly"
child_profile_id = 12345

await client.partner_amm.ensure_allowance(
    AmmAllowanceParams(market=market_slug, side="BUY", on_behalf_of=child_profile_id)
)
await client.partner_amm.ensure_allowance(
    AmmAllowanceParams(market=market_slug, side="SELL", on_behalf_of=child_profile_id)
)

A submitted response from approve_allowance (HTTP 202) is not confirmation. Either use ensure_allowance, or poll check_allowance until confirmed is true.

Buy shares

buy spends an exact collateral amount on the chosen outcome. Pass a unique idempotency_key per trade. On a timeout retry, reuse the exact same params so the server replays the original submission rather than opening a second trade.

from limitless_sdk import AmmBuyParams

buy = await client.partner_amm.buy(
    AmmBuyParams(
        market=market_slug,
        outcome_index=0,               # 0 = YES, 1 = NO
        collateral_amount="1000000",   # 1 USDC in base units
        slippage_bps=100,              # optional, 0..1000
        idempotency_key="buy-unique-key-001",
        on_behalf_of=child_profile_id, # omit for a direct profile
    )
)

print(buy.status, buy.expected_shares, buy.min_shares)

Sell shares

sell requests an exact collateral return by selling outcome shares.

from limitless_sdk import AmmSellParams

sell = await client.partner_amm.sell(
    AmmSellParams(
        market=market_slug,
        outcome_index=0,
        collateral_return_amount="992015",
        idempotency_key="sell-unique-key-001",
        on_behalf_of=child_profile_id,
    )
)

print(sell.status, sell.expected_shares, sell.max_shares)

Reusing an idempotency_key with different params raises ConflictError (HTTP 409). The four AMM routes share a rate limit of 10 requests / 10 seconds per actor. Pass with_raw_response=True to any AMM method to receive an HttpRawResponse exposing status, headers, and data.

Cancelling orders

Cancel a single order
Cancel all orders on a market

Cancel a specific order by its ID:

await order_client.cancel(order_id="abc123-def456")

Cancel every open order you have on a given market:

await order_client.cancel_all(market_slug="btc-above-100k-march-2025")

Cancel and replace

cancel_replace cancels one open order and submits a replacement in the same request. Use it to reprice or resize a resting order in one round-trip instead of separate cancel and create calls. cancel_replace_batch runs several of these operations in a single call. The cancel and the replacement are not atomic: they report independent outcomes, and a successful cancel does not guarantee a successful replacement. Choose the failure mode with CancelReplaceMode:

Mode	Cancellation fails	Replacement result
`STOP_ON_FAILURE`	Stops the operation	`NOT_ATTEMPTED`
`ALLOW_FAILURE`	Continues the operation	`SUCCESS`, `FAILURE`, or `UNKNOWN` independently

Identify the order to cancel by exactly one of order_id or client_order_id. The replacement is a normal signed order and uses the same fields as create_order (order_type, market_slug, token_id, side, price, size or maker_amount, post_only, stp_policy, etc.).

Single cancel-replace

from limitless_sdk.types import CancelReplaceMode, OrderType, Side

result = await order_client.cancel_replace(
    order_id="order_abc123",
    mode=CancelReplaceMode.STOP_ON_FAILURE,
    market_slug=market.slug,
    order_type=OrderType.GTC,
    token_id=market.tokens.yes,
    side=Side.BUY,
    price=0.62,
    size=100,
)

if result.cancel.status == "SUCCESS":
    print("Cancelled:", result.cancel.order_id)
if result.replacement.status == "SUCCESS":
    print("Replacement placed:", result.replacement.data.id)

Batch cancel-replace

Each operation is a dict of the same keyword arguments accepted by cancel_replace. Results come back with the caller’s index:

batch = await order_client.cancel_replace_batch([
    {
        "order_id": "order_abc123",
        "mode": CancelReplaceMode.ALLOW_FAILURE,
        "market_slug": market.slug,
        "order_type": OrderType.GTC,
        "token_id": market.tokens.yes,
        "side": Side.BUY,
        "price": 0.62,
        "size": 100,
    },
    {
        "client_order_id": "my-tag-42",
        "mode": CancelReplaceMode.STOP_ON_FAILURE,
        "market_slug": market.slug,
        "order_type": OrderType.GTC,
        "token_id": market.tokens.no,
        "side": Side.SELL,
        "price": 0.41,
        "size": 50,
    },
])

for item in batch.results:
    print(item.index, item.cancel.status, item.replacement.status)

Delegated cancel-replace

Partners with the delegated_signing scope call delegated_order_service.cancel_replace and .cancel_replace_batch. The server signs the replacement using the sub-account’s managed wallet, so no private key is required. Pass on_behalf_of (the sub-account profile ID) on every operation:

await delegated_order_service.cancel_replace(
    order_id="order_abc123",
    mode=CancelReplaceMode.STOP_ON_FAILURE,
    on_behalf_of=partner_account.profile_id,
    market_slug=market.slug,
    order_type=OrderType.GTC,
    token_id=market.tokens.yes,
    side=Side.BUY,
    price=0.62,
    size=100,
)

See POST /orders/cancel-replace and POST /orders/cancel-replace/batch for the full request and response shapes, per-status fields, and failure semantics.

Enums reference

Side

Value	Description
`Side.BUY`	Buy shares with USDC
`Side.SELL`	Sell shares for USDC

OrderType

Value	Description
`OrderType.GTC`	Good-Til-Cancelled limit order (rests on the book)
`OrderType.FAK`	Fill-And-Kill limit order (cancels any unmatched remainder)
`OrderType.FOK`	Fill-or-Kill market order (fills immediately or rejects)

Error handling

The SDK raises APIError for non-2xx responses. Always wrap order calls in try/except:

from limitless_sdk.api import APIError

try:
    result = await order_client.create_order(
        token_id=market.tokens.yes,
        price=0.65,
        size=10.0,
        side=Side.BUY,
        order_type=OrderType.GTC,
        market_slug="btc-above-100k-march-2025",
    )
except APIError as e:
    print(f"Order failed — status {e.status_code}: {e.message}")

See Error Handling & Retry for details on APIError fields and the @retry_on_errors decorator.

Complete example

import asyncio
import os
from eth_account import Account
from limitless_sdk.api import HttpClient, APIError
from limitless_sdk import HMACCredentials
from limitless_sdk.markets import MarketFetcher
from limitless_sdk.orders import OrderClient
from limitless_sdk.types import Side, OrderType

async def main():
    http_client = HttpClient(
        hmac_credentials=HMACCredentials(
            token_id=os.environ["LMTS_TOKEN_ID"],
            secret=os.environ["LMTS_TOKEN_SECRET"],
        ),
    )
    account = Account.from_key("0xYOUR_PRIVATE_KEY")
    market_fetcher = MarketFetcher(http_client)
    order_client = OrderClient(http_client, account)

    try:
        # Fetch market (caches venue automatically)
        market = await market_fetcher.get_market("btc-above-100k-march-2025")

        # Place a GTC BUY order for 10 YES shares at $0.65
        result = await order_client.create_order(
            token_id=market.tokens.yes,
            price=0.65,
            size=10.0,
            side=Side.BUY,
            order_type=OrderType.GTC,
            market_slug="btc-above-100k-march-2025",
        )
        print("GTC order placed:", result)

        # Place a FAK BUY order for 10 YES shares at $0.45
        fak_result = await order_client.create_order(
            token_id=market.tokens.yes,
            price=0.45,
            size=10.0,
            side=Side.BUY,
            order_type=OrderType.FAK,
            market_slug="btc-above-100k-march-2025",
        )
        print("FAK order placed:", fak_result)

        # Place a FOK BUY order spending 5 USDC
        fok_result = await order_client.create_order(
            token_id=market.tokens.yes,
            maker_amount=5.0,
            side=Side.BUY,
            order_type=OrderType.FOK,
            market_slug="btc-above-100k-march-2025",
        )
        print("FOK order placed:", fok_result)

        # Cancel all orders on this market
        await order_client.cancel_all(market_slug="btc-above-100k-march-2025")
        print("All orders cancelled")

    except APIError as e:
        print(f"API error — status {e.status_code}: {e.message}")
    finally:
        await http_client.close()

asyncio.run(main())

Always call await http_client.close() when finished. Failing to close the client can leave open connections and cause resource leaks.

Getting Started

Quick Start

TypeScript SDK

Python SDK

Go SDK

Rust SDK

WebSocket

Overview

Prerequisites

Token approvals

GTC orders (Good-Til-Cancelled)

Post-only GTC order

Self-trade prevention

FAK orders (Fill-And-Kill)

FOK orders (Fill-or-Kill)

AMM trading

Requirements

One-time approval per wallet and market

Buy shares

Sell shares

Cancelling orders

Cancel and replace

Single cancel-replace

Batch cancel-replace

Delegated cancel-replace

Enums reference

Side

OrderType

Error handling

Complete example

​Overview

​Prerequisites

​Token approvals

​GTC orders (Good-Til-Cancelled)

​Post-only GTC order

​Self-trade prevention

​FAK orders (Fill-And-Kill)

​FOK orders (Fill-or-Kill)

​AMM trading

​Requirements

​One-time approval per wallet and market

​Buy shares

​Sell shares

​Cancelling orders

​Cancel and replace

​Single cancel-replace

​Batch cancel-replace

​Delegated cancel-replace

​Enums reference

​Side

​OrderType

​Error handling

​Complete example

Overview

Prerequisites

Token approvals

GTC orders (Good-Til-Cancelled)

Post-only GTC order

Self-trade prevention

FAK orders (Fill-And-Kill)

FOK orders (Fill-or-Kill)

AMM trading

Requirements

One-time approval per wallet and market

Buy shares

Sell shares

Cancelling orders

Cancel and replace

Single cancel-replace

Batch cancel-replace

Delegated cancel-replace

Enums reference

Side

OrderType

Error handling

Complete example