Place an Order

Orders are submitted through the backend as EIP-712 signed payloads. Backend authentication and order signing are separate: a wallet session can identify a user, but the order itself must still be signed. For the full SIWE login flow before placing or cancelling orders, see Sign In & Trade.

Base URL
`https://api.unitedmarket.ai`

United Market is now live on BNB Smart Chain mainnet. We just launched — start trading on-chain prediction markets today.

1. Load Market Data

Fetch the market first so your client knows the market id, condition id, and outcome token ids.

curl "https://api.unitedmarket.ai/markets/{id}/trading"

Then fetch the market’s effective trading fee. You must sign this exact feeRateBps value into the order.

curl "https://api.unitedmarket.ai/markets/{id}/fee"

{ "feeRateBps": 15, "feeRateBpsOverride": null }

feeRateBps is in basis points (15 = 0.15%). It can vary per market or tag, so read it right before signing. Orders signing less than the market’s effective rate are rejected; markets with a 0 rate still accept 0.

2. Approve Trading Contracts

Before trading, the wallet must approve the exchange contract.

Action	Approval
Buy outcome tokens	Approve the collateral ERC-20 for `CTFExchange`.
Sell outcome tokens	Call `setApprovalForAll(CTFExchange, true)` on the ConditionalTokens contract.

Use the mainnet exchange address 0x8db26793D99b2E9Ac53102de110Fe783F676D516. See Contracts for all deployed addresses.

3. Build the EIP-712 Domain

const domain = {
  name: "Polymarket CTF Exchange",
  version: "1",
  chainId: 56,
  verifyingContract: "0x8db26793D99b2E9Ac53102de110Fe783F676D516",
} as const;

4. Sign the Order

const types = {
  Order: [
    { name: "salt", type: "uint256" },
    { name: "maker", type: "address" },
    { name: "signer", type: "address" },
    { name: "taker", type: "address" },
    { name: "tokenId", type: "uint256" },
    { name: "makerAmount", type: "uint256" },
    { name: "takerAmount", type: "uint256" },
    { name: "expiration", type: "uint256" },
    { name: "nonce", type: "uint256" },
    { name: "feeRateBps", type: "uint256" },
    { name: "side", type: "uint8" },
    { name: "signatureType", type: "uint8" },
  ],
} as const;

const order = {
  salt: BigInt(Date.now()),
  maker: walletAddress,
  signer: walletAddress,
  taker: "0x0000000000000000000000000000000000000000",
  tokenId,
  makerAmount,
  takerAmount,
  expiration: 0n,
  nonce: 0n,
  feeRateBps: BigInt(feeRateBps), // from GET /markets/{id}/fee
  side: 0,
  signatureType: 0,
};

const signature = await walletClient.signTypedData({
  account: walletAddress,
  domain,
  types,
  primaryType: "Order",
  message: order,
});

5. Submit the Order

curl -X POST "https://api.unitedmarket.ai/markets/{id}/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "orderType": "GTC",
    "order": {
      "salt": "123456789",
      "maker": "0xYourWallet",
      "signer": "0xYourWallet",
      "taker": "0x0000000000000000000000000000000000000000",
      "tokenId": "9173991505859985195806122260131852520306883753774963004628888314748377483211",
      "makerAmount": "50000000",
      "takerAmount": "100000000",
      "expiration": "0",
      "nonce": "0",
      "feeRateBps": "15",
      "side": 0,
      "signatureType": 0,
      "signature": "0x..."
    }
  }'

The response includes an orderHash. Store it for order status and cancellation.

Submit Multiple Orders

Submit up to 50 signed orders for the same market in one request:

const response = await fetch(
  "https://api.unitedmarket.ai/markets/{id}/orders/batch",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      orders: [
        { order: signedOrder1, orderType: "GTC" },
        { order: signedOrder2, orderType: "POST_ONLY" },
      ],
    }),
  },
);

const result = await response.json();

Orders are processed sequentially in request order. The operation is not atomic: one order can fail while other orders are accepted. Always inspect every entry in results.

{
  "accepted": 1,
  "rejected": 1,
  "results": [
    {
      "ok": true,
      "orderHash": "0x...",
      "status": "open",
      "orderType": "GTC",
      "matches": []
    },
    {
      "ok": false,
      "statusCode": 400,
      "error": "Insufficient available balance",
      "orderHash": "0x..."
    }
  ]
}

Order Types

Type	Behavior
`GTC`	Good-till-cancelled. The order rests until filled, cancelled, or expired.
`IOC`	Immediate-or-cancel. Fills what it can immediately and cancels the rest.
`FOK`	Fill-or-kill. Must fully fill immediately or the order is rejected.
`POST_ONLY`	Maker-only. Rejected if it would immediately cross the spread.
`MARKET`	Takes the best available liquidity. Unfilled remainder is cancelled.

Amount Conventions

Side	`makerAmount`	`takerAmount`
BUY	Collateral amount	Outcome token amount
SELL	Outcome token amount	Collateral amount

Check or Cancel Orders

curl "https://api.unitedmarket.ai/orders/0xORDER_HASH"

curl -X POST "https://api.unitedmarket.ai/markets/{id}/orders/cancel" \
  -H "Authorization: Bearer <SIWE_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "orderHash": "0xORDER_HASH" }'

To cancel selected orders without cancelling every open order, submit up to 100 hashes to POST /orders/cancel-many:

curl -X POST "https://api.unitedmarket.ai/orders/cancel-many" \
  -H "Authorization: Bearer <SIWE_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderHashes": [
      "0xORDER_HASH_1",
      "0xORDER_HASH_2"
    ]
  }'

Ownership is checked for each hash. The response separates successfully cancelled orderHashes from failed entries, so partial success is possible.

Overview

Guides

API Reference

1. Load Market Data

2. Approve Trading Contracts

3. Build the EIP-712 Domain

4. Sign the Order

5. Submit the Order

Submit Multiple Orders

Order Types

Amount Conventions

Check or Cancel Orders

​1. Load Market Data

​2. Approve Trading Contracts

​3. Build the EIP-712 Domain

​4. Sign the Order

​5. Submit the Order

​Submit Multiple Orders

​Order Types

​Amount Conventions

​Check or Cancel Orders

1. Load Market Data

2. Approve Trading Contracts

3. Build the EIP-712 Domain

4. Sign the Order

5. Submit the Order

Submit Multiple Orders

Order Types

Amount Conventions

Check or Cancel Orders