> 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

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.

All traffic passes through an Aliyun API Gateway — every request (including WebSocket handshakes) carries an HMAC-SHA256 gateway signature plus your partner API key, and user-scoped endpoints add a session cookie obtained at registration. 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` |
| Production  | Provided by ForeGate           | Provided by ForeGate         |

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="/pages/BWeJcUeoEaESfcdbbSBM">/pages/BWeJcUeoEaESfcdbbSBM</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="/pages/8nbMBLzHYqxIZO6HM2Qc">/pages/8nbMBLzHYqxIZO6HM2Qc</a></td></tr><tr><td><strong>Accounts</strong></td><td>Query balances, positions, and wallet history for your users.</td><td><a href="/pages/a2hWDtkGXUC0hpNurJQC">/pages/a2hWDtkGXUC0hpNurJQC</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="/pages/jl7KMJ2sYegZqNbPYAn8">/pages/jl7KMJ2sYegZqNbPYAn8</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="/pages/2CCBlQI1s8UPq7E8Axd1">/pages/2CCBlQI1s8UPq7E8Axd1</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="/pages/xHAWE71W0oPQm816iLHG">/pages/xHAWE71W0oPQm816iLHG</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="/pages/DsnRQsp4Y0IYOY9vuYpI">/pages/DsnRQsp4Y0IYOY9vuYpI</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="/pages/asMqybhY3nVN1UsBZBuG">/pages/asMqybhY3nVN1UsBZBuG</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="/pages/WW3bfMtyv43ajq22yyBY">/pages/WW3bfMtyv43ajq22yyBY</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="/pages/BLtr8ip2Yn3d2Kq2qjFZ">/pages/BLtr8ip2Yn3d2Kq2qjFZ</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="https://github.com/gph-tech/fg-centralize-api/tree/develop/openapi.yaml">https://github.com/gph-tech/fg-centralize-api/tree/develop/openapi.yaml</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          |

List-style responses add top-level fields alongside `code` / `msg` / `data`: `current` (page number), `size` (page size), `total` (total items), `pages` (total pages), `totalRow`, and `empty`.

## 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`            |
| **Response timestamps**           | ISO 8601                                                           | `2024-01-15T10:30:00Z`           |
| **CLOB WebSocket events**         | ISO 8601 / RFC 3339, nanosecond precision                          | `2026-05-29T06:30:53.143177724Z` |
| **Market-price WebSocket points** | Unix seconds                                                       | `1780033983`                     |

**Precision notes:**

* IDs (market/outcome/option/order) can exceed JavaScript's safe-integer range (2⁵³) — send them as strings where the endpoint allows and avoid native `Number` parsing.
* Monetary and price fields are transmitted as big-number strings (e.g. `396.878928000000000000`, `0E-18`) to avoid IEEE 754 precision loss — parse with `decimal.js` / `BigDecimal` equivalents.