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 eight services, listed in the sidebar under their own sections:

Service	Covers
Trades	Individual trade/fill records for a wallet
Markets	Look up market configuration, list markets, and retrieve a live summary
Orderbook	Simulate aggregated bid/ask depth for a market
Orders	Look up one order or list a wallet’s orders
Permissions	Generate, list, and delete API keys
Portfolio	Aggregated per-wallet snapshot: margin, PnL, equity, open positions/orders
Positions	List a wallet’s open positions
Prices	Current oracle price and historical OHLC candles

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

Every request needs an API key, sent as a bearer token in the Authorization header. Requests without one return 401 unauthenticated. To create an API key:

Open the Fairground app

Go to app.fairground.fi and connect your wallet.

Open API Keys

Open the More tab in the navigation, then select API Keys.

Generate a key

Create a key and store it somewhere safe. Treat it like a password.

Example

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

Response

{
  "marketConfig": {
    "marketId": "1",
    "marketName": "BTC-USD",
    "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.

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
`unauthenticated`	Missing or invalid API key in the `Authorization` header
`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 it if it persists.

Developer Docs

API Reference

Overview

Services

Making requests

Base URL

Authentication

Example

Common patterns

Errors

​Overview

​Services

​Making requests

​Base URL

​Authentication

​Example

​Common patterns

​Errors

Overview

Services

Making requests

Base URL

Authentication

Example

Common patterns

Errors