Skip to main content
Questions not answered here: <CONTACT_EMAIL>.

How do I make my first request?

Get an access token at <CONTACT_EMAIL> (private alpha), then curl the wallet endpoint with Authorization: Bearer $LUCIDBLOCK_TOKEN. The first request for a wallet usually returns 202 with a job: poll its poll_url after Retry-After seconds until it is succeeded, then request the wallet again for the 200 snapshot. Copy-paste curl, JavaScript and Python versions are in Quickstart.

Which protocols and position types are supported?

Today: native staking (native_stake), liquid staking via SPL Stake Pool and Sanctum pools (spl_stake_pool), Jupiter perpetuals (jupiter_perps), Kamino lending (kamino_lend) and Raydium liquidity (raydium_clmm, raydium_cpmm, raydium_amm_v4). Meteora DLMM, vaults and farm rewards arrive in M3. Orca Whirlpools is pending licence clearance and Drift is not supported. The generated table, the categories not yet covered and the list of detected-but-unsupported protocols are in Supported protocols.

How fresh is the data?

Snapshots older than 120 s are served immediately as stale while a refresh runs (refreshing: true); a wallet with no snapshot returns 202 and is usually scanned within a few seconds. Built-in prices are priced for up to 300 s (TokenPrices prices up to 900 s) and refresh every 2 minutes; lending interest is valued as of each reserve’s last refresh. Everything about freshness, with field names, is in Concepts: data freshness.

How accurate and complete are the results?

Amounts come exactly from chain state. Completeness is reported per protocol in coverage (complete means a missing position is really absent); USD values are given only when sourced, otherwise null, and thin-market or estimated values are labelled indicative or estimated. total_value_usd is null unless both coverage and valuation are complete. See Concepts: coverage vs valuation.

What are the rate limits, and do I need a key?

60 units per minute per IP, a wallet read costs 5 and everything else 1, plus at most 20 new scans per IP per hour. During the private alpha you need an access token (not a paid key; there are no API keys or tiers in v1). See Rate limits and access.

How are USD prices calculated?

From the built-in on-chain price source (graded; thin markets are indicative, old prices stale), with LSTs valued by redemption rate × SOL/USD. Protocol mark prices are informational only, and Pyth is not used. See Concepts: prices in one page.

What do you store about the wallets I look up, and for how long?

Snapshots of the wallet’s public positions and its scan jobs, for 7 days. Logs carry only a wallet_hash, never the address; IP addresses are used in memory for rate limiting; there are no cookies or analytics. See Privacy below.

What does this error mean?

Every error has a stable code, a human message and a request_id. 429 and 503 are retryable after Retry-After; other 4xx mean the request needs fixing. The full table and troubleshooting per code are in Errors.

Why is my position missing?

First check coverage: if the protocol is partial, error or skipped, its positions are not ruled out. The protocol or the position kind may not be supported (unsupported_position_kind), the stake may be one where you are only the stake_authority (shown but not counted), a protocols filter may have excluded it, or the snapshot may be stale and a refresh still running. See Concepts: coverage and Supported protocols.

Why is total_value_usd null?

total_null_reasons says why: coverage_incomplete (a protocol was not fully checked, or the snapshot is stale), empty_universe (no supported protocol scanned), unpriced_legs, indicative_legs, stale_legs, peg_unverified or price_source_unavailable. Read known_value_usd instead: the sum of what could be priced, labelled as partial. See Concepts: totals.

Where can I see what changed?

In the changelog: one entry per milestone with coverage, valuation, endpoint and behaviour changes. Within v1 changes are additive only.

Why doesn’t the total match my wallet app or net worth?

Totals cover only positions in the supported protocols, not plain token balances or unsupported protocols, and they leave out indicative, stale, estimated and staker-only values. It is not net worth. See Concepts: totals.

Why is my stake shown but not counted?

You are the stake authority but not the withdraw authority (owner_role: "stake_authority", flag staker_only): you can delegate it but cannot withdraw it, so it is not yours to count (D-09). See Concepts: ownership.

How are LSTs valued?

By the pool’s redemption rate × SOL/USD (D-08), not the LST’s market price; the market price is shown as market_price_usd for reference. See Concepts: prices.

Why are rewards not in the total?

Claimable rewards and fees count only with include_rewards_in_total=true; estimated accruals never count. See Concepts: exact vs estimated.

Why do slots differ inside one snapshot?

Reads are not atomic, so snapshot_consistency is multi_slot and each leg’s context.as_of_slot says when its amount was exact. See Concepts: snapshots.

Do you support Orca, Drift or marginfi?

Orca Whirlpools is pending licence clearance, Drift is not supported, and marginfi / Project 0 are planned for M3b. See Supported protocols.

Do I need to connect a wallet or sign anything?

No. The API is read-only: give it an address; it never asks for a connection or a signature.

Can I call it from a browser?

Yes: CORS allows any origin and exposes the rate-limit headers. During the alpha, keep the token server-side in public apps. See API reference: CORS.

Is there an SLA, an OpenAPI spec or a demo?

There is no SLA. The OpenAPI 3.1 contract is at /openapi.json. The demo viewer is at https://app.lucidblock.xyz.

Privacy

What we store about a wallet you look up, and for how long:
  • Snapshots of its public positions: kept 7 days (the latest per wallet until replaced). Scan jobs: 7 days.
  • Logs carry a wallet_hash (the first 16 hex characters of SHA-256 of the address), never the raw address.
  • Discovery (from M4) stores only rotating HMAC hashes; raw wallets are deleted within 24 h; transaction signatures are never stored; public candidate endpoints carry no wallet data.
  • IP addresses are used only in memory for rate limiting and are not persisted by us (Cloudflare’s own logging applies).
  • No cookies, no analytics and no third-party scripts on / or the viewer. No wallet connection or signature is ever requested: the API is read-only.