solana-risk-engine 0.0.0-stage → 0.2.0

package/src/i18n/es.js

@@ -0,0 +1,109 @@
+// Spanish texts: the same wording the original single-file scanner used
+function usd(n) {
+  if (!n) return "0 $";
+  if (n < 0.01) return "<0,01 $";
+  // de-DE instead of es-ES: same format (dot thousands, comma decimals), but es-ES does not group
+  // 4-digit numbers and "6494 $" showed next to "22.505 $"
+  return n.toLocaleString("de-DE", { minimumFractionDigits: n < 1000 ? 2 : 0, maximumFractionDigits: n < 1000 ? 2 : 0 }) + " $";
+}
+function pct(n) { return Math.round(n) + "%"; }
+function short(a) { return a.slice(0, 4) + "…" + a.slice(-4); }
+function prog(d) { return d && d.prog >= 20 ? ". Los pools y programas guardan el " + pct(d.prog) : ""; }
+
+const EXT = {
+  permanentDelegate: "El emisor puede mover o quemar tus tokens (delegado permanente). Es normal en acciones tokenizadas, pero hay que confiar en el emisor",
+  transferHook: "Tiene transfer hook: ejecuta código externo en cada transferencia",
+  transferFeeConfig: "Cobra una comisión en cada transferencia",
+  nonTransferable: "No se puede transferir",
+  defaultAccountState: "Las cuentas nuevas pueden crearse congeladas"
+};
+
+export default {
+  fmt: { usd: usd, pct: pct, short: short },
+  signals: {
+    NO_INFO: () => "No se pudo leer la información del token",
+    MINT_BY_PROGRAM: () => "El mint lo controla un programa (suele ser un puente o un protocolo): hay que confiar en ese código",
+    MINT_ACTIVE: (d) => "El creador todavía puede crear más tokens (mint activo" + (d && d.byWallet ? ", en manos de una wallet" : "") + ")",
+    FREEZE_BY_PROGRAM: () => "El freeze lo controla un programa: puede congelar cuentas según su código",
+    FREEZE_ACTIVE: (d) => "El creador puede congelar cuentas (freeze activo" + (d && d.byWallet ? ", en manos de una wallet" : "") + ")",
+    EXTENSION: (d) => EXT[d.ext] || ("Extensión " + d.ext),
+    NO_MARKET: () => "No hay mercado en DexScreener (sin precio ni liquidez)",
+    MARKET_UNCHECKED: () => "No se pudo consultar el mercado de este token (fallo de red al conectar con DexScreener): vuelve a analizarlo para comprobarlo",
+    KNOWN_TOKEN: () => "Token muy conocido",
+
+    CTL_MINT_ACTIVE: () => "El creador puede crear más tokens (mint activo)",
+    CTL_FREEZE_ACTIVE: () => "El creador puede congelar cuentas (freeze activo)",
+    CTL_TRANSFER_HOOK: () => "Ejecuta código externo en cada transferencia",
+    CTL_TRANSFER_FEE: () => "Cobra una comisión en cada transferencia",
+    CTL_NON_TRANSFERABLE: () => "No se puede transferir",
+    CTL_DEFAULT_FROZEN: () => "Las cuentas nuevas pueden crearse congeladas",
+    CTL_ONLY_PROGRAMS: () => "Solo hay autoridades controladas por un programa (ver dependencia)",
+    CTL_NONE: () => "Sin autoridades activas: nadie puede crear más ni congelar",
+    IMPOSTOR: (d) => "Se hace pasar por " + d.symbol + ": el " + d.symbol + " de verdad tiene otra dirección (" + short(d.real) + "). Es una copia, casi seguro una estafa",
+
+    CON_SKIPPED: () => "Sin comprobar la concentración de holders",
+    CON_UNAVAILABLE: () => "No se pudo comprobar la concentración de holders (el servicio no respondió; prueba otra vez en un rato)",
+    CON_ALL_POOLS: (d) => "Casi todo el supply está en pools o programas" + prog(d),
+    CON_OK: (d) => "Sin concentración preocupante (mayor wallet individual: " + pct(d.w1) + ")" + prog(d),
+    CON_HIGH: (d) => "La mayor wallet individual tiene el " + pct(d.w1) + " y las 10 mayores el " + pct(d.w10) + " del supply" + prog(d),
+    CON_UNSPLIT: (d) => "No se pudo separar pools de personas. La mayor cuenta tiene el " + pct(d.top1) + " del supply",
+
+    MKT_LIQ_INFLATED: (d) => "Liquidez inflada: DexScreener dice " + usd(d.reported) + ", pero el pool solo tiene unos " + usd(d.real) + " en tokens de verdad (USDC, USDT o SOL). Es lo máximo que podrías sacar al vender",
+    MKT_LIQ_VERY_LOW: (d) => "Liquidez muy baja (" + usd(d.liq) + ")",
+    MKT_LIQ_LOW: (d) => "Liquidez baja (" + usd(d.liq) + ")",
+    MKT_VOLUME_LOW: (d) => "Volumen de 24 h casi nulo (" + usd(d.vol) + ")",
+    MKT_NEW: (d) => "Mercado muy nuevo (" + (d.days < 1 ? "menos de un día" : d.days + (d.days === 1 ? " día" : " días")) + ")",
+    MKT_POSITION_HEAVY: (d) => "La posición de esta wallet equivale al " + pct(d.pct) + " de la liquidez: vender de golpe movería mucho el precio",
+    MKT_LP_UNLOCKED: (d) => "Solo el " + pct(d.pct) + " de la liquidez está bloqueada o quemada (según RugCheck): el resto se puede retirar de golpe",
+    MKT_LP_PARTLY_LOCKED: (d) => "Solo el " + pct(d.pct) + " de la liquidez está bloqueada o quemada (según RugCheck)",
+    MKT_OK: (d) => "Liquidez " + usd(d.liq) + " · volumen 24 h " + usd(d.vol),
+
+    DEP_PROGRAM_AUTHORITY: () => "Un programa controla el mint o el freeze (puente o protocolo): hay que confiar en su código",
+    DEP_PERMANENT_DELEGATE: () => "El emisor puede mover o quemar tus tokens (delegado permanente): confías en el emisor",
+    DEP_STABLE_ISSUER: () => "Su valor depende de quien la emite y la respalda",
+    DEP_NONE: () => "No depende de un emisor ni de un puente"
+  },
+  offSolana: " y su mercado principal puede estar fuera de Solana",
+  levels: {
+    HIGH: "Riesgo alto", MEDIUM: "Riesgo medio", LOW: "Riesgo bajo", SPAM: "Probable spam",
+    NO_DATA: "Sin comprobar", NO_MARKET: "Sin mercado", MEDIUM_DATA_ONLY: "Medio por falta de datos"
+  },
+  types: {
+    STABLE: { label: "Stablecoin", note: "Se juzga por su liquidez y por la confianza en quien la emite; la concentración pesa menos." },
+    TOKENIZED: { label: "Tokenizado o regulado", note: "Lo normal es que el emisor tenga control (delegado permanente). El riesgo real es confiar en el emisor y que haya liquidez para salir." },
+    BRIDGED: { label: "Puenteado o de protocolo", note: "Lo normal es que un programa controle el mint. El riesgo real es confiar en ese puente y que su mercado en Solana sea pequeño, porque el principal puede estar en otra red." },
+    CREATOR: { label: "Con control del creador", note: "Una wallet puede crear más tokens o congelar cuentas: es el patrón típico de estafa, así que se juzga con más dureza." },
+    OPEN: { label: "Token abierto", note: "Sin autoridades del creador, típico de memecoins y proyectos nuevos. Pesan sobre todo la concentración en personas y la liquidez." }
+  },
+  lights: { control: "Control del creador", concentration: "Concentración", market: "Mercado y salida", dependency: "Dependencia" },
+  missing: { control: "quién controla el token", concentration: "la concentración de holders", market: "el mercado", dependency: "la dependencia de un emisor" },
+  steps: {
+    address: "Comprobando la dirección…", wallet: "Leyendo la wallet…", markets: "Consultando precios y liquidez…",
+    tokens: "Revisando tokens…", token: "Leyendo el token…", owners: "Buscando a quién pertenece cada cuenta…",
+    kinds: "Distinguiendo wallets de pools y programas…", bots: "Separando personas de bots y exchanges…",
+    funders: "Buscando wallets con el mismo origen de fondos…", exchangeSources: "Comprobando si el origen de cada grupo es un exchange…",
+    creator: "Mirando quién creó el token (RugCheck)…", creatorTokens: "Revisando otros tokens del creador…",
+    networks: "Comprobando cuánto tienen hoy las redes de wallets…", wallets: "Leyendo wallets…",
+    pnl: "Estimando el resultado de cada wallet…", done: "Listo"
+  },
+  notes: {
+    PNL_NO_HELIUS: "No se estimó el resultado de las wallets porque falta una clave de Helius.",
+    PNL_PARTIAL: "No se pudo leer el historial de algunas wallets.",
+    PNL_APPROX: "No se pudo obtener el histórico de precio de SOL: se usó el precio de hoy y los resultados pueden estar muy alejados de la realidad."
+  },
+  errors: {
+    CANCELLED: () => "Cancelado.",
+    INVALID_ADDRESS: () => "Esa dirección no parece de Solana. Son de 32 a 44 letras y números y no empiezan por 0x.",
+    NOT_A_TOKEN: () => "Esa dirección no es un token.",
+    IS_NFT: () => "Esa dirección es un NFT, no un token. El escáner no revisa NFTs.",
+    NO_HOLDERS: () => "El RPC no devolvió datos de holders.",
+    HELIUS_REQUIRED: () => "Para estimar el resultado hace falta una clave de Helius (o una URL de RPC de Helius con la clave).",
+    SOL_PRICE: () => "No se pudo obtener el precio de SOL para calcular el resultado. Prueba otra vez dentro de un rato.",
+    DEX_UNREACHABLE: () => "No se pudo conectar con DexScreener. Revisa tu conexión a internet y prueba otra vez.",
+    TOO_FEW_WALLETS: (d) => d && d.filter ? "Solo " + d.n + (d.n === 1 ? " wallet cumple" : " wallets cumplen") + " el filtro de resultado (de " + d.total + " leídas)." : "Hacen falta al menos 2 wallets que se puedan leer.",
+    TOO_FEW_TOKENS: () => "Pega al menos 2 direcciones de tokens de Solana.",
+    NETWORK_PUBLIC: () => "Los servicios gratuitos de Solana no han respondido (a veces se saturan). Espera un minuto y prueba otra vez, o usa tu propia URL de RPC (Helius tiene plan gratuito).",
+    NETWORK_OWN: () => "No se pudo conectar con tu URL de RPC. Revisa que esté bien copiada (con la clave al final).",
+    UNKNOWN: (d) => "Algo ha fallado: " + d.message + ". Prueba otra vez o usa otro RPC."
+  }
+};

package/src/i18n/index.js

@@ -0,0 +1,77 @@
+import es from "./es.js";
+import en from "./en.js";
+import { dataOnly } from "../risk.js";
+
+const LANGS = { es: es, en: en };
+
+function pack(lang) {
+  return LANGS[lang] || LANGS.en;
+}
+
+/** Adds or replaces a language: addLanguage("pt", {...same shape as en.js}) */
+export function addLanguage(code, texts) {
+  LANGS[code] = texts;
+}
+
+/** One signal ({code, data}) as a sentence */
+export function describe(signal, lang) {
+  const L = pack(lang), f = L.signals[signal.code];
+  let t = f ? f(signal.data || {}) : signal.code;
+  if (signal.data && signal.data.offSolana) t += L.offSolana;
+  return t;
+}
+
+/** A whole traffic light as one sentence, its signals joined like the original scanner did */
+export function explainLight(light, lang) {
+  return light.items.map(function (x) { return describe(x, lang); }).join(". ");
+}
+
+export function lightLabel(k, lang) {
+  return pack(lang).lights[k] || k;
+}
+
+/** Label of a result's level; says "medium due to missing data" when that is the only reason */
+export function levelLabel(result, lang) {
+  const L = pack(lang);
+  if (typeof result === "string") return L.levels[result] || result;
+  return dataOnly(result) ? L.levels.MEDIUM_DATA_ONLY : (L.levels[result.lvl] || result.lvl);
+}
+
+/** What could not be checked, e.g. "la concentración de holders y el mercado" */
+export function missingText(result, lang) {
+  const L = pack(lang), and = lang === "es" ? " y " : " and ";
+  return (result.lights || []).filter(function (l) { return l.s === "na"; }).map(function (l) { return L.missing[l.k]; }).join(and);
+}
+
+export function typeInfo(type, lang) {
+  return type ? pack(lang).types[type] || null : null;
+}
+
+/** Progress object from onProgress as text, e.g. "Revisando tokens… 3/10" */
+export function describeStep(p, lang) {
+  const L = pack(lang);
+  let t = L.steps[p.step] || p.step;
+  if (p.done !== undefined && p.total) t += " " + p.done + "/" + p.total;
+  return t;
+}
+
+export function describeNote(code, lang) {
+  return pack(lang).notes[code] || code;
+}
+
+/**
+ * A friendly message for any error the engine throws.
+ * @param [ctx.ownRpc]  whether the user configured their own RPC (changes the network advice)
+ */
+export function describeError(e, lang, ctx) {
+  const L = pack(lang), code = e && e.code;
+  if (code === "NETWORK" || code === "HTTP" || code === "RPC") return L.errors[ctx && ctx.ownRpc ? "NETWORK_OWN" : "NETWORK_PUBLIC"]();
+  const f = L.errors[code];
+  if (f) return f(e.data || {});
+  return L.errors.UNKNOWN({ message: (e && e.message) || String(e) });
+}
+
+/** Formatting helpers of each language: format(lang).usd(1234) */
+export function format(lang) {
+  return pack(lang).fmt;
+}

package/src/index.js

@@ -0,0 +1,55 @@
+import { createClient } from "./client.js";
+import { analyzeToken, analyzeWallet, analyzeAddress } from "./wallet.js";
+import { analyzeHolders } from "./holders.js";
+import { estimatePnl } from "./pnl.js";
+import { takeSnapshots } from "./changes.js";
+import { confluence, commonHolders } from "./confluence.js";
+import { getTokens } from "./tokens.js";
+
+/**
+ * The easy entry point: one object with every high-level analysis bound to one network client.
+ *
+ *   const scanner = createScanner({ rpcUrl: "https://mainnet.helius-rpc.com/?api-key=..." });
+ *   const r = await scanner.analyzeToken(mint);
+ *
+ * Options are those of createClient (rpcUrl, heliusApiKey, signal, fetch...). Each method also
+ * accepts its own opts (onProgress, ...), see the module docs.
+ */
+export function createScanner(opts) {
+  const client = createClient(opts);
+  return {
+    client: client,
+    analyzeToken: (mint, o) => analyzeToken(client, mint, o),
+    analyzeWallet: (wallet, o) => analyzeWallet(client, wallet, o),
+    analyzeAddress: (addr, o) => analyzeAddress(client, addr, o),
+    analyzeHolders: (mint, o) => analyzeHolders(client, mint, o),
+    estimatePnl: async (wallets, o) => {
+      // Current balances trim tokens the wallet moved away; read them if the caller did not pass them
+      o = o || {};
+      let bal = o.balances;
+      if (!bal) {
+        bal = {};
+        for (const w of wallets) bal[w] = (await getTokens(client, w)).tokens;
+      }
+      return estimatePnl(client, wallets, bal, o);
+    },
+    takeSnapshots: (wallets, o) => takeSnapshots(client, wallets, o),
+    confluence: (wallets, o) => confluence(client, wallets, o),
+    commonHolders: (mints, o) => commonHolders(client, mints, o)
+  };
+}
+
+export { createClient };
+export { ScanError, isCancel } from "./errors.js";
+export * from "./constants.js";
+export { isOnCurve, onCurve, b58bytes } from "./curve.js";
+export { getTokens, getMint, getConc, getAuthKinds, isMint, accountKinds, kindOf } from "./tokens.js";
+export { getMarkets, realLiq, impostorOf, INFLATED_RATIO } from "./markets.js";
+export { rugcheckSummary, rugcheckReport, rugcheckGraph, netBalances } from "./rugcheck.js";
+export { score, tokenType, buildLights, levelFrom, dataOnly, reasonsFrom, assess } from "./risk.js";
+export { analyzeToken, analyzeWallet, analyzeAddress, sortResults } from "./wallet.js";
+export { holderBase, markBusy, findFunder, findFunders, clusterByFunder, holderRows, creatorInfo, analyzeHolders } from "./holders.js";
+export { fetchSwaps, solHistory, priceSeries, parseTrades, pnlFromTrades, pnlStatus, estimatePnl } from "./pnl.js";
+export { capSnap, chgDiff, chgAgg, takeSnapshots, diffSnapshots } from "./changes.js";
+export { confluence, commonHolders } from "./confluence.js";
+export { describe, explainLight, lightLabel, levelLabel, missingText, typeInfo, describeStep, describeNote, describeError, format, addLanguage } from "./i18n/index.js";

package/src/markets.js

@@ -0,0 +1,58 @@
+import { DEX, USDC, USDT, WSOL, FAMOUS } from "./constants.js";
+import { ScanError, isCancel } from "./errors.js";
+import { sleep } from "./util.js";
+
+// DexScreener values both sides of a pool at the pool's own price. A scammer creates a pool with
+// 4 billion of their token against 2 real USDC and it shows "liquidity $4,000M". What you can actually
+// take out when selling is the real-token side (USDC, USDT or SOL): if that is much smaller, it wins.
+// Concentrated-liquidity pools (Orca Whirlpools, Raydium CLMM, Meteora DLMM) are lopsided by nature,
+// often 10-20% real side, so only an extreme gap counts: real side under 5% of the reported value.
+// The scams this targets sit far below that (2 USDC against "$4,000M" is 0.00000005%).
+// Mutates the pair: keeps the reported figure in liqRaw and replaces liquidity.usd with the real one.
+export const INFLATED_RATIO = 0.05;
+
+export function realLiq(p) {
+  const l = p.liquidity, qa = p.quoteToken && p.quoteToken.address;
+  if (!l || !l.usd || (qa !== USDC && qa !== USDT && qa !== WSOL)) return;
+  const pn = Number(p.priceNative), pu = Number(p.priceUsd), q = Number(l.quote);
+  if (!(pn > 0 && pu > 0 && q >= 0)) return;
+  const real = 2 * q * pu / pn;   // pu/pn = USD price of the real token
+  if (real < INFLATED_RATIO * l.usd) { p.liqRaw = l.usd; p.liquidity = Object.assign({}, l, { usd: real }); }
+}
+
+// A token using the symbol (or name) of a famous one but with another address is a copy
+export function impostorOf(mint, pair) {
+  const b = (pair && pair.baseToken) || {};
+  let s = String(b.symbol || "").replace(/[\s$]/g, "").toUpperCase();
+  const n = String(b.name || "").trim().toLowerCase();
+  if (!FAMOUS[s]) { if (n === "usd coin") s = "USDC"; else if (n === "tether usd" || n === "tether") s = "USDT"; }
+  return (FAMOUS[s] && FAMOUS[s] !== mint) ? { sym: s, real: FAMOUS[s] } : null;
+}
+
+// Best (most liquid) DexScreener pair per mint, 30 mints per request.
+// `failed` lists mints whose batch failed: unknown, which is not the same as "no market".
+export async function getMarkets(client, mints, onStep) {
+  const best = {};
+  let failed = [];
+  for (let i = 0; i < mints.length; i += 30) {
+    const lote = mints.slice(i, i + 30);
+    try {
+      const pares = await client.jfetch(DEX + lote.join(","));
+      if (Array.isArray(pares)) pares.forEach(function (p) {
+        const m = p.baseToken && p.baseToken.address;
+        if (lote.indexOf(m) < 0) return;
+        realLiq(p);
+        const liq = (p.liquidity && p.liquidity.usd) || 0;
+        const cur = best[m] && best[m].liquidity && best[m].liquidity.usd || 0;
+        if (!best[m] || liq > cur) best[m] = p;
+      });
+    } catch (e) {
+      if (isCancel(e)) throw e;
+      if (i === 0 && e.code === "NETWORK") throw new ScanError("DEX_UNREACHABLE", "could not reach DexScreener");
+      failed = failed.concat(lote);
+    }
+    if (onStep) onStep(Math.min(i + 30, mints.length), mints.length);
+    if (i + 30 < mints.length) await sleep(250);
+  }
+  return { data: best, failed: failed };
+}

package/src/pnl.js

@@ -0,0 +1,148 @@
+import { HELIUS_API, COINGECKO_SOL, USDC, USDT, WSOL } from "./constants.js";
+import { ScanError, isCancel } from "./errors.js";
+import { pool, short } from "./util.js";
+import { getMarkets } from "./markets.js";
+
+export async function fetchSwaps(client, addr, max) {
+  const key = client.heliusKey();
+  if (!key) throw new ScanError("HELIUS_REQUIRED", "PnL needs a Helius API key");
+  let out = [], before = null;
+  while (out.length < max) {
+    const url = HELIUS_API + addr + "/transactions?api-key=" + encodeURIComponent(key) + "&type=SWAP&limit=100" + (before ? "&before=" + before : "");
+    const page = await client.jfetch(url);
+    if (!Array.isArray(page) || !page.length) break;
+    out = out.concat(page); before = page[page.length - 1].signature;
+    if (page.length < 100) break;
+  }
+  return out;
+}
+
+// SOL price over the last year (CoinGecko) with today's price as fallback. at(ts) gives the price at a unix time.
+export async function solHistory(client) {
+  let cur = 0, pts = null;
+  try { const mkr = await getMarkets(client, [WSOL]); cur = Number((mkr.data[WSOL] && mkr.data[WSOL].priceUsd) || 0); } catch (e) { if (isCancel(e)) throw e; }
+  try { const j = await client.jfetch(COINGECKO_SOL); pts = j && j.prices; } catch (e) { if (isCancel(e)) throw e; }
+  return priceSeries(pts, cur);
+}
+
+export function priceSeries(pts, cur) {
+  const approx = !(pts && pts.length);
+  return {
+    approx: approx, now: cur, at: function (ts) {
+      if (approx) return cur;
+      const ms = ts * 1000;
+      let lo = 0, hi = pts.length - 1;
+      while (lo < hi) { const mid = (lo + hi) >> 1; if (pts[mid][0] < ms) lo = mid + 1; else hi = mid; }
+      return pts[lo][1];
+    }
+  };
+}
+
+// Real net balance change of the wallet in each swap (balances are the most reliable source)
+export function parseTrades(addr, txs, sol) {
+  const out = [];
+  txs.forEach(function (tx) {
+    if (!tx || tx.transactionError || !tx.accountData) return;
+    const d = {};
+    let nat = 0;
+    tx.accountData.forEach(function (ad) {
+      if (ad.account === addr) nat += Number(ad.nativeBalanceChange || 0) / 1e9;
+      (ad.tokenBalanceChanges || []).forEach(function (c) {
+        if (c.userAccount !== addr || !c.mint || !c.rawTokenAmount) return;
+        const q = Number(c.rawTokenAmount.tokenAmount || 0) / Math.pow(10, Number(c.rawTokenAmount.decimals || 0));
+        d[c.mint] = (d[c.mint] || 0) + q;
+      });
+    });
+    const solDelta = nat + (d[WSOL] || 0), usdDelta = (d[USDC] || 0) + (d[USDT] || 0);
+    delete d[WSOL]; delete d[USDC]; delete d[USDT];
+    const bases = Object.keys(d).filter(function (m) { return Math.abs(d[m]) > 0; });
+    if (bases.length !== 1) return;                         // swaps with several tokens at once are ignored
+    const m = bases[0], q = d[m], flow = usdDelta + solDelta * sol.at(tx.timestamp);   // net dollars in (+) or out (-) of the wallet
+    if (Math.abs(flow) < 5) return;                         // tiny trades: noise
+    if (q > 0 && flow < 0) out.push({ t: tx.timestamp, mint: m, side: "buy", qty: q, usd: -flow });
+    else if (q < 0 && flow > 0) out.push({ t: tx.timestamp, mint: m, side: "sell", qty: -q, usd: flow });
+  });
+  out.sort(function (a, b) { return a.t - b.t; });
+  return out;
+}
+
+// FIFO PnL. Only what has a known entry price counts as realized; open lots are valued at today's price.
+export function pnlFromTrades(trades, bal, price, sym, approx) {
+  const lots = {};
+  let realized = 0, costClosed = 0;
+  trades.forEach(function (t) {
+    const L = lots[t.mint] || (lots[t.mint] = []);
+    if (t.side === "buy") { L.push({ q: t.qty, c: t.usd }); return; }
+    let need = t.qty, cost = 0, cov = 0;
+    while (need > 1e-12 && L.length) {
+      const l = L[0], take = Math.min(l.q, need), part = l.c * (take / l.q);
+      cost += part; l.c -= part; l.q -= take; need -= take; cov += take;
+      if (l.q <= 1e-12) L.shift();
+    }
+    if (cov > 0) { realized += t.usd * (cov / t.qty) - cost; costClosed += cost; }
+  });
+  const open = [];
+  let unreal = 0, costOpen = 0, noPrice = 0;
+  Object.keys(lots).forEach(function (m) {
+    const L = lots[m];
+    let q = 0, c = 0;
+    L.forEach(function (l) { q += l.q; c += l.c; });
+    if (q <= 0) return;
+    const have = (bal && bal[m]) || 0;
+    if (have < q) { c = c * (have / q); q = have; }        // if it no longer has that many tokens (moved them), trim
+    if (q <= 1e-9) return;
+    const p = price[m] || 0, v = q * p;
+    if (!p) noPrice++;
+    unreal += v - c; costOpen += c;
+    open.push({ mint: m, sym: (sym && sym[m]) || short(m), q: q, cost: c, entry: c / q, price: p, value: v, ret: c > 0 ? (v - c) / c : null });
+  });
+  open.sort(function (a, b) { return b.value - a.value; });
+  const base = costClosed + costOpen, total = realized + unreal;
+  const p = { n: trades.length, since: trades.length ? trades[0].t : 0, realized: realized, unreal: unreal, total: total, base: base, ret: base > 0 ? total / base : null, open: open.slice(0, 5), noPrice: noPrice, ts: Date.now() };
+  p.st = pnlStatus(p, approx);
+  return p;
+}
+
+// win | lose | flat | unk
+export function pnlStatus(p, approx) {
+  if (!p || p.n < 3 || !(p.base >= 100)) return "unk";
+  if (approx) return "unk";   // without real SOL price history there is no reliable base to say win or lose
+  if (p.ret >= 0.05) return "win";
+  if (p.ret <= -0.05) return "lose";
+  return "flat";
+}
+
+/**
+ * Estimated result of each wallet from its last ~300 swaps (needs a Helius key).
+ *
+ * @param addrs      wallets
+ * @param balances   {wallet: {mint: amount}} current holdings (from getTokens), to trim moved tokens
+ * @returns {pnl: {wallet: result|null}, down, approx}
+ */
+export async function estimatePnl(client, addrs, balances, opts) {
+  opts = opts || {};
+  if (!client.heliusKey()) throw new ScanError("HELIUS_REQUIRED", "PnL needs a Helius API key");
+  const sol = await solHistory(client);
+  if (sol.approx && !(sol.now > 0)) throw new ScanError("SOL_PRICE", "no SOL price available");
+  const tb = {};
+  let done = 0, down = false;
+  await pool(addrs, 3, async function (a) {
+    if (down) { tb[a] = null; return; }
+    try { tb[a] = parseTrades(a, await fetchSwaps(client, a, opts.maxSwaps || 300), sol); }
+    catch (e) {
+      if (isCancel(e)) throw e;
+      tb[a] = null;
+      if (e.code === "NETWORK" || (e.code === "HTTP" && (e.data.status === 401 || e.data.status === 403))) down = true;
+    }
+    done++; if (opts.onStep) opts.onStep(done, addrs.length);
+  });
+  const set = {};
+  addrs.forEach(function (a) { (tb[a] || []).forEach(function (t) { set[t.mint] = 1; }); });
+  const ms = Object.keys(set);
+  const mk = ms.length ? (await getMarkets(client, ms)).data : {};
+  const price = {}, sym = {};
+  Object.keys(mk).forEach(function (m) { price[m] = Number(mk[m].priceUsd || 0); sym[m] = (mk[m].baseToken && mk[m].baseToken.symbol) || short(m); });
+  const out = {};
+  addrs.forEach(function (a) { out[a] = tb[a] ? pnlFromTrades(tb[a], (balances && balances[a]) || {}, price, sym, sol.approx) : null; });
+  return { pnl: out, down: down, approx: sol.approx };
+}