​

Data Quality and Observability

​

1. Wallet Graph / Holder Wall

​

Endpoint

GET /api/wallet?address=<0x-address-or-ENS>

​

WalletGraph v1 response contract

​

Provider selection

​

Observability fields

{
  "provider": "etherscan",
  "source": "live",
  "partial": false,
  "fallback": false,
  "providerErrors": false,
  "freshness": "2026-05-14",
  "durationMs": 312,
  "timing": { "totalMs": 312, "providerMs": 180, "coingeckoMs": 80 }
}

• provider: normalized provider name.
• source: data class — live (real provider data), mock (demo/no keys), or fallback (price fallback active).
• partial: true when any provider sub-request failed or transaction data is sampled.
• fallback: true when fallback pricing or demo data is being served.
• providerErrors: true when apiErrors contains entries with severity === 'partial' or 'error'.
• freshness: wallet’s lastActive ISO date string, or null.
• durationMs: total route wall-clock time in milliseconds.
• timing: sub-phase breakdowns. Allowed keys: totalMs, providerMs, coingeckoMs, graphMs, duneMs.

​

dataQuality flags

{
  "isFallback": false,
  "isDemo": false,
  "isPartial": true,
  "warnings": ["Loaded latest 200 normal transactions; totals may be partial."],
  "flags": {
    "partial": true,
    "sampled": false,
    "fallback": false,
    "demo": false,
    "providerErrors": true
  },
  "providerErrors": []
}

• partial: set when data is sampled or any provider sub-call degraded.
• sampled: set when transactionSample.isSampled is true.
• fallback: set when fallback pricing is active.
• demo: set only for explicit mock/demo data.
• providerErrors: set when apiErrors contains partial or error entries.

​

apiErrors sanitization

1. Strips URL query strings (which may contain provider API keys or tokens) — replaced with [params redacted].
2. Caps message length at 200 characters.

​

UI status badge behavior

• Reads from observability when present; falls back to legacy dataQuality fields.
• Invariant copy: “Read-only public wallet data · No wallet connection required”
• Conditional: partial note, “Some provider data unavailable”, “Fallback data source”, “Demo mode”, provider name, freshness, durationMs.
• Never exposes raw URLs, API keys, stack traces, or provider error details.

​

2. Stable Seer

​

Endpoint

GET /api/market-radar?q=<search-query>

​

Cache behavior

​

confidence values

​

3. Agent guardrails

• Do not conflate Holder Wall and Stable Seer. These are separate features with separate data sources and API routes.
• Do not invent holder data. holderAnalyticsSupported: false on all Stable Seer responses is a hard invariant.
• Do not expose secrets. sanitizeApiErrorMessage strips query strings from error messages. Tests verify no provider key strings appear in normalized output.
• Keep partial provider degradation non-fatal and non-scary. A failed sub-provider call sets partial: true and contributes an apiErrors entry. It does not fail the route. UI copy should say “Provider data may be partial” — not “Error” or “Failed”.
• Preserve existing response contracts. contractVersion: "walletGraph.v1" must be present on every /api/wallet response. The observability field must be present on every normalized response.

​

Related files