{"openapi":"3.1.0","info":{"title":"LumpTools API","version":"0.9.0-beta","description":"Live Cardano token, market and on-chain data — computed directly from our own full node stack (cardano-node + Kupo + Ogmios + cardano-db-sync), not resold from a third party. Public read endpoints are keyless; a personal key (Authorization: Bearer) lifts rate limits and unlocks the premium+ endpoints. Beta — response shapes may change before a formal /v1.","contact":{"name":"LumpTools","url":"https://lumptools.xyz/#api"}},"servers":[{"url":"https://lumptools.xyz/api"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A personal API key minted on the Account page (#account). Sent as `Authorization: Bearer <key>`. The linked wallet’s live on-chain $LUMP sets the tier: premium (≥ 2,000,000) or premium+ (≥ 5,000,000)."}},"parameters":{"TokenId":{"name":"id","in":"path","required":true,"description":"Token unit (policyId hex + assetName hex, concatenated) or a vanity slug / ticker, e.g. `lump`. Prefer the unit for exactness.","schema":{"type":"string"}},"AssetId":{"name":"id","in":"path","required":true,"description":"ANY policy id or unit — verified or unverified long-tail token / NFT.","schema":{"type":"string"}},"HandleName":{"name":"name","in":"path","required":true,"description":"The handle without its sigil (LumpTag `@name` or ADA Handle `$name`).","schema":{"type":"string"}}},"responses":{"RateLimited":{"description":"Rate limited. Per-minute limits emit standard `x-ratelimit-*` + `Retry-After`. The per-day cap (keyed callers) returns `{ error, remaining: 0, resetAt }` with `Retry-After` = seconds to the next UTC midnight. Served keyed responses also carry `x-lt-daily-limit` / `x-lt-daily-remaining`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the caller may retry."},"x-lt-daily-limit":{"schema":{"type":"integer"},"description":"The account’s daily request cap for its tier."},"x-lt-daily-remaining":{"schema":{"type":"integer"},"description":"Remaining requests in today’s cap."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"remaining":{"type":"integer"},"resetAt":{"type":"integer"}}}}}},"Forbidden":{"description":"The endpoint needs a higher tier than the caller currently holds (premium+ endpoints).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"tier":{"type":"string"},"lump":{"type":"number"}}}}}}},"schemas":{"TokenRow":{"type":"object","description":"A token’s market snapshot. ADA-suffixed fields are in ADA; USD-suffixed in USD. null = unknown, not zero.","properties":{"id":{"type":"string","description":"on-chain unit (policyId + assetNameHex)"},"ticker":{"type":"string"},"name":{"type":"string"},"policy":{"type":"string","description":"policy id (56 hex)"},"decimals":{"type":"integer"},"verified":{"type":"boolean","description":"editorially verified (anti-impersonation)"},"category":{"type":"string","description":"e.g. AI, Meme, DeFi, Stablecoin"},"extraCategories":{"type":"array","items":{"type":"string"}},"priceAda":{"type":["number","null"]},"priceUsd":{"type":["number","null"]},"change24h":{"type":["number","null"]},"changes":{"type":"object","description":"% price change per window, each nullable","properties":{"h1":{"type":["number","null"]},"h4":{"type":["number","null"]},"h24":{"type":["number","null"]},"d7":{"type":["number","null"]},"d30":{"type":["number","null"]}}},"volume24hAda":{"type":["number","null"]},"volume24hUsd":{"type":["number","null"]},"liquidityAda":{"type":["number","null"],"description":"≈ 2 × ADA across the token’s pool cluster"},"marketCapAda":{"type":["number","null"]},"marketCapUsd":{"type":["number","null"]},"circulatingSupply":{"type":["number","null"],"description":"decimal-adjusted"},"totalSupply":{"type":["number","null"]},"holders":{"type":["number","null"],"description":"distinct wallet holders (pools/contracts excluded)"},"createdAt":{"type":["number","null"],"description":"first-mint time (UNIX seconds)"},"updatedAt":{"type":["number","null"],"description":"last refresh (UNIX ms)"},"logoUrl":{"type":["string","null"]},"website":{"type":["string","null"]},"xUrl":{"type":["string","null"]},"projectName":{"type":["string","null"]},"description":{"type":["string","null"]}}},"MarketSnapshot":{"type":"object","properties":{"ready":{"type":"boolean","description":"false while the node is warming up after a restart"},"adaUsd":{"type":["number","null"]},"lastSweep":{"type":["number","null"],"description":"ms timestamp of the last data refresh"},"count":{"type":"integer"},"tokens":{"type":"array","items":{"$ref":"#/components/schemas/TokenRow"},"description":"sorted by 24h USD volume, desc"}}},"Candle":{"type":"object","properties":{"time":{"type":"integer","description":"UNIX seconds (bucket start)"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"},"volume":{"type":"number"},"synthetic":{"type":"boolean","description":"present when the bar was filled from an adjacent close (no trades in the bucket)"}}},"Chart":{"type":"object","properties":{"candles":{"type":"array","items":{"$ref":"#/components/schemas/Candle"}},"quote":{"type":"string","description":"usually \"ADA\""},"stale":{"type":"boolean"},"source":{"type":"string","description":"e.g. \"onchain-direct\""}}},"AssetLookup":{"type":"object","description":"Universal on-demand lookup for any asset. For NFTs it returns node-sourced ownership/supply — no marketplace floor.","properties":{"kind":{"type":"string","enum":["token","nft"]},"policy":{"type":"string"},"unit":{"type":"string"},"verified":{"type":"boolean"},"name":{"type":["string","null"]},"ticker":{"type":["string","null"]},"priceAda":{"type":["number","null"]},"liquidityAda":{"type":["number","null"]},"marketCapAda":{"type":["number","null"]},"holders":{"type":["number","null"]},"supply":{"type":["number","null"]},"ageDays":{"type":["number","null"]},"image":{"type":["string","null"]},"trust":{"type":"object","description":"{ score, label, … }"},"impersonation":{"type":["object","null"],"description":"set when the asset appears to impersonate a known token"}}},"Usage":{"type":"object","properties":{"day":{"type":"string","description":"UTC YYYY-MM-DD"},"tier":{"type":"string","enum":["free","premium","premium+"]},"graceActive":{"type":"boolean"},"rpm":{"type":"integer","description":"per-minute limit for the tier"},"dailyCap":{"type":"integer"},"used":{"type":"integer","description":"keyed requests counted today (site/browser use is not metered)"},"remaining":{"type":"integer"}}}}},"paths":{"/tokens":{"get":{"tags":["Market"],"summary":"Full market snapshot","description":"Every tracked token in one payload (~250 KB). Poll no more than every 30 s; supports conditional GET (ETag → 304).","responses":{"200":{"description":"Market snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketSnapshot"}}}},"304":{"description":"Not modified (ETag matched)."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/universe":{"get":{"tags":["Market"],"summary":"Verified-token symbol map","description":"Lightweight list of verified tokens (id + ticker + name) — cheap for building a symbol map.","responses":{"200":{"description":"Symbol list","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"ticker":{"type":"string"},"name":{"type":"string"}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/ada-usd":{"get":{"tags":["Market"],"summary":"ADA→USD rate + USD→EUR factor","description":"EUR = value × adaUsd × usdEur.","responses":{"200":{"description":"Rates","content":{"application/json":{"schema":{"type":"object","properties":{"adaUsd":{"type":"number"},"usdEur":{"type":"number"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/macro/{symbol}/chart":{"get":{"tags":["Market"],"summary":"Macro OHLC candles (ADAUSD, BTCUSD, ADABTC)","description":"Candles for the macro charts — Binance.US for the USD pairs, Kraken for ADA/BTC. symbol ∈ ADAUSD | BTCUSD | ADABTC; period ∈ 1min 5min 15min 1hour 4hour 1day 1week (default 1day). candle.time is UNIX seconds at bucket start; quote is USD or BTC.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","enum":["ADAUSD","BTCUSD","ADABTC"]}},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["1min","5min","15min","1hour","4hour","1day","1week"],"default":"1day"}}],"responses":{"200":{"description":"Candle series","content":{"application/json":{"schema":{"type":"object","properties":{"candles":{"type":"array","items":{"type":"object","properties":{"time":{"type":"number"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"},"volume":{"type":"number"}}}},"quote":{"type":"string"},"stale":{"type":"boolean"},"updatedAt":{"type":"number"}}}}}},"400":{"description":"Bad period."},"404":{"description":"Unknown symbol."},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"Upstream source unavailable and no cached data."}}}},"/token/{id}":{"get":{"tags":["Token data"],"summary":"Single-token snapshot","description":"The primary endpoint for price / market cap / volume / liquidity / holder count.","parameters":[{"$ref":"#/components/parameters/TokenId"}],"responses":{"200":{"description":"Token row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRow"}}}},"404":{"description":"Unknown token."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/token/{id}/detail":{"get":{"tags":["Token data"],"summary":"Token snapshot + holders, pools, trades, top traders","description":"Heavier — cache aggressively. holders[] up to 1000, desc by amount.","parameters":[{"$ref":"#/components/parameters/TokenId"}],"responses":{"200":{"description":"Token detail","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"$ref":"#/components/schemas/TokenRow"},"fdvAda":{"type":["number","null"]},"fdvUsd":{"type":["number","null"]},"holders":{"type":"array","items":{"type":"object","description":"{ address, amount, pct, isContract, label, category, handle }"}},"pools":{"type":"array","items":{"type":"object","description":"{ dex, ada, token, pair, tvlAda, priceAda, share }"}},"trades":{"type":"array","items":{"type":"object","description":"{ time, side, ada, token, dex, wallet, txHash }"}},"topTraders":{"type":"array","items":{"type":"object","description":"{ wallet, buys, sells, volumeAda, netAda, pnlAda, roi }"}},"traderRank":{"type":["number","null"]},"tradeQuote":{"type":"string","description":"unit the trade ada values are denominated in — usually \"ADA\""},"tradesNextCursor":{"type":["number","null"],"description":"cursor for /token/{id}/trades?before= (older trades); null = no deeper history"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/token/{id}/trades":{"get":{"tags":["Token data"],"summary":"Paginated trade feed (full history)","description":"One page of the token trade feed, walking back toward pool birth (infinite scroll / \"load older trades\"). On-chain only — reserve-delta swaps across every DEX pool the token trades on, including the pre-graduation snek curve.","parameters":[{"$ref":"#/components/parameters/TokenId"},{"name":"before","in":"query","required":false,"description":"cursor from /detail's tradesNextCursor (then each page's nextCursor); omit for the newest page","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"target page size 1–100 (default 50); sizes the per-pool fetch window, so a dense multi-pool token may return somewhat more. Page by nextCursor, not by row count.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Trade page","content":{"application/json":{"schema":{"type":"object","properties":{"trades":{"type":"array","items":{"type":"object","description":"{ time, side, ada, token, dex, wallet, txHash }"}},"nextCursor":{"type":["number","null"],"description":"pass as before= for the next (older) page; null = start of history"},"degraded":{"type":"boolean","description":"a pool read failed — older history may be incomplete this page"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/token/{id}/chart":{"get":{"tags":["Token data"],"summary":"OHLCV candles","description":"Built from on-chain pool history (multi-pool, depth-weighted).","parameters":[{"$ref":"#/components/parameters/TokenId"},{"name":"period","in":"query","required":false,"description":"candle period (default 1hour)","schema":{"type":"string","enum":["1min","5min","15min","1hour","4hour","1day","1week"],"default":"1hour"}}],"responses":{"200":{"description":"Candles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Chart"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/token/{id}/holder-history":{"get":{"tags":["Token data"],"summary":"Daily holder-count series","description":"One point per UTC day; accruing since 2026-07-02.","parameters":[{"$ref":"#/components/parameters/TokenId"}],"responses":{"200":{"description":"Holder history","content":{"application/json":{"schema":{"type":"object","properties":{"history":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"holders":{"type":"integer"},"top10Pct":{"type":["number","null"]}}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/asset/{id}":{"get":{"tags":["Token data"],"summary":"Universal asset lookup + Trust score","description":"Resolves basic stats, a Trust score and an impersonation flag for ANY asset, even untracked tokens / NFTs.","parameters":[{"$ref":"#/components/parameters/AssetId"}],"responses":{"200":{"description":"Asset lookup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetLookup"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/new-listings":{"get":{"tags":["Discovery"],"summary":"Tokens first seen on-chain in the last 24h","description":"snek.fun launches + recent mints. Always verified:false (verification is a manual step).","responses":{"200":{"description":"New listings","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"type":"object","description":"{ unit, ticker, name, source('snek.fun'|'dex'), listedAtMs, priceAda, marketCapAda, volume24hAda, holders, bondedPct, graduated }"}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/handle/{name}":{"get":{"tags":["Handles & protocol stats"],"summary":"Resolve a LumpTag @handle to its holder","parameters":[{"$ref":"#/components/parameters/HandleName"}],"responses":{"200":{"description":"Handle → address","content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string"},"address":{"type":["string","null"]}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/adahandle/{name}":{"get":{"tags":["Handles & protocol stats"],"summary":"Resolve an ADA Handle $name to its holder","parameters":[{"$ref":"#/components/parameters/HandleName"}],"responses":{"200":{"description":"Handle → address","content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string"},"address":{"type":["string","null"]}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/strike":{"get":{"tags":["Handles & protocol stats"],"summary":"Strike (perps) dashboard","description":"On-chain TVL, staking, fees, holder revenue. Returns a stats object with updatedAt.","responses":{"200":{"description":"Strike stats"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/surf":{"get":{"tags":["Handles & protocol stats"],"summary":"Surf (lending) dashboard","description":"Per-market supply/borrow APY, utilization, TVL. Returns a stats object with updatedAt.","responses":{"200":{"description":"Surf stats"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/indigo":{"get":{"tags":["Handles & protocol stats"],"summary":"Indigo (synthetics) dashboard","description":"TVL, INDY staking APR, per-iAsset stability-pool APYs. Returns a stats object with updatedAt.","responses":{"200":{"description":"Indigo stats"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/analysis/{tokenId}":{"get":{"tags":["Premium+"],"summary":"Deep holder analysis (premium+)","description":"Supply concentration, linked (sybil) wallet clusters from the on-chain funding graph, a bubble-map (nodes + within-cluster links), top/bottom net-ADA traders, ATH price / market cap. Keyed access needs a premium+ key; the site keeps its ≥ 2M $LUMP premium wallet gate for this view. Response is no-store.","security":[{"apiKey":[]}],"parameters":[{"name":"tokenId","in":"path","required":true,"description":"token unit or vanity slug / ticker","schema":{"type":"string"}}],"responses":{"200":{"description":"Analysis","content":{"application/json":{"schema":{"type":"object","description":"{ holderCount, concentration{top3,top5,top10}, clusters[], clusterCount, totalClusteredPct, clusterAnalyzable, nodes[], links[], topTraders[], bottomTraders[], tradersWindow, athPriceAda, athMcapAda }"}}}},"401":{"description":"Auth required."},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/token/{id}/chart-depth":{"get":{"tags":["Premium+"],"summary":"Stored-OHLC depth audit for one token (premium+)","description":"Per-period bar counts, calendar span, gap/fill coverage and the on-chain vs snek-curve source mix.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TokenId"}],"responses":{"200":{"description":"Depth audit","content":{"application/json":{"schema":{"type":"object","description":"{ id, periods: [{ period, bars, withVolume, snekCurve, onchain, spanDays, first, last, emptyBuckets, expectedBuckets, fillPct }] }"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/chart-depth":{"get":{"tags":["Premium+"],"summary":"Stored-OHLC depth audit across all tokens (premium+)","description":"The same depth audit for every token with stored candles. Large payload; poll sparingly.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Depth audit (all tokens)","content":{"application/json":{"schema":{"type":"object","description":"{ tokenCount, tokens: [{ id, periods: [ … ] }] }"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/account/usage":{"get":{"tags":["Account"],"summary":"Current tier + today’s keyed-request usage","description":"Accepts a profile session (Account page) OR an API key (a bot polling its own quota). Does not consume quota.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"Sign-in / key required."}}}}},"tags":[{"name":"Market"},{"name":"Token data"},{"name":"Discovery"},{"name":"Handles & protocol stats"},{"name":"Premium+","description":"Heavy, differentiated data. Requires a premium+ key (or a proven premium+ wallet session on the site)."},{"name":"Account","description":"Bearer-authenticated account utilities."}]}