Freshness

Snapshot age, slots, price age and the stale-while-refreshing rules.

Snapshots, slots and freshness

as_of is when the snapshot was built. Reads are not atomic: observed_slots gives the slot range read and snapshot_consistency is normally multi_slot. Each leg’s context.as_of_slot says when its amount was exact. freshness gives age_seconds, stale and max_age_seconds. A stale snapshot comes with refreshing: true and a refresh_job_id. After an adapter failure, a position may be carried forward from the previous snapshot (flag carried_forward). Data freshness has the numbers.

Data freshness

How old is what you see?

• Snapshot freshness target: 120 s (SNAPSHOT_FRESHNESS_S). An older snapshot is served immediately with freshness.stale: true and refreshing: true, and a refresh scan starts; poll refresh_job_id or request again later. While stale, coverage.status is stale and total_value_usd is null (coverage_incomplete).
• Cold wallets: the first request returns 202; retry_after_seconds is 3 when the scan was kicked at once (otherwise the seconds to the next scheduled run plus 5). Typical scans take 2–6 s.
• freshness_seconds (0…86,400) sets how old a snapshot you accept. Lower values cause more scans and can hit the cold-scan limit; freshness_seconds=0 always marks the stored snapshot stale.
• Time and slots: as_of is when the snapshot was built; observed_slots is the slot range read; snapshot_consistency: multi_slot is normal because reads are not atomic.
• Price age: each leg has price_as_of. A built-in on-chain price is priced for up to 300 s, a TokenPrices price for up to 900 s; older prices are stale (shown, not counted) up to 24 h and not served beyond that. LST redemption rates are stale from an epoch lag of 3 (a warning at 1–2). Prices refresh every 2 minutes.
• Lending interest is valued as of each reserve’s last refresh: the leg’s context.as_of_slot says which slot, an old reserve sets the interest_stale flag, and no interest is projected forward (D-15).
• Retention: snapshots are kept 7 days.
• Measured numbers (latency, cold-scan time, RPC calls per scan) are in Performance and freshness.

Captured example

GET /v1/solana/wallets/GSyXx6WRm2o6Qu4RWxTH17swLZKpTKQdQTS2uGcus1NF/defi-positions?freshness_seconds=0 → 200 (captured 2026-11-12 from local positions-stale)

{
  "chain": "solana",
  "network": "mainnet-beta",
  "wallet": "GSyXx6WRm2o6Qu4RWxTH17swLZKpTKQdQTS2uGcus1NF",
  "snapshot_id": "b25c3f87-0625-4adf-92b2-6143dab53368",
  "release_status": "alpha_partial",
  "as_of": "2026-11-12T20:33:37Z",
  "observed_slots": {
    "minimum": 468660616,
    "maximum": 468660623
  },
  "snapshot_consistency": "multi_slot",
  "refreshing": true,
  "refresh_job_id": "635ed7d1-403a-4526-8954-710fee88c2fe",
  "freshness": {
    "age_seconds": 37,
    "stale": true,
    "max_age_seconds": 0
  },
  "coverage": {
    "status": "stale",
    "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": 1
    },
    "warnings": [
      "program_discovery_not_run"
    ],
    "last_scan_status": "complete_for_supported_protocols",
    "skipped_protocol_count": 0
  },
  "positions": [
    {
      "id": "solana:spl_stake_pool:Jito4APyf642JPZPx3hGc6WWJ8zPKtRbRs4P815Awbb",
      "protocol": {
        "id": "spl_stake_pool",
        "name": "SPL Stake Pool",
        "program_id": "SPoo1Ku8WFXoNDMHPsrGSTSG1Y47rzgn41SLUNakuHy"
      },
      "position_type": "liquid_staking",
      "category": "liquid_staking",
      "position_account": "Jito4APyf642JPZPx3hGc6WWJ8zPKtRbRs4P815Awbb",
      "owner_role": "token_holder",
      "market": "Jito4APyf642JPZPx3hGc6WWJ8zPKtRbRs4P815Awbb",
      "assets": [
        {
          "role": "staked",
          "mint": "J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn",
          "symbol": "JitoSOL",
          "amount_raw": "284373080105",
          "decimals": 9,
          "amount": "284.373080105",
          "price_usd": "106.909966539254995",
          "value_usd": "30402.316478690430312825",
          "pricing_source": "lst_redemption_rate×SOL/USD",
          "price_as_of": "2026-11-12T20:31:41.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": "Jito4APyf642JPZPx3hGc6WWJ8zPKtRbRs4P815Awbb",
            "as_of_slot": null,
            "status": null,
            "reward_index": null
          }
        }
      ],
      "debts": [],
      "rewards": [],
      "net_value_usd": "30402.316478690430312825",
      "known_value_usd": "30402.316478690430312825",
      "valuation": {
        "status": "complete",
        "priced_leg_count": 1,
        "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": 468660616,
        "adapter_version": "1.0.0",
        "method": "wallet_token",
        "accounts": [
          "Jito4APyf642JPZPx3hGc6WWJ8zPKtRbRs4P815Awbb",
          "SysvarC1ock11111111111111111111111111111111",
          "8yoigZfzZ1nNaadumY9uPVD118225UYHTDpmjpr2nrSa"
        ],
        "decoder_hash": "651da9f5fe95ee3f66d40eee52bc1d0ba9dc6fd35a00bdb8823672f372a2e31d"
      },
      "details": {
        "program": "SPoo1Ku8WFXoNDMHPsrGSTSG1Y47rzgn41SLUNakuHy",
        "sol_per_lst": "1.31112971092582292",
        "sol_equivalent_lamports": "372849994313",
        "view_only": true,
        "last_update_epoch": "1084",
        "clock_epoch": "1084",
        "token_accounts": [
          "8yoigZfzZ1nNaadumY9uPVD118225UYHTDpmjpr2nrSa"
        ],
        "epoch_fee_bps": "400",
        "redeemable_sol_after_fee": null,
        "pricing_basis": "lst_redemption_rate×SOL/USD"
      },
      "warnings": []
    }
  ],
  "page": {
    "limit": 100,
    "returned": 1,
    "total_positions": 1,
    "next_cursor": null,
    "page_complete": true
  },
  "totals": {
    "total_value_usd": null,
    "known_value_usd": "30402.316478690430312825",
    "total_null_reasons": [
      "coverage_incomplete"
    ],
    "unpriced_position_count": 0,
    "priced_leg_count": 1,
    "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": 0,
    "include_rewards_in_total": false,
    "limit": 100
  }
}