> For the complete documentation index, see [llms.txt](https://docs.forepaas.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forepaas.org/readme.md).

# Introduction

Developer documentation for the ForeGate PaaS API - integrate prediction markets into your application

Documentation version: `2.6.0`

Welcome to the developer documentation for the ForeGate PaaS API. This API provides a comprehensive suite of tools for merchants to embed a prediction-market platform into their applications: user and session management, wallet funding, market discovery, a central limit order book (CLOB), trading, and real-time WebSocket streams.

PaaS traffic on `openapi.foregate.com` passes through an Aliyun API Gateway: every request (including `/socket/*` WebSocket handshakes) carries an HMAC-SHA256 gateway signature plus your partner API key, and user-scoped endpoints add a session cookie obtained at registration. Public market data on `openapiws.foregate.com` is unauthenticated. Start with [Authentication](/getting-started/authentication.md).

## Base URLs

All REST endpoints in this documentation are relative to a base URL (host). Use the environment provided to you by ForeGate.

| Environment        | REST Base URL                    | WebSocket Base URL                       |
| ------------------ | -------------------------------- | ---------------------------------------- |
| Development        | `https://openapi.foregate.com`   | `wss://openapi.foregate.com`             |
| Public market data | `https://openapiws.foregate.com` | `wss://openapiws.foregate.com/ws/market` |
| Production         | Provided by ForeGate             | Provided by ForeGate                     |

The public market-data host is unauthenticated. The development and production PaaS hosts use the credentials described below.

Credentials (APP Key, APP Secret, and `X-API-KEY`) are provisioned per PaaS client — contact your ForeGate account manager. See [Authentication](/getting-started/authentication.md) for how they are used.

## Key Capabilities

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Users &#x26; Sessions</strong></td><td>Register users from your application and manage cookie-based sessions.</td><td><a href="/api-reference/api-reference/user.md">User</a></td></tr><tr><td><strong>Wallet: Deposits &#x26; Withdrawals</strong></td><td>Fetch deposit addresses, track on-chain deposits, and process withdrawals.</td><td><a href="/api-reference/api-reference/deposit.md">Deposit</a></td></tr><tr><td><strong>Accounts</strong></td><td>Query balances, positions, and wallet history for your users.</td><td><a href="/api-reference/api-reference/account.md">Account</a></td></tr><tr><td><strong>Market Discovery</strong></td><td>Browse, search, and inspect prediction markets with live volume data.</td><td><a href="/api-reference/api-reference/markets.md">Markets</a></td></tr><tr><td><strong>Order Book &#x26; Pricing</strong></td><td>Read the CLOB: full book snapshots, best bid/ask, midpoint, spread, and price history.</td><td><a href="/api-reference/api-reference/orderbook.md">Orderbook</a></td></tr><tr><td><strong>Public Market Data</strong></td><td>Read a token's historical prices and stream public CLOB and market lifecycle events.</td><td><a href="/api-reference/api-reference/public-market-data.md">Public Market Data</a></td></tr><tr><td><strong>Trading</strong></td><td>Place LIMIT and MARKET orders, cancel, track open orders, and claim winnings.</td><td><a href="/api-reference/api-reference/ordering.md">Ordering</a></td></tr><tr><td><strong>Real-Time Data</strong></td><td>WebSocket streams for order-book deltas, price curves, balances, positions, and open orders.</td><td><a href="/advanced/websocket-api.md">WebSocket API</a></td></tr></tbody></table>

{% hint style="info" %}
This API is designed for a centralized merchant model: your application registers users with ForeGate via `POST /user/register` and acts on their behalf using the session cookie returned by that call. All user-specific actions require both your partner credentials and the user's session cookie.
{% endhint %}

## Getting Started

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Quick Start</strong></td><td>Make your first API call in minutes with our step-by-step guide.</td><td><a href="/getting-started/quick-start.md">Quick Start Guide</a></td></tr><tr><td><strong>Authentication</strong></td><td>Learn the gateway HMAC-SHA256 signature, API keys, and session cookies.</td><td><a href="/getting-started/authentication.md">Authentication</a></td></tr><tr><td><strong>Code Examples</strong></td><td>Complete client implementations in Node.js and Python with end-to-end workflows.</td><td><a href="/advanced/code-examples.md">Code Examples</a></td></tr><tr><td><strong>OpenAPI Spec</strong></td><td>Generate clients in 50+ languages using our OpenAPI 3.0 specification.</td><td><a href="/resources/openapi-specification.md">OpenAPI Specification</a></td></tr><tr><td><strong>AsyncAPI Spec</strong></td><td>Generate event models and clients for the public market WebSocket.</td><td><a href="/resources/asyncapi-specification.md">AsyncAPI Specification</a></td></tr></tbody></table>

{% hint style="success" %}
**New to prediction markets?** Start with the [Quick Start Guide](/getting-started/quick-start.md), then follow the complete [Code Examples](/advanced/code-examples.md) in Node.js and Python.
{% endhint %}

## Pagination Standards

Paginated endpoints accept:

| Parameter  | Type   | Default | Description                                                                |
| ---------- | ------ | ------- | -------------------------------------------------------------------------- |
| `page`     | number | 1       | Page number (1-indexed)                                                    |
| `pageSize` | number | 10      | Items per page; effective maximum 100 (larger values are truncated to 100) |

All successful JSON responses use `code` / `message` / `data`. Deposit and withdrawal history use `data.count` and `data.records`; market and account history keep pagination metadata beside `data.records` inside `data`; search, trades, and open orders expose their documented pagination fields alongside the envelope.

Public monetary endpoints currently support USDT only. The gateway supplies upstream `coinId` as the string `"2"`, so clients must not send `coinId` in their request query or body.

## Time & Precision Standards

| Context                                    | Format                                                             | Example                |
| ------------------------------------------ | ------------------------------------------------------------------ | ---------------------- |
| **`date` signing header**                  | `YYYY-MM-DD HH:mm:ss`, UTC (UTC+0), within \~15 min of server time | `2026-06-01 17:51:23`  |
| **Known HTTP response timestamps**         | ISO 8601 UTC, second precision                                     | `2024-01-15T10:30:00Z` |
| **CLOB WebSocket events**                  | ISO 8601 UTC, second precision                                     | `2026-05-29T06:30:53Z` |
| **Market-price WebSocket points**          | ISO 8601 UTC, second precision                                     | `2026-05-29T06:33:03Z` |
| **Public `openapiws.foregate.com` events** | Unix milliseconds encoded as strings                               | `1757908892351`        |

**Precision notes:**

* IDs in JSON request and response payloads are strings, preserving values above JavaScript's safe-integer range (2⁵³). URL path and query parameters use the transport type documented by each endpoint.
* Fields documented as decimal strings (for example balances, volumes, and public WebSocket prices/sizes) should remain strings or be parsed with `decimal.js` / `BigDecimal`. Fields documented as JSON numbers—such as position quantities/costs and selected fees—must be parsed as numbers according to their endpoint schema.