Overview

Conventions, authentication, errors, caching and CORS.

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 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). /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 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.