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

# Integrate with ?wait=8

> Get the snapshot in one call for most cold wallets, with polling as the fallback.

**Simplest integration: add `?wait=8`.** The API then holds a cold request open for up to 8 seconds while the scan
runs and answers with the `200` snapshot in one call in most cases. If the scan takes longer you get the same `202`
as without `wait`, so keep the [polling loop](https://docs.lucidblock.xyz/guides/polling.md) as the fallback. `wait` is 0 to 10 seconds (default 0)
and the call costs 5 units once.

> [tab] curl
>
> ```bash theme={null}
> BASE_URL="https://api.lucidblock.xyz"
> W="G4VmLamEV6h15gndx7nHn8TTcu7fJkBBNVN3wTugMNtH"
> curl -s -H "Authorization: Bearer $LUCIDBLOCK_TOKEN" "$BASE_URL/v1/solana/wallets/$W/defi-positions?wait=8"
> # usually 200 with the snapshot; otherwise a 202, then poll as in the quickstart
> ```

> [tab] JavaScript
>
> ```js theme={null}
> const BASE_URL = process.env.BASE_URL ?? "https://api.lucidblock.xyz";
> const WALLET = "G4VmLamEV6h15gndx7nHn8TTcu7fJkBBNVN3wTugMNtH";
> const res = await fetch(`${BASE_URL}/v1/solana/wallets/${WALLET}/defi-positions?wait=8`, {
>   headers: { Authorization: `Bearer ${process.env.LUCIDBLOCK_TOKEN}` },
> });
> if (res.status === 200) console.log(await res.json()); // the snapshot
> else if (res.status === 202) console.log("scan still running; poll", (await res.json()).poll_url);
> ```

> [tab] Python
>
> ```python theme={null}
> import os, requests
>
> BASE_URL = os.environ.get("BASE_URL", "https://api.lucidblock.xyz")
> WALLET = "G4VmLamEV6h15gndx7nHn8TTcu7fJkBBNVN3wTugMNtH"
> r = requests.get(f"{BASE_URL}/v1/solana/wallets/{WALLET}/defi-positions",
>                  params={"wait": 8},
>                  headers={"Authorization": f"Bearer {os.environ['LUCIDBLOCK_TOKEN']}"}, timeout=30)
> if r.status_code == 200:
>     print(r.json())  # the snapshot
> elif r.status_code == 202:
>     print("scan still running; poll", r.json()["poll_url"])
> ```

## How it works

The API kicks the scan as usual, then holds the request open for up to `N` seconds. If the scan finishes in time you
get the normal fresh `200` for the new snapshot in one call; if not, you get exactly the `202` (or the stale `200` with
`refreshing: true`) you would have got without `wait`, and the [async flow](https://docs.lucidblock.xyz/guides/polling.md#the-async-flow-202)
continues. A waiting request costs 5 units once.

* On a cold or stale request the API waits up to `N` seconds for the scan it just started. The wait reads only the job
  status from storage, never the chain, so it adds no RPC cost.
* A fresh snapshot is returned at once; `wait` changes nothing.
* Out of range (above 10) is a `400 INVALID_PARAMETER`.

## Why 8 seconds

**`?wait=8` spot check (local, 2026-11-14, not production):** two never-scanned sample wallets each returned `200` in
one call, in 4.7 s and 4.0 s. Consistent with the cold-scan p90 of 6.5 s in
[Performance](https://docs.lucidblock.xyz/reference/performance.md#measured-latency), `?wait=8` returns the snapshot directly for most cold wallets;
slower scans fall back to `202`.


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