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

# API Overview

> Convallax API reference — REST and WebSocket endpoints for trading options on prediction markets, with live quote request price discovery and on-chain Polygon settlement.

## Base URL

```
https://api.convallax.com
```

## Authentication

Convallax uses two credentials depending on what you are doing:

* **Maker API key** (`X-API-Key`) — authorizes market-maker traffic across the **three-channel transport**. The SSE quote-request stream and the REST quote endpoints use the `X-API-Key` header (or `?apiKey=`); the post-trade WebSocket uses `?apiKey=` on the URL or an `auth` message. Keys are **self-serve**: any signed-in user generates one from the dashboard (Settings → API Keys), and it maps to a stable `makerId`.
* **Privy access token** (`Authorization: Bearer <jwt>`) — authorizes the **account endpoints** under `/v1/user/*` (profile and API-key management).
* **Takers need neither.** The REST trading endpoints (`/quote-requests`, `/quote-requests/:id/quotes`, `/quote-requests/:id/stream`, `/quote-requests/:id/commit`) are open. A taker's authorization is the on-chain `fill()` call signed by their own wallet — only the wallet named as `taker` in the signed order can settle.

See the [Authentication guide](/guides/authentication) for full details.

The three maker channels are:

| Channel                    | Transport | Direction      | Endpoint                                                    |
| -------------------------- | --------- | -------------- | ----------------------------------------------------------- |
| Quote requests             | SSE       | server → maker | `GET /v1/mm/quote-requests/stream`                          |
| Quote submission + confirm | REST      | maker → server | `POST /v1/mm/quotes`, `POST /v1/mm/quotes/:quoteId/confirm` |
| Post-trade events          | WebSocket | server → maker | `WS /maker/v1/ws`                                           |

## Response Envelope

Successful responses are wrapped:

```json theme={null}
{
  "success": true,
  "bestQuote": { /* resource */ }
}
```

Failed responses return:

```json theme={null}
{
  "success": false,
  "error": "Human-readable error message"
}
```

## Endpoint Groups

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/authentication">
    How market makers obtain and use per-MM API keys — and why takers need none.
  </Card>

  <Card title="Trading" icon="bolt" href="/api-reference/trading/create-quote-request">
    Open live quote requests, poll for market maker quotes, and commit to the best price.
  </Card>

  <Card title="Market Maker" icon="chart-line" href="/api-reference/market-maker/status">
    Subscribe to the SSE quote-request stream, submit quotes over REST, and receive post-trade events over the WebSocket.
  </Card>

  <Card title="User" icon="user" href="/api-reference/user/get-profile">
    Manage your account profile and generate or revoke self-serve API keys.
  </Card>

  <Card title="Settlement" icon="gavel" href="/api-reference/settlement/prepare">
    Compute VWAP resolution prices and generate signed settlement attestations.
  </Card>

  <Card title="On-Chain Contracts" icon="file-contract" href="/api-reference/contracts/fill">
    Call smart contract functions directly: fill orders, claim payouts, and settle options.
  </Card>
</CardGroup>

## On-Chain Settlement

After committing to a quote via `POST /quote-requests/:id/commit`, the taker receives a signed `Order` struct and interacts directly with the Polygon smart contracts. The taker makes the single USDC approval indicated by `takerApproval`, then calls `fill()` on `ConvallaxRFQSettlement` to atomically lock collateral, pay premium, and mint the option. No further API calls are needed for settlement.

## Rate Limits

API endpoints are not rate-limited. The only exception is the testnet [faucet](/api-reference/testnet/faucet), which is capped per wallet (default once per 24h) and returns `429` within the cooldown. Be a good citizen: hold a single quote-request SSE stream and update your quotes only when your price meaningfully changes.