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 as the fallback. wait is 0 to 10 seconds (default 0) and the call costs 5 units once.

curl

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

JavaScript

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);

Python

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 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, ?wait=8 returns the snapshot directly for most cold wallets; slower scans fall back to 202.