> ## 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.

# Coverage vs valuation

> Did we look everywhere we support, and could we price what we found?

## The supported universe

Only verified, approved protocol adapters contribute positions. Every response says so with
`universe: "supported_adapters_only"`, and `release_status` is `alpha_partial` until the full-scope release gate passes,
then `v1`. Protocols the API does not support are invisible to it: a wallet's total is the total of its positions **in
the supported protocols**, not its net worth. [Supported protocols](https://docs.lucidblock.xyz/reference/supported-protocols.md) lists them.

## Coverage vs valuation: two independent axes

Two separate questions are answered for every snapshot:

| Axis | Question | Fields |
| - | - | - |
| Coverage | Did we look everywhere we support? | `coverage.status`, `coverage.protocols[].status`, `error_code`, `wallet_token_scan`, `unsupported_programs_detected` |
| Valuation | Could we price what we found? | leg `valuation_status`, position `valuation.status`, `totals.valuation_status` |

**Snapshot coverage** (`coverage.status`):

* `complete_for_supported_protocols`: every supported protocol was checked for this wallet.
* `partial`: at least one protocol could not be fully checked (see its `error_code`).
* `stale`: the snapshot is older than the freshness target (but at most 10 minutes old); it is served at once while a refresh runs. A snapshot older than 10 minutes is never served: the request returns `202` and runs a fresh scan.
* `pending`: reserved for a snapshot still being built; never returned in a 200 (you get a 202 instead).

**Per-protocol coverage** (`coverage.protocols[].status`): `complete` (checked, so any absence is real), `partial`
(some accounts could not be read), `error` (the adapter failed; `error_code` says why), `not_applicable` (nothing to
check for this wallet) and `skipped` (not run: for example `ADAPTER_QUARANTINED`, `ADAPTER_DISABLED`,
`ADAPTER_NOT_APPROVED`, `BUDGET_EXCEEDED`). `unsupported_programs_detected` is `null` when the check was not done.

The two axes combine: coverage can be complete while valuation is partial (we found everything but could not price a
token), or coverage partial while every found leg is priced. **Absence of a position is trustworthy only for protocols
listed `complete`.** Accuracy follows from both: amounts come exactly from chain state; a USD figure is shown only when
a qualified source priced it (`valuation_status` `priced`), or labelled `indicative` (thin market) or `estimated`
(an accrual not yet booked on chain). `total_value_usd` is `null` whenever either axis is incomplete, with
`total_null_reasons` saying which; `known_value_usd` still reports what could be priced.

> [accordion] Captured example
>
> `GET /v1/solana/wallets/hmrMmA2tRn3LvzJVRWp61MMBhEppATWnQnD7HyqxJvo/defi-positions` → `200` (captured 2026-11-12 from local `positions-perps`)
>
> ```json theme={null}
> {
>   "chain": "solana",
>   "network": "mainnet-beta",
>   "wallet": "hmrMmA2tRn3LvzJVRWp61MMBhEppATWnQnD7HyqxJvo",
>   "snapshot_id": "701cd92f-485d-424b-953c-c3186f4a8b85",
>   "release_status": "alpha_partial",
>   "as_of": "2026-11-12T20:34:08Z",
>   "observed_slots": {
>     "minimum": 468660763,
>     "maximum": 468660769
>   },
>   "snapshot_consistency": "multi_slot",
>   "refreshing": false,
>   "refresh_job_id": null,
>   "freshness": {
>     "age_seconds": 3,
>     "stale": false,
>     "max_age_seconds": 120
>   },
>   "coverage": {
>     "status": "complete_for_supported_protocols",
>     "universe": "supported_adapters_only",
>     "supported_protocol_count": 7,
>     "completed_protocol_count": 7,
>     "failed_protocol_count": 0,
>     "unsupported_programs_detected": null,
>     "protocols": [
>       {
>         "id": "native_stake",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "spl_stake_pool",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "jupiter_perps",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "kamino_lend",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "raydium_cpmm",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "raydium_amm_v4",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "raydium_clmm",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [
>           "limit_orders_not_scanned"
>         ],
>         "error_code": null
>       }
>     ],
>     "wallet_token_scan": {
>       "spl_token": "complete",
>       "token_2022": "complete",
>       "token_accounts_found": 7
>     },
>     "warnings": [
>       "program_discovery_not_run"
>     ],
>     "skipped_protocol_count": 0
>   },
>   "positions": [
>     {
>       "id": "solana:jupiter_perps:2UsFXJiSryxUVrARQahEvgzhdfMVHQx1XsMkmHc5BwaN",
>       "protocol": {
>         "id": "jupiter_perps",
>         "name": "Jupiter Perps",
>         "program_id": "PERPHjGBqRHArX4DySjwM6UJHiR3sWAatqfdBS2qQJu"
>       },
>       "position_type": "perpetual",
>       "category": "perpetual",
>       "position_account": "2UsFXJiSryxUVrARQahEvgzhdfMVHQx1XsMkmHc5BwaN",
>       "owner_role": "authority",
>       "market": "5BUwFW4nRbftYTDMbgxykoFWqWHPzahFSNAaaaJtVKsq",
>       "assets": [
>         {
>           "role": "margin",
>           "mint": "3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh",
>           "symbol": null,
>           "amount_raw": "5837975",
>           "decimals": 8,
>           "amount": "0.05837975",
>           "price_usd": "71592.807753817981",
>           "value_usd": "4179.570218465955276285",
>           "pricing_source": "builtin:meteora-dlmm",
>           "price_as_of": "2026-11-12T20:33:47.000Z",
>           "valuation_status": "priced",
>           "confidence": "qualified",
>           "claimable": null,
>           "amount_basis": "exact",
>           "informational": false,
>           "in_totals": true,
>           "market_price_usd": null,
>           "protocol_mark_price_usd": null,
>           "price_warnings": [],
>           "exclusion_reason": null,
>           "context": {
>             "account": "5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm",
>             "as_of_slot": null,
>             "status": null,
>             "reward_index": null
>           }
>         }
>       ],
>       "debts": [
>         {
>           "role": "unrealized_pnl",
>           "mint": "3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh",
>           "symbol": null,
>           "amount_raw": "2473252",
>           "decimals": 8,
>           "amount": "0.02473252",
>           "price_usd": "71592.807753817981",
>           "value_usd": "1770.670549627458291442",
>           "pricing_source": "builtin:meteora-dlmm",
>           "price_as_of": "2026-11-12T20:33:47.000Z",
>           "valuation_status": "priced",
>           "confidence": "qualified",
>           "claimable": null,
>           "amount_basis": "exact",
>           "informational": false,
>           "in_totals": true,
>           "market_price_usd": null,
>           "protocol_mark_price_usd": null,
>           "price_warnings": [],
>           "exclusion_reason": null,
>           "context": {
>             "account": "5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm",
>             "as_of_slot": null,
>             "status": null,
>             "reward_index": null
>           }
>         },
>         {
>           "role": "funding",
>           "mint": "3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh",
>           "symbol": null,
>           "amount_raw": "3231",
>           "decimals": 8,
>           "amount": "0.00003231",
>           "price_usd": "71592.807753817981",
>           "value_usd": "2.313163618525858966",
>           "pricing_source": "builtin:meteora-dlmm",
>           "price_as_of": "2026-11-12T20:33:47.000Z",
>           "valuation_status": "priced",
>           "confidence": "qualified",
>           "claimable": null,
>           "amount_basis": "exact",
>           "informational": false,
>           "in_totals": true,
>           "market_price_usd": null,
>           "protocol_mark_price_usd": null,
>           "price_warnings": [],
>           "exclusion_reason": null,
>           "context": {
>             "account": "5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm",
>             "as_of_slot": null,
>             "status": null,
>             "reward_index": null
>           }
>         }
>       ],
>       "rewards": [],
>       "net_value_usd": "2406.586505219971125877",
>       "known_value_usd": "2406.586505219971125877",
>       "valuation": {
>         "status": "complete",
>         "priced_leg_count": 3,
>         "indicative_leg_count": 0,
>         "unpriced_leg_count": 0
>       },
>       "accounting": {
>         "counts_toward_totals": true,
>         "parent_position_id": null,
>         "carried_forward_from_snapshot": null
>       },
>       "flags": [],
>       "evidence": {
>         "slot": 468660579,
>         "adapter_version": "1.0.0",
>         "method": "pda",
>         "accounts": [
>           "2UsFXJiSryxUVrARQahEvgzhdfMVHQx1XsMkmHc5BwaN",
>           "5BUwFW4nRbftYTDMbgxykoFWqWHPzahFSNAaaaJtVKsq",
>           "5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm",
>           "hUqAT1KQ7eW1i6Csp9CXYtpPfSAvi835V7wKi5fRfmC"
>         ],
>         "decoder_hash": "e1147a2da83b2a1c3836583e06e8d8b1aae5803f4edf0dc9e475d373a0d73876"
>       },
>       "details": {
>         "side": "long",
>         "custody": "5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm",
>         "collateral_custody": "5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm",
>         "market_mint": "3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh",
>         "size_usd": "180619.471873",
>         "notional_usd": "180619.471873",
>         "signed_size_usd": "180619.471873",
>         "entry_price_usd": "72039.747749",
>         "collateral_usd": "4164.580896",
>         "realised_pnl_usd": "-7488.810591",
>         "locked_amount_raw": "250721966",
>         "open_time": "1794461719",
>         "update_time": "1794512430",
>         "max_leverage_bps": "5000000",
>         "liquidation_price_usd": null,
>         "protocol_mark_usd": "71336.051934",
>         "collateral_mark_usd": "71336.051934",
>         "oracle_timestamp": "1794515648",
>         "pnl_usd": "-1764.319983",
>         "borrow_fee_usd": "2.304344",
>         "equity_usd": "2397.956569",
>         "estimated_close_fee_usd": "126.433631",
>         "net_close_value_usd": "2271.522938"
>       },
>       "warnings": []
>     }
>   ],
>   "page": {
>     "limit": 100,
>     "returned": 1,
>     "total_positions": 1,
>     "next_cursor": null,
>     "page_complete": true
>   },
>   "totals": {
>     "total_value_usd": "2406.586505219971125877",
>     "known_value_usd": "2406.586505219971125877",
>     "total_null_reasons": [],
>     "unpriced_position_count": 0,
>     "priced_leg_count": 3,
>     "indicative_leg_count": 0,
>     "unpriced_leg_count": 0,
>     "excluded": {
>       "indicative_value_usd": null,
>       "stale_value_usd": null,
>       "estimated_rewards_value_usd": null,
>       "claimable_rewards_not_included_usd": null,
>       "staker_only_value_usd": null
>     },
>     "valuation_status": "complete",
>     "include_rewards_in_total": false,
>     "price_sources": [],
>     "note": "Value includes only the explicitly supported scanned DeFi universe; it is not universal wallet net worth."
>   },
>   "request": {
>     "include": [
>       "underlying",
>       "rewards",
>       "valuation"
>     ],
>     "protocols": null,
>     "freshness_seconds": 120,
>     "include_rewards_in_total": false,
>     "limit": 100
>   }
> }
> ```

## Null, not zero

> [!WARNING]
>
> **`null` is never `0`.** An unknown amount or value is `null`; a real zero is the string `"0"`. Never sum a `null` as
> zero: read `total_null_reasons` or the leg's `valuation_status` instead.

Unknown values are `null`, never `"0"`. A verified empty, complete universe gives `total_value_usd: "0"` and
`known_value_usd: null`. Amounts are strings: `amount_raw` is the atomic integer and `amount` the exact decimal (with
`decimals`). USD values are decimal strings too. Parse them with a decimal library; floats lose precision.

> [accordion] Captured example
>
> `GET /v1/solana/wallets/4kwmwFxgKnFb3nEDd149KLNCAJLSvgPVTWAQM9qUCJw1/defi-positions` → `200` (captured 2026-11-12 from local `positions-empty`)
>
> ```json theme={null}
> {
>   "chain": "solana",
>   "network": "mainnet-beta",
>   "wallet": "4kwmwFxgKnFb3nEDd149KLNCAJLSvgPVTWAQM9qUCJw1",
>   "snapshot_id": "0e01e06b-2cbe-440f-9990-8e959d4796c0",
>   "release_status": "alpha_partial",
>   "as_of": "2026-11-12T20:34:11Z",
>   "observed_slots": {
>     "minimum": 468660778,
>     "maximum": 468660784
>   },
>   "snapshot_consistency": "multi_slot",
>   "refreshing": false,
>   "refresh_job_id": null,
>   "freshness": {
>     "age_seconds": 3,
>     "stale": false,
>     "max_age_seconds": 120
>   },
>   "coverage": {
>     "status": "complete_for_supported_protocols",
>     "universe": "supported_adapters_only",
>     "supported_protocol_count": 7,
>     "completed_protocol_count": 7,
>     "failed_protocol_count": 0,
>     "unsupported_programs_detected": null,
>     "protocols": [
>       {
>         "id": "native_stake",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "spl_stake_pool",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "jupiter_perps",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "kamino_lend",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "raydium_cpmm",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "raydium_amm_v4",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [],
>         "error_code": null
>       },
>       {
>         "id": "raydium_clmm",
>         "adapter_version": "1.0.0",
>         "status": "complete",
>         "warnings": [
>           "limit_orders_not_scanned"
>         ],
>         "error_code": null
>       }
>     ],
>     "wallet_token_scan": {
>       "spl_token": "complete",
>       "token_2022": "complete",
>       "token_accounts_found": 0
>     },
>     "warnings": [
>       "program_discovery_not_run"
>     ],
>     "skipped_protocol_count": 0
>   },
>   "positions": [],
>   "page": {
>     "limit": 100,
>     "returned": 0,
>     "total_positions": 0,
>     "next_cursor": null,
>     "page_complete": true
>   },
>   "totals": {
>     "total_value_usd": "0",
>     "known_value_usd": null,
>     "total_null_reasons": [],
>     "unpriced_position_count": 0,
>     "priced_leg_count": 0,
>     "indicative_leg_count": 0,
>     "unpriced_leg_count": 0,
>     "excluded": {
>       "indicative_value_usd": null,
>       "stale_value_usd": null,
>       "estimated_rewards_value_usd": null,
>       "claimable_rewards_not_included_usd": null,
>       "staker_only_value_usd": null
>     },
>     "valuation_status": "complete",
>     "include_rewards_in_total": false,
>     "price_sources": [],
>     "note": "Value includes only the explicitly supported scanned DeFi universe; it is not universal wallet net worth."
>   },
>   "request": {
>     "include": [
>       "underlying",
>       "rewards",
>       "valuation"
>     ],
>     "protocols": null,
>     "freshness_seconds": 120,
>     "include_rewards_in_total": false,
>     "limit": 100
>   }
> }
> ```


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