Skip to main content
How Lucidblock Positions turns exact on-chain amounts into USD values, and when it refuses to. Every value is an indicative mark-to-market at spot: it is not a liquidation, execution or sale price, and the wallet total is not net worth (see Not net worth). Amounts are always exact. Valuation never changes an amount and never drops a leg: when a price is missing or not credible the leg stays, with value_usd: null and a valuation_status saying why. Unknown is null, never 0.

Sources

Each mint gets one price per snapshot, used by every leg of that mint. Sources are consulted in this order:
  1. Rate-derived (lst_rate): liquid staking tokens are valued at their on-chain redemption rate × SOL/USD (see LST basis). Our own maths over public stake-pool state.
  2. TokenPrices (tokenprices): the owner’s sibling on-chain DEX pricing service. Disabled until it serves Solana.
  3. Built-in on-chain reader (builtin_onchain): our own reading of a fixed, verified set of Raydium AMM v4, Raydium CLMM, Raydium CPMM and Meteora DLMM pools, refreshed every 2 minutes. Prices route to USDC or USDT, directly or through SOL (at most 2 hops).
Never used for a value: protocol oracle prices (Kamino reserve prices, the Jupiter Perps Doves mark, Pyth) and third-party price APIs. A protocol price may appear only in the informational field protocol_mark_price_usd; it is never summed and changing it changes no total. Fungible LP tokens, CLMM position NFTs and vault shares are never priced by any source: their value comes only from the adapter’s underlying legs (valued_via_underlying). Every leg carries pricing_source (the methodology, for example builtin:raydium-amm-v4 or lst_redemption_rate×SOL/USD) and price_as_of (the time of the chain state the price was read from).

Grades

Each candidate route is graded on its liquidity (2 × min(side value), sides net of protocol, fund and creator fees) and on the cost of selling $100 through it, fee included: The best route is chosen by grade, then liquidity, then $1,000 cost. If another grade-A route disagrees by more than 500 bps, the price is withheld (error, divergent_markets): we do not know which market is right. SOL anchor. SOL/USD is priced only when at least two grade-A pools on two different programs, each with at least $1M of liquidity, agree within 50 bps. When only one such pool qualifies, a qualified TokenPrices SOL/USD quote no older than 15 minutes that agrees within the same 50 bps counts as the second source: SOL stays priced at the on-chain price, and pricing_source names the confirmation (for example builtin:raydium-amm-v4+anchor_confirmed_by:tokenprices). TokenPrices is read once per 2-minute price refresh, never per request. Without that confirmation, one source gives indicative (anchor_single_source); 50 to 500 bps of disagreement gives indicative (anchor_sources_disagree); more is an error. Every token priced through SOL inherits this ceiling.

Thresholds

Peg limitation

USDC and USDT are served as exactly $1 only after a cross-stable check: the direct USDT/USDC pool and the triangular rate through SOL must agree (within 25 bps of 1, or 50 bps with warning stable_peg_drift). When they disagree a third stable (PYUSD) identifies the outlier; the failing coin and every price routed through it are withheld (peg_unverified, anchor_peg_unverified), and a recovering coin needs 3 consecutive passing samples. Limitation: cross-stable checks cannot detect all USD stablecoins depegging together; only an off-chain USD reference could, and none is used. A $1 USDC therefore means “USDC is still worth the same as USDT and PYUSD”.

LST basis

Liquid staking tokens (JitoSOL and other SPL stake pools) are valued at their redemption rate: amount × (SOL per LST) × SOL/USD, as an exact rational rounded once. The same rate applies to the same mint everywhere in a snapshot (wallet holdings and lending collateral alike).
  • A rate one or two epochs old adds warning rate_not_updated_this_epoch; three or more epochs makes the leg stale.
  • If SOL is indicative, the LST is indicative too.
  • An LST without a verified rate is unsupported; it never gets a guessed rate or a market price as its value.
  • The market price is shown alongside as market_price_usd only when a qualified market exists. Below 97 % of the rate value the leg gets lst_market_discount; above 101 %, lst_market_premium. It is never summed.
  • The SOL-equivalent amount in details is a view, never a leg and never summed.

Indicative and stale

  • indicative: a real but thin or estimated market. The leg shows price_usd and value_usd and counts in known_value_usd, but total_value_usd becomes null with reason indicative_legs.
  • stale: the last good price is older than its freshness limit. The leg shows the old value, flagged, but it counts in neither sum; total_value_usd becomes null with reason stale_legs.
  • unsupported, no_liquidity, error: no value at all (value_usd: null); the total becomes null with reason unpriced_legs. A detected position kind that is not valued yet (for example a DLMM limit order) has the same effect: it is never shown as zero.
known_value_usd is “the current value we can show”. total_value_usd is the same sum, reported only when it is complete: every supported protocol scanned, every counted leg priced, no peg failure and no unavailable source. Rewards and claimable fees are excluded unless include_rewards_in_total=true; estimated rewards never count.

Not net worth

Totals cover only the explicitly supported, scanned DeFi universe. They are not total wallet net worth: plain token balances outside supported protocols, unsupported protocols and off-chain assets are not included. Values are spot marks, not executable: selling a large position would move the market (see position_exceeds_market_liquidity), and lending or perp positions are not valued at liquidation.