Introduction

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:

POST /package.ServiceName/MethodName

Base URL

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

Authentication

Authentication will be introduced in future API versions.

Example

curl -X POST https://api.fairground.fi/market_service.v1.MarketService/GetMarketConfigs \
  -H "Content-Type: application/json" \
  -d '{"market": {"marketSymbol": {"assetSymbol": "BTC", "quoteSymbol": "PERP"}}}'

Response

{
  "marketConfig": {
    "marketId": "1",
    "marketName": "BTC-PERP",
    "minLeverage": 1,
    "maxLeverage": 20,
    "tickDecimals": 1,
    "sizeDecimals": 8
  }
}

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.

Common patterns

A few conventions repeat across most endpoints:

Selecting a market: market_id vs. market_symbol

Most endpoints that take a market accept either form:

{"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.

Wallet addresses

Wallet address fields are matched case-insensitively and trimmed of surrounding whitespace server-side.

Pagination

Endpoints that paginate use limit/offset. Defaults and caps vary per endpoint, check each endpoint’s description.

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.

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.

Errors

Errors follow the Connect error format:

{
  "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

Developer Docs

API Reference

SDK Reference

Overview

Services

Making requests

Base URL

Authentication

Example

Common patterns

Streaming endpoints

Errors

​Overview

​Services

​Making requests

​Base URL

​Authentication

​Example

​Common patterns

​Streaming endpoints

​Errors

Overview

Services

Making requests

Base URL

Authentication

Example

Common patterns

Streaming endpoints

Errors