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

# CLOB Trading API

> Programmatic order-book trading on Foresight: signed limit and market orders, real-time market data, and a private WebSocket feed. This is a separate API from the legacy AMM Trade API.

The **CLOB Trading API (v1)** lets bots and integrations trade Foresight
prediction markets through a central limit order book. You place
**EIP-712-signed orders** that rest on an order book and match against other
participants — distinct from the legacy [AMM Trade API](/foresight-apis/foresight-api-documentation),
which swaps against an automated market maker.

<Info>
  The CLOB API and the AMM Trade API are **different APIs** with different
  endpoints, payloads, and semantics. The AMM API lives under `/trade/*`; the
  CLOB API lives under `/v1/*`. They are not interchangeable.
</Info>

## Base URL

```
https://api.foresight.now
```

Every endpoint in this section is prefixed with `/v1`. The realtime gateway is
at `wss://api.foresight.now/v1/ws`.

## Network

The CLOB currently runs on **BNB Smart Chain (BSC) mainnet**.

| Field               | Value |
| ------------------- | ----- |
| `chain_id`          | `56`  |
| Collateral decimals | `18`  |

<Warning>
  The collateral token on BSC has **18 decimals**, not 6. Always read the
  authoritative `decimals` from the `GET /v1/markets/{condition_id}/tokens`
  endpoint and scale your order amounts to it. Amounts signed at the wrong scale
  are rejected at ingest with `Drifted signed amounts`. See
  [Signing orders](/foresight-apis/clob/signing-orders).
</Warning>

## Core concepts

<AccordionGroup>
  <Accordion title="A market is a (condition_id, chain_id) pair">
    Every CLOB call identifies a market by its on-chain **`condition_id`**
    (ConditionalTokens condition hash) plus **`chain_id`**. Internal database
    identifiers are never exposed.
  </Accordion>

  <Accordion title="Outcomes and tokens">
    Each market has two outcomes: **`1` = YES** and **`0` = NO**. Each outcome
    maps to an ERC-1155 `token_id` returned by the `/tokens` endpoint. You sign
    orders against a specific outcome's `token_id`.
  </Accordion>

  <Accordion title="Orders are signed off-chain, matched asynchronously">
    You sign an order with your wallet (EIP-712) and `POST` it. The API
    **always returns `status: OPEN`** — matching runs in a background worker.
    Matched, partial, and failed transitions arrive on the private `user`
    WebSocket channel, not in the POST response.
  </Accordion>

  <Accordion title="Prices are 2-decimal probability ticks">
    A price is a YES probability in `[0.01, 1.00]`, quantized to 2 decimal
    places (100 ticks). `0.55` means a 55% implied probability. Sub-tick
    precision is rejected.
  </Accordion>

  <Accordion title="Amounts are BigInt, integer-tick math">
    `maker_amount` and `taker_amount` are raw token wei (BigInt strings) derived
    from integer-tick math — **BUY ceils** collateral, **SELL floors** it. Float
    arithmetic drifts and gets rejected. See the
    [Signing orders](/foresight-apis/clob/signing-orders) guide.
  </Accordion>
</AccordionGroup>

## Authentication tiers

| Tier   | Who             | Credentials                                                                 |
| ------ | --------------- | --------------------------------------------------------------------------- |
| **L0** | Anyone          | None — all market-data routes are public                                    |
| **L1** | Logged-in users | Privy JWT (`Authorization: Bearer …`) — manage API keys                     |
| **L2** | Bots or users   | Privy JWT **or** `fs-api-key` + `fs-api-secret` — trading and private reads |

See [Authentication](/foresight-apis/clob/authentication) for the API-key
lifecycle and permissions.

## A typical trading flow

<Steps>
  <Step title="Create an API key">
    With a logged-in Privy JWT, call `POST /v1/auth/api-keys` to mint a key with
    `["read", "trade"]` permissions. The secret is shown **once**.
  </Step>

  <Step title="Find a market">
    `GET /v1/markets?chain_id=56` lists open markets. Read `ctf_exchange_address`
    and the outcome `token_id`s you'll need to sign.
  </Step>

  <Step title="Sign and place an order">
    Build the EIP-712 order, sign it with your wallet, and `POST /v1/orders`.
    See [Signing orders](/foresight-apis/clob/signing-orders).
  </Step>

  <Step title="Track fills in real time">
    Get a WS token (`POST /v1/auth/ws-token`), connect to `/v1/ws`, and subscribe
    to the `user` channel for order-lifecycle and fill events. See
    [WebSocket](/foresight-apis/clob/websocket).
  </Step>
</Steps>

## Reference

The full interactive endpoint reference is under **CLOB API Reference** in the
sidebar. Continue with:

* [Authentication](/foresight-apis/clob/authentication) — API keys, tiers, permissions
* [Signing orders](/foresight-apis/clob/signing-orders) — EIP-712 domain, struct, and amount math
* [WebSocket](/foresight-apis/clob/websocket) — realtime book, ticker, trades, and user events
* [Errors](/foresight-apis/clob/errors) — error envelope and codes