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

# Overview

> Conventions, authentication, errors, caching and CORS.

```bash theme={null}
BASE_URL="https://api.lucidblock.xyz"
```

The machine-readable contract is the OpenAPI 3.1 document served at `/openapi.json`. The endpoint pages in this section
are generated from it; [Shared types](https://docs.lucidblock.xyz/api-reference/shared-types.md) lists the objects they return.

## Conventions

| Topic | Rule |
| - | - |
| Format | JSON, UTF-8. Field names are `snake_case`. |
| Numbers | Amounts and USD values are decimal **strings** (`amount`, `value_usd`); `amount_raw` is the atomic integer as a string. Slots and counts are JSON numbers. |
| Unknown | `null`, never `"0"`. A real zero is `"0"`. |
| Time | ISO 8601 UTC (`2026-11-12T15:52:49Z`). |
| Addresses | Base58, 32 bytes, case-sensitive. |
| Versioning | Path prefix `/v1`. Within v1 changes are additive: new optional fields, and new values in **open enums** (`flags`, `warnings`, `price_warnings`, coverage `error_code`, `details` keys). Clients must ignore unknown fields and unknown open-enum values. **Closed enums** (`valuation_status`, `position_type`, `owner_role`, coverage `status`, job `status`) change only with a new path version. |
| Query parameters | Strict: an unknown parameter is a `400 INVALID_PARAMETER`. |

## Authentication

During the private alpha every `/v1/*` route except `/v1/health` needs `Authorization: Bearer $LUCIDBLOCK_TOKEN`
(request a token: see [Rate limits and access](https://docs.lucidblock.xyz/reference/rate-limits.md#access-during-the-alpha)). `/v1/health`,
`/openapi.json` and `/` are open. A missing or wrong token gives `401 UNAUTHORIZED`.

## Errors

Every error uses one envelope, `{"error": {"code", "message", "details?"}, "request_id"}`; codes never change meaning.
[Errors](https://docs.lucidblock.xyz/reference/errors.md) lists every code.

## Caching, CORS and request IDs

* `Cache-Control`: wallet snapshots `no-store`; `/v1/solana/protocols` and `/v1/solana/coverage` `public, max-age=60`;
  `/` and `/openapi.json` `public, max-age=3600`.
* CORS: `Access-Control-Allow-Origin: *`; allowed request headers `authorization`, `x-request-id`; exposed response
  headers `x-request-id`, `ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`, `retry-after`; preflights are
  cached for 7,200 s and cost nothing. Browsers send no cookies.
* Every response carries `X-Request-Id` (yours, if you sent one); quote it when reporting a problem.


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