Trading & Orders - Limitless Exchange

Prerequisites

Before placing orders, initialize the required clients:

import { ethers } from 'ethers';
import {
  HttpClient,
  MarketFetcher,
  OrderClient,
} from '@limitless-exchange/sdk';

const httpClient = new HttpClient({
  baseURL: 'https://api.limitless.exchange',
  hmacCredentials: {
    tokenId: process.env.LMTS_TOKEN_ID,
    secret: process.env.LMTS_TOKEN_SECRET,
  },
});

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!);
const marketFetcher = new MarketFetcher(httpClient);

const orderClient = new OrderClient({
  httpClient,
  wallet,
  marketFetcher, // Optional: enables venue caching for faster order creation
});

OrderClient constructor

Option	Type	Required	Description
`httpClient`	`HttpClient`	Yes	Authenticated HTTP client
`wallet`	`ethers.Wallet`	Yes	Wallet for EIP-712 signing
`marketFetcher`	`MarketFetcher`	No	Enables automatic venue caching. If omitted, venue data is fetched on each order.

The OrderClient automatically fetches your user profile data (including ownerId) from the API on the first order. You do not need to supply it manually.

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 trading, your wallet must approve the relevant venue contracts to spend USDC and conditional tokens. This is a one-time setup per venue.

Approval requirements

Market type	USDC approval	Conditional token approval
CLOB	Venue `exchange` contract	Venue `exchange` contract
NegRisk	NegRisk `exchange` contract	NegRisk `exchange` contract

Manual approval with ethers

import { ethers } from 'ethers';

const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'; // USDC on Base
const ERC20_ABI = [
  'function approve(address spender, uint256 amount) returns (bool)',
];
const ERC1155_ABI = [
  'function setApprovalForAll(address operator, bool approved)',
];

const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

async function approveVenue(venueExchange: string) {
  const usdc = new ethers.Contract(USDC_ADDRESS, ERC20_ABI, signer);
  const tx1 = await usdc.approve(venueExchange, ethers.MaxUint256);
  await tx1.wait();
  console.log('USDC approved for', venueExchange);
}

Run approvals once per venue. After approval, all subsequent orders on markets using that venue work without additional on-chain transactions.

GTC orders (Good-Til-Cancelled)

GTC orders remain on the orderbook until filled, cancelled, or the market resolves. Specify price (probability between 0 and 1) and size (number of shares).

Buy YES shares

import { OrderType, Side } from '@limitless-exchange/sdk';

const market = await marketFetcher.getMarket('btc-100k-weekly');

const result = await orderClient.createOrder({
  marketSlug: market.slug,
  tokenId: market.tokens.yes, // YES token
  side: Side.BUY,
  price: 0.65,
  size: 100,
  orderType: OrderType.GTC,
});

console.log('Order created:', result.order.id);

Post-only GTC order

Use postOnly: 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.

const result = await orderClient.createOrder({
  marketSlug: market.slug,
  tokenId: market.tokens.yes, // YES token
  side: Side.BUY,
  price: 0.65,
  size: 100,
  orderType: OrderType.GTC,
  postOnly: true,
});

Sell NO shares

const result = await orderClient.createOrder({
  marketSlug: market.slug,
  tokenId: market.tokens.no, // NO token
  side: Side.SELL,
  price: 0.40,
  size: 50,
  orderType: OrderType.GTC,
});

GTC parameter reference

Parameter	Type	Description
`marketSlug`	`string`	Market slug identifier
`tokenId`	`string`	YES or NO token ID from `market.tokens` (yes / no)
`side`	`Side`	`Side.BUY` (0) or `Side.SELL` (1)
`price`	`number`	Price between 0 and 1 (exclusive), tick-aligned
`size`	`number`	Number of shares (positive, step-aligned)
`orderType`	`OrderType`	`OrderType.GTC`
`postOnly`	`boolean`	Optional. When `true`, rejects the order if it would immediately match. Default `false`.

Self-trade prevention

Pass stpPolicy 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.

const result = await orderClient.createOrder({
  marketSlug: market.slug,
  tokenId: market.positionIds[0], // YES token
  side: Side.BUY,
  price: 0.65,
  size: 100,
  orderType: OrderType.GTC,
  stpPolicy: '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:

if (result.execution.settlementStatus === 'CANCELED' &&
    result.execution.reason === 'STP_TAKER_REJECTED') {
  console.log('Order rejected by self-trade prevention');
} else if (result.execution.stpMakerCancels?.length) {
  console.log('Cancelled own resting orders:', result.execution.stpMakerCancels);
}

`execution` field	Type	Description
`settlementStatus`	`string`	`CANCELED` when a `cancel_taker` / `cancel_both` order is rejected.
`reason`	`string?`	`STP_TAKER_REJECTED` when the incoming order was rejected.
`stpMakerCancels`	`string[]?`	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. postOnly is not supported for FAK orders.

Buy with FAK

const result = await orderClient.createOrder({
  marketSlug: market.slug,
  tokenId: market.tokens.yes, // YES token
  side: Side.BUY,
  price: 0.45,
  size: 100,
  orderType: OrderType.FAK,
});

if (result.makerMatches.length > 0) {
  console.log(`FAK order matched immediately with ${result.makerMatches.length} fill(s)`);
} else {
  console.log('FAK remainder was cancelled.');
}

Sell with FAK

const result = await orderClient.createOrder({
  marketSlug: market.slug,
  tokenId: market.tokens.no, // NO token
  side: Side.SELL,
  price: 0.40,
  size: 50,
  orderType: OrderType.FAK,
});

FAK parameter reference

Parameter	Type	Description
`marketSlug`	`string`	Market slug identifier
`tokenId`	`string`	YES or NO token ID from `market.tokens` (yes / no)
`side`	`Side`	`Side.BUY` (0) or `Side.SELL` (1)
`price`	`number`	Price between 0 and 1 (exclusive), tick-aligned
`size`	`number`	Number of shares (positive, step-aligned)
`orderType`	`OrderType`	`OrderType.FAK`

FOK orders (Fill-or-Kill)

FOK orders execute immediately against the existing orderbook or are rejected entirely. Instead of price and size, specify makerAmount which represents the total value to trade.

Buy with FOK

For a BUY FOK order, makerAmount is the amount of USDC you are willing to spend:

import { OrderType, Side } from '@limitless-exchange/sdk';

const result = await orderClient.createOrder({
  marketSlug: market.slug,
  tokenId: market.tokens.yes, // YES token
  side: Side.BUY,
  makerAmount: 50, // Spend up to 50 USDC
  orderType: OrderType.FOK,
});

Sell with FOK

For a SELL FOK order, makerAmount is the number of shares you want to sell:

const result = await orderClient.createOrder({
  marketSlug: market.slug,
  tokenId: market.tokens.yes, // YES token
  side: Side.SELL,
  makerAmount: 100, // Sell 100 shares
  orderType: OrderType.FOK,
});

FOK parameter reference

Parameter	Type	Description
`marketSlug`	`string`	Market slug identifier
`tokenId`	`string`	YES or NO token ID from `market.tokens` (yes / no)
`side`	`Side`	`Side.BUY` (0) or `Side.SELL` (1)
`makerAmount`	`number`	BUY: USDC to spend. SELL: shares to sell. Max 6 decimals.
`orderType`	`OrderType`	`OrderType.FOK`

NegRisk orders

When trading NegRisk markets, always use the submarket slug. The group slug is not tradeable. Fetch the group to discover submarkets, then fetch the specific submarket to get its token IDs.

import { OrderType, Side } from '@limitless-exchange/sdk';

// 1. Fetch the NegRisk group
const group = await marketFetcher.getMarket('us-election-2024');

// 2. Pick a submarket from the group's markets array
const submarket = group.markets[0];

// 3. Fetch submarket details to get token IDs
const submarketDetail = await marketFetcher.getMarket(submarket.slug);

// 4. Place an order using the submarket slug and token IDs
const result = await orderClient.createOrder({
  marketSlug: submarketDetail.slug,
  tokenId: submarketDetail.tokens.yes, // YES token
  side: Side.BUY,
  price: 0.55,
  size: 25,
  orderType: OrderType.GTC,
});

Passing the group slug to createOrder() will fail. The group slug does not resolve to a tradeable market. Always use the submarket slug.

AMM trading

CLOB orders trade against the orderbook. AMM (FPMM) markets trade against a pool, and the SDK exposes them through client.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 identityToken. Legacy x-api-key credentials are rejected.
The trade runs against a server-wallet sub-account. Set onBehalfOf 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.
slippageBps is optional and ranges from 0 to 1000. The server default is 100 (1%).
outcomeIndex 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. ensureAllowance runs checkAllowance, submits approveAllowance at most once when missing, then polls the check until confirmed is true. Tune the poll with intervalMs (default 2000) and maxAttempts (default 30).

import { Client } from '@limitless-exchange/sdk';

const client = new Client({
  hmacCredentials: {
    tokenId: process.env.LMTS_TOKEN_ID!,
    secret: process.env.LMTS_TOKEN_SECRET!,
  },
});

const marketSlug = 'btc-100k-weekly';
const childProfileId = 12345;

await client.amm.ensureAllowance({ market: marketSlug, side: 'BUY', onBehalfOf: childProfileId });
await client.amm.ensureAllowance({ market: marketSlug, side: 'SELL', onBehalfOf: childProfileId });

A submitted response from approveAllowance (HTTP 202) is not confirmation. Either use ensureAllowance, or poll checkAllowance until confirmed is true.

Buy shares

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

const buy = await client.amm.buy({
  market: marketSlug,
  outcomeIndex: 0,             // 0 = YES, 1 = NO
  collateralAmount: '1000000', // 1 USDC in base units
  slippageBps: 100,            // optional, 0..1000
  idempotencyKey: 'buy-unique-key-001',
  onBehalfOf: childProfileId,  // omit for a direct profile
});

console.log(buy.status, buy.expectedShares, buy.minShares);

Sell shares

sell requests an exact collateral return by selling outcome shares.

const sell = await client.amm.sell({
  market: marketSlug,
  outcomeIndex: 0,
  collateralReturnAmount: '992015',
  idempotencyKey: 'sell-unique-key-001',
  onBehalfOf: childProfileId,
});

console.log(sell.status, sell.expectedShares, sell.maxShares);

Reusing an idempotencyKey with different params raises ConflictError (HTTP 409). The four AMM routes share a rate limit of 10 requests / 10 seconds per actor. Pass { withRawResponse: true } to any AMM method to receive an SdkResponse with HTTP status and headers.

Cancelling orders

Cancel an open order by its ID:

const result = await orderClient.cancel('order_abc123');
console.log(result.message);

Cancel all orders in a market:

const result = await orderClient.cancelAll('btc-100k-weekly');
console.log(result.message);

Cancel and replace

cancelReplace 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 rather than issuing separate cancel + create calls. cancelReplaceBatch runs several of these operations in a single call. The two actions are not atomic: the cancel and the replacement have 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 orderId or clientOrderId. The replacement is a normal signed order and accepts the same fields as createOrder (orderType, marketSlug, tokenId, side, price, size or makerAmount, postOnly, stpPolicy, etc.).

Single cancel-replace

import { CancelReplaceMode, OrderType, Side } from '@limitless-exchange/sdk';

const result = await orderClient.cancelReplace({
  cancel: { orderId: 'order_abc123' },
  mode: CancelReplaceMode.STOP_ON_FAILURE,
  replacement: {
    marketSlug: market.slug,
    orderType: OrderType.GTC,
    tokenId: market.tokens.yes,
    side: Side.BUY,
    price: 0.62,
    size: 100,
  },
});

if (result.cancel.status === 'SUCCESS') {
  console.log('Cancelled:', result.cancel.orderId);
}
if (result.replacement.status === 'SUCCESS') {
  console.log('Replacement placed:', result.replacement.data.id);
}

Batch cancel-replace

Each entry runs independently and its result is returned with the caller’s index:

const batch = await orderClient.cancelReplaceBatch({
  operations: [
    {
      cancel: { orderId: 'order_abc123' },
      mode: CancelReplaceMode.ALLOW_FAILURE,
      replacement: { marketSlug: market.slug, orderType: OrderType.GTC, tokenId: market.tokens.yes, side: Side.BUY, price: 0.62, size: 100 },
    },
    {
      cancel: { clientOrderId: 'my-tag-42' },
      mode: CancelReplaceMode.STOP_ON_FAILURE,
      replacement: { marketSlug: market.slug, orderType: OrderType.GTC, tokenId: market.tokens.no, side: Side.SELL, price: 0.41, size: 50 },
    },
  ],
});

for (const item of batch.results) {
  console.log(item.index, item.cancel.status, item.replacement.status);
}

Delegated cancel-replace

Partners with the delegated_signing scope call client.delegatedOrders.cancelReplace and client.delegatedOrders.cancelReplaceBatch. The server signs the replacement using the sub-account’s managed wallet, so no private key is required. Set onBehalfOf to the sub-account profile ID on every operation:

await client.delegatedOrders.cancelReplace({
  cancel: { orderId: 'order_abc123' },
  mode: CancelReplaceMode.STOP_ON_FAILURE,
  onBehalfOf: partnerAccount.profileId,
  replacement: {
    marketSlug: market.slug,
    orderType: OrderType.GTC,
    tokenId: 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.

Order states

State	Description
`OPEN`	Order is live on the orderbook
`PARTIALLY_FILLED`	Some shares have been matched
`FILLED`	Order fully matched
`CANCELLED`	Order cancelled by user or system
`REJECTED`	Order rejected (insufficient funds, invalid params, etc.)

Error handling

The SDK throws APIError for HTTP-level failures. Inspect status and message for details.

import { APIError, OrderType, Side } from '@limitless-exchange/sdk';

try {
  await orderClient.createOrder({
    marketSlug: 'btc-100k-weekly',
    tokenId: market.tokens.yes,
    side: Side.BUY,
    price: 0.65,
    size: 100,
    orderType: OrderType.GTC,
  });
} catch (error) {
  if (error instanceof APIError) {
    switch (error.status) {
      case 400:
        console.error('Bad request:', error.message);
        break;
      case 401:
        console.error('Unauthorized: check your API key');
        break;
      case 429:
        console.error('Rate limited: slow down requests');
        break;
      default:
        console.error(`API error ${error.status}:`, error.message);
    }
  } else {
    throw error;
  }
}

See the Error Handling and Retry guide for retry strategies.

Validation rules

Price validation

Prices must be between 0 and 1 (exclusive). A price of 0.65 means you value the outcome at 65%. Prices outside this range will be rejected by the API.

// Valid
price: 0.01
price: 0.99

// Invalid (will throw)
price: 0
price: 1
price: 1.5
price: -0.1

Size validation

Size must be a positive number. Fractional sizes are allowed if they align to the shares step (0.001). Max 3 decimal places.

// Valid
size: 1
size: 100
size: 1.5
size: 0.001

// Invalid (will throw)
size: 0
size: -1
size: 0.0001  // too many decimals

​Prerequisites

​OrderClient constructor

​Token approvals

​Approval requirements

​Manual approval with ethers

​GTC orders (Good-Til-Cancelled)

​Buy YES shares

​Post-only GTC order

​Sell NO shares

​GTC parameter reference

​Self-trade prevention

​FAK orders (Fill-And-Kill)

​Buy with FAK

​Sell with FAK

​FAK parameter reference

​FOK orders (Fill-or-Kill)

​Buy with FOK

​Sell with FOK

​FOK parameter reference

​NegRisk orders

​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

​Order states

​Error handling

​Validation rules

Prerequisites

OrderClient constructor

Token approvals

Approval requirements

Manual approval with ethers

GTC orders (Good-Til-Cancelled)

Buy YES shares

Post-only GTC order

Sell NO shares

GTC parameter reference

Self-trade prevention

FAK orders (Fill-And-Kill)

Buy with FAK

Sell with FAK

FAK parameter reference

FOK orders (Fill-or-Kill)

Buy with FOK

Sell with FOK

FOK parameter reference

NegRisk orders

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

Order states

Error handling

Validation rules