# Create an API key Source: https://docs.foresight.now/api-reference/auth/create-an-api-key /api-reference/openapi-clob-v1.yaml post /v1/auth/api-keys Create a new API key for the authenticated user. **L1 — Privy JWT only** (you cannot create keys with a key). The `secret` is returned only once. # Issue a WebSocket token Source: https://docs.foresight.now/api-reference/auth/issue-a-websocket-token /api-reference/openapi-clob-v1.yaml post /v1/auth/ws-token Issue a single-use, 60-second token used to authenticate the private `user` WebSocket channel. **L2 — JWT or API key.** # List API keys Source: https://docs.foresight.now/api-reference/auth/list-api-keys /api-reference/openapi-clob-v1.yaml get /v1/auth/api-keys List non-revoked API keys for the authenticated user. **L1 — Privy JWT only.** Secrets are never returned. # Revoke an API key Source: https://docs.foresight.now/api-reference/auth/revoke-an-api-key /api-reference/openapi-clob-v1.yaml delete /v1/auth/api-keys/{key_id} Soft-revoke a key (sets `revokedAt`; the key stops working immediately). **L1 — Privy JWT only.** # Rotate an API-key secret Source: https://docs.foresight.now/api-reference/auth/rotate-an-api-key-secret /api-reference/openapi-clob-v1.yaml post /v1/auth/api-keys/{key_id}/regenerate Issue a new secret for an existing key. The old secret stops working immediately. **L1 — Privy JWT only.** # List fills Source: https://docs.foresight.now/api-reference/fills/list-fills /api-reference/openapi-clob-v1.yaml get /v1/fills List the authenticated wallet's fills (maker or taker side). **L2, permission `read`.** # Get a market Source: https://docs.foresight.now/api-reference/market-data/get-a-market /api-reference/openapi-clob-v1.yaml get /v1/markets/{condition_id} Single-market detail by `condition_id`. Accepts any status. **L0 — public.** # Get market tokens Source: https://docs.foresight.now/api-reference/market-data/get-market-tokens /api-reference/openapi-clob-v1.yaml get /v1/markets/{condition_id}/tokens ERC-1155 token ids and collateral `decimals` for this market. **L0 — public.** # Get orderbook snapshot Source: https://docs.foresight.now/api-reference/market-data/get-orderbook-snapshot /api-reference/openapi-clob-v1.yaml get /v1/markets/{condition_id}/book Aggregated orderbook snapshot. **L0 — public.** # Get public trades Source: https://docs.foresight.now/api-reference/market-data/get-public-trades /api-reference/openapi-clob-v1.yaml get /v1/markets/{condition_id}/trades Public settled trade prints (no maker/taker direction). **L0 — public.** Paginated. # Get ticker Source: https://docs.foresight.now/api-reference/market-data/get-ticker /api-reference/openapi-clob-v1.yaml get /v1/markets/{condition_id}/ticker Best bid/ask, last price, and spread. **L0 — public.** # List markets Source: https://docs.foresight.now/api-reference/market-data/list-markets /api-reference/openapi-clob-v1.yaml get /v1/markets List CLOB markets on a chain. **L0 — public.** Paginated. # Cancel orders Source: https://docs.foresight.now/api-reference/orders/cancel-orders /api-reference/openapi-clob-v1.yaml post /v1/orders/cancel Cancel orders by hash, by filter, or all. **L2, permission `trade`.** # Get an order Source: https://docs.foresight.now/api-reference/orders/get-an-order /api-reference/openapi-clob-v1.yaml get /v1/orders/{order_hash} Get a single order by hash, scoped to the authenticated wallet. **L2, permission `read`.** # Get on-chain cancel calldata Source: https://docs.foresight.now/api-reference/orders/get-on-chain-cancel-calldata /api-reference/openapi-clob-v1.yaml post /v1/orders/{order_hash}/cancel-onchain Return unsigned calldata to cancel an order directly against the CTF Exchange. The backend does **not** submit this transaction — you sign and send it yourself. **L2, permission `trade`.** # List orders Source: https://docs.foresight.now/api-reference/orders/list-orders /api-reference/openapi-clob-v1.yaml get /v1/orders List the authenticated wallet's orders. **L2, permission `read`.** # Place orders Source: https://docs.foresight.now/api-reference/orders/place-orders /api-reference/openapi-clob-v1.yaml post /v1/orders Batch-place up to **15** signed EIP-712 orders. **L2, permission `trade`.** Matching is asynchronous: every accepted order returns `status: OPEN`. Per-order rejections are returned inline in `results[]` — always inspect each item. Request-level failures (batch > 15, auth) are HTTP errors. See the **Signing orders** guide for the EIP-712 domain, struct, and the integer-tick `maker_amount` / `taker_amount` math. # List positions Source: https://docs.foresight.now/api-reference/positions/list-positions /api-reference/openapi-clob-v1.yaml get /v1/positions List the authenticated wallet's CLOB positions. **L2, permission `read`.** # Authentication Source: https://docs.foresight.now/foresight-apis/clob/authentication How to authenticate against the CLOB Trading API: the three auth tiers, API-key lifecycle, permissions, and short-lived WebSocket tokens. The CLOB API has three auth tiers. Each route picks exactly one. | Tier | Used by | Required credentials | | ------ | ------------------- | ------------------------------------------------------- | | **L0** | Anyone | None | | **L1** | Logged-in web users | `Authorization: Bearer ` | | **L2** | Bots or users | Privy JWT **or** `fs-api-key` + `fs-api-secret` headers | * **L0** — all `GET /v1/markets/*` routes. No auth. * **L1** — API-key management (`/v1/auth/api-keys*`). Privy JWT only — you cannot manage keys with a key. * **L2** — trading and private reads (`/v1/orders*`, `/v1/fills`, `/v1/positions`, `/v1/auth/ws-token`). Accepts a JWT **or** an API-key pair. ## API keys API keys are how bots authenticate. Each key is bound to the wallet that created it and carries a set of permissions. ### Headers Send both headers on every L2 request: ```http theme={null} fs-api-key: fs_key_abc123... fs-api-secret: fs_secret_... ``` ### Lifecycle All key-management routes require an **L1 Privy JWT** (not an API key). ```bash theme={null} curl -X POST https://api.foresight.now/v1/auth/api-keys \ -H "Authorization: Bearer $PRIVY_JWT" \ -H "Content-Type: application/json" \ -d '{ "permissions": ["read", "trade"] }' ``` ```json theme={null} { "key_id": "fs_key_abc123...", "secret": "fs_secret_..." } ``` The `secret` is returned **only once**. Store it immediately — it cannot be retrieved later, only rotated. The server keeps a bcrypt hash, never the plaintext. `GET /v1/auth/api-keys` returns key metadata (never secrets), including `permissions` and `last_used_at`. `POST /v1/auth/api-keys/{key_id}/regenerate` issues a new secret. The old one stops working immediately. `DELETE /v1/auth/api-keys/{key_id}` soft-revokes the key. It stops working immediately. If `permissions` is omitted on creation it defaults to `["read"]`. ## Permissions Permissions gate L2 routes. They are checked only for API keys — a Privy JWT user implicitly has all permissions. | Permission | Unlocks | | ---------- | ------------------------------------------------------------------------------------ | | `read` | All list/get endpoints: `GET /v1/orders`, `/v1/fills`, `/v1/positions` | | `trade` | `POST /v1/orders`, `POST /v1/orders/cancel`, `POST /v1/orders/{hash}/cancel-onchain` | ## Wallet binding A key can only trade for the wallet that created it. `POST /v1/orders` also checks that each order's EIP-712 **`signer` equals the authenticated wallet** — a mismatch returns a `WALLET_MISMATCH` error inline for that order. You cannot place orders on behalf of another wallet. ## WebSocket tokens Private WebSocket channels require a short-lived token, **not** your API-key headers. ```bash theme={null} curl -X POST https://api.foresight.now/v1/auth/ws-token \ -H "fs-api-key: $FS_API_KEY" \ -H "fs-api-secret: $FS_API_SECRET" ``` ```json theme={null} { "token": "deadbeef...", "expires_in": 60 } ``` * **Single-use.** The token is consumed by the first WS connection that uses it. * **60-second TTL.** Re-issue one per connection / reconnect. * Pass it as a query param: `wss://api.foresight.now/v1/ws?token=`. WS tokens authenticate the WebSocket upgrade only. They do **not** authenticate REST calls — REST always uses a JWT or API-key headers. # Errors Source: https://docs.foresight.now/foresight-apis/clob/errors The CLOB API error envelope, the full error-code table with HTTP mappings, inline vs HTTP errors, idempotency, batch caps, and pagination. ## Error envelope Every non-2xx response shares one shape. All field names are snake\_case, and the HTTP status equals `status_code`. ```json theme={null} { "correlation_id": "abc-123", "code": "NOT_FOUND", "message": "Market not found", "status_code": 404, "timestamp": "2026-06-03T10:15:30.000Z", "path": "/v1/markets/0x.../book" } ``` `correlation_id` comes from the request's correlation id or the `x-correlation-id` header; it falls back to `"unknown"`. Quote it when reporting an issue. ## Error codes | Code | HTTP | When | | ---------------------- | ---- | -------------------------------------------------------- | | `AUTH_MISSING` | 401 | Required credentials absent | | `AUTH_INVALID` | 401 | Bad JWT, bad key, or bad secret | | `AUTH_REVOKED` | 401 | API key revoked | | `FORBIDDEN` | 403 | Authenticated but not allowed (e.g. missing permission) | | `NOT_FOUND` | 404 | Market / key / chain not found | | `ORDER_NOT_FOUND` | 404 | `order_hash` not owned by caller or doesn't exist | | `MARKET_NOT_ACTIVE` | 422 | Market is not `OPEN` and the endpoint needs it to be | | `MARKET_NOT_CLOB` | 422 | Market is AMM — use the AMM routes instead | | `INSUFFICIENT_BALANCE` | 422 | Collateral or position shortfall | | `ORDER_EXPIRED` | 422 | Order past its `expiration` | | `ORDER_ALREADY_FILLED` | 422 | Cannot cancel a fully filled order | | `INVALID_SIGNATURE` | 422 | EIP-712 signature verification failed | | `WALLET_MISMATCH` | 422 | Order `signer` ≠ authenticated wallet | | `PRICE_OUT_OF_RANGE` | 422 | `price` outside `[0.01, 1.00]` | | `SIZE_TOO_SMALL` | 422 | `size` below the minimum | | `BATCH_SIZE_EXCEEDED` | 422 | More than 15 orders in one placement | | `IDEMPOTENCY_CONFLICT` | 409 | Same `fs-idempotency-key` replayed with a different body | | `SERVICE_DEGRADED` | 503 | Upstream (chain / DB / cache) unhealthy | | `INTERNAL_ERROR` | 500 | Anything uncaught | ## Inline vs HTTP errors `POST /v1/orders` splits errors two ways: * **Request-level** failures (batch size, auth) are **HTTP errors**. * **Per-order** rejections (wallet mismatch, bad signature, market closed) are returned **inline** inside `results[]`: ```json theme={null} { "error": { "code": "WALLET_MISMATCH", "message": "..." } } ``` Always iterate `results[]` and check each item. Success items have an `order_hash`. ## Batch caps | Endpoint | Max | | ---------------------------------------------- | --------------------------------------- | | `POST /v1/orders` | 15 orders per request | | `POST /v1/orders/cancel` (by hash) | 100 hashes per request | | `POST /v1/orders/cancel` (filter / cancel-all) | No fixed cap — all matching open orders | Exceeding the placement cap returns `BATCH_SIZE_EXCEEDED` (422). A hash list over 100 fails request validation (422). ## Idempotency Set `fs-idempotency-key: ` on `POST /v1/orders`: * Keyed per `(user, key)`, with the request body hash stored alongside the result. * **Same key + same body** → returns the cached result with `_idempotent_replayed: true`. * **Same key + different body** → `IDEMPOTENCY_CONFLICT` (409). * Honored on order placement only. ## Pagination All list endpoints (`/v1/markets`, `/v1/orders`, `/v1/fills`, `/v1/positions`, `/v1/markets/{id}/trades`) share a cursor envelope: ```json theme={null} { "data": [], "next_cursor": "...", "has_more": true } ``` * `cursor` — opaque string from the prior response's `next_cursor`. A malformed cursor is treated as no cursor. * `limit` — default `20`, max `100`. Results are ordered newest first (`created_at` descending). # CLOB Trading API Source: https://docs.foresight.now/foresight-apis/clob/introduction 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. 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. ## 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` | 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). ## Core concepts Every CLOB call identifies a market by its on-chain **`condition_id`** (ConditionalTokens condition hash) plus **`chain_id`**. Internal database identifiers are never exposed. 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`. 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. 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. `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. ## 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 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**. `GET /v1/markets?chain_id=56` lists open markets. Read `ctf_exchange_address` and the outcome `token_id`s you'll need to sign. Build the EIP-712 order, sign it with your wallet, and `POST /v1/orders`. See [Signing orders](/foresight-apis/clob/signing-orders). 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). ## 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 # Signing orders Source: https://docs.foresight.now/foresight-apis/clob/signing-orders Build and sign EIP-712 orders for the CLOB: the typed-data domain, the Order struct, the integer-tick maker/taker amount math, and a complete worked example. Orders are signed off-chain with EIP-712 typed data and submitted to `POST /v1/orders`. This page covers exactly what to sign and how to compute the amounts so the matching engine accepts your order. Amount math is unforgiving. `maker_amount` and `taker_amount` must be derived with **BigInt integer-tick math** at the collateral's decimals (18 on BSC), with **BUY ceiling** and **SELL flooring** the collateral. Anything signed with float arithmetic or the wrong decimals is rejected at ingest with `Drifted signed amounts`. ## EIP-712 domain ```ts theme={null} const domain = { name: "ForesightExchange", version: "1", chainId: 56, // BSC mainnet verifyingContract: market.ctf_exchange_address, // from GET /v1/markets/{id} }; ``` `verifyingContract` is the market's **`ctf_exchange_address`** — read it from the market object. Do not hard-code it; it can differ per chain. ## The `Order` struct The typed-data primary type is `Order`, with these 12 fields **in this 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" }, ], }; ``` | Field | Meaning | | --------------- | ------------------------------------------------------------------ | | `salt` | Random `uint256` (as a decimal string) for uniqueness | | `maker` | The wallet placing the order. **Must equal `signer`.** | | `signer` | The signing wallet. Must equal the authenticated wallet. | | `taker` | Counterparty restriction. Use the zero address for an open order. | | `tokenId` | ERC-1155 `token_id` of the outcome you're trading (from `/tokens`) | | `makerAmount` | What you give, in raw token wei. See [amount math](#amount-math). | | `takerAmount` | What you receive, in raw token wei | | `expiration` | Unix seconds; `0` = no expiry. Required non-zero for `GTD` orders. | | `nonce` | Order nonce | | `feeRateBps` | Fee in basis points (`100` = 1%) | | `side` | `0` = BUY, `1` = SELL | | `signatureType` | `0` = EOA, `1` = EIP-1271 (smart-contract wallet) | The order **kind** (`LIMIT` / `MARKET` / `GTD`) is **not** part of the signed struct — it travels on the REST request body only as `order_type`. The signed struct carries `side` as a number, not the human-readable string. ## Outcome → token Pick the `token_id` for the outcome you want from `GET /v1/markets/{condition_id}/tokens`: ```json theme={null} { "tokens": [ { "outcome": 0, "outcome_label": "NO", "token_id": "1234...", "decimals": 18 }, { "outcome": 1, "outcome_label": "YES", "token_id": "5678...", "decimals": 18 } ] } ``` To buy YES, sign with `outcome: 1` and the YES `token_id`. ## Prices are 2-decimal ticks A price is a YES probability in `[0.01, 1.00]`, quantized to **2 decimal places** (100 ticks). Sign at sub-tick precision and the on-chain crossing check can reject the match, so round first: ```ts theme={null} // "0.7657" -> "0.77" (round half up to 2dp) function quantizePrice(price: string): string { const [w = "0", f = ""] = price.split("."); if (f.length <= 2) return `${BigInt(w)}.${(f + "00").slice(0, 2)}`; let ticks = BigInt(w) * 100n + BigInt(f.slice(0, 2)); if (f[2] >= "5") ticks += 1n; return `${ticks / 100n}.${(ticks % 100n).toString().padStart(2, "0")}`; } ``` ## Amount math Read `decimals` from the market's `/tokens` response (**18 on BSC**). Then, with `price` (already quantized) and `size` as decimal strings: ``` BUY: makerAmount = ceil(size × price) (collateral you pay) takerAmount = size (shares you receive) SELL: makerAmount = size (shares you sell) takerAmount = floor(size × price) (collateral you receive) ``` All values are scaled to the collateral's `decimals`. **BUY ceils** the collateral and **SELL floors** it — this asymmetric rounding is what keeps the on-chain crossing check satisfied. It costs at most 1 wei. ```ts theme={null} const DECIMALS = 18n; // BSC — confirm via /tokens function toWei(decimal: string, decimals: bigint): bigint { const [w = "0", f = ""] = decimal.split("."); const frac = (f + "0".repeat(Number(decimals))).slice(0, Number(decimals)); return BigInt(w) * 10n ** decimals + BigInt(frac || "0"); } function computeAmounts(side: "BUY" | "SELL", price: string, size: string, decimals: bigint) { const sizeWei = toWei(size, decimals); const priceWei = toWei(price, decimals); const denom = 10n ** decimals; const collateral = side === "BUY" ? (sizeWei * priceWei + denom - 1n) / denom // ceil : (sizeWei * priceWei) / denom; // floor return side === "BUY" ? { makerAmount: collateral, takerAmount: sizeWei } : { makerAmount: sizeWei, takerAmount: collateral }; } ``` Stay in BigInt the entire way. `Number`, `parseFloat`, and `* price` on a float silently corrupt 18-decimal amounts by a few wei, which the ingest validator rejects. Compute collateral as `size × price` at full scale, then ceil (BUY) or floor (SELL). ## Complete example (viem) ```ts theme={null} import { createWalletClient, custom } from "viem"; const account = "0xYourWallet..."; const market = await ( await fetch("https://api.foresight.now/v1/markets/" + conditionId + "?chain_id=56") ).json(); const { tokens } = await ( await fetch( "https://api.foresight.now/v1/markets/" + conditionId + "/tokens?chain_id=56" ) ).json(); const outcome = 1; // YES const yes = tokens.find((t) => t.outcome === outcome); const decimals = BigInt(yes.decimals); // 18 on BSC const side = "BUY"; const price = quantizePrice("0.55"); const size = "100"; const { makerAmount, takerAmount } = computeAmounts(side, price, size, decimals); const struct = { salt: randomUint256(), // e.g. crypto.getRandomValues -> decimal string maker: account, signer: account, // maker must equal signer taker: "0x0000000000000000000000000000000000000000", tokenId: yes.token_id, makerAmount: makerAmount.toString(), takerAmount: takerAmount.toString(), expiration: "0", // no expiry nonce: "0", feeRateBps: "100", side: side === "BUY" ? 0 : 1, signatureType: 0, // EOA }; const walletClient = createWalletClient({ account, transport: custom(window.ethereum) }); const signature = await walletClient.signTypedData({ account, domain: { name: "ForesightExchange", version: "1", chainId: 56, verifyingContract: market.ctf_exchange_address, }, 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" }, ], }, primaryType: "Order", message: struct, }); ``` ## Submit the order The request body wraps the signed struct in snake\_case, plus the human-readable `order_type`, `outcome`, `price`, and `size`: ```bash theme={null} curl -X POST https://api.foresight.now/v1/orders \ -H "fs-api-key: $FS_API_KEY" \ -H "fs-api-secret: $FS_API_SECRET" \ -H "fs-idempotency-key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "orders": [{ "condition_id": "0x...", "chain_id": 56, "side": "BUY", "order_type": "LIMIT", "outcome": 1, "price": "0.55", "size": "100", "salt": "...", "signer": "0xYourWallet...", "taker": "0x0000000000000000000000000000000000000000", "token_id": "5678...", "maker_amount": "...", "taker_amount": "...", "expiration": "0", "nonce": "0", "fee_rate_bps": 100, "signature_type": 0, "signature": "0x..." }] }' ``` You can batch up to **15** orders per request. The response always returns `status: OPEN` for accepted orders — matching is asynchronous: ```json theme={null} { "results": [ { "order_hash": "0x...", "condition_id": "0x...", "chain_id": 56, "status": "OPEN", "side": "BUY", "outcome": 1, "price": "0.55", "size": "100", "remaining_size": "100", "fills": [], "book_added_at": null, "created_at": "2026-06-03T..." } ] } ``` Each item in `results[]` is **either** a success **or** an inline `{ "error": { "code", "message" } }`. A mixed array is normal — always inspect every item. Fills and status transitions arrive on the [`user` WebSocket channel](/foresight-apis/clob/websocket), not here. ## Idempotency Set an `fs-idempotency-key` header on `POST /v1/orders` to make retries safe. Replaying the **same key + same body** returns the cached result with `_idempotent_replayed: true`. The **same key + a different body** returns `IDEMPOTENCY_CONFLICT` (409). Idempotency is honored on order placement only. ## Cancelling * `POST /v1/orders/cancel` — cancel by hash (up to 100), by filter (`condition_id` + `chain_id` + optional `outcome`/`side`), or all (empty body). * `POST /v1/orders/{order_hash}/cancel-onchain` — returns unsigned calldata for a hard on-chain cancel against the CTF Exchange. You submit and pay for that transaction yourself; the backend does not send it. # WebSocket Source: https://docs.foresight.now/foresight-apis/clob/websocket Realtime CLOB feed: connect to /v1/ws, subscribe to public book/ticker/trades channels and the private user channel, and apply order-book deltas correctly. The realtime gateway streams orderbook, ticker, trade, and private user events. ``` wss://api.foresight.now/v1/ws[?token=] ``` * The token is **optional** — without it you can still subscribe to public channels. * The token is **required** for the private `user` channel. Get one from `POST /v1/auth/ws-token` (single-use, 60s TTL). See [Authentication](/foresight-apis/clob/authentication#websocket-tokens). Every message — inbound and outbound — is JSON with a `type` field. Invalid JSON gets `{ "type": "error", "message": "Invalid JSON" }`. ## Inbound messages (client → server) ### Ping ```json theme={null} { "type": "ping" } ``` The server replies `{ "type": "pong" }`. There is no server-initiated heartbeat — send `ping` yourself periodically. ### Subscribe Public channels require `condition_id` + `chain_id`: ```json theme={null} { "type": "subscribe", "channel": "book", "condition_id": "0x...", "chain_id": 56 } ``` The private channel requires only the channel name (events are wallet-scoped): ```json theme={null} { "type": "subscribe", "channel": "user" } ``` The server acks: ```json theme={null} { "type": "subscribed", "channel": "book", "condition_id": "0x...", "chain_id": 56 } ``` For the `book` channel, a `book_snapshot` is pushed immediately after the ack. ### Unsubscribe Same shape as `subscribe`; the server acks with `type: "unsubscribed"`. ## Channels ### Public | Channel | Carries | | -------- | ------------------------------------------------------ | | `book` | Orderbook snapshot (once) + `book_delta_batch` updates | | `ticker` | Best bid/ask and last-price updates | | `trades` | Public trade prints | ### Private | Channel | Carries | | ------- | ------------------------------------------------------------------------------ | | `user` | Every order-lifecycle, fill, and settlement event for the authenticated wallet | The `user` channel is a **single unified stream** — filter client-side on `event.type`. Subscribing to it without a valid token returns: ```json theme={null} { "type": "error", "code": "AUTH_REQUIRED", "message": "Private channel requires authentication" } ``` One market `(condition_id, chain_id)` yields **three** public subscriptions: `book`, `ticker`, and `trades`. There is no wildcard subscription — subscribe per market. ## Outbound messages (server → client) ### `book_snapshot` Sent once after subscribing to `book`, and again on reconnect. ```json theme={null} { "type": "book_snapshot", "condition_id": "0x...", "chain_id": 56, "seq": 42, "timestamp": 1713619200000, "bids": [{ "price": "0.54", "remainingSize": "123.45" }], "asks": [{ "price": "0.55", "remainingSize": "80.0" }] } ``` Adopt `seq` as your sequence anchor. Each book level is `{ price, remainingSize }` as decimal strings. ### `book_delta_batch` A batch of price-level updates coalesced from a single matcher commit or cancel. Apply all deltas as a group. ```json theme={null} { "type": "book_delta_batch", "condition_id": "0x...", "chain_id": 56, "seq": 43, "deltas": [ { "side": "BUY", "price": "0.62", "size": "450" }, { "side": "BUY", "price": "0.61", "size": "0" }, { "side": "SELL", "price": "0.64", "size": "120" } ] } ``` | Field | Meaning | | ---------------- | ------------------------------------------------------------------------------------------- | | `seq` | Monotonic per `(condition_id, chain_id)`. Increments by 1 per batch. Use for gap detection. | | `deltas[].side` | `BUY` = bids, `SELL` = asks | | `deltas[].price` | Price level (decimal string, 2dp) | | `deltas[].size` | New **total** remaining size at that level. `0` means remove the level. | Read levels from `deltas[]`, not from the top-level message. Each entry's `size` is the new aggregate size at that price — replace the level, or delete it when `size` is `0`. The same `(side, price)` never appears twice in one batch. ### `ticker` / `trade` ```json theme={null} { "type": "ticker", "condition_id": "0x...", "chain_id": 56, "...": "..." } { "type": "trade", "condition_id": "0x...", "chain_id": 56, "...": "..." } ``` ### `user` events The private `user` channel carries several event types — filter on `type`. **Order-lifecycle events** carry the full order snapshot (same shape as `GET /v1/orders/{hash}`): | `type` | Trigger | | -------------------- | ------------------------------------------------------------------------------------------------------------ | | `order_placement` | Order accepted and resting on the book | | `order_update` | `remaining_size` changed (partial fill or settlement rollback) | | `order_cancellation` | You cancelled the order | | `order_expired` | Engine evicted it (no liquidity for MARKET, expired LIMIT, rollback) | | `order_filled` | Fully matched — terminal `MATCHED`, then `FILLED` after settle | | `order_failed` | Async matcher exhausted retries / hit a permanent error — `MATCH_FAILED` (may include `match_failed_reason`) | ```json theme={null} { "type": "order_update", "order": { "order_hash": "0x...", "condition_id": "0x...", "chain_id": 56, "side": "BUY", "outcome": 1, "order_type": "LIMIT", "price": "0.55", "size": "100", "remaining_size": "60", "status": "PARTIALLY_FILLED", "token_id": "...", "fee_rate_bps": 100, "expiration": "0", "created_at": "...", "book_added_at": "...", "updated_at": "..." }, "timestamp": 1713619200000 } ``` **Fill events** (`type: "fill"`) — one per match per side: ```json theme={null} { "type": "fill", "order": { "...full order snapshot..." }, "fill": { "batch_id": "...", "price": 0.55, "size": 50 }, "trade_id": "...", "role": "maker", "timestamp": 1713619200000 } ``` **Settlement events** (`type: "settlement_update"`) — after on-chain settlement: ```json theme={null} { "type": "settlement_update", "settlement_status": "SETTLED", "tx_hash": "0x...", "trade_ids": ["..."], "timestamp": 1713619200000 } ``` `FAILED` settlements may include `error_code` / `error_reason`. ### `error` ```json theme={null} { "type": "error", "code": "AUTH_REQUIRED", "message": "..." } ``` `code` is optional. ## Applying book deltas Build `bids` and `asks` maps keyed by `price` from `book_snapshot`, using `{ price, remainingSize }`. Record `seq`. For every entry in `book_delta_batch.deltas` (in array order): pick the side (`BUY` → bids, `SELL` → asks). If `size` is `0`, delete the level; otherwise set the level to `size`. Track `seq` per market. If a batch arrives with `seq !== last + 1`, you missed an update — resync by re-fetching `GET /v1/markets/{id}/book` or re-subscribing (which sends a fresh snapshot). Sort bids high→low, asks low→high, slice to the depth you need. ## Reconnect 1. `POST /v1/auth/ws-token` → fresh token (single-use). 2. Open `wss://api.foresight.now/v1/ws?token=`. 3. Re-subscribe to every channel you need. 4. For `book`, the new `book_snapshot` resets your baseline — drop any deltas received before it. A slow consumer is dropped if its send buffer backs up past \~1 MiB (close code `1013`). Reconnect, re-subscribe, and pull a fresh snapshot. # Foresight API Documentation Source: https://docs.foresight.now/foresight-apis/foresight-api-documentation ## Trade API Documentation ### Overview The Trade API provides functionality to list markets, get trade quotes, and execute trades on prediction markets. ### Example ```typescript theme={null} import { createPublicClient, createWalletClient, http, type Hex } from 'viem' import { privateKeyToAccount } from 'viem/accounts' import { mainnet } from 'viem/chains' const publicClient = createPublicClient({ chain: mainnet, transport: http(), }) const TRADE_API_URL = '' // 1. Get available markets const marketsResponse = await fetch(`${TRADE_API_URL}/markets`) const markets = await marketsResponse.json() console.log('Available markets:', markets) // 2. Get a quote for a trade const marketAddress = '0x...' // Market contract address const amount = '100000000' // 100 USDC in base units (6 decimals) const outcome = 1 // 1 = YES, 0 = NO const tradeType = 'Buy' const quoteResponse = await fetch(`${TRADE_API_URL}/quote`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ market: marketAddress, amount: amount, outcome: outcome, type: tradeType }) }) const quote = await quoteResponse.json() console.log('Trade quote:', quote) // 3. Check and handle token approval (required for buying) const account = '0x...' // User wallet address const tokenAddress = '0x...' // USDC token address const spenderAddress = '0x...' // Market maker contract address // Check current allowance const allowance = await publicClient.readContract({ address: tokenAddress, abi: erc20ABI, functionName: 'allowance', args: [account, spenderAddress] }) // If allowance is insufficient, approve the spender if (allowance < BigInt(amount)) { const approveHash = await walletClient.writeContract({ address: tokenAddress, abi: erc20ABI, functionName: 'approve', args: [spenderAddress, BigInt('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff')] }) // Wait for approval confirmation await publicClient.waitForTransactionReceipt({ hash: approveHash }) console.log('Token approval confirmed') } // 4. Create a trade intent and get execution data // POST /trade requires a platform API key. const executeResponse = await fetch(`${TRADE_API_URL}`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string, }, body: JSON.stringify({ market: marketAddress, amount: amount, outcome: outcome, type: tradeType, account: account }) }) const tradeData = await executeResponse.json() console.log('Trade execution data:', tradeData) // tradeData: { intentId, marketType: 'AMM' | 'CLOB', market, outcome, amount, // estimatedReturn, price, tx? (AMM) | typedData? (CLOB) } // For AMM markets, tradeData.tx is the encoded transaction to send. // (For CLOB markets you receive tradeData.typedData to sign instead.) if (tradeData.tx) { // Simulate the transaction first (sign/send from the user's own account) const callResult = await publicClient.call({ account: account, data: tradeData.tx.data, to: tradeData.tx.to, value: BigInt(tradeData.tx.value), }) console.log('Simulation result:', callResult) // Send the actual transaction const PRIVATE_KEY = process.env.PRIVATE_KEY as Hex const walletClient = createWalletClient({ chain: mainnet, transport: http(), }) const hash = await walletClient.sendTransaction({ account: privateKeyToAccount(PRIVATE_KEY), data: tradeData.tx.data, to: tradeData.tx.to, value: BigInt(tradeData.tx.value), }) console.log('Transaction hash:', hash) // 5. Save the transaction hash. Call this right after broadcasting — // you do not need to wait for the transaction receipt. await fetch(`${TRADE_API_URL}/save`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string, }, body: JSON.stringify({ txHash: hash, chainId: 8453 }), // chainId = chain the trade was sent on }) } // 6. Get user positions and redeem winning positions async function redeemWinningPositions(userAddress: string) { // Get resolved positions const positionsResponse = await fetch(`${TRADE_API_URL}/positions?walletAddress=${userAddress}&type=resolved&pg=1&ps=20`) const positionsData = await positionsResponse.json() // Filter for claimable positions (resolved markets where user has winning shares) const claimablePositions = positionsData.positions.filter(position => position.resolutionOutcome === position.outcome && position.totalShareAmount > 0 ) console.log(`Found ${claimablePositions.length} claimable positions`) // Redeem each claimable position for (const position of claimablePositions) { try { // POST /trade/redeem requires a platform API key. const redeemResponse = await fetch(`${TRADE_API_URL}/redeem`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string, }, body: JSON.stringify({ market: position.market, account: userAddress }) }) const redeemData = await redeemResponse.json() if (redeemData.tx) { // Simulate the transaction first const callResult = await publicClient.call({ account: redeemData.tx.account, data: redeemData.tx.data, to: redeemData.tx.to, value: BigInt(redeemData.tx.value), }) console.log('Redeem simulation successful') // Send the actual transaction const redeemHash = await walletClient.sendTransaction({ data: redeemData.tx.data, to: redeemData.tx.to, value: BigInt(redeemData.tx.value), }) console.log('Redeem transaction hash:', redeemHash) // Wait for confirmation — the indexer auto-processes the redeem. // Redeems need no /trade/save or /trade/complete call. await publicClient.waitForTransactionReceipt({ hash: redeemHash }) } } catch (error) { console.error(`Error redeeming position for market ${position.market}:`, error) } } } // Usage example // await redeemWinningPositions('0x...') // User wallet address ``` ## API Endpoints ### 1. GET `/trade/markets` - Get All Tradeable Markets Returns a list of all available prediction markets. Public — no API key required. **Query Parameters:** ```typescript theme={null} interface MarketsQuery { chainId?: number; // Optional. If omitted, defaults to the legacy default chain. } ``` **Response:** ```typescript theme={null} interface MarketInfo { address: string; question: string; marketType: 'AMM' | 'CLOB'; // Which trading API this market needs (a chain can host both) outcome1Price: number; // Current price for the YES outcome (index 1) outcome0Price: number; // Current price for the NO outcome (index 0) endDate: string; // ISO-8601 (market group end) volume: number; // All-time cumulative volume in human USD (already normalized by chain decimals — do NOT divide again) transactionCount: number; // All-time cumulative trade count createdAt: string; // ISO-8601 — when the market instance became tradeable on its chain } ``` > `volume` is normalized server-side (`raw / 10^chainDecimals`), so it is already in human USD — do **not** divide it again client-side. This works for 18-decimal collateral too; never hardcode `1e6`. **Example:** ```typescript theme={null} const markets = await fetch(`${TRADE_API_URL}/markets`) // or `${TRADE_API_URL}/markets?chainId=8453` const data = await markets.json() ``` ### 2. POST `/trade/quote` - Get Trade Quote Get pricing information for a potential trade. Public — no API key required. **Request:** ```typescript theme={null} interface TradeQuoteRequest { market: string; // Market contract address amount: string; // Amount in base units (6 decimals for USDC) outcome: 0 | 1; // 0 = NO, 1 = YES type: 'Buy' | 'Sell'; // Trade type chainId?: number; // Optional. Auto-resolved from the market when omitted. } ``` **Response:** ```typescript theme={null} interface TradeQuote { market: string; tokenAddress: string; // Token to approve (collateral for buy; ERC1155 setApprovalForAll for sell) amount: string; outcome: 0 | 1; type: 'Buy' | 'Sell'; estimatedReturn: string; estimatedPricePerShare: number; } ``` **Example:** ```typescript theme={null} const quote = await fetch(`${TRADE_API_URL}/quote`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ market: "0x...", amount: "100000000", // 100 USDC outcome: 1, // YES type: "Buy" }) }) const data = await quote.json() ``` ### 3. POST `/trade` - Create Trade Intent Creates a `TransactionIntent` and returns the data needed to execute the trade. The response shape depends on the market model: * **AMM markets** return an encoded `tx` block to sign and send. * **CLOB markets** return an EIP-712 `typedData` block to sign. **Requires a platform API key.** Send it as the `X-Platform-API-Key` header (or `Authorization: Bearer `). Without it the request is rejected with `401`. **Request:** ```typescript theme={null} interface TradeExecuteRequest { market: string; // Market contract address amount: string; // Amount in base units (6 decimals for USDC) outcome: 0 | 1; // 0 = NO, 1 = YES type: 'Buy' | 'Sell'; // Trade type account: string; // User wallet address chainId?: number; // Optional. Auto-resolved from the market when omitted. } ``` **Response:** ```typescript theme={null} interface TradeIntentResponse { intentId: string; // ID of the created TransactionIntent marketType: 'AMM' | 'CLOB'; // Determines whether `tx` or `typedData` is present market: string; outcome: 0 | 1; amount: string; // Echoed from the request (base units) estimatedReturn: string; // Shares for buy, USDC for sell (base units) price: number; // Estimated price per share tx?: { // AMM only to: string; // Contract address to send transaction to (the market) data: string; // Transaction data (encoded function call) value: string; // ETH value to send (usually "0") chainId: number; // Chain the transaction must be submitted on }; typedData?: object; // CLOB only — EIP-712 typed data to sign } ``` The AMM `tx` block no longer includes an `account` field. Sign and send the transaction from the user's own wallet (the `account` you passed in the request). **Example:** ```typescript theme={null} const tradeData = await fetch(`${TRADE_API_URL}`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string, }, body: JSON.stringify({ market: "0x...", amount: "100000000", outcome: 1, type: "Buy", account: "0x..." // user wallet address }) }) const data = await tradeData.json() // AMM markets: send transaction using the user's wallet client const hash = await walletClient.sendTransaction({ data: data.tx.data, to: data.tx.to, value: BigInt(data.tx.value), account: "0x...", // the same user wallet address }) // POST `/trade/save` - Record the broadcast trade for origin attribution. // Send the transaction hash right after broadcasting; no need to wait for the receipt. await fetch(`${TRADE_API_URL}/save`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string, }, body: JSON.stringify({ txHash: hash, chainId: 8453 }), }) // No /trade/complete call is required — the indexer auto-processes the confirmed transaction. ``` ### 4. POST `/trade/redeem` - Execute Redeem Generate redeem calldata for executing a redeem transaction on resolved markets where the user has winning positions. **Requires a platform API key** (`X-Platform-API-Key` header, or `Authorization: Bearer `). **Request:** ```typescript theme={null} interface RedeemExecuteRequest { market: string; // Market contract address account: string; // User wallet address chainId?: number; // Optional. Auto-resolved from the market when omitted. } ``` **Response:** ```typescript theme={null} interface RedeemExecuteResponse { tx: { to: string; // Contract address to send transaction to data: string; // Transaction data (encoded function call) account: string; // User account address value: string; // ETH value to send (usually "0") }; expectedReturn: string; // Expected return amount in base units market: string; // Market address } ``` **Example:** ```typescript theme={null} const redeemData = await fetch(`${TRADE_API_URL}/redeem`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string, }, body: JSON.stringify({ market: "0x...", // Market contract address account: "0x..." // User wallet address }) }) const data = await redeemData.json() // Send transaction using wallet client const hash = await walletClient.sendTransaction({ data: data.tx.data, to: data.tx.to, value: BigInt(data.tx.value), account: data.tx.account, }) // Redeems are recorded automatically — no save or completion call needed. ``` ### 5. GET `/trade/positions` - Get User Positions Retrieve user positions with pagination support. Supports filtering by active or resolved markets. **Query Parameters:** ```typescript theme={null} interface PositionsQuery { walletAddress: string; // User wallet address (required) type: 'active' | 'resolved'; // Filter by market status (required) pg?: number; // Page number (default: 1) ps?: number; // Page size (default: 20, max: 100) } ``` **Response:** ```typescript theme={null} interface UserPositionsResponse { positions: Array<{ market: string; // Market address tokenAddress: string; // Token address for the market shares amountInvested: number; // Amount invested in collateral token (in base units) outcome: 0 | 1; // Outcome index bought (0 for NO, 1 for YES) totalShareAmount: number; // Total share amount held (in base units) question: string; // Market question resolutionOutcome: number | null; // Resolution outcome (0 for NO, 1 for YES, -1 for DRAW/TIE; null if market not resolved) marketEndDate: string | null; // Market end date }>; page: number; // Current page number pageSize: number; // Number of items per page hasPrevious: boolean; // Whether there is a previous page hasNext: boolean; // Whether there is a next page totalCount: number; // Total number of positions for a given user } ``` **Example:** ```typescript theme={null} const positions = await fetch(`${TRADE_API_URL}/positions?walletAddress=0x...&type=resolved&pg=1&ps=20`) const data = await positions.json() // Filter for claimable positions (resolved markets where user has winning shares) const claimablePositions = data.positions.filter(position => position.resolutionOutcome === position.outcome && position.totalShareAmount > 0 ) // Redeem each claimable position for (const position of claimablePositions) { const redeemData = await fetch(`${TRADE_API_URL}/redeem`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string, }, body: JSON.stringify({ market: position.market, account: "0x..." // User wallet address }) }) // ... execute redeem transaction } ``` ### 6. POST `/trade/save` - Save Trade After broadcasting a trade transaction, send its transaction hash to this endpoint. Call it right after submitting the transaction — you do **not** need to wait for the transaction receipt. **Headers:** * `X-Platform-API-Key: ` **Request:** ```typescript theme={null} interface TradeSaveRequest { txHash: string; // 0x-prefixed 32-byte transaction hash from broadcast chainId: number; // EVM chain id the transaction was sent on } ``` **Response:** ```typescript theme={null} interface TradeSaveResponse { ok: true; } ``` ## Token Approval Process Before executing trades, users must approve the market maker contract to spend their tokens. This is a standard ERC-20 requirement. ### Approval Steps 1. **Check Current Allowance**: Query the token contract to see how much the market maker is allowed to spend 2. **Approve if Needed**: If allowance is insufficient, call the `approve` function on the token contract 3. **Wait for Confirmation**: Wait for the approval transaction to be confirmed 4. **Execute Trade**: Proceed with the trade execution ### Example Approval Code ```typescript theme={null} // Check current allowance const allowance = await publicClient.readContract({ address: tokenAddress, // USDC token address abi: erc20ABI, functionName: 'allowance', args: [userAddress, marketMakerAddress] }) // Approve if needed (using max uint256 for unlimited approval) if (allowance < BigInt(tradeAmount)) { const approveHash = await walletClient.writeContract({ address: tokenAddress, abi: erc20ABI, functionName: 'approve', args: [marketMakerAddress, BigInt('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff')] }) await publicClient.waitForTransactionReceipt({ hash: approveHash }) } ``` ### Important Notes * **Buy trades require approval**: Only buying tokens requires token approval * **Sell trades require ERC1155 setApprovalForAll**: Selling conditional tokens require ERC1155 approval, as we are using ERC1155 to represent market shares * **Unlimited approval**: The example uses max uint256 for unlimited approval to avoid repeated approval transactions * **Gas costs**: Approval transactions require gas fees, so consider this in your UX ## Key Notes * All amounts are handled in base units (6 decimals for USDC) * The execute endpoint returns transaction data that must be signed and sent by the user's wallet * Always simulate transactions before execution to catch potential failures * Token approval is required before executing any trades * After broadcasting a trade, send its transaction hash to `/trade/save`. Call it right after submitting — you do not need to wait for the transaction receipt. * The API follows RESTful conventions with appropriate HTTP status codes * `/trade` and `/trade/redeem` require a platform API key (`X-Platform-API-Key`); `/trade/markets`, `/trade/quote`, and `/trade/positions` are public * `/trade` returns a trade **intent** — AMM markets include a `tx` block, CLOB markets include `typedData` * Use `/trade/positions` to get a user's positions * Use `/trade/redeem` to get the calldata neccessary to redeem a position * No `/trade/complete` call is needed after a trade or redeem — the indexer auto-processes confirmed transactions * `/trade/save` applies to trades only (origin attribution); redeems need no save call The API follows a clear pattern where: * **Markets endpoint** provides available trading opportunities * **Quote endpoint** calculates trade details and pricing * **Execute endpoint** prepares blockchain transaction data for the user to sign and send * **Save endpoint** records the broadcast trade's transaction hash for the backend * **Positions endpoint** retrieves user's current positions with pagination * **Redeem endpoint** prepares redeem transaction data for winning positions * Indexer processes confirmed transactions to ensure positions appear in the frontend # Foresight API Swagger Source: https://docs.foresight.now/foresight-apis/foresight-api-swagger This section provides developers with interactive API documentation to explore and test Foresight’s endpoints. It is intended for building integrations, automating workflows, and accessing platform data programmatically. The core Trade API endpoints are: **GET** `/trade/markets` - Get all active markets and details (public) **POST** `/trade/quote` - To get price and number of shares to purchase based on amount to bet (public) **POST** `/trade` - Create a trade intent and get calldata (AMM) or EIP-712 typed data (CLOB). **Requires a platform API key.** **POST** `/trade/save` - Send the transaction hash after broadcasting a trade for origin attribution (requires a platform API key) **GET** `/trade/positions` - Fetch active or resolved positions for a wallet (public) **POST** `/trade/redeem` - Generate redeem calldata for a resolved market. **Requires a platform API key.** > **Authentication.** `/trade/markets`, `/trade/quote`, and `/trade/positions` are public. `/trade` and `/trade/redeem` require a platform API key, sent as the `X-Platform-API-Key` header (or `Authorization: Bearer `). Iframe partner tokens are additionally gated on the `trade` / `redeem` capability. > **`chainId`.** Trading endpoints accept an optional `chainId`; when omitted the API resolves the market's chain automatically and falls back to the default chain for legacy markets. `/trade/complete` (deprecated) requires `chainId`. Below is the Swagger API yaml for reference: ```yaml theme={null} openapi: 3.0.3 info: title: Trade API description: API to enable trading on Foresight version: 1.0.0 contact: name: Foresight Team servers: - url: http://localhost:3000 description: Development server - url: https://api.foresight.now description: Production server paths: /trade/markets: get: tags: - Trade summary: Gets all active markets and details that are available/active for trading description: Retrieve all markets available for trading, with details such as marketAddress, outcomePrices (outcome1 for YES, outcome0 for NO), marketEndDate, the marketQuestion, and trading-activity metadata (volume in human USD, transactionCount, createdAt). operationId: getTradeableMarkets parameters: - name: chainId in: query required: false description: Optional chain network id. If omitted, tradeable markets default to the legacy default chain. schema: type: integer minimum: 1 example: 8453 responses: '200': description: Returns list of active markets with details content: application/json: schema: type: array items: $ref: '#/components/schemas/MarketInfoResponseDTO' /trade/quote: post: tags: - Trade summary: Generates a quote based on the given marketAddress, outcome to bet on (1 for YES, 0 for NO) and amount(USDC). Returns the estimated shares bought for the given amount description: Generates a quote based on the given marketAddress, outcome and amount(USDC), with details such as the estimateReturn amount based on the input amount, and the estimatedPricePerShare. operationId: getTradeQuote requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeDTO' responses: '200': description: Quote generated based on the given marketAddress, outcome and amount(USDC). content: application/json: schema: $ref: '#/components/schemas/TradeQuoteResponseDTO' /trade: post: tags: - Trade summary: Create a trade intent and return execution data. Requires a platform API key. description: > Reads the market's model (AMM vs CLOB), creates a TransactionIntent, and returns the data needed to execute. For AMM markets the response includes an encoded `tx` block to sign and send; for CLOB markets it includes an EIP-712 `typedData` block to sign. Requires the `X-Platform-API-Key` header (or `Authorization: Bearer `). operationId: prepareExecuteTrade security: - PlatformApiKey: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeExecuteDTO' responses: '201': description: Intent created. AMM responses include a `tx` block; CLOB responses include a `typedData` block. content: application/json: schema: $ref: '#/components/schemas/TradeIntentResponseDTO' '401': description: Missing or invalid platform API key content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '404': description: Market not found content: application/json: schema: $ref: '#/components/schemas/NotFoundError' /trade/redeem: post: tags: - Trade summary: Generates redeem calldata necessary for executing a redeem transaction based on given arguments. Requires a platform API key. description: "Generates the calldata necessary to execute a redeem transaction for a given resolved market, and the expected return amount in base units. Requires the `X-Platform-API-Key` header (or `Authorization: Bearer `)." operationId: prepareExecuteRedeem security: - PlatformApiKey: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RedeemExecuteDTO' responses: '201': description: Returns the expected return amount in base units and the calldata necessary to execute a redeem transaction for a given resolved market content: application/json: schema: $ref: '#/components/schemas/RedeemExecuteResponseDTO' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Missing or invalid platform API key content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '404': description: Market not found content: application/json: schema: $ref: '#/components/schemas/NotFoundError' /trade/save: post: tags: - Trade summary: Save a broadcast trade's transaction hash description: | Send the transaction hash here right after broadcasting a trade. You do not need to wait for the transaction receipt. operationId: saveTrade parameters: - name: X-Platform-API-Key in: header required: true description: Your platform API key schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeSaveRequestDTO' responses: '201': description: Trade saved content: application/json: schema: $ref: '#/components/schemas/TradeSaveResponseDTO' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/BadRequestError' /trade/positions: get: tags: - Trade summary: Get positions for a given user, with pagination support description: Retrieve user positions (active or resolved) with pagination support. operationId: getUserPositions parameters: - name: walletAddress in: query required: true description: User wallet address schema: type: string pattern: '^0x[a-fA-F0-9]{40}$' example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' - name: type in: query required: true description: Filter positions by market status schema: type: string enum: [active, resolved] example: 'active' - name: pg in: query required: false description: Page number (default 1) schema: type: integer minimum: 1 default: 1 example: 1 - name: ps in: query required: false description: Page size (default 20) schema: type: integer minimum: 1 maximum: 100 default: 20 example: 20 responses: '200': description: Returns the positions and details for a given user, with pagination support content: application/json: schema: $ref: '#/components/schemas/UserPositionsResponseDTO' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' components: schemas: TradeType: type: string enum: - Buy - Sell description: Type of trade operation TradeDTO: type: object required: - market - amount - outcome - type properties: market: type: string description: Market address example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' pattern: '^0x[a-fA-F0-9]{40}$' amount: type: string description: Amount in USDC in base units example: '100000000' pattern: '^[0-9]+$' outcome: type: integer description: Outcome selection example: 1 enum: [0, 1] type: $ref: '#/components/schemas/TradeType' chainId: type: integer description: Optional chain network id. If omitted, the API resolves the market chain automatically and falls back to the default chain for legacy markets. minimum: 1 example: 8453 TradeExecuteDTO: allOf: - $ref: '#/components/schemas/TradeDTO' - type: object required: - account properties: account: type: string description: User Address example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' pattern: '^0x[a-fA-F0-9]{40}$' TradeQuoteResponseDTO: type: object required: - market - tokenAddress - amount - outcome - type - estimatedReturn - estimatedPricePerShare properties: market: type: string description: Market address example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' tokenAddress: type: string description: Address of token to call approval on (setApprovalForAll for sell since our market shares are ERC1155) example: '0x9F42B4e7A1C16DAF7c09A0ad8F47CF8206C5b9A3' amount: type: string format: bigint description: Amount in USDC in base units example: '100' outcome: type: integer description: Outcome selection example: 1 enum: [0, 1] type: $ref: '#/components/schemas/TradeType' estimatedReturn: type: string format: bigint description: Estimated return (shares for buy, USDC for sell) example: '95.5' estimatedPricePerShare: type: number format: float description: Estimated price per share example: '0.24' TransactionDetailsDTO: type: object required: - to - data - account - value properties: to: type: string description: Contract address to send transaction to example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' data: type: string description: Encoded function call data example: '0x1234567890abcdef...' account: type: string description: Account address executing the trade example: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6' value: type: string description: Value in wei sent with this transaction (typically 0 for USDC trades) example: '0' TradeExecuteResponseDTO: allOf: - $ref: '#/components/schemas/TradeQuoteResponseDTO' - type: object required: - tx properties: tx: $ref: '#/components/schemas/TransactionDetailsDTO' TradeSaveRequestDTO: type: object required: - txHash - chainId properties: txHash: type: string description: Transaction hash from broadcast example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' pattern: '^0x[a-fA-F0-9]{64}$' chainId: type: integer description: EVM chain id the transaction was sent on example: 8453 TradeSaveResponseDTO: type: object required: - ok properties: ok: type: boolean description: Always true example: true MarketInfoResponseDTO: type: object required: - address - question - marketType - outcome1Price - outcome0Price - endDate - volume - transactionCount - createdAt properties: address: type: string description: Market address example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' question: type: string description: Market question example: 'Will Bitcoin reach $100,000 by end of 2024?' marketType: type: string enum: ['AMM', 'CLOB'] description: >- Trading model for this market. AMM → execute via POST /trade (returns tx). CLOB → sign the EIP-712 order. A chain can host both, so callers must branch on this. example: 'AMM' outcome1Price: type: number format: float description: Current price for YES outcome example: 0.65 outcome0Price: type: number format: float description: Current price for NO outcome example: 0.35 endDate: type: string format: date-time description: Market group end date example: '2024-12-31T23:59:59Z' volume: type: number description: >- All-time cumulative trading volume in human USD, already normalized by the chain's collateral decimals (raw / 10^chainDecimals) — do NOT divide again client-side. example: 12345.67 transactionCount: type: integer description: All-time cumulative number of trades on this market. example: 421 createdAt: type: string format: date-time description: When this market instance became tradeable on its chain (ISO 8601). example: '2024-01-15T08:30:00Z' RedeemExecuteDTO: type: object required: - market - account properties: market: type: string description: Market address example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' pattern: '^0x[a-fA-F0-9]{40}$' account: type: string description: User Address example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' pattern: '^0x[a-fA-F0-9]{40}$' chainId: type: integer description: Optional chain network id. If omitted, the API resolves the market chain automatically and falls back to the default chain for legacy markets. minimum: 1 example: 8453 RedeemExecuteResponseDTO: type: object required: - tx - expectedReturn - market properties: tx: $ref: '#/components/schemas/TransactionDetailsDTO' expectedReturn: type: string format: bigint description: Expected return amount in base units example: '100' market: type: string description: Market address example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' UserPositionDTO: type: object required: - market - tokenAddress - amountInvested - outcome - totalShareAmount - question - resolutionOutcome - marketEndDate properties: market: type: string description: Market address example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' tokenAddress: type: string description: Token address for the market shares example: '0x9F42B4e7A1C16DAF7c09A0ad8F47CF8206C5b9A3' amountInvested: type: number description: Amount invested in collateral token (in base units) example: 100.5 outcome: type: integer description: Outcome index bought (0 for NO, 1 for YES) enum: [0, 1] example: 1 totalShareAmount: type: number description: Total share amount held (in base units) example: 95.5 question: type: string description: Market question example: 'Will Bitcoin reach $100,000 by end of 2024?' resolutionOutcome: type: integer nullable: true description: Resolution outcome (0 for NO, 1 for YES, -1 for DRAW/TIE; null if market not resolved) enum: [-1, 0, 1] example: 1 marketEndDate: type: string format: date-time nullable: true description: Market end date example: '2024-12-31T23:59:59Z' UserPositionsResponseDTO: type: object required: - positions - page - pageSize - hasPrevious - hasNext - totalCount properties: positions: type: array items: $ref: '#/components/schemas/UserPositionDTO' page: type: integer description: Current page number example: 1 pageSize: type: integer description: Number of items per page example: 20 hasPrevious: type: boolean description: Whether there is a previous page example: false hasNext: type: boolean description: Whether there is a next page example: true totalCount: type: integer description: Total number of positions for a given user example: 45 BadRequestError: type: object required: - message properties: message: type: string description: Error message example: 'Bad request' statusCode: type: integer description: HTTP status code example: 400 error: type: string description: Error type example: 'Bad Request' NotFoundError: type: object required: - message properties: message: type: string description: Error message example: 'Market not found' statusCode: type: integer description: HTTP status code example: 404 error: type: string description: Error type example: 'Not Found' InternalServerError: type: object required: - message properties: message: type: string description: Error message example: 'Failed to get trade quote' statusCode: type: integer description: HTTP status code example: 500 error: type: string description: Error type example: 'Internal Server Error' IntentTxDTO: type: object required: - to - data - value - chainId properties: to: type: string description: Contract address to send the transaction to (the market address for AMM trades) example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' data: type: string description: Encoded function call data example: '0x1234567890abcdef...' value: type: string description: Value in wei sent with this transaction (typically '0' for USDC trades) example: '0' chainId: type: integer description: Chain id the transaction must be submitted on example: 8453 TradeIntentResponseDTO: type: object required: - intentId - marketType - market - outcome - amount - estimatedReturn - price properties: intentId: type: string description: ID of the TransactionIntent created for this trade example: 'clx1a2b3c4d5e6f7g8h9' marketType: type: string enum: [AMM, CLOB] description: Market model. AMM responses carry a `tx` block; CLOB responses carry a `typedData` block. example: 'AMM' market: type: string description: Market address (echoed from the request) example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F' outcome: type: integer enum: [0, 1] description: Outcome selection (echoed from the request) example: 1 amount: type: string description: Amount in USDC base units (echoed from the request) example: '100000000' estimatedReturn: type: string format: bigint description: Estimated return (shares for buy, USDC for sell) in base units example: '95500000' price: type: number format: float description: Estimated price per share example: 0.24 tx: description: AMM only — encoded transaction to sign and send. Absent for CLOB markets. allOf: - $ref: '#/components/schemas/IntentTxDTO' typedData: type: object additionalProperties: true description: CLOB only — EIP-712 typed data to sign. Absent for AMM markets. securitySchemes: PlatformApiKey: type: apiKey in: header name: X-Platform-API-Key description: "Platform API key. May also be supplied as `Authorization: Bearer `." tags: - name: Trade description: Trading endpoints for Foresight. Includes endpoints for getting active markets, generating quotes for trades and getting calldata to execute a trade ``` # Brand Assets Source: https://docs.foresight.now/foresight-brand-assets/downloadables * [Download Foresight Brand Guidelines (PDF)](https://file.notion.so/f/f/ce00c82b-76b3-48fe-bc32-83ad56570910/5ffe4a35-ec6b-49c4-9541-e1b75ed39a30/Foresight_Brand_Deck.pdf?table=block\&id=1c6f40b9-92df-8015-a3fd-e01b92b27c53\&spaceId=ce00c82b-76b3-48fe-bc32-83ad56570910\&expirationTimestamp=1769774400000\&signature=RGAQTGjpkoF6h1o4fZL1nvTusTvdPjydMYmgf56Z0-0\&downloadName=Foresight+Brand+Guideline.pdf) * [Download Foresight Brand Pack (ZIP)](https://file.notion.so/f/f/ce00c82b-76b3-48fe-bc32-83ad56570910/650f455a-3562-4f7f-8b90-bfc6db59d6f3/Foresight_Brand_Pack.zip?table=block\&id=1d9f40b9-92df-8081-a7ff-ce4c2460681e\&spaceId=ce00c82b-76b3-48fe-bc32-83ad56570910\&expirationTimestamp=1769774400000\&signature=MbwUsFLH359CnLT0esMVNth8F0z5vrFT8PJoHFin-UM\&downloadName=Foresight+Brand+Pack.zip) # FAQs Source: https://docs.foresight.now/guides/arena-markets/arena-faqs * The feature will be opened to all users, anyone can create a market. * Yes. All Arena markets must include a defined end date that specifies when the event outcome will be determined and the market will resolve. * The seeding phase must run for at least 2 days and ends no later than **3 days before the market’s resolution date**. Markets that do not reach the seeding goal by this deadline will fail. * Markets must be clear, factual, objectively verifiable, and time-bound. Questions must have a reliable source of truth and are typically structured as **Yes / No** outcomes. * You must fund at least **\$100** to create a market. The market must reach **\$1,000 in total seeding** to activate trading. * No. Funds are locked during seeding and cannot be withdrawn unless the market fails or the event resolves during the seeding period. * The market enters a **Failed** state. Seeders can withdraw their funds with a **5% penalty fee** applied. * The market enters a **cancelled** state, all seeded funds are refunded without any added fees. * No. Market questions, sources, and deadlines cannot be changed after publishing. * Creators and seeders receive **50% of the trading fees** generated by the market once it resolves. * Funds become claimable once the market reaches the **Resolved** state and the outcome is verified. * It is not possible to seed a market on the wrong network. The transaction will fail. * Markets are resolved using the predefined source of truth and resolution rules shown on each market. # Arena Market Creation Source: https://docs.foresight.now/guides/arena-markets/arena-market-creation Allows anyone to create and participate in user-generated prediction markets. Instead of waiting for official listings, users can propose verifiable events, seed liquidity with conviction, and earn rewards from market activity. ## Foresight Arena Community Market Creation {EECC0562 0FA5 4C06 A699 78FCFD0055FD} Foresight also supports community-driven market creation through **Arena**. Arena allows users and communities to propose and launch their own markets around niche topics, experiments, and emerging narratives.\ \ Before a market becomes publicly tradable, it enters a [**Seeding Phase**](/guides/arena-markets/arena-seeding), where creators and early supporters stake initial liquidity to demonstrate conviction and validate demand. Markets that successfully reach their seeding requirements graduate into open trading, while insufficiently seeded markets expire. Seeding aligns incentives between creators and participants, encourages higher-quality market proposals, and helps ensure healthy liquidity once trading begins. Community-created markets follow platform rules for clarity, resolution integrity, and abuse prevention. This enables decentralized innovation while maintaining market quality and trust. Arena empowers communities to define what is worth predicting not just the platform. ## How it works: * **Market Creation:** Submit a clear market question with a verifiable source of truth **and a defined end date**. Seed at least \$100 to show conviction. We approve and launch within 12 hours. There is no maximum duration for a user-generated market, but users must adhere to the minimum durations and criteria below. * **Seeding Phase** (**minimum** **2 days**, seeding **deadline** occurs **3 days** before the market’s resolution date): Needs **\$1,000** seeded to graduate a market. No withdrawals during this period. If not seeded by deadline, there’s a 5% penalty on your initial bet. If event resolves during seeding, all bets refunded. * **Trading Phase (min 3 days, total ≥ 5 days):** Once fully seeded, the market appears on the homepage for open trading and price discovery. Users can freely buy or sell positions. * **Resolution & Rewards:** Creators/seeders earn 50% of market trading fees regardless of which side they bet. Future bonuses and incentives will be added! ## Arena Market Creation Step-by-Step ### 1. Pick a topic Image * Choose a topic for your market * Choose a **topic category** that best matches your market idea Crypto, Sports, Gaming, Politics, Entertainment, Culture or Custom. * Each topic represents a different type of event. Example: * **Crypto:** Price movements, protocol upgrades, or token listings. *Example:* “Will Ethereum trade above \$3,500 by the end of October?” * **Sports:** Match results, player stats, or season outcomes. *Example:* “Will Team A win the championship this year?” * **Gaming:** Esports tournaments, in-game events, or release dates. *Example:* “Will Game X’s new patch launch before November?” * **Custom**: If none of the topic matches the question you want to create, just add a custom one! ### 2. Formulate your question Image(1) * Write a clear, factual question with a verifiable outcome, ideally designed as a **YES/NO** prediction. * Example: “Will Bitcoin close above \$70,000 on December 31, 2025?” * Make sure your question is time-specific and objectively resolvable. * You can upload an image for your market. If you don't provide one, the admins will add an appropriate image for you (The image uploaded must be a square image). ### 3. Provide a source of truth Image(2) * Provide a **verifiable source** that will confirm the event's outcome once it resolves. * This could be: * a specific news website * a reputable data source (such as ESPN, CoinGecko, etc.) * an official government record * NOTE: Don't use general websites like `google.com` or `yahoo.com`. The source should be directly relevant to the market question. ### 4. Set Event Deadline Deadline * Set the date and time when your market will close and the event outcome will be determined. **All Arena markets must include a defined end date.** * The deadline should match the timeframe in your question (e.g., the end of a tournament, a specific announcement date, or a crypto price snapshot). * Markets must meet these timing requirements: * Minimum 2 days for seeding * This allows enough time for users to discover and seed the market. * Minimum 3 days for trading * Once the market graduates from seeding, it needs at least 3 days of active trading ### 5. Seed Initial Liquidity {B74286B9 F7BC 483A 8C13 3125CA6CD899} * Decide how much you want to **seed** on your market to demonstrate your conviction. * A minimum of **\$100** is required to create a market. * Markets need at least **\$1000** during the seeding phase to go live. You can select and seed any amount above the minimum to help activate your market faster. * 50% of the trading fees will be distributed to seeders. ### 6. Accept the terms Image(3) * Before publishing your market, review the key phases and requirements below. These ensure that all community-created markets on Foresight Arena remain transparent, fair, and fully verifiable. * By checking the box, you confirm that you understand these terms and agree to follow Foresight Arena’s market guidelines ### 7. Review and publish Image(4) * Once all the steps are done, you can review your market on the preview card * The question, topic, end dates are shown as a preview. * After reviewing your market, all you have to do is click publish and approve the transaction! *** # Arena Seeding Source: https://docs.foresight.now/guides/arena-markets/arena-seeding This is where you confirm your position, review all key information about the market, and stake your funds to help it reach the seeding goal. ## **Seeding Markets** On this page, you can browse and support markets that are currently in the **seeding phase**. Seeding 3 ### **1. Choosing a Market to Seed** Select a market you believe in and want to help activate. Each market must reach its **seeding goal of \$1,000** before the **seeding deadline** to move into trading. * If a market **meets the goal**, it will automatically advance to open trading. * If a market **fails to reach the goal** by the deadline, it will expire. Users can then **unstake their funds** directly from the contract, with a **5% penalty fee** applied. This small fee goes to the protocol to discourage spam submissions and promote more intentional market creation. ### **2. How to Participate** * **Seed Market:** Click Seed Market to visit the seeding page and stake on the selected market with your desired amount * **Share:** Click **Share** to post the market directly to **X (Twitter)** and attract other seeders or traders to help the market reach its goal. ### **3. Purpose of Seeding** The seeding phase ensures each market has sufficient initial liquidity and community interest before it becomes tradable. By seeding early, you not only help the market go live but also earn potential **bonus yields** and **fee rewards** once the market resolves. ## **Seeding Steps** ### **Enter Your Amount** Pp 1 Use the input box to choose how much you want to seed (**any amount**). The right-hand panel shows: * Current **progress for the market.** * Total seeding goal * Your contributions and share of the pool Click **Seed** to confirm your position. Once seeded, your funds are staked until the market advances to trading or expires. ### **Review Market Summary & Rules** On the left side, you’ll find full context for the market you’re entering: * **Market Summary:** A short overview of what the market is about — including recent performance, forecasts, and relevant event details. * **Rules:** The exact criteria used to resolve the market, including data sources (e.g., Binance), edge conditions, and resolution time.This ensures every participant understands exactly **how the outcome will be verified** and **what counts as a win**. *** ## Failed Markets If a market doesn’t reach its required seeding goal by the **seeding deadline**, it automatically enters a **“Failed”** state. Fail ### **1. Market Status** Once failed, the market card will display a **Failed** label in red, along with all seeding progress data frozen at its final values. This visual cue lets users quickly identify markets that didn’t activate for trading. ### **2. Withdrawing Your Funds** If you contributed liquidity to a failed market, you’ll see a **Withdraw** button appear on the card. You can click this button to reclaim your seeded funds directly from the contract. * A **5% penalty fee** is applied to the withdrawn amount. * This fee goes to the protocol and is designed to promote more mindful market creation and reduce spam submissions. * Example: If you seeded **\$100**, your withdrawal will return **\$95** after the penalty. ## Canceled Markets If a market resolves during the **seeding phase**, it will enter a **Canceled** state. In a canceled market: * Users can **withdraw their funds** * **No fees** are charged * No trading outcomes are settled Cancel This ensures users are not penalized for markets that resolve before becoming fully active. ## Resolved Markets When a market reaches its resolution date and the outcome is verified, it moves into the **Resolved** state. This means the event has concluded, the results are confirmed, and payouts are ready. Resol ### **1. Viewing Results** Each resolved market card shows: * The **final outcome** (e.g., *Position “YES” Won*) * Your **seeded amount** — how much you originally staked * Your claimable amount - how much you can claim This gives you a full summary of your performance in that market. ### **2. Claiming Your Rewards** If your seeded position was on the **winning side**, the **Claim** (or **Withdraw**) button will become active. To receive your funds: 1. Click **Claim / Withdraw**. 2. Confirm the transaction in your wallet. 3. Your **seeded funds plus winnings** will be automatically transferred back to your wallet. # Deposit via Fiat Source: https://docs.foresight.now/guides/deposits-and-withdrawals/deposit-via-card-1 Purchase supported stablecoins using your local currency via card payments. Funds are processed through a third-party on-ramp provider and credited to your Foresight account. ## Quick Overview * Open the Deposit menu * Select **Use FIAT** * Enter the amount in your local currency (e.g., MYR) * Review the quote and provider * Complete payment via the on-ramp provider (e.g., AlchemyPay) * Funds will be credited after successful processing *** ## Step-by-Step Flow ### Open the deposit menu 1. From the Foresight app, navigate to **Profile → Deposit** Open deposit menu *** ### Select Fiat deposit 1. Select **Use FIAT** 2. Choose **Card** as your payment method Image *** ### Enter amount and review quote 1. Enter the amount you want to fund (e.g., **MYR 200**) Image 2. Review: * Sending currency (e.g., MYR) * Receiving asset (e.g., USDC) * Estimated conversion value You may expand **Transaction details** to view: * Fees * Exchange rate *** ### Proceed to payment 1. Click **Continue** 2. A secure on-ramp window will open Image *** ### Complete payment with provider 1. Review your order details: * Amount to pay * Estimated USDC received 2. Select **payment method (Card)** Image 3. Enter your card details and billing information *** ### Identity verification (if required) Depending on your region or transaction size, you may be required to complete **KYC verification**: * Upload identification document * Take a selfie for verification Image Verification typically takes a few minutes to complete. *** ### Wait for confirmation 1. After completing payment: * The system will show **pending / processing status** 2. Once confirmed: * Funds will be credited to your Foresight account automatically *** Do not close the payment window or navigate away while your transaction is being processed. Availability, supported currencies, fees, and limits may vary depending on your region and payment provider. *** ## Need help? Please contact us via our [telegram group](https://t.me/foresightnow) for support. # Deposit via Crypto Source: https://docs.foresight.now/guides/deposits-and-withdrawals/deposit-via-wallet Fund your Foresight account by sending supported tokens directly from your wallet using a deposit address or QR code. ## Quick Overview * Open the Deposit menu * Select **Use Crypto** * Choose your token and network * Copy your deposit address or scan the QR code * Send funds from your external wallet * Funds will be credited after on-chain confirmation *** ## Step-by-Step Flow ### Open the deposit menu 1. From the Foresight app, navigate to **Profile → Deposit** Open deposit menu *** ### Select Crypto deposit 1. In the deposit modal, select **Use Crypto** 2. Click on **Transfer Crypto** Image *** ### Select token and network 1. Choose the token you want to deposit (e.g., **USDC / USDT**) 2. Select your preferred **network** * Example: Ethereum, Arbitrum, BNB Chain, etc. Image Always ensure the network you select matches the network you are sending from. *** ### Copy address or scan QR code 1. Your unique **deposit address** will be generated Image 1. Either: * Copy the address, or * Scan the QR code using your wallet *** ### Send funds from your wallet 1. Go to your external wallet (e.g., MetaMask, Exchange) 2. Paste the deposit address or scan the QR code 3. Enter the amount and confirm the transaction *** ### Wait for confirmation * Once the transaction is confirmed on-chain: * Your funds will be automatically credited to your Foresight balance Processing time depends on the selected network and current congestion. *** Always double-check: * The **network** is correct * The **deposit address** is correct Sending funds on the wrong network may result in permanent loss. *** ## Need help? Please contact us via our [telegram group](https://t.me/foresightnow) for support. # Withdrawals Source: https://docs.foresight.now/guides/deposits-and-withdrawals/withdrawals Withdrawals allow you to move your available balance from Foresight back to your external wallet. All withdrawals are executed on-chain and processed on the network and stablecoin associated with your selected chain (e.g., Katana, Base, or Citrea). This page applies to users using an embedded wallet (Email / Google sign-in).\ If you are trading directly using your own crypto wallet, your funds already remain in your wallet and no withdrawal is required. ## Quick Overview * Open your **Portfolio** and select **Withdraw** from the Available Balance panel. * Enter your **wallet address** that supports the stable coin on the specific chain. \ for more information : Trading currency: **vbUSDC** Contract Address: [**0x203A662b0BD271A6ed5a60EdFbd04bFce608FD36**](https://katanascan.com/token/0x203a662b0bd271a6ed5a60edfbd04bfce608fd36) Chain ID: **747474** Trading currency: **USDC** Contract Address: [**0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913**](https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913) Chain ID: **8453** Trading currency: **ctUSD** Contract Address: [**0x8D82c4E3c936C7B5724A382a9c5a4E6Eb7aB6d5D**](https://citreascan.com/address/0x8D82c4E3c936C7B5724A382a9c5a4E6Eb7aB6d5D) Chain ID: **4114** Trading currency: **USDT** Contract Address: [0x524bC91Dc82d6b90EF29F76A3ECAaBAffFD490Bc](https://bscscan.com/token/0x524bc91dc82d6b90ef29f76a3ecaabafffd490bc) Chain ID: **97** * Specify the amount you want to withdraw (or select **Max**). * Confirm the transaction and wait for on-chain processing. * Funds will arrive in your wallet once the transaction is finalized. ## Step-by-Step ### 1. Open the Withdraw Panel From the Portfolio page, locate your **Available Balance** and click **Withdraw**. {87C7C995 16F4 45D3 B75D 3FE7BA6F5D93} *** ### 2. Enter Your Wallet Address * Paste your wallet address into the **Wallet Address** field. * Ensure the address supports the stablecoin and network currently selected (e.g., vbUSDC on Katana, USDC on Base, ctUSD on Citrea). {4AADBF6A D097 435B B99B 78953262AD32} *** ### 3. Enter Withdrawal Amount Enter the amount you wish to withdraw, or click **Max** to withdraw your full available balance. The system will automatically validate your available balance. ### 4. Confirm Withdrawal Click **Withdraw** to submit the transaction.\ The status will change to **Withdrawing…** while the transaction is being processed on-chain. Once finalized, the funds will appear in your wallet. # How to Add Funds Source: https://docs.foresight.now/guides/getting-started/how-to-add-funds Before placing a prediction on Foresight, you need to fund your wallet with supported stablecoins on a supported network. This section explains how to fund your wallet, choose the appropriate network, and safely move assets into the platform. ## About Networks and Trading Currency ### Supported Networks Foresight supports multi-chain trading and settlement across supported networks, including **Katana**, **Base**, and **Citrea**. Markets may operate on different networks depending on availability and configuration. When funding your wallet, always ensure that the selected network matches the network supported by the market you intend to trade on. ### Trading Currency All markets on Foresight are denominated in stablecoins pegged to **USD** (e.g., USDC or equivalent assets depending on network). Stablecoins provide predictable pricing and minimize volatility when placing predictions. ## Who This Section Is For This section applies mainly to users who signed up using **Email / Google** and are using an **embedded wallet**. If you signed up using your **own crypto wallet (e.g., MetaMask, Bybit Wallet)**, you can already trade directly from your wallet without using the Add Funds flow. Deposits and balances are managed directly in your wallet. ## Funding Process (Embedded Wallet Users) ### Open the Add Funds Panel 1. Click **Login** and connect your wallet. 2. From the top navigation or trading panel, click your **Balance** > **Deposit**. {4E7FB58D 176D 41CA 8241 75B5A4F63062} 3. The funding modal will display the supported network and token.
Always confirm that the network and token shown match your intended funding source.
## Funding Options Foresight supports **two primary ways to deposit funds**: **Crypto** and **Fiat**. Choose the method based on how you prefer to fund your account. *** ### Deposit with Crypto Use this option if you already hold crypto in an external wallet or exchange. You can fund your account by transferring supported assets directly to your **Foresight deposit address**. * Select **Use Crypto** * Choose your **token** (e.g., USDC / USDT) * Select your **preferred network** * Copy your deposit address or scan the **QR code** * Send funds from your external wallet Once the transaction is confirmed on-chain, your balance will be credited automatically. > You may choose from multiple supported networks. Always ensure you are using the correct network when sending funds. * [How to deposit via Crypto](/guides/deposits-and-withdrawals/deposit-via-wallet) *** ### Deposit with Fiat (Card / Local Currency) Use this option if you want to purchase crypto directly using your **bank card or local currency**. * Select **Use FIAT** * Enter the amount you wish to fund * Choose your **payment method** (e.g., card) * Select your **receiving asset** (e.g., USDC) * Review the quote and provider details * Complete the payment Your funds will be automatically converted and credited to your account upon successful payment. > Availability, supported currencies, fees, and limits may vary depending on your region and payment provider. * [How to deposit via Fiat](/guides/deposits-and-withdrawals/deposit-via-card-1) *** Always ensure you are using the correct network and address when depositing crypto. Sending funds via unsupported networks or incorrect details may result in permanent loss. # How to Sign-Up Source: https://docs.foresight.now/guides/getting-started/how-to-sign-up You can create a Foresight account using either an email login or a crypto wallet. Choose the option that best fits your workflow and security preferences. ## Social Sign-Up When you sign up with email or Google, Foresight automatically creates a secure **embedded wallet** for you. This wallet uses modern cryptographic primitives and battle-tested key management infrastructure to protect your private keys. You can immediately use this wallet to trade once it is funded, no manual wallet setup required. **Steps** 1. Click **Login / Sign Up** on the top right of homepage. {D0415A80 1FC6 4D32 9648 2A863F198403}
2. Select **Log in with email or socials.** {67F528E9 1AF7 4615 B1F2 DD63B3E043F6}
3. Choose to enter your **email** or sign up with **Google** to complete verification flow. Download
4. Your embedded wallet is created automatically and linked to your account.
You can immediately use this wallet to trade, but you need to [deposit](/guides/getting-started/how-to-add-funds) into this wallet.
## **Crypto Wallet Sign-Up** Use wallet login if you prefer to trade directly using your own self-custody wallet and retain full control over your private keys and funds. When you connect a wallet, Foresight does not create or manage a wallet for you. All transactions are signed and executed directly from your wallet, and your wallet address becomes your on-chain identity on the platform. **Steps** 1. Click **Login / Connect Wallet**. {D0415A80 1FC6 4D32 9648 2A863F198403}
2. Select your wallet provider (e.g., MetaMask or Bybit Wallet and others). {ECD55CDE 9217 4A9B BF29 9B9DD069514F}
3. If you have the specific wallet extension approve the connection in your wallet and follow the specific steps provided, else scan the QR code provided with your chosen wallet. {7DB176C5 4E58 4FCC B16E B38D92ED7F20}
4. Ensure your wallet is connected to a supported network (e.g., Katana, Citrea, or Base).
**Wallet & Network Compatibility** Not all wallets support every blockchain network. * Example: **Phantom does not support Katana.** * Always verify that your wallet supports the network you plan to use before connecting. Using an unsupported wallet may prevent balances from displaying correctly or transactions from completing.
## Next Step Once your account is created, you can fund your wallet and place your first prediction. # Introduction to Foresight Source: https://docs.foresight.now/guides/getting-started/introduction-to-foresight Foresight is a social prediction market where users trade on real-world outcomes using community-driven insights and enables information discovery. Share your conviction, influence how markets move, and earn when others act on your conviction, all backed by transparent on-chain execution. Incentives are aligned so only genuine and accurate conviction creates value. *** ## Foresight's Approach Foresight is built to make prediction markets easier to understand, more engaging to participate in, and more accessible to global users. Foresight connects prediction, information, and participation into one single platform. Instead of showing only prices and odds, each specified market surfaces context, social signals, and community activity, helping users understand why a market moves. Participants earn [**Vision Points**](/guides/rewards/vision-points-1), our unique platform-level rewards and incentive structure that encourage meaningful engagement and long-term ecosystem growth. Built with a focus towards the Asian market, Foresight supports localization, regional markets, and multilingual access to serve global communities more effectively. Users can also create their own markets using [**Arena**](/guides/arena-markets/arena-market-creation), allowing communities and niche groups to price markets and surface information quicker and also relates closer to their circle. ## Quick Overview * On Foresight, you can **buy and sell shares** representing the outcome of real-world events (e.g., “Will BYD lead EV sales in China by 2025?”). * Each market has two outcomes: **YES** and **NO**. Share prices range between **\$0.00** and **\$1.00 USD** and reflect the market’s current probability of the event occurring. * If the outcome you hold resolves as correct, each share pays out **\$1.00 USD** upon market resolution. If incorrect, the share pays out **\$0.00**. * Unless specified in the rules shares can be **bought or sold at any time before resolution date**, allowing you to take profit or reduce risk based on market movement. * All trades are executed on-chain across supported networks, ensuring transparent settlement and verifiable ownership. * Foresight integrates **social signals, market context, and community insights** directly into each market, helping you understand not just price movement, but the reasoning behind it. * Users may also earn **platform incentives and referral rewards** based on participation and activity. ## Market and Prices On Foresight, each market functions as a **peer-to-peer prediction exchange** where participants collectively discover the probability of an outcome through trading activity. Prices are not set by the platform, they emerge from supply and demand as users express their conviction by buying and selling outcome shares. When you view a market, you are observing a real-time signal of collective belief, similar to how stock prices reflect investor expectations in traditional financial markets. ### Prices Represent Implied Probability Each outcome share is priced between **\$0.00 and \$1.00 USD**.\ This price represents the market’s **implied probability** of the outcome occurring. * A price near **\$1.00** implies strong market confidence. * A price near **\$0.00** implies weak confidence. For example: > If a YES share is trading at **\$0.72**, the market is implying approximately a **72% probability** that the event will occur. ### How Reliable Are Foresight Market Signals? Foresight markets aggregate the collective views of many independent participants into a single price signal. As more users trade based on news, analysis, and community discussion, prices continuously adjust to reflect the latest available information. Unlike static forecasts or isolated opinions, this peer-to-peer price discovery process allows markets to react quickly to real-world developments. While no market can guarantee certainty, Foresight provides a transparent, real-time indicator of collective belief supported by visible context, activity, and social signals giving users a stronger foundation for forming conviction and making informed decisions. ## Multi-Chain Support Foresight supports multi-chain trading, deposits, and withdrawals across supported blockchain networks such as : Trading currency: **vbUSDC** Contract Address: [**0x203A662b0BD271A6ed5a60EdFbd04bFce608FD36**](https://katanascan.com/token/0x203a662b0bd271a6ed5a60edfbd04bfce608fd36) Chain ID: **747474** Trading currency: **USDC** Contract Address: [**0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913**](https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913) Chain ID: **8453** Trading currency: **ctUSD** Contract Address: [**0x8D82c4E3c936C7B5724A382a9c5a4E6Eb7aB6d5D**](https://citreascan.com/address/0x8D82c4E3c936C7B5724A382a9c5a4E6Eb7aB6d5D) Chain ID: **4114** Trading currency: **USDT** Contract Address: [0x524bC91Dc82d6b90EF29F76A3ECAaBAffFD490Bc](https://bscscan.com/token/0x524bc91dc82d6b90ef29f76a3ecaabafffd490bc) Chain ID: **97** Users can fund their accounts on supported networks and trade on the selected chain. Each blockchain maintains its own independent markets, balances, and liquidity. Funds deposited on one network can only be used to trade on markets on that same network. For example, a BTC market on **Katana** is separate from a BTC market on **Base**. Prices and liquidity do not automatically sync across chains. This design enables independent price discovery on each network while allowing arbitragers and advanced traders to rebalance prices based on real-world information. ## Global Language Support Foresight supports global language localization across most areas of the platform to improve accessibility for users worldwide. Key pages such as market titles, rules, description and certain features. * **English** * **Chinese**
Note: The news section is currently available in its original language only and is not yet supported for translation. # Making Your First Prediction Source: https://docs.foresight.now/guides/getting-started/making-your-first-prediction Once you've Signed-up and Added Funds, you can place your first prediction in just a few steps. ## Walkthrough ### Choose a Market Browse or search for a market that matches your interests (e.g., sports, crypto). Each market represents a real-world question with defined outcomes, such as **YES / NO** or other outcome structures depending on the market. {9DA46FEB 44C0 47B6 8089 267B1DB73DA2}
### Select an Outcome Review the available information, community signals, and market context under the specific market. Choose the outcome you believe is most likely to occur (e.g., **YES / NO**)
### Enter Your Amount and Confirm Enter the amount you want to allocate. Review the estimated price, potential exposure, and transaction details on the Wallet pop-up before confirming the trade in your wallet. Image 1 Understanding Your Bet : * **Resolution (e.g., May 27, 7:59AM MYT)**: When the market will close and resolve. * **Profit (e.g., +\$11.86)**: Your potential payout on top of your original investment if your prediction is correct * **Multiplier (e.g., 2.19x)**: Your potential return multiple if your prediction is correct Additionally you may also make your predictions on the home page itself by using the slider or input field to set your bet amount : Image
### Track Your Position After confirmation, your position will appear in your portfolio. You can monitor price movement, total value and unrealized PnL. {F688260F 3C9A 470B 88AD 58787E4AC282}
### Market Resolution and Claiming When the market resolves, winning positions become **claimable**.\ You must manually submit a claim transaction to receive your payout on-chain. There is **no time limit** to claim your rewards. Once a position becomes claimable, it remains available for collection indefinitely.
## Reminder Before placing your bet you are required to have : **A connected wallet.**\ (e.g. MetaMask, Embedded Wallet) **Supported stablecoin on a supported network.**\ (e.g. USDC on Katana, USDC on Base and ctUSD on Citrea) **Sufficient native gas token for the selected network.**\ (Only for external wallets) # Market Creation Source: https://docs.foresight.now/guides/platform-markets/market-creation ## Markets on Foresight are created through : ### Platform-Curated Markets Core markets are curated and maintained by the Foresight team to ensure: * Clear and objective resolution criteria * Reliable data sources * Sufficient expected liquidity and user interest * Compliance with platform standards These markets typically cover major real-world events, macro trends, and high-demand topics. # Market Resolutions and Payouts Source: https://docs.foresight.now/guides/platform-markets/market-resolutions-and-payouts-1 ## How Are Prediction Markets Resolved? When a market reaches its defined resolution condition (such as a date, event outcome, or verified data point), the market is finalized according to its published rules and resolution source. {BD74F450 5A86 4125 9D3A CF55650DE0E6} Once resolved: * The correct outcome is confirmed on-chain. * Winning positions become claimable. * Losing positions have no payout. * Trading for that market permanently stops. There may be possible outcomes which some markets may resolve to a **Tie / Draw** outcome with all position valued at **\$0.50** per share. On Foresight, users must manually claim their winning positions after a market resolves. Claimed funds are credited directly to the user’s wallet balance. There is **no expiration period for claiming rewards**. Winning positions remain claimable indefinitely until the user claims them. This ensures users retain full control over when they collect their settlement funds. # Market Rules and Clarification Source: https://docs.foresight.now/guides/platform-markets/market-rules-and-clarification-1 ## Each market includes clearly defined rules that specify: * The exact resolution condition * Accepted data sources * Edge-case handling * Timing and cutoff conditions In rare situations, unforeseen circumstances may arise after a market has launched. When this happens, the platform may publish clarifications or additional context to ensure the market resolves fairly and consistently with its original intent. Clarifications are issued transparently and applied consistently for all participants. If users believe a market requires clarification, they may submit feedback through official community channels or support channels for review. # Market States Source: https://docs.foresight.now/guides/platform-markets/market-states-1 Each market on Foresight moves through different states during its lifecycle. These states determine whether you can trade, when prices update, and when payouts become available. ## Trading The **Trading** state means the market is live and actively trading. Users can buy and sell positions freely, and prices update continuously based on market demand. Liquidity is available and positions can be adjusted or hedged until the market reaches its scheduled close time or a qualifying event occurs. Trading ## Paused The **Paused** state temporarily halts all trading activity. This may happen when a potential resolution event has occurred or when additional verification is required. Paused Pause While **paused**: * New trades cannot be placed. * Existing positions remain unchanged. * Prices do not update. If the pause was triggered by incorrect or incomplete information, the market may resume trading. If the event is confirmed, the market will move to the **Resolved** state. ## Resolved The **Resolved** state means the market outcome has been finalized. Trading is permanently closed, the winning outcome is confirmed, and users can claim their payouts and rewards. Market data becomes read-only and the market cannot reopen. {C5FE1D1A D41B 458F 9CFC B497765F8624}
Market status is visible on the market card and market page # Market Types Source: https://docs.foresight.now/guides/platform-markets/market-types Foresight supports two primary market types: Single markets and Multi markets. Each type defines how outcomes are structured and how resolution timelines behave. ## Single Markets A **Single market** contains one standalone prediction with a fixed set of outcomes. {E24AE6EC C5D7 487E 9ABE F9F2EB7EF861} Single markets typically: * Present a clear outcome structure, such as **Yes / No**. * Resolve as a single event with one final outcome with a possiblility of a **Tie / Draw** outcome depending on the market. * Have one lifecycle and one resolution state. Single markets do not contain submarkets. ## Multi Markets A **Multi market** groups multiple related submarkets under a single market umbrella. Each submarket represents its own independent prediction. {37B2839B 4F72 4A16 B524 23C83DC87589} In a multi market: * Each submarket operates independently. * Submarkets may enter different states (Open, Paused, Resolved) at different times. * Each submarket can resolve separately based on its own conditions. The timeline shown at the top of a multi market reflects the **latest possible resolution date** across all submarkets. Some submarkets may resolve earlier. The primary difference from single markets is that multi markets organize several related predictions within one grouped experience. Always review each submarket individually for its status and resolution timing. *** ## Trading Mechanisms In addition to market structure, Foresight supports two different **trading mechanisms**: AMM and CLOB. These determine **how trades are executed**, not what the market predicts. *** ### AMM (Automated Market Maker) AMM markets use a **liquidity pool** to facilitate trading. {A4DE345C D047 4FEE 9873 FC8D106813D9} * Users trade directly against the pool * Prices adjust automatically based on supply and demand * Trades are always executable as long as liquidity exists * No need to wait for another user to take the opposite side This is the **default trading experience**. *** ### CLOB (Central Limit Order Book) CLOB markets use an **order book system**, where users trade by placing orders that are matched with other traders. * Users place **Buy or Sell orders** at specific prices * Orders are listed in the **order book (Bids and Asks)** * Trades only execute when matching orders are available * Supports: * Market orders (instant execution at best available price) * Limit orders (set your own price) * Split and Merge operations *** #### Order Book & Trading Interface {16103533 66B9 41B4 A997 8AC80C5198AF} The interface includes: * **Order Book** * Displays active **bids (buyers)** and **asks (sellers)** * Shows price levels, available shares, and total value * **Open Orders** * Displays your active orders * Shows filled amount, total size, and order status * **Price Chart** * Tracks market price movement over time * **Position Summary** * Displays purchased positions and current P\&L *** #### Split & Merge CLOB markets allow users to **convert between USDC and position shares**: * **Split** {803164A0 D19E 4EF0 84CD 5B8CCEF96BE3} * Convert **1 USDC → 1 Yes + 1 No** * Useful when: * You want to create both sides of a position * You want to sell one side while keeping the other * You want to access liquidity more efficiently * **Merge** {7D3C532A 42BB 422A B34A 40AE5DC1866A} * Convert **1 Yes + 1 No → 1 USDC** * Useful when: * Exiting positions without relying on the order book * Avoiding slippage or illiquid markets These functions allow users to manage positions even when there are no matching orders available. *** Unlike AMM, trades are not guaranteed to execute immediately — they depend on market liquidity and matching orders. CLOB gives you full control over pricing, while Split/Merge ensures you can always enter or exit positions even without liquidity. # Pricing and Probability Source: https://docs.foresight.now/guides/platform-markets/pricing-and-probability ## Prices on Foresight Prices are determined entirely by market activity, not by the platform. Each market operates as a peer-to-peer exchange where participants express their conviction by buying and selling outcome shares. As demand shifts between YES and NO positions, prices update in real time based on supply and demand. A higher price reflects stronger collective belief that an outcome will occur.\ A lower price reflects weaker confidence. Because prices respond continuously to trading activity, they naturally incorporate: * **New information and news** * **Community discussion and sentiment** * **Liquidity depth and trading volume** This dynamic price discovery process allows markets to function as real-time probability signals rather than static forecasts. Actual execution prices may differ slightly from displayed prices depending on available liquidity and current market depth. # KAT Market Incentives Source: https://docs.foresight.now/guides/rewards/kat-market-incentives ## What Are KAT Market Incentives? KAT Market Incentives reward users with **KAT tokens** for trading on eligible markets. Some markets offer **standard KAT rewards**, while selected markets display a **boost multiplier** that increases the reward rate. Both standard and boosted markets distribute rewards from a limited KAT pool. KAT incentives are designed to: * Encourage liquidity on targeted markets * Accelerate price discovery * Reward early and active participation ## Eligible Markets Markets may fall into one of two categories: ### Standard KAT Markets * Earn KAT rewards at the base rate. * No multiplier is applied. * Rewards continue until the market's KAT pool is fully distributed. ### Boosted KAT Markets * Display a visible **boost multiplier** on the market card or market page. * The boost increases the effective reward rate. * Each boosted market has its own reward cap and availability window. Not all markets may offer KAT incentives at all times. ## Base Reward Rate Eligible trading activity earns KAT rewards at a base rate of: > **0.025 KAT per \$1 held per day** This base rate applies to standard markets and is multiplied when a boost is active. Rewards accumulate while the incentive pool remains available. Positions must be held receive KAT tokens, once sold it will no longer be calculated. ## Boost Multipliers Boosted markets may display multipliers such as: * **2×** * **3×** * **5×** * **10×** * **25×** * **50×** When a boost is active: * Your KAT rewards are multiplied by the displayed boost. * The boost applies on top of the base reward rate. * Each boost may have its own distribution cap. Boost availability may change over time. Imwdadwage ## Reward Limits and Caps Each market distributes rewards from a finite KAT pool. * Once a market's KAT pool is fully allocated, no additional KAT rewards will be earned on that market. * Trading remains available even after the reward pool is exhausted. * Boosted markets may also have additional boost-specific caps. These limits ensure controlled and fair reward distribution. ## How to Claim KAT Rewards KAT rewards earned from eligible markets are claimed externally through **Merkl**, the rewards distribution platform used for Katana incentives. To claim your KAT rewards, follow the steps below. ## Step-by-Step Claim Process ### 1. Open Merkl 1. Visit: [**https://app.merkl.xyz/**](https://app.merkl.xyz/) 2. Click **Launch App** in the top-right corner. 5E3B1C2A 1A71 4F57 84F5 DADE799D8AF2 ### 2. Connect Your Wallet 1. In the Merkl app, click **Connect** in the top-right corner. 2. Connect the wallet that: * You used to trade on Foresight, and * Is **eligible for Katana**. > The connected wallet must be the same wallet that earned the KAT rewards. FCBE2C3B 3A63 4AE4 9FA0 3A72640659B4 ### 3. Navigate to Dashboard 1. Once connected, navigate to **Dashboard**. 2. The dashboard will display: * Your **claimable KAT balance** * Any active or past reward campaigns associated with your wallet {4AC04324 AC20 465E A93E 46F2DDCB404C} ### 4. Claim Your KAT 1. If KAT rewards are available, click **Claim**. 2. Confirm the transaction in your wallet. 3. Once confirmed, the KAT tokens will be transferred to your wallet.
* KAT incentives are market-specific and subject to availability. * Not all markets are eligible for KAT rewards. * Boost multipliers and reward pools may change. * KAT rewards stop once the market's pool or cap is reached. # Vision Points Source: https://docs.foresight.now/guides/rewards/vision-points-1 A rewards system that incentivizes active trading, market creation, and meaningful participation on Foresight. Earn points by trading, seeding markets, and contributing to the ecosystem. ## What Are Vision Points? Vision Points are Foresight’s permanent participation system designed to reward users who actively trade, contribute liquidity, and support market discovery. The system prioritizes real economic activity while still recognizing high-quality community contributions. Vision Points may unlock future incentives, rewards, and platform benefits as the ecosystem evolves. ## Weekly Tracking & Updates * Vision Points are calculated and reviewed weekly on every **Monday 12am UTC** which is displayed as **Weekly Snapshot** in the Vision tab which will also determine the eligibility of the user for that week:
{B2F77BCB 383B 4FC1 8A8A D16EB55DB9BF}
* Leaderboards accumulate over time. * Rankings may be used for future campaigns, incentives, or access programs. ## Eligibility Requirement To earn any Vision Points in a given week, you must: Trade at least **\$200** in total volume during the week. If you do not meet the **\$200** minimum: * You will **not earn any Vision Points for that week**. * Trading \$199 or below earns **0 points**. * If you miss the requirement, you must meet the minimum again before the next Weekly Snapshot. This rule ensures Vision Points reward active and meaningful participation. ## How Vision Points Are Earned Vision Points are earned across three activity categories: 1. **Trading Activity** 2. **Arena** 3. **X Contributions (Formerly twitter)** ## Trading Activity Once you meet the \$200 weekly trading requirement: * **Every \$1 traded = 1 Vision Point** * Minimum per week: **200 points** This includes buying and selling positions. Example: * Trade \$500 in a week → Earn **500 Vision Points** * Trade \$199 in a week → Earn **0 Vision Points** ## Arena If you create or seed markets on Foresight Arena, you can earn additional Vision Points. ### Market Creator Rewards * If your created market successfully launches → **+500 Vision Points** ### Seeding Reward To be eligible for seeding rewards: You must seed at least **\$100** to qualify for seeding rewards * **Every \$1 seeded = 3 Vision Points** * Seeding rewards are granted only when the minimum threshold is met. Seeding supports liquidity, market quality, and discovery. ## X Contributions Social activity still contributes to Vision Points, but carries **lower weighting compared to trading activity**. To qualify: * You must have an **active trade** and a post on X. * X contributions are evaluated based on **engagement quality**, **relevance to your trading activity**, and **overall contribution value**. Factors such as audience interaction, originality, and usefulness of insights may influence how points are awarded. To prevent abuse and automated manipulation, the exact scoring mechanics are intentionally not disclosed. Spam, low-effort, or unrelated posts will not qualify. ## Benefits of Vision Points Vision Points recognize meaningful participation and may unlock: * Eligibility for future reward programs and campaigns * Increased visibility and recognition Reward structures may evolve as the platform grows. ## Best Practices for Maximizing Vision Points * Maintain consistent weekly trading activity above \$200. * Trade actively in markets you understand and follow. * Participate in Arena by seeding or creating quality markets. * Share thoughtful analysis tied to your actual trades. * Avoid spam, artificial engagement, or low-effort content. # FAQs Source: https://docs.foresight.now/guides/rewards/vision-points-faqs * Engagement is measured directly from activity on your posts on X (formerly Twitter), including likes, reposts (RTs), replies, quotes, bookmarks, and views. These metrics remain publicly visible on individual posts and can still be evaluated. * You will receive **0 Vision Points for that week**. The \$200 trading volume minimum must be met in full to qualify. * No. Seeding points are only awarded if you meet the weekly trading minimum. * Yes. Both buys and sells contribute to your total weekly trading volume. * No. Trading volume resets weekly and does not roll over. * Vision Points are intended to represent individual participation. Multi-account activity may be reviewed if abuse is detected. * Only successfully confirmed on-chain trades count toward trading volume and Vision Points. * No. Only executed trades on Foresight markets count toward trading volume. * Deleted posts may be excluded during review. Engagement is evaluated based on verifiable activity at review time. * Vision Points provide eligibility for incentives and programs, but rewards may vary by campaign and are not guaranteed. * Yes. The program may evolve as the platform grows. Updates will be communicated in advance.