---
title: "Verified current on-chain holdings (ULTRA)"
method: GET
path: "/wallet/{address}/holdings"
tags: ["Wallet"]
---

# Verified current on-chain holdings (ULTRA)

`GET /wallet/{address}/holdings`

## Request

- Base URL: `https://madeonsol.com/api/v1`
- URL: `https://madeonsol.com/api/v1/wallet/{address}/holdings`
- Auth: HTTP bearer

The wallet's ACTUAL current token balances, read live from chain (SPL + Token-2022 accounts + SOL balance), then enriched from our data (price, market cap, name/symbol). Unlike `/positions` (trade-derived FIFO — transfer-blind, launchpad-scoped), this is a chain-verified holdings census. Each holding carries `transfer_delta` = on-chain amount minus the trade-derived net position, which exposes tokens that arrived/left WITHOUT a swap (airdrops, insider funding, wallet-hopping). 90s cache; 6 uncached lookups/min/user. ULTRA only.

## Path parameters

- `address` string, required

## Query parameters

- `limit` integer
- `min_value_usd` number

## Response `200`

OK

- object
  - `address` string
  - `sol_balance` number
  - `holdings` WalletHolding[]
    - `mint` string
    - `symbol` string, nullable
    - `name` string, nullable
    - `amount` number
    - `amount_raw` string: Raw integer amount (pre-decimals) as a string.
    - `decimals` integer
    - `token_program` 'spl' | 'token2022'
    - `price_usd` number, nullable
    - `value_usd` number, nullable
    - `market_cap_usd` number, nullable
    - `is_bonded` boolean, nullable
    - `trade_derived_amount` number, nullable
    - `transfer_delta` number, nullable
  - `summary` object
    - `token_accounts` integer
    - `non_zero` integer
    - `returned` integer
    - `priced` integer
    - `total_value_usd` number
    - `truncated` boolean
  - `verified_at` string, date-time
  - `trade_window_days` integer
  - `cache_hit` boolean
  - `ttl_seconds` integer
  - `coverage` TradeCoverage: Coverage disclosure for endpoints backed by our persisted trade capture (`token_trades` / early-buyer data). Capture starts 2026-04-12 and persistence is gated to the launchpad pipeline (pump.fun, LaunchLab/bonk, bags) — it is NOT a full Solana trade history. Three separate answers (2026-09-21): `data_observed`/`in_scope` = at least one persisted row (presence, not completeness — a brand-new in-scope mint with no trades yet also reads false), `eligibility` = whether the CURRENT gate admits the subject, `completeness` = always `not_verified`. When no rows exist, zero/empty values mean 'not captured' (see eligibility for why), never 'no activity'.
    - `history_start` integer: Epoch seconds of the first persisted trade (2026-04-12).
    - `scope` string
    - `in_scope` boolean, nullable: Kept for compatibility — same value as data_observed: true = we hold ≥1 persisted trade for this subject · false = none persisted (see eligibility for why — a brand-new in-scope mint also reads false) · null = probe unavailable
    - `data_observed` boolean, nullable
    - `eligibility` 'eligible' | 'lapsed' | 'excluded' | 'unknown' | 'admitted_previously' | 'not_applicable' | 'null', nullable: Resolved against the EFFECTIVE production capture settings (refreshed every few minutes; if they cannot be confirmed the answer narrows, never widens). eligible = admitted by the current gate · lapsed = launched via our pipeline, capture window closed under the current settings · excluded = blacklisted · unknown = no evidence the gate admits it (most likely outside the launchpad pipeline; basis capture_state_unavailable = settings could not be confirmed, no claim either way) · admitted_previously = persisted rows prove past admission, current status not established · not_applicable = wallet subjects · null = lookup failed
    - `eligibility_basis` string, nullable: Evidence behind eligibility (e.g. unresolved_launch, recently_bonded, revived_curve, pipeline_known, launchlab_pool, bags_vanity_mint, launchpad_proven, resolved_launch, bonded_over_7d, revival_expired, blacklisted, persisted_rows, capture_state_unavailable, lookup_failed)
    - `completeness` 'not_verified'
    - `size_floor` object: Persistence size floor of the same write path (added 2026-09-30). Buys under 0.05 SOL (under $3.50 when paid in USDC/USDT) are not stored; sells that receive SOL are kept at any size. Live streams, prices and candles are not subject to it.
      - `min_sol` number
      - `min_stable_usd` number
      - `applies_to` string
    - `note` string: How to read the values (always present since 2026-09-21: eligibility-specific when no rows exist, a completeness caveat when they do).

## Other responses

- `400`: Invalid wallet address
- `401`: Missing or invalid API key, or an expired free-tier key. Authentication-stage error: no `X-RateLimit-*` headers, no `_rid`.
- `403`: Forbidden. One of: the key's tier is below this endpoint's or parameter's gate (`tier_required` with an `upgrade` block); the public demo key used outside its allow-list (`demo_key_endpoint_not_allowed`); an invalid or revoked key; an origin-restricted key called from a disallowed origin (`code` `origin_not_allowed` / `origin_required`). `X-RateLimit-*` headers are present only on `tier_required`.
- `429`: Too many requests. Every 429 carries `Retry-After`. A quota 429 (`rate_limit_exceeded`, with `X-RateLimit-*`), a heavy-query concurrency 429 (`error_kind` `concurrency`/`capacity`), or the per-IP authentication-failure block (30 failed auths/min; plain `error` + `retry_after_seconds`, no `X-RateLimit-*`).
- `500`: Unexpected server error from the route (`Internal server error`, with `_rid`). Safe to retry with backoff. A failed API-key lookup is a 503 `auth_backend_unavailable`, never a 500.
- `503`: Temporarily too heavy — either the upstream RPC is busy or the wallet holds too many tokens to aggregate right now. Retry shortly (retry_after_seconds).

---

[API](https://skmtc.dev/madeonsol/apis/madeonsol-api.md) · [All operations](https://skmtc.dev/madeonsol/apis/madeonsol-api/llms.txt) · [OpenAPI document](https://skmtc.dev/madeonsol/apis/madeonsol-api/revisions/96ce84657f55?raw)