---
title: "Wallet stats + flags + enrichments"
method: GET
path: "/wallet/{address}"
tags: ["Wallet"]
---

# Wallet stats + flags + enrichments

`GET /wallet/{address}`

## Request

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

Aggregate counters for any Solana wallet over the last 90 days plus cross-product flags joining `kol_wallets`, `mv_alpha_wallets` (incl. bot_confidence), `deployers`, and the reputation caches (`is_sniper`, `is_bundler`, `is_dumper` + dump-cluster cohort counts). Backed by `idx_token_trades_wallet_cover` — sub-100ms even on heavy wallets. Returns 404 if the wallet has no trades AND no flag-table presence.

**v1.8.1 enrichments** (additive, non-breaking): also returns `top_tokens` (top-traded tokens with realized PnL + peak MC), `trading_style` (avg trade size, sniper-rate, round-trip rate, median hold), `deployer_breakdown` (tier-distribution of deployers bought from), and `recent_trades` (last 10 trades with symbols). PRO+.

## Path parameters

- `address` string, required: Base58 wallet address

## Response `200`

OK

- WalletStats
  - `address` string, required
  - `completeness` 'complete' | 'incomplete': Realized-PnL completeness. incomplete when at least one sell in the response has proceeds that went to another wallet (price_status proceeds_unattributed, migration 508): realized PnL and ROI then cover the known basis only, and the basis those sells consumed is reported as unknown_realized_cost_basis_sol, never as 0 proceeds or a loss. This is realized-PnL completeness. It is NOT `coverage.completeness` (source-coverage verification: verified / not_verified / ...), which says whether the trade capture for this subject is proven complete.
  - `incomplete_reasons` string[]: Empty when complete. /wallet/{address} and /tokens/{mint}/top-traders emit only proceeds_unattributed; unknown_consideration is shared with the FIFO routes (/pnl, /positions).
  - `pnl_basis_note` string: Fixed sentence: realized_pnl_sol and ROI cover the known basis only; unattributed sells are excluded and the basis they consumed is unknown_realized_cost_basis_sol.
  - `stats` object, nullable
    - `first_seen` string, date-time
    - `last_seen` string, date-time
    - `total_trades` integer
    - `buys` integer
    - `sells` integer
    - `bought_sol` number
    - `sold_sol` number
    - `unique_tokens` integer
    - `unknown_realized_cost_basis_sol` number: Migration 508: cost basis consumed by sells whose proceeds went to another wallet. NOT in realized_pnl_sol or ROI (neither a loss nor a gain). 0 when complete.
    - `unattributed_sells` integer: Migration 508: sells with price_status proceeds_unattributed. 0 when complete.
    - `window_days` integer: Lookback window — currently 90
  - `flags` object, required
    - `is_kol` boolean
    - `kol_name` string, nullable
    - `is_alpha_tracked` boolean
    - `bot_confidence` 'none' | 'low' | 'medium' | 'high', nullable: Bot-likeness classification from alpha-wallet rules
    - `alpha_win_rate` number, nullable
    - `alpha_net_pnl_sol` number, nullable
    - `alpha_tokens_traded` integer, nullable
    - `is_deployer` boolean
    - `deployer_tokens_deployed` integer, nullable
    - `deployer_bonding_rate` number, nullable
    - `coverage_note` string: Fixed disclosure: is_sniper/is_bundler/is_dumper derive from the launchpad trade pipeline — false means 'not observed in covered trades', not 'verified clean'.
    - `is_sniper` boolean: >=5 tokens early-bought & >=80% flipped <5min (behavior-updated hourly). Pump.fun-pipeline scoped; false = not observed, not verified clean
    - `is_bundler` boolean: Bought >1 token in the same block, ever (lifetime flag)
    - `is_dumper` boolean: >=5 dump cohorts + 0 runner cohorts in rolling 42d window (recomputed daily)
    - `dump_cluster` object, nullable: Raw dump-cluster cohort counts (present when the wallet has >=5 recent early-buyer cohort appearances)
      - `dump_cohorts` integer
      - `runner_cohorts` integer
      - `total_cohorts` integer
      - `as_of` string, date-time
  - `top_tokens` object[]: Top traded tokens (90d window) with realized PnL. Cross-joined with deployer-tokens for symbol + peak MC where available.
    - `token_mint` string
    - `token_symbol` string, nullable
    - `buys` integer
    - `sells` integer
    - `sol_in` number
    - `sol_out` number
    - `realized_pnl_sol` number: Known basis only (migration 508): sells whose proceeds went to another wallet are excluded, see unknown_realized_cost_basis_sol.
    - `current_mc_usd` number, nullable
    - `peak_mc_usd` number, nullable
    - `last_traded_at` string, date-time
    - `unknown_realized_cost_basis_sol` number: Migration 508: cost basis consumed by sells whose proceeds went to another wallet. NOT in realized_pnl_sol or ROI (neither a loss nor a gain). 0 when complete.
    - `unattributed_sells` integer: Migration 508: sells with price_status proceeds_unattributed. 0 when complete.
    - `realized_status` 'known' | 'partial' | 'unknown': known = no unattributed sell; partial = some sells unattributed (realized on the known basis); unknown = every sell unattributed: the outcome is unknown, not a loss (same vocabulary as /pnl closed_positions).
  - `trading_style` object, nullable: Behavioural signals: avg trade size, sniper rate, round-trip rate, median hold time.
    - `total_trades` integer
    - `avg_trade_size_sol` number
    - `sniper_rate` number: 0–1: fraction of trades with early_buyer_rank ≤ 10.
    - `early_entries` integer
    - `round_trip_rate` number: 0–1: fraction of tokens with both buys and sells.
    - `tokens_with_round_trips` integer
    - `median_hold_minutes` number, nullable: Median minutes between first buy and first sell across tokens.
    - `dominant_action` 'buy' | 'sell' | 'balanced'
  - `deployer_breakdown` object, nullable: Tier distribution of pump.fun deployers this wallet has bought from. Useful for spotting alpha-buyers vs random degens.
    - `total_tokens` integer
    - `tracked_deployers` integer
    - `by_tier` object[]
      - `tier` string: elite / good / rising / moderate / cold / unranked
      - `count` integer
  - `recent_trades` object[]: Last 10 trades regardless of window (raw timeline, cross-joined with deployer-tokens for symbol).
    - `token_mint` string
    - `token_symbol` string, nullable
    - `action` 'buy' | 'sell'
    - `sol_amount` number
    - `block_time` integer
    - `traded_at` string, date-time
    - `tx_signature` string
  - `derived` object: Derived wallet stats computed from the enrichments above (src/lib/wallet-enrichments.ts DerivedStats: standout trades, biggest miss, realized/unrealized PnL rollups).
  - `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).
  - `stats_unavailable` boolean: Present (true) only when the 90-day trade aggregation failed. `stats` null is then UNPROVEN, not an inactive wallet.
  - `enrichment_unavailable` boolean: Present (true) only when one or more enrichment queries failed; `degraded_fields` names them. Absent on a fully measured response.
  - `degraded_fields` string[]: Enrichment blocks whose query failed (e.g. a database timeout under load). Their null / [] value is UNKNOWN, not 'no data'; retry later. `biggest_miss` refers to `derived.biggest_miss`. Present only together with `enrichment_unavailable: true`.

## 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`.
- `404`: Wallet has no recorded activity
- `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`: The API-key or subscription lookup could not be answered (authentication stage). Retryable and not your fault: it is never counted as a failed authentication. Honour `Retry-After`; no `X-RateLimit-*`, no `_rid`.

---

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