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

# Overview

> Explore the APIs available for building with Calibri prediction markets.

Calibri exposes REST and WebSocket APIs for discovering markets, reading live
books, placing signed orders, and managing positions and account data.

## APIs

Calibri's API is grouped by path prefix under one base URL. Each group covers a
distinct part of an integration.

<CardGroup cols={2}>
  <Card title="Market data" icon="database">
    **`https://calibri.io/api/v2/pythia`**

    Discover events and markets, then read books, tickers, candles, and the
    public trade tape — no authentication.
  </Card>

  <Card title="Trading" icon="arrows-rotate">
    **`https://calibri.io/api/v2/atlas`** · **`…/pythia`**

    Place EIP-712-signed orders, then list and cancel resting orders. Needs a
    key your client can sign with — see below.
  </Card>

  <Card title="Account" icon="chart-line">
    **`https://calibri.io/api/v2/atlas`**

    Balances, transactions, PnL, contracts, limits, preferences, and rewards.
  </Card>

  <Card title="Wallet" icon="bolt">
    **`https://calibri.io/api/v2/atlas`**

    Self-custody Safe setup, passkey enrolment, signing keys, session keys, and
    gasless relay — without holding funds on Calibri.
  </Card>

  <Card title="WebSocket" icon="radio" href="/api-reference/websockets">
    **Realtime streams**

    Order-book increments, candles, trade prints, underlying prices, and your
    own order / fill / balance updates.
  </Card>

  <Card title="Identity" icon="user">
    **`https://calibri.io/api/v2/persona`**

    Account reads and wallet linking for machine integrations. Browser sign-in
    is a product UI flow, not a documented API path.
  </Card>
</CardGroup>

## Before you integrate

<CardGroup cols={2}>
  <Card title="End-to-end flow" icon="list-check" href="/api-reference/quickstart">
    Wallet config, approvals, funding, a signed order, status, WebSocket — in order.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Mint an API key and HMAC-sign every private request.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/api-reference/rate-limits">
    Request limits and caching behaviour for public and private endpoints.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    HTTP status codes and the `errors: ["dot.coded"]` body shape.
  </Card>

  <Card title="Models" icon="cube" href="/api-reference/models/overview">
    Every request and response shape, generated from the specification.
  </Card>

  <Card title="Self-custody" icon="lock" href="/non-custodial/overview">
    How signed orders and Safe wallets work — Calibri never holds your funds.
  </Card>
</CardGroup>

## Can your account place orders from a script?

Reading is always available. **Writing depends on what owns your wallet**, because an
order carries your own signature as well as the request signature — and a passkey cannot
sign outside the browser it was created in.

<CardGroup cols={2}>
  <Card title="Your own wallet" icon="circle-check">
    `signature_type` `2`. You hold the key, so your client signs orders,
    withdrawals and redemptions. Nothing to set up.
  </Card>

  <Card title="Passkey wallet" icon="key">
    `signature_type` `3`. Reads work as they are. To place orders, add a
    [signing key](/non-custodial/signing-keys) — a wallet you hold the key for,
    which becomes an owner of the same Safe.
  </Card>
</CardGroup>

Check `signature_type` on `GET /api/v2/atlas/account/wallet` before you build, and see
[Authentication](/api-reference/authentication#authentication-is-not-authorisation-to-trade)
for what each type signs.

## Base URL

All requests share one base URL and are routed by path prefix:

```
https://calibri.io
```

| Prefix | Serves |
| - | - |
| `/api/v2/pythia/*` | Market data — events, markets, books, tickers, open orders |
| `/api/v2/atlas/*` | Trading and account — balances, signed-order placement, contracts, wallet |
| `/api/v2/persona/*` | Identity — account reads and wallet link |

## Response format

Responses are **plain JSON** — a resource object or an array of them. There is
**no `{ success, data }` envelope**.

Monetary and volume values are **strings** — parse them as decimals, not floats.

```json theme={null}
{
  "id": 90231,
  "market": "12",
  "side": "yes",
  "ord_type": "limit",
  "price": "0.60",
  "remaining_volume": "100",
  "origin_volume": "100",
  "locked": "61.68",
  "state": "wait",
  "contracts_count": 0,
  "created_at": "2026-08-07T10:00:00Z",
  "updated_at": "2026-08-07T10:00:00Z"
}
```

## Authentication

Private requests use an **HMAC-signed API key** (`X-Auth-Apikey`,
`X-Auth-Nonce`, `X-Auth-Signature`). There is no `Authorization: Bearer`
header. See [Authentication](/api-reference/authentication).

<Warning>
  Authentication proves **who you are**. It does not authorise the movement of
  funds. Every order carries your own EIP-712 signature; every transfer out of
  your Safe is a transaction you sign.
</Warning>

## Pagination

List endpoints that page accept `page` and `limit` (or similar). Totals come
back in response headers:

| Header | Meaning |
| - | - |
| `Page` | Current page |
| `Per-Page` | Page size |
| `Total` | Total matching rows |

## Caching

Public market-data routes send `Cache-Control` (short TTL on live books, longer
on browse, `immutable` on closed asset ranges). Private account and trade
routes are not shared-cacheable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.