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

# Arbitrage REST API Reference Overview

> Complete reference for the Arbitrage REST API — base URLs, auth methods, request format, response envelopes, pagination, and health endpoints.

The Arbitrage REST API gives you programmatic access to cross-platform prediction market data, scored arbitrage opportunities, unified market indexes, and your Developer Console. All endpoints are served under `/api/v1/` and return JSON. This page covers the conventions that apply to every request you make.

## Base URLs

| Environment | Base URL                          |
| ----------- | --------------------------------- |
| Production  | `https://api.predexy.com`         |
| Staging     | `https://staging-api.predexy.com` |

Use the staging environment for testing integrations without affecting production data. All endpoints, response shapes, and authentication methods are identical across environments.

## API version

The current version is **1.0.0**. Every endpoint path begins with `/api/v1/`. The two health endpoints — `GET /health` and `GET /ready` — sit at the root with no version prefix.

## Request format

Set `Content-Type: application/json` on all requests that include a body. Query parameters are accepted as standard URL-encoded key-value pairs.

## Authentication

Arbitrage supports three authentication methods depending on the endpoint group:

| Method       | Credential                                           | Used for                                                                   |
| ------------ | ---------------------------------------------------- | -------------------------------------------------------------------------- |
| Session JWT  | `Authorization: Bearer <jwt>` or `pdx_access` cookie | Web app, discovery, arbitrage, watchlists, alerts, wallet tracker, console |
| SIWE session | `predex_siwe` cookie                                 | Wallet-connected product routes                                            |
| API key      | `X-API-Key: pdx_...` header                          | External arbitrage endpoint for trading bots and paid integrations         |

See [Authentication](/authentication) for full details on obtaining tokens, refreshing sessions, and creating API keys.

## Health endpoints

Two liveness probes are available with no authentication required:

* `GET /health` — returns `200 OK` when the API server process is running.
* `GET /ready` — returns `200 OK` when the database and dependencies are reachable.

Both return the same shape:

```json theme={null}
{
  "status": "ok",
  "service": "predexy-api",
  "version": "1.0.0"
}
```

## Response envelope

Successful responses wrap the payload in a `data` key. List endpoints additionally include a `meta` object with pagination details:

```json theme={null}
{
  "data": [...],
  "meta": {
    "count": 20,
    "total": 142,
    "offset": 0,
    "limit": 50
  }
}
```

Single-resource endpoints return `data` as an object rather than an array. Some endpoints include additional top-level keys (for example, `tokens` on auth responses).

## Error envelope

All errors follow the same shape:

```json theme={null}
{
  "status": "MACHINE_READABLE_CODE",
  "message": "Human-readable description"
}
```

Internal server details are never exposed. Common status codes include `INVALID_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_ERROR`, `INVALID_API_KEY`, and `QUOTA_EXCEEDED`. See [Error reference](/reference/errors) for the full list.

## Pagination

List endpoints accept `limit` and `offset` query parameters and return pagination state in `meta`:

<ParamField query="limit" default="50" type="number">
  Maximum items to return per page. Range 1–200.
</ParamField>

<ParamField query="offset" default="0" type="number">
  Number of items to skip. Use this to page through results.
</ParamField>

See [Pagination](/reference/pagination) for full details and examples.

## Rate limits

All responses include rate-limit headers:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window              |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

| Tier                           | Requests / min | Burst |
| ------------------------------ | -------------- | ----- |
| Product read (unauthenticated) | 120            | 40    |
| Authenticated session          | 60             | 20    |
| API key                        | 600            | 50    |

See [Rate limits](/reference/rate-limits) for full details and retry guidance.

## Key sections

<CardGroup cols={2}>
  <Card title="Markets & Discovery" icon="chart-bar" href="/api-reference/discover">
    Browse canonical questions with index prices, divergence metrics, and platform slugs.
  </Card>

  <Card title="Arbitrage" icon="arrows-left-right" href="/api-reference/arbitrage-opportunities">
    Scored arbitrage opportunities with session auth or API key access.
  </Card>

  <Card title="Account" icon="user" href="/api-reference/auth">
    Register, log in, manage watchlists, set price alerts, and track wallet positions.
  </Card>

  <Card title="Console" icon="terminal" href="/api-reference/api-keys">
    Create and revoke API keys, and inspect usage statistics and request logs.
  </Card>
</CardGroup>