> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unitedmarket.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Place an Order

> Submit an EIP-712 signed order through the public backend API.

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](/guides/sign-in-and-trade).

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

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

## 1. Load Market Data

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

```bash theme={null}
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.

```bash theme={null}
curl "https://api.unitedmarket.ai/markets/{id}/fee"
```

```json theme={null}
{ "feeRateBps": 15, "feeRateBpsOverride": null }
```

<Note>
  `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`.
</Note>

## 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](/contracts) for all deployed addresses.

## 3. Build the EIP-712 Domain

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

## 4. Sign the Order

```ts theme={null}
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

```bash theme={null}
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:

```ts theme={null}
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`.

```json theme={null}
{
  "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

```bash theme={null}
curl "https://api.unitedmarket.ai/orders/0xORDER_HASH"
```

```bash theme={null}
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`:

```bash theme={null}
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.