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

# Shared types

> Field tables for the objects the endpoints return.

## Shared types

Field tables generated from `openapi.yaml` (the contract wins for field names). Closed enum values are listed in
[Concepts](https://docs.lucidblock.xyz/concepts/coverage-and-valuation.md).

### Position

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | yes | |
| `protocol` | object | yes | |
| `position_type` | `PositionType` | yes | |
| `category` | `PositionCategory` \| null | yes | |
| `position_account` | string \| null | yes | |
| `owner_role` | `OwnerRole` | yes | |
| `market` | string \| null | yes | |
| `assets` | `Leg`\[] | yes | |
| `debts` | `Leg`\[] | yes | |
| `rewards` | `Leg`\[] | yes | |
| `net_value_usd` | `NullableDecimal` | yes | |
| `known_value_usd` | `NullableDecimal` | yes | |
| `valuation` | object | yes | |
| `accounting` | object | yes | |
| `flags` | string\[] | yes | Open enum. Known values excluded\_from\_totals, staker\_only, unsupported\_position\_kind, interest\_stale, oracle\_stale, incomplete\_position, carried\_forward, has\_estimated\_legs, has\_indicative\_legs, has\_stale\_legs, locked, out\_of\_range. |
| `evidence` | object | yes | |
| `details` | object | yes | Adapter-specific, non-additive data (keys documented per adapter in 02/03). Amounts, prices and rates are strings. |
| `warnings` | string\[] | yes | Open enum; format code or code:detail. |

### Leg

| Field | Type | Required | Description |
| - | - | - | - |
| `role` | `LegRole` | yes | |
| `mint` | `Address` | yes | |
| `symbol` | string \| null | yes | |
| `amount_raw` | `AtomicAmount` | yes | |
| `decimals` | integer | yes | |
| `amount` | `Decimal` | yes | |
| `price_usd` | `NullableDecimal` | yes | |
| `value_usd` | `NullableDecimal` | yes | |
| `pricing_source` | string \| null | yes | |
| `price_as_of` | string \| null | yes | |
| `valuation_status` | `LegValuationStatus` | yes | |
| `confidence` | string \| null (`qualified`, `indicative`) | yes | |
| `claimable` | boolean \| null | yes | |
| `amount_basis` | string (`exact`, `estimated`) | yes | |
| `informational` | boolean | yes | |
| `in_totals` | boolean | yes | |
| `exclusion_reason` | `ExclusionReason` \| null | yes | |
| `context` | `LegContext` \| null | yes | |
| `market_price_usd` | `NullableDecimal` | yes | |
| `protocol_mark_price_usd` | `NullableDecimal` | yes | |
| `price_warnings` | string\[] | yes | |

### LegContext

| Field | Type | Required | Description |
| - | - | - | - |
| `account` | string \| null | yes | |
| `as_of_slot` | integer \| null | yes | |
| `status` | string \| null (`active`, `activating`, `deactivating`, `inactive`, `warming_up`, `unstaking`) | yes | |
| `reward_index` | integer \| null | yes | |

### Coverage

| Field | Type | Required | Description |
| - | - | - | - |
| `status` | string (`complete_for_supported_protocols`, `partial`, `stale`, `pending`) | yes | |
| `last_scan_status` | string (`complete_for_supported_protocols`, `partial`) | no | |
| `universe` | `"supported_adapters_only"` | yes | |
| `supported_protocol_count` | integer | yes | |
| `completed_protocol_count` | integer | yes | |
| `failed_protocol_count` | integer | yes | |
| `skipped_protocol_count` | integer | yes | |
| `unsupported_programs_detected` | integer \| null | yes | |
| `protocols` | `ProtocolCoverage`\[] | yes | |
| `wallet_token_scan` | object | no | |
| `warnings` | string\[] | yes | |

### ProtocolCoverage

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | `AdapterId` | yes | |
| `status` | string (`complete`, `partial`, `error`, `not_applicable`, `skipped`) | yes | |
| `adapter_version` | string | yes | |
| `warnings` | string\[] | yes | |
| `error_code` | string \| null | yes | Open enum. DISCOVERY\_FAILED, INVALID\_ADAPTER\_OUTPUT, ADAPTER\_EXCEPTION, BUDGET\_EXCEEDED, DEADLINE\_EXCEEDED, RPC\_UNSUPPORTED, RPC\_RATE\_LIMITED, ADAPTER\_QUARANTINED, ADAPTER\_DISABLED, ADAPTER\_NOT\_APPROVED, ADAPTER\_SHADOW. |

### Totals

| Field | Type | Required | Description |
| - | - | - | - |
| `total_value_usd` | `NullableDecimal` | yes | |
| `known_value_usd` | `NullableDecimal` | yes | |
| `total_null_reasons` | string (`coverage_incomplete`, `empty_universe`, `unpriced_legs`, `indicative_legs`, `stale_legs`, `peg_unverified`, `price_source_unavailable`)\[] | yes | |
| `unpriced_position_count` | integer | yes | |
| `priced_leg_count` | integer | yes | |
| `indicative_leg_count` | integer | yes | |
| `unpriced_leg_count` | integer | yes | |
| `excluded` | object | yes | |
| `valuation_status` | string (`complete`, `partial`, `unavailable`) | yes | |
| `include_rewards_in_total` | boolean | yes | |
| `price_sources` | `PriceSourceStatus`\[] | yes | |
| `note` | string | yes | |

### WalletTokens

Returned as `tokens` only with `include=tokens` (null otherwise, or for a snapshot stored before tokens existed). It covers the whole snapshot (identical on every page) and comes from the same scan: the wallet's SPL Token and Token-2022 accounts plus one `getBalance` for native SOL. Its total, `tokens_total`, is separate from `totals` and never added to it.

| Field | Type | Description |
| - | - | - |
| `scan.spl_token`, `scan.token_2022`, `scan.native_sol` | `complete` \| `error` | Whether each read succeeded. Any `error` makes `tokens_total.total_value_usd` null. |
| `holdings[]` | object | Native SOL first (mint `11111111111111111111111111111111`, `token_program: native`), then one row per mint with a non-zero balance (`spl_token` or `token_2022`), token accounts summed. |
| `holdings[].amount_raw`, `decimals`, `amount` | string, integer, decimal | As on a leg. |
| `holdings[].symbol`, `name`, `logo_url` | string \| null | From the metadata resolver (display only). |
| `holdings[].verified` | boolean | In our verified token sources. |
| `holdings[].spam_suspected` | boolean | Unverified and either unpriced or flagged `suspicious_name` / `symbol_collision`. Never in `tokens_total`. |
| `holdings[].price_usd`, `value_usd`, `valuation_status`, `pricing_source`, `price_as_of` | | Same rules as a leg: unpriced means `value_usd: null`, never `0`. |
| `holdings[].counted_in_position` | string \| null | The position id that already counts this token (LP mint, LST or vault share, position NFT). Never in `tokens_total`. |
| `holdings[].in_total` | boolean | Counted in `tokens_total.total_value_usd`. |

`tokens_total` (null without `valuation`): `total_value_usd` (null unless every counted holding is `priced` and the scan and snapshot are complete and fresh; `total_null_reasons` from `coverage_incomplete`, `unpriced_tokens`, `indicative_tokens`, `stale_tokens`), `known_value_usd` (priced + indicative), `valuation_status`, per-status counts, `counted_in_position_count`, `spam_suspected_count`, `note`.

### Page

| Field | Type | Required | Description |
| - | - | - | - |
| `limit` | integer | yes | |
| `returned` | integer | yes | |
| `total_positions` | integer | yes | |
| `next_cursor` | string \| null | yes | |
| `page_complete` | boolean | yes | |

### Job

| Field | Type | Required | Description |
| - | - | - | - |
| `job_id` | string | yes | |
| `wallet` | `Address` | yes | |
| `status` | `JobStatus` | yes | |
| `trigger` | string \| null (`kick`, `cron`, `admin`, `canary`) | no | |
| `attempts` | integer | yes | |
| `requested_at` | string \| null | yes | |
| `started_at` | string \| null | yes | |
| `finished_at` | string \| null | yes | |
| `next_retry_at` | string \| null | yes | |
| `retry_reason` | string \| null | yes | |
| `snapshot_id` | string \| null | yes | |
| `observed_slots` | `SlotRange` \| null | no | |
| `errors` | object\[] | no | |

### JobAccepted

| Field | Type | Required | Description |
| - | - | - | - |
| `job_id` | string | yes | |
| `status` | string (`queued`, `running`) | yes | |
| `wallet` | `Address` | yes | |
| `retry_after_seconds` | integer | yes | |
| `poll_url` | string | yes | |
| `request` | `RequestEcho` | yes | |

### ErrorEnvelope

| Field | Type | Required | Description |
| - | - | - | - |
| `error` | object | yes | |
| `request_id` | string | yes | |


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