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

# API Reference

> What every 0xinsider endpoint shares: base URL, auth, envelope, IDs, rate limits, and trust metadata.

## Base URL

```
https://api.0xinsider.com/api/v1/
```

## Authentication

Every endpoint except `/health` needs a Bearer token:

```bash theme={null}
Authorization: Bearer oxi_sk_live_...
```

Generate yours at [0xinsider.com/developers](https://0xinsider.com/developers). Full details in [Authentication](/authentication).

## Response envelope

Single-resource endpoints return:

```json theme={null}
{
  "object": "trader",
  "data": { ... },
  "meta": { "request_id": "req_550e8400", "cached": false }
}
```

List endpoints add pagination fields:

```json theme={null}
{
  "object": "list",
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "97.94_0x863...",
  "meta": { "request_id": "req_550e8400", "cached": false }
}
```

| Field                      | Meaning                                                                         |
| -------------------------- | ------------------------------------------------------------------------------- |
| `object`                   | Shape of `data`. A singular type (`trader`, `market`, `health`, ...) or `list`. |
| `data`                     | The payload: an object or an array.                                             |
| `meta.request_id`          | Give us this when you contact support.                                          |
| `meta.cached`              | `true` when the response came from cache.                                       |
| `has_more` / `next_cursor` | Present on list responses. See [Pagination](/concepts/pagination).              |

Errors share the same envelope, with `"object": "error"`. See [Errors](/errors).

## Prefixed IDs

Every ID is prefixed with its type, so it's self-describing in logs and chat transcripts.

| Entity      | Prefix | Example              |
| ----------- | ------ | -------------------- |
| Trader      | `trd_` | `trd_0xabc123def456` |
| Market      | `mkt_` | `mkt_0x789condition` |
| Whale trade | `wt_`  | `wt_12345`           |
| Radar flag  | `rf_`  | `rf_67890`           |
| Request     | `req_` | `req_550e8400`       |

Trader path endpoints accept raw addresses and valid `trd_...` wallet IDs. Market path endpoints such as `/market/{condition_id}/intel` and `/market/{condition_id}/snapshot` accept either raw provider-backed condition IDs or the `mkt_...` IDs emitted by V1 responses. Single-record whale trade and radar endpoints accept raw integer IDs or their `wt_...` / `rf_...` forms.

## Rate limits

100 requests per minute per user, sliding window. Batch endpoints have an additional 100-item-unit-per-minute budget. `GET /api/v1/usage` does not spend primary quota, but it has its own 100 reads/minute guard.

| Header                        | Meaning                                          |
| ----------------------------- | ------------------------------------------------ |
| `X-RateLimit-Limit`           | Maximum requests per window (`100`).             |
| `X-RateLimit-Remaining`       | How many you have left in the current window.    |
| `X-RateLimit-Reset`           | Unix timestamp (seconds) when the window resets. |
| `X-Request-Cost`              | Item units this single batch call charged.       |
| `X-Batch-RateLimit-Limit`     | Max batch item units per minute.                 |
| `X-Batch-RateLimit-Remaining` | Batch item units remaining.                      |
| `X-Batch-RateLimit-Reset`     | Unix timestamp when the batch window resets.     |
| `Retry-After`                 | Seconds to wait. Only on `429`.                  |

See [Rate Limits](/rate-limits) for backoff patterns.

## Browser CORS

Public REST `/api/v1/*` endpoints, excluding remote MCP (`/api/v1/mcp`), are
callable from third-party browser origins with `Authorization: Bearer ...`. Do
not send cookies or `credentials: "include"` on public API calls.

Remote MCP at `/api/v1/mcp` is also non-credentialed, but still validates
`Origin` against the 0xinsider/localhost allowlist per the MCP Streamable HTTP
DNS-rebinding guidance.

Allowed public request headers:

* `Authorization`
* `Content-Type`
* `If-None-Match`
* `Mcp-Session-Id`

Browser JavaScript may read these response headers:

* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset`
* `Retry-After`
* `ETag`
* `X-Request-Id`
* `X-Request-Cost`
* `X-Batch-RateLimit-Limit`
* `X-Batch-RateLimit-Remaining`
* `X-Batch-RateLimit-Reset`
* `Mcp-Session-Id`
* `X-Mcp-Error-Code`

Credentialed first-party routes such as `/api/keys`, `/api/billing`, and auth
endpoints remain restricted to configured 0xinsider origins.

## Trust metadata

Newer builder endpoints (snapshots, history ranges, batch reads, reports) attach metadata to provider-owned values so you can tell provider-backed, cached, partial, stale, and unavailable data apart.

Per value, four dimensions:

* `source`: where it came from (`provider`, `database`, `cache`, `computed`, `client_input`, `unavailable`).
* `freshness`: how current it is (`fresh`, `refreshing`, `stale`, `not_live`, `unknown`, `unavailable`).
* `reconciliation`: whether it was cross-checked against the source of truth (`provider_backed`, `db_mirror`, `computed`, `partial`, `not_applicable`, `unavailable`).
* `completeness`: whether it reflects the full picture (`complete`, `partial`, `not_computed`, `not_applicable`, `unavailable`).

See [Trust metadata](/concepts/trust-metadata) for what each value means and how to request field-level trust with `expand=trust`.

Rule of thumb: **don't flatten unavailable values into `0`, `[]`, or `{}`.** Read the metadata and surface "unavailable" to your consumer instead of inventing a zero. Provider data that quietly becomes `0` causes silent bugs downstream.