> 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/api-reference/api-reference/markets.md).

# Markets

Browse markets, view details, top holders, and live volume

The market endpoints are read-only and require only your ForeGate API key plus the gateway signature — no session cookie. Responses use the standard ForeGate envelope; endpoint-specific normalization is documented below.

### Get Market List

{% openapi src="/files/5MOm3p5RkCwChISqy4Ij" path="/markets/list" method="get" %}
[openapi.yaml](https://3978567741-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlpNKReYzAUPT4VYMRTyV%2Fuploads%2Fgit-blob-df203d883ae750a5f7d589901c91e8064f358f8d%2Fopenapi.yaml?alt=media)
{% endopenapi %}

Retrieves a paginated list of markets on the platform.

**Use Case:** The primary endpoint for discovering markets. Use it to build a market browser or listing page.

| Property           | Value                         |
| ------------------ | ----------------------------- |
| **Method**         | `GET`                         |
| **Path**           | `/markets/list`               |
| **Authentication** | `Gateway signature + API key` |

*Gateway behavior: internally maps to `GET /api/market/query/list` and applies the public market/outcome/option field whitelist. This endpoint requires only your API key — no session cookie.*

**Request Headers:**

All requests must carry the [gateway signing headers](/getting-started/authentication.md) (`x-ca-key`, `x-ca-signature`, `x-ca-signature-headers`, `x-api-key`, `accept`, `date`).

| Header      | Required | Description                                                    |
| ----------- | -------- | -------------------------------------------------------------- |
| `x-api-key` | Yes      | Your ForeGate API key (participates in the gateway signature). |

**Query Parameters:**

| Parameter  | Type    | Required | Description                                      |
| ---------- | ------- | -------- | ------------------------------------------------ |
| `page`     | integer | No       | Page number, minimum 1. Default: 1.              |
| `pageSize` | integer | No       | Items per page, from 1 through 100. Default: 10. |

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://openapi.foregate.com/markets/list?page=1&pageSize=10" \
  -H "accept: application/json" \
  -H "date: 2026-06-01 17:51:23" \
  -H "x-ca-key: <APP Key>" \
  -H "x-ca-signature: <base64 HMAC-SHA256>" \
  -H "x-ca-signature-headers: x-api-key" \
  -H "x-api-key: <X-API-KEY>"
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
// client is configured as shown in code-examples.md
const res = await client.request('GET', '/markets/list', {
  query: { page: 1, pageSize: 10 },
});
```

{% endtab %}

{% tab title="Python" %}

```python
# client is configured as shown in code-examples.md
res = client.request("GET", "/markets/list", query={"page": 1, "pageSize": 10})
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "current": 1,
    "size": 10,
    "total": 38,
    "pages": 4,
    "records": [
      {
        "marketId": "418889258426699776",
        "title": "Example market",
        "category": "16",
        "status": "open",
        "coinId": "2",
        "marketType": null,
        "volume": "0E-10",
        "hotScore": 0,
        "isOnline": true,
        "marketLogo": "https://example.com/market.png",
        "startTime": "2026-06-01T03:03:00Z",
        "endTime": "2026-06-07T16:00:00Z",
        "matchDate": null,
        "matchStartTime": null,
        "modelType": "orderbook",
        "outcomes": [{
          "outcomeId": "418889258426699777",
          "name": "Yes / No",
          "options": [{
            "optionId": "418889258426699778",
            "title": "Yes",
            "price": "0",
            "chance": 0,
            "optionIndex": 0
          }]
        }]
      }
    ],
    "totalRow": null,
    "empty": false
  }
}
```

{% endtab %}
{% endtabs %}

Market records expose only `marketId`, `title`, `category`, `status`, `coinId`, `marketType`, `volume`, `hotScore`, `isOnline`, `marketLogo`, `startTime`, `endTime`, `matchDate`, `matchStartTime`, `modelType`, and `outcomes`. Outcomes expose only `outcomeId`, `name`, and `options`; options expose only `optionId`, `title`, `price`, `chance`, and `optionIndex`. IDs and option prices are strings, recognized times are ISO 8601 UTC, and unknown upstream fields are not exposed.

**Error Responses:**

`401 Unauthorized` — missing API key:

```json
{
  "code": 1401,
  "message": "unauthorized: Missing X-API-KEY header",
  "data": null
}
```

***

### Get Category Tree

{% openapi src="/files/5MOm3p5RkCwChISqy4Ij" path="/markets/category-tree" method="get" %}
[openapi.yaml](https://3978567741-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlpNKReYzAUPT4VYMRTyV%2Fuploads%2Fgit-blob-df203d883ae750a5f7d589901c91e8064f358f8d%2Fopenapi.yaml?alt=media)
{% endopenapi %}

Returns all online, non-deleted market categories, or one tree selected by its level-one category ID. Category IDs in the JSON response are strings.

| Property           | Value                         |
| ------------------ | ----------------------------- |
| **Method**         | `GET`                         |
| **Path**           | `/markets/category-tree`      |
| **Authentication** | `Gateway signature + API key` |

**Query Parameters:**

| Parameter     | Type    | Required | Description                                                                                                      |
| ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `category1Id` | integer | No       | Return only this level-one category tree. This URL query parameter intentionally uses an integer transport type. |
| `language`    | enum    | No       | `en-US`, `zh-CN`, `vi-VN`, `tr-TR`, `es-ES`, `pt-BR`, or `ko-KR`.                                                |

When `language` is absent, the gateway chooses the highest-weight supported language from `Accept-Language`, then falls back to `en-US`. `nameDisplay` falls back from the selected language to `en-US`, then to `name`.

```json
{
  "code": 0,
  "message": "ok",
  "data": [{
    "id": "5",
    "level": 1,
    "level1Id": null,
    "level2Id": null,
    "name": "Sports",
    "nameDisplay": "Sports",
    "logoUrl": "",
    "children": [{
      "id": "20123",
      "level": 2,
      "level1Id": "5",
      "level2Id": null,
      "name": "Cricket",
      "nameDisplay": "Cricket",
      "logoUrl": "https://example.com/cricket.png",
      "children": []
    }]
  }]
}
```

Invalid `language` or `category1Id` values return HTTP 400 with business code `1001`; a missing API key returns HTTP 401 with business code `1401`.

***

### Get Market Details

{% openapi src="/files/5MOm3p5RkCwChISqy4Ij" path="/markets/{marketId}/detail" method="get" %}
[openapi.yaml](https://3978567741-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlpNKReYzAUPT4VYMRTyV%2Fuploads%2Fgit-blob-df203d883ae750a5f7d589901c91e8064f358f8d%2Fopenapi.yaml?alt=media)
{% endopenapi %}

Retrieves the detailed information for a single market.

**Use Case:** Display a detailed view of one market, showing everything a user needs to make a trade.

| Property           | Value                         |
| ------------------ | ----------------------------- |
| **Method**         | `GET`                         |
| **Path**           | `/markets/{marketId}/detail`  |
| **Authentication** | `Gateway signature + API key` |

*Gateway behavior: internally maps to `GET /api/market/query/{marketId}/detail`. The `data` object is the complete market contract shown in the Swagger schema, with IDs normalized to strings, known times normalized to ISO 8601 UTC, and `outcomes[].options[].price` returned as a string. This endpoint requires only your API key — no session cookie.*

**Request Headers:**

All requests must carry the [gateway signing headers](/getting-started/authentication.md) (`x-ca-key`, `x-ca-signature`, `x-ca-signature-headers`, `x-api-key`, `accept`, `date`).

| Header      | Required | Description                                                    |
| ----------- | -------- | -------------------------------------------------------------- |
| `x-api-key` | Yes      | Your ForeGate API key (participates in the gateway signature). |

**Path Parameters:**

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `marketId` | string | Yes      | Market ID.  |

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://openapi.foregate.com/markets/1001/detail" \
  -H "accept: application/json" \
  -H "date: 2026-06-01 17:51:23" \
  -H "x-ca-key: <APP Key>" \
  -H "x-ca-signature: <base64 HMAC-SHA256>" \
  -H "x-ca-signature-headers: x-api-key" \
  -H "x-api-key: <X-API-KEY>"
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const res = await client.request('GET', '/markets/1001/detail');
```

{% endtab %}

{% tab title="Python" %}

```python
res = client.request("GET", "/markets/1001/detail")
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "marketId": "1001",
    "title": "USDT market example",
    "coinId": "2",
    "description": "Will ETH rise in July?",
    "category": "3",
    "marketType": null,
    "modelType": "AMM",
    "creatorType": "Creator",
    "marketLogo": "https://example.com/market.jpg",
    "marketBanner": "https://example.com/banner.jpg",
    "marketLogoBackground": null,
    "status": "settled",
    "rules": "...",
    "isOnline": false,
    "totalStake": null,
    "liquidity": 500,
    "buyFee": 0.02,
    "sellFee": 0.02,
    "startTime": "2025-08-18T06:45:00Z",
    "endTime": "2025-08-18T07:00:00Z",
    "matchStartTime": null,
    "matchDate": null,
    "volume": "35.0000000000",
    "wishlist": false,
    "commentCount": 0,
    "fee": "0.010000",
    "creator": {
      "creatorId": "167",
      "name": "User_1749620060",
      "profileImage": "https://example.com/profile.jpeg",
      "creatorAddress": null
    },
    "outcomes": [{
      "outcomeId": "1073",
      "title": "Yes",
      "name": "Yes",
      "chance": 0,
      "outcomeLogo": "https://example.com/yes.jpg",
      "description": "yes",
      "options": [{
        "optionId": "2107",
        "title": "Yes",
        "chance": 49.47,
        "price": "0",
        "priceBuy": 0,
        "priceSell": 0,
        "isWinFirst": "1",
        "isWin": null,
        "optionIndex": 0
      }]
    }],
    "clicks": 0,
    "topic": "Crypto",
    "tags": "Cabinet, Politics",
    "priOrPub": "Public",
    "dataResource": "coinbase",
    "platformFees": 0.25,
    "makerFee": 0,
    "takerFee": 0,
    "buyMaxAmount": 100000002,
    "buyMinAmount": 1,
    "sellMinShares": 0.02,
    "sellMaxShares": 100000002,
    "challengeBondAmount": 500,
    "hotScore": null,
    "isResolveOvertime": false,
    "ifHasChallenged": null,
    "poolAddress": "3AcnnVSf8hD7Rt6L8UdmvAzteVWgmHKyj1Ewh3ibbgLy",
    "orderbookMakers": null,
    "marketOrderPriceProtection": 0.1,
    "limitOrderPriceProtection": 0.1,
    "liveVideoType": null,
    "liveSourcePlat": null,
    "liveLinkUrl": null,
    "isWorldCup": false
  }
}
```

{% endtab %}
{% endtabs %}

**Error Responses:**

`401 Unauthorized` — missing API key:

```json
{
  "code": 1401,
  "message": "unauthorized: Missing X-API-KEY header",
  "data": null
}
```

***

### Get Top Holders

{% openapi src="/files/5MOm3p5RkCwChISqy4Ij" path="/markets/{marketId}/holders" method="get" %}
[openapi.yaml](https://3978567741-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlpNKReYzAUPT4VYMRTyV%2Fuploads%2Fgit-blob-df203d883ae750a5f7d589901c91e8064f358f8d%2Fopenapi.yaml?alt=media)
{% endopenapi %}

Retrieves the top holders for a specific market.

**Use Case:** Display a leaderboard of the largest position holders in a market to drive engagement.

| Property           | Value                         |
| ------------------ | ----------------------------- |
| **Method**         | `GET`                         |
| **Path**           | `/markets/{marketId}/holders` |
| **Authentication** | `Gateway signature + API key` |

*Gateway behavior: internally maps to `POST /api/market/query/getTopHolders?marketId={marketId}` — the gateway sends `marketId` as a query parameter with an empty request body. The response hierarchy is outcome → option → holder, and every ID is a string. This endpoint requires only your API key — no session cookie.*

**Request Headers:**

All requests must carry the [gateway signing headers](/getting-started/authentication.md) (`x-ca-key`, `x-ca-signature`, `x-ca-signature-headers`, `x-api-key`, `accept`, `date`).

| Header      | Required | Description                                                    |
| ----------- | -------- | -------------------------------------------------------------- |
| `x-api-key` | Yes      | Your ForeGate API key (participates in the gateway signature). |

**Path Parameters:**

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `marketId` | string | Yes      | Market ID.  |

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://openapi.foregate.com/markets/1001/holders" \
  -H "accept: application/json" \
  -H "date: 2026-06-01 17:51:23" \
  -H "x-ca-key: <APP Key>" \
  -H "x-ca-signature: <base64 HMAC-SHA256>" \
  -H "x-ca-signature-headers: x-api-key" \
  -H "x-api-key: <X-API-KEY>"
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const res = await client.request('GET', '/markets/1001/holders');
```

{% endtab %}

{% tab title="Python" %}

```python
res = client.request("GET", "/markets/1001/holders")
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "outcomeId": "1073",
    "outcomeName": "Yes",
    "outcomeTitle": "Yes",
    "outcomeLogo": "https://example.com/yes.jpg",
    "outcomeOptionHolderVoList": [{
      "outcomeId": "1073",
      "optionId": "2107",
      "optionTitle": "Yes",
      "assetId": "22222",
      "yes": true,
      "optionIndex": 0,
      "price": 0,
      "priceBuy": 0,
      "priceSell": 0,
      "holderVoList": [{
        "userId": "39399",
        "userName": "343434",
        "avatarUrl": "https://example.com/profile.jpg",
        "userAvatarFrameUrl": null,
        "share": 29271676
      }]
    }]
  }
}
```

{% endtab %}
{% endtabs %}

**Error Responses:**

`401 Unauthorized` — missing API key:

```json
{
  "code": 1401,
  "message": "unauthorized: Missing X-API-KEY header",
  "data": null
}
```

***

### Get Live Volume

{% openapi src="/files/5MOm3p5RkCwChISqy4Ij" path="/markets/{marketId}/live-volume" method="get" %}
[openapi.yaml](https://3978567741-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlpNKReYzAUPT4VYMRTyV%2Fuploads%2Fgit-blob-df203d883ae750a5f7d589901c91e8064f358f8d%2Fopenapi.yaml?alt=media)
{% endopenapi %}

Retrieves the real-time trading volume for a specific market.

**Use Case:** Show a compact, always-current volume figure for a market without fetching the full market detail payload.

| Property           | Value                             |
| ------------------ | --------------------------------- |
| **Method**         | `GET`                             |
| **Path**           | `/markets/{marketId}/live-volume` |
| **Authentication** | `Gateway signature + API key`     |

*Gateway behavior: sourced from the `data.volume` field of `GET /api/market/query/{marketId}/detail`. The gateway extracts that field and returns it on its own so downstream consumers don't receive the extra fields. This endpoint requires only your API key — no session cookie.*

**Request Headers:**

All requests must carry the [gateway signing headers](/getting-started/authentication.md) (`x-ca-key`, `x-ca-signature`, `x-ca-signature-headers`, `x-api-key`, `accept`, `date`).

| Header      | Required | Description                                                    |
| ----------- | -------- | -------------------------------------------------------------- |
| `x-api-key` | Yes      | Your ForeGate API key (participates in the gateway signature). |

**Path Parameters:**

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `marketId` | string | Yes      | Market ID.  |

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://openapi.foregate.com/markets/1001/live-volume" \
  -H "accept: application/json" \
  -H "date: 2026-06-01 17:51:23" \
  -H "x-ca-key: <APP Key>" \
  -H "x-ca-signature: <base64 HMAC-SHA256>" \
  -H "x-ca-signature-headers: x-api-key" \
  -H "x-api-key: <X-API-KEY>"
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const res = await client.request('GET', '/markets/1001/live-volume');
```

{% endtab %}

{% tab title="Python" %}

```python
res = client.request("GET", "/markets/1001/live-volume")
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "marketId": "1001",
    "volume": "35.0000000000"
  }
}
```

{% endtab %}
{% endtabs %}

**Response Fields:**

| Field           | Type   | Description                                                                                                       |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `data.marketId` | string | The market ID.                                                                                                    |
| `data.volume`   | string | Real-time trading volume. Preserved in the upstream's original type — typically a string to avoid precision loss. |

**Error Responses:**

`401 Unauthorized` — missing API key:

```json
{
  "code": 1401,
  "message": "unauthorized: Missing X-API-KEY header",
  "data": null
}
```

***