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

# Introduction

> Fairground API reference and integration guide

## Overview

We've built the Fairground API to support your backend data needs. Use it to look up markets and prices, and track a wallet's orders, positions, and trade history.

## Services

Endpoints are grouped into seven services, listed in the sidebar under their own sections:

| Service         | Covers                                                                           |
| --------------- | -------------------------------------------------------------------------------- |
| **Order**       | Look up orders, list a wallet's orders, preview fees, check executable liquidity |
| **Position**    | List open or all positions for a wallet, position-level fee info                 |
| **Market**      | Market configuration, live summaries, symbol-to-ID lookup                        |
| **OrderBook**   | Simulate aggregated bid/ask depth for a market                                   |
| **Price**       | Current oracle price, historical OHLC candles                                    |
| **Portfolio**   | Aggregated per-wallet snapshot: margin, PnL, equity, open positions/orders       |
| **FillHistory** | Individual trade/fill records for a wallet                                       |

## Making requests

Every endpoint, including reads, is a `POST` request with a JSON body, following the ConnectRPC convention:

```text theme={null}
POST /package.ServiceName/MethodName
```

## Base URL

| Environment | URL                         |
| ----------- | --------------------------- |
| Production  | `https://api.fairground.fi` |

## Authentication

Authentication will be introduced in future API versions.

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.fairground.fi/market_service.v1.MarketService/GetMarketConfigs \
    -H "Content-Type: application/json" \
    -d '{"market": {"marketSymbol": {"assetSymbol": "BTC", "quoteSymbol": "PERP"}}}'
  ```
</CodeGroup>

```json Response theme={null}
{
  "marketConfig": {
    "marketId": "1",
    "marketName": "BTC-PERP",
    "minLeverage": 1,
    "maxLeverage": 20,
    "tickDecimals": 1,
    "sizeDecimals": 8
  }
}
```

<Warning>
  Each endpoint page documents its own request fields, response fields, and one
  populated example, use those, not this generic one, for the exact shape of a
  specific call.
</Warning>

## Common patterns

A few conventions repeat across most endpoints:

<AccordionGroup>
  <Accordion title="Selecting a market: market_id vs. market_symbol">
    Most endpoints that take a market accept either form:

    ```json theme={null}
    {"market": {"marketId": "1"}}
    // or
    {"market": {"marketSymbol": {"assetSymbol": "BTC", "quoteSymbol": "PERP"}}}
    ```

    `GetHistoricalPrices` is the one exception. It only supports the `marketId` form. Check the endpoint's own description on its specific behavior.
  </Accordion>

  <Accordion title="Wallet addresses">
    Wallet address fields are matched case-insensitively and trimmed of
    surrounding whitespace server-side.
  </Accordion>

  <Accordion title="Pagination">
    Endpoints that paginate use `limit`/`offset`. Defaults and caps vary per endpoint, check each endpoint's description.
  </Accordion>
</AccordionGroup>

## Streaming endpoints

The streaming endpoints are ConnectRPC server-streaming methods. The server keeps the connection open and pushes a new message on a fixed interval instead of returning a single response.

<Warning>
  This reference's "Try it" panel sends a single request/response and can't
  exercise a real stream. Use a Connect-capable client (the SDKs, or
  `connect-web`/`connect-go` directly) to consume these endpoints. Each
  streaming endpoint's page still documents the request/response shape and one
  example of a single streamed message.
</Warning>

## Errors

Errors follow the [Connect error format](https://connectrpc.com/docs/go/errors/#http-representation):

```json theme={null}
{
  "code": "invalid_argument",
  "message": "market selector must contain a non-zero market_id or a valid asset symbol"
}
```

The codes you'll actually encounter across these endpoints are:

| Code               | Meaning                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `invalid_argument` | Request failed validation (missing required field, malformed selector, out-of-range value) |
| `not_found`        | The requested resource (order, position, market, price) doesn't exist                      |
| `internal`         | Server-side failure — retry or report if persistent                                        |
| `unimplemented`    | Endpoint isn't functional yet                                                              |