dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/data/src/sources/goplus.js

@@ -0,0 +1,161 @@
+// GoPlus Solana token-security adapter (task-1298; inventory 2026-10-06 §1d). Keyless, read-only.
+//   GET https://api.gopluslabs.io/api/v1/solana/token_security?contract_addresses={mint}
+//     -> { code: 1, message: "ok", result: { [mint]: {
+//            mintable | freezable | closable | balance_mutable_authority | metadata_mutable |
+//            transfer_fee_upgradable | transfer_hook_upgradable | default_account_state_upgradable:
+//              { status: "0"|"1", authority: [{ address, malicious_address }] | ... },
+//            non_transferable: "0"|"1", default_account_state: "0"|"1", transfer_hook: [...], transfer_fee: {...},
+//            holder_count, total_supply, holders: [{ account, token_account, balance, percent, is_locked, tag }],
+//            lp_holders: [...], dex: [{ dex_name, id, tvl, lp_amount, price, type, ... }],
+//            creators: [{ address, malicious_address }], metadata: { name, symbol, uri, description }, trusted_token } } }
+// Docs: https://docs.gopluslabs.io/reference/solanatokensecurityusingget (fetched for task-1285).
+// A second opinion next to RugCheck: authorities, Token-2022 hooks/fees, LP holders. `code !== 1`
+// is a failure. All free-text fields (names, tags, descriptions) are untrusted (CL-06).
+import { numOrNull } from "../util.js";
+export const GOPLUS_BASE = 'https://api.gopluslabs.io/api/v1';
+const META = { source: 'goplus', bucket: 'goplus' };
+function flag(v) {
+    if (v === undefined || v === null || v === '')
+        return null;
+    const s = String(v);
+    if (s === '1' || s === 'true')
+        return true;
+    if (s === '0' || s === 'false')
+        return false;
+    return null;
+}
+function authorityFlag(a) {
+    if (!a)
+        return null;
+    const st = flag(a.status);
+    if (st !== null)
+        return st;
+    return Array.isArray(a.authority) ? a.authority.length > 0 : null;
+}
+/** GoPlus percentages are fractions on EVM ("0.0123"); accept both fraction and percent forms. */
+export function toPercent(v, total = null, balance = null) {
+    const p = numOrNull(v);
+    if (p !== null)
+        return p <= 1 ? p * 100 : p;
+    const b = numOrNull(balance);
+    if (b !== null && total && total > 0)
+        return (b / total) * 100;
+    return 0;
+}
+function holder(h, total) {
+    const locked = flag(h.is_locked);
+    return {
+        address: h.account ?? h.token_account ?? '',
+        tokenAccount: h.token_account ?? null,
+        pct: Math.round(toPercent(h.percent, total, h.balance) * 1000) / 1000,
+        amount: numOrNull(h.balance) ?? 0,
+        isLocked: locked,
+        tag: typeof h.tag === 'string' && h.tag !== '' ? h.tag : null,
+    };
+}
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+export function normalizeGoPlus(mint, raw, fetchedAt) {
+    const total = numOrNull(raw.total_supply);
+    const malicious = new Set();
+    const addrs = (a) => {
+        for (const x of (a?.authority ?? [])) {
+            if (typeof x === 'object' && x && x.address && flag(x.malicious_address) === true)
+                malicious.add(x.address);
+        }
+    };
+    for (const a of [raw.mintable, raw.freezable, raw.closable, raw.balance_mutable_authority, raw.metadata_mutable, raw.transfer_fee_upgradable, raw.transfer_hook_upgradable, raw.default_account_state_upgradable])
+        addrs(a);
+    const creators = [];
+    for (const c of raw.creators ?? []) {
+        if (c?.address) {
+            creators.push(c.address);
+            if (flag(c.malicious_address) === true)
+                malicious.add(c.address);
+        }
+    }
+    const sec = {
+        mint,
+        mintable: authorityFlag(raw.mintable),
+        freezable: authorityFlag(raw.freezable),
+        closable: authorityFlag(raw.closable),
+        balanceMutable: authorityFlag(raw.balance_mutable_authority),
+        metadataMutable: authorityFlag(raw.metadata_mutable),
+        transferFeeUpgradable: authorityFlag(raw.transfer_fee_upgradable),
+        transferHookUpgradable: authorityFlag(raw.transfer_hook_upgradable),
+        defaultAccountStateUpgradable: authorityFlag(raw.default_account_state_upgradable),
+        nonTransferable: flag(raw.non_transferable),
+        transferHook: raw.transfer_hook === undefined ? null : Array.isArray(raw.transfer_hook) && raw.transfer_hook.length > 0,
+        transferFee: raw.transfer_fee === undefined ? null : !!raw.transfer_fee && Object.keys(raw.transfer_fee).length > 0,
+        defaultAccountState: raw.default_account_state === undefined || raw.default_account_state === null ? null : String(raw.default_account_state),
+        holderCount: numOrNull(raw.holder_count),
+        totalSupply: total,
+        holders: (raw.holders ?? []).filter((h) => h && (h.account || h.token_account)).map((h) => holder(h, total)).sort((a, b) => b.pct - a.pct),
+        lpHolders: (raw.lp_holders ?? []).filter((h) => h && (h.account || h.token_account)).map((h) => holder(h, total)).sort((a, b) => b.pct - a.pct),
+        dex: (raw.dex ?? []).filter((d) => d && (d.dex_name || d.id)).map((d) => ({ name: str(d.dex_name) ?? 'unknown', pool: str(d.id), tvlUsd: numOrNull(d.tvl), lpAmount: numOrNull(d.lp_amount), type: str(d.type) })),
+        creators,
+        maliciousAddresses: [...malicious],
+        trustedToken: flag(raw.trusted_token),
+        flags: [],
+        source: 'goplus',
+        metadataUri: typeof raw.metadata?.uri === 'string' ? raw.metadata.uri : null,
+        fetchedAt,
+    };
+    const flags = [];
+    if (sec.mintable)
+        flags.push('goplus:mintable');
+    if (sec.freezable)
+        flags.push('goplus:freezable');
+    if (sec.closable)
+        flags.push('goplus:closable');
+    if (sec.balanceMutable)
+        flags.push('goplus:balance-mutable');
+    if (sec.nonTransferable)
+        flags.push('goplus:non-transferable');
+    if (sec.transferHook)
+        flags.push('goplus:transfer-hook');
+    if (sec.transferFee)
+        flags.push('goplus:transfer-fee');
+    if (sec.defaultAccountState === '2')
+        flags.push('goplus:default-frozen');
+    if (sec.maliciousAddresses.length)
+        flags.push('goplus:malicious-address');
+    sec.flags = flags;
+    return sec;
+}
+/** The Audit fields GoPlus can speak to (authorities, top-10 by token account, risk names). */
+export function auditPatchFromGoPlus(s) {
+    const top10 = s.holders.slice(0, 10).reduce((sum, h) => sum + h.pct, 0);
+    return {
+        mintAuthority: s.mintable,
+        freezeAuthority: s.freezable,
+        top10Pct: s.holders.length ? Math.round(top10 * 1000) / 1000 : null,
+        rugRisks: s.flags,
+    };
+}
+/** `code !== 1` is an API-level failure even with HTTP 200; code 4029 is GoPlus's rate limit. */
+export const goplusBodyCheck = (data) => {
+    const r = data;
+    if (!r || typeof r !== 'object')
+        return { error: 'goplus: empty body' };
+    if (r.code === 1)
+        return null;
+    const msg = `goplus code ${r.code ?? '?'}: ${r.message ?? 'unknown'}`;
+    return r.code === 4029 || /rate|limit|too many/i.test(r.message ?? '') ? { status: 429, error: msg } : { error: msg };
+};
+export class GoPlus {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    static url(mint) {
+        return `${GOPLUS_BASE}/solana/token_security?contract_addresses=${encodeURIComponent(mint)}`;
+    }
+    async tokenSecurity(mint) {
+        const r = await this.http.getJson(GoPlus.url(mint), META, goplusBodyCheck);
+        const result = r.data.result ?? {};
+        const raw = result[mint] ?? Object.values(result).find((v) => v) ?? null;
+        if (!raw)
+            throw new Error(`goplus: no result for ${mint}`);
+        return normalizeGoPlus(mint, raw, r.fetchedAt);
+    }
+}

package/dist/packages/data/src/sources/jupiter-swap.js

@@ -0,0 +1,236 @@
+// Jupiter Swap *Quote* API (SPEC §3.1 S11, §6.1). KEYLESS, READ-ONLY, quote only.
+//
+// This adapter fetches a swap quote — route, in/out amounts, price impact, fees, slippage —
+// and NOTHING else. There is deliberately no /swap build, no /order?taker, no /execute and no
+// transaction assembly in this file, so the paper-trading lane (task-1310 T0) can price a fill
+// from a live route while being provably unable to reach a signable transaction (SPEC §6.0).
+//
+//   GET {host}/swap/v1/quote?inputMint=&outputMint=&amount=&slippageBps=&swapMode=
+//
+// Host order mirrors sources/jupiter.ts: the documented `api.jup.ag` first; on a keyless refusal
+// (401/403) switch, for the session, to `lite-api.jup.ag` (still keyless; SPEC §9.1). Shares the
+// keyless `jupiter` rate-limit bucket (see SOURCE_BUCKET['jupiter-swap']='jupiter') and so is paced
+// and budget-metered exactly like the Tokens/Price calls (free-forever, per-IP quota).
+import { HttpError, SourceUnavailableError } from "../http.js";
+import { systemClock } from "../clock.js";
+import { numOrNull } from "../util.js";
+export const JUP_SWAP_HOSTS = ['https://api.jup.ag', 'https://lite-api.jup.ag'];
+const SWAP = { source: 'jupiter-swap', bucket: 'jupiter' };
+// ------------------------------------------------------------------------------------ retry policy (task-1368)
+// A live ticket died on `build-failed: HTTP 429 for https://api.jup.ag/swap/v1/swap`: the old adapters
+// switched host only on a keyless refusal (401/403), never retried, and a single per-IP 429 on the build killed
+// the plan while the shared `jupiter` bucket paused for 30 s (the preview "fetching… forever"). Both hosts answer
+// 200 a moment later, so a 429 (or a 5xx / a dropped connection) is TRANSIENT and is handled here, once, for
+// the quote adapter AND the build adapter: honour Retry-After, retry with a jittered exponential backoff, try the
+// OTHER host (api ⇄ lite-api) for the next attempt, and give up only when the attempt count or the total time
+// budget is spent — with a typed error that says exactly when to try again. Nothing here changes what the
+// signer checks: it only decides when a keyless HTTP call is re-issued.
+/** Retry budget for a keyless Jupiter call: at most this many attempts within this many ms. */
+export const JUP_RETRY_MAX_ATTEMPTS = 3;
+export const JUP_RETRY_MAX_TOTAL_MS = 10_000;
+/** First backoff (doubles per attempt), multiplied by a jitter factor in [0.5, 1.5). */
+export const JUP_RETRY_BASE_MS = 1_000;
+/**
+ * A keyless Jupiter call was rate limited (429) and the retry budget is spent — or the data layer's own health
+ * gate is cooling the source down after repeated 429s (SPEC §3.3: two 429s inside a minute → 30 s, doubling).
+ * `retryAfterMs` is the honest wait: the largest of the server's Retry-After / reset, the next backoff, the
+ * shared bucket's remaining pause and the health cool-down, so a UI that shows "retrying in Ns" and retries then
+ * will usually get through. `status` is 429 when the last answer was a 429; 0 when only the cool-down spoke.
+ */
+export class JupiterRateLimitedError extends Error {
+    status;
+    host;
+    retryAfterMs;
+    attempts;
+    constructor(status, host, retryAfterMs, attempts) {
+        const s = Math.max(1, Math.ceil(retryAfterMs / 1000));
+        super(status === 429
+            ? `Jupiter is rate limiting this IP (429 from ${hostnameOf(host)}); retry in ${s}s`
+            : `Jupiter calls are paused after repeated rate limits (dexterm cool-down); retry in ${s}s`);
+        this.name = 'JupiterRateLimitedError';
+        this.status = status;
+        this.host = host;
+        this.retryAfterMs = retryAfterMs;
+        this.attempts = attempts;
+    }
+}
+function hostnameOf(host) {
+    try {
+        return new URL(host).hostname;
+    }
+    catch {
+        return host;
+    }
+}
+/** 429, any 5xx, a dropped connection or a transport timeout: worth another attempt. A caller abort never is. */
+export function isTransientJupiterError(err) {
+    if (err instanceof HttpError)
+        return err.status === 429 || (err.status >= 500 && err.status <= 599);
+    if (err instanceof Error) {
+        if (err.name === 'AbortError')
+            return false;
+        if (err.name === 'TimeoutError')
+            return true;
+        // undici's `fetch failed` (DNS, reset, refused) is a TypeError.
+        return err instanceof TypeError;
+    }
+    return false;
+}
+/**
+ * Host rotation + the retry policy above, shared by the quote and build adapters (one instance per adapter).
+ * `run` calls `fn(host)`; on a keyless refusal (401/403) it fails over to the next host for the session (as
+ * before); on a transient error it alternates to the other host and retries after `max(Retry-After, backoff)`
+ * while the budget allows; otherwise it rethrows. The caller's `signal` cuts a backoff sleep short.
+ */
+export class JupiterHosts {
+    hosts;
+    index = 0;
+    clock;
+    maxAttempts;
+    maxTotalMs;
+    baseMs;
+    random;
+    bucketPausedMs;
+    sourceUnavailableMs;
+    constructor(hosts = JUP_SWAP_HOSTS, opts = {}) {
+        if (hosts.length === 0)
+            throw new Error('JupiterHosts needs at least one host');
+        this.hosts = hosts;
+        this.clock = opts.clock ?? systemClock;
+        this.maxAttempts = Math.max(1, opts.maxAttempts ?? JUP_RETRY_MAX_ATTEMPTS);
+        this.maxTotalMs = Math.max(0, opts.maxTotalMs ?? JUP_RETRY_MAX_TOTAL_MS);
+        this.baseMs = Math.max(0, opts.baseBackoffMs ?? JUP_RETRY_BASE_MS);
+        this.random = opts.random ?? Math.random;
+        this.bucketPausedMs = opts.bucketPausedMs ?? (() => 0);
+        this.sourceUnavailableMs = opts.sourceUnavailableMs ?? (() => 0);
+    }
+    get host() { return this.hosts[this.index]; }
+    async run(fn, signal) {
+        const started = this.clock.now();
+        let attempt = 0;
+        let lastStatus = 0;
+        for (;;) {
+            attempt++;
+            const host = this.host;
+            try {
+                return await fn(host, attempt);
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw err;
+                // The health gate refused to send (the source is DEGRADED — after two 429s inside a minute, or three
+                // failures in a row): report it as the rate-limit wait it is, so the ticket counts down instead of
+                // failing with "source jupiter-swap is degraded". Status 429 when this run saw one, else the cool-down form.
+                if (err instanceof SourceUnavailableError) {
+                    const wait = Math.max(this.sourceUnavailableMs(), this.bucketPausedMs(), 1_000);
+                    throw new JupiterRateLimitedError(lastStatus === 429 ? 429 : 0, host, wait, attempt);
+                }
+                // Keyless refusal: switch host for the session (sticky), no wait, not counted as a retry.
+                if (err instanceof HttpError && (err.status === 401 || err.status === 403)) {
+                    if (this.index < this.hosts.length - 1) {
+                        this.index++;
+                        continue;
+                    }
+                    throw err;
+                }
+                if (!isTransientJupiterError(err))
+                    throw err;
+                // Transient: the NEXT attempt goes to the other host (round robin; it stays there afterwards).
+                if (this.hosts.length > 1)
+                    this.index = (this.index + 1) % this.hosts.length;
+                const status = err instanceof HttpError ? err.status : 0;
+                lastStatus = status;
+                const retryAfter = err instanceof HttpError && err.retryAfterMs !== undefined ? err.retryAfterMs : 0;
+                const backoff = Math.round(this.baseMs * 2 ** (attempt - 1) * (0.5 + this.random()));
+                const wait = Math.max(retryAfter, backoff);
+                const elapsed = this.clock.now() - started;
+                if (attempt >= this.maxAttempts || elapsed + wait > this.maxTotalMs) {
+                    if (status === 429)
+                        throw new JupiterRateLimitedError(status, host, Math.max(wait, this.bucketPausedMs()), attempt);
+                    throw err;
+                }
+                await this.clock.sleep(wait, signal);
+                if (signal?.aborted)
+                    throw abortError();
+            }
+        }
+    }
+}
+function abortError() {
+    const e = new Error('aborted by caller');
+    e.name = 'AbortError';
+    return e;
+}
+/**
+ * Parse a raw base-unit amount. STRICT (task-1310 round 2): only a non-negative decimal integer string
+ * is accepted. `"1.5e11"`, `"abc"`, `"-1"`, `""`, a number or a missing field THROW instead of mapping
+ * to 0n — a zero amount silently voided the USD caps downstream.
+ */
+function toBig(s, field = 'amount') {
+    if (typeof s !== 'string' || !/^[0-9]{1,30}$/.test(s)) {
+        throw new Error(`malformed quote: ${field} is not an integer string (${JSON.stringify(s).slice(0, 40)})`);
+    }
+    return BigInt(s);
+}
+export function normalizeSwapQuote(raw, fetchedAt) {
+    return {
+        inputMint: raw.inputMint,
+        outputMint: raw.outputMint,
+        inAmount: toBig(raw.inAmount, 'inAmount'),
+        outAmount: toBig(raw.outAmount, 'outAmount'),
+        otherAmountThreshold: toBig(raw.otherAmountThreshold, 'otherAmountThreshold'),
+        mode: raw.swapMode === 'ExactOut' ? 'ExactOut' : 'ExactIn',
+        slippageBps: numOrNull(raw.slippageBps) ?? 0,
+        // DEFECT 1: Jupiter's priceImpactPct is a 0..1 fraction; convert to a percent exactly once.
+        priceImpactPct: (() => { const f = numOrNull(raw.priceImpactPct); return f === null ? null : f * 100; })(),
+        route: (raw.routePlan ?? []).map((r) => r.swapInfo?.label ?? '').filter((s) => s.length > 0),
+        platformFeeBps: numOrNull(raw.platformFee?.feeBps),
+        platformFeeAmount: raw.platformFee?.amount !== undefined ? toBig(raw.platformFee.amount, 'platformFee.amount') : null,
+        usdValue: numOrNull(raw.swapUsdValue),
+        contextSlot: numOrNull(raw.contextSlot),
+        source: 'jupiter-swap',
+        fetchedAt,
+    };
+}
+export class JupiterSwap {
+    http;
+    hosts;
+    constructor(http, hosts = JUP_SWAP_HOSTS, retry = {}) {
+        this.http = http;
+        this.hosts = new JupiterHosts(hosts, { clock: http.clock, bucketPausedMs: () => http.pausedFor(SWAP.bucket), sourceUnavailableMs: () => http.unavailableFor(SWAP.source), ...retry });
+    }
+    get host() {
+        return this.hosts.host;
+    }
+    /**
+     * A single keyless quote. Throws HttpError (redacted) on transport/HTTP/validation failure.
+     * `signal` bounds the wait (task-1310): a confirm-time quote passes an 8 s abort so a 429 pause
+     * on the shared keyless bucket can never hang the booking; the abort rejects with an AbortError.
+     */
+    async quote(req, signal) {
+        if (!(req.amount > 0n))
+            throw new Error('quote amount must be a positive integer of base units');
+        if (req.inputMint === req.outputMint)
+            throw new Error('quote needs two different mints');
+        const params = new URLSearchParams({
+            inputMint: req.inputMint,
+            outputMint: req.outputMint,
+            amount: req.amount.toString(),
+            slippageBps: String(Math.max(0, Math.round(req.slippageBps))),
+            swapMode: req.mode ?? 'ExactIn',
+        });
+        const r = await this.get(`/swap/v1/quote?${params.toString()}`, signal);
+        const d = r.data;
+        if (!d || typeof d !== 'object' || d.inAmount === undefined || d.outAmount === undefined) {
+            throw new HttpError(r.status, `${this.host}/swap/v1/quote`, 'empty or malformed quote');
+        }
+        return normalizeSwapQuote(d, r.fetchedAt);
+    }
+    /** task-1368: 401/403 → sticky failover; 429/5xx/transport → alternate host + bounded retry (JupiterHosts). */
+    get(path, signal) {
+        return this.hosts.run((host) => this.http.getJson(`${host}${path}`, SWAP, (data) => {
+            const e = data?.error;
+            return typeof e === 'string' && e.length > 0 ? { error: e } : null;
+        }, signal), signal);
+    }
+}

package/dist/packages/data/src/sources/jupiter.js

@@ -0,0 +1,198 @@
+// Jupiter Tokens API v2 + Price API v3 adapter (SPEC §3.1 S2/S3). Keyless, read-only.
+// Docs: solana-launchpad/docs/jupiter/tokens-api.md, tokens-api-list.md;
+// rate limits: developers.jup.ag/docs/portal/rate-limits (keyless 0.5 rps, one
+// bucket shared by Tokens and Price).
+//   GET /tokens/v2/search?query=<csv ≤100 mints | symbol | name>
+//   GET /tokens/v2/recent
+//   GET /tokens/v2/{toptrending|toporganicscore|toptraded}/{5m|1h|6h|24h}?limit=
+//   GET /price/v3?ids=<csv ≤50>
+// Host: the documented `api.jup.ag` first; if it refuses keyless access
+// (401/403) we switch, for the session, to `lite-api.jup.ag`, which still
+// answers keyless (SPEC §9.1).
+import { HttpError } from "../http.js";
+import { chunk, isoToMs, num, numOrNull } from "../util.js";
+export const JUPITER_HOSTS = ['https://api.jup.ag', 'https://lite-api.jup.ag'];
+export const JUP_SEARCH_BATCH = 100;
+export const JUP_PRICE_BATCH = 50;
+const TOKENS = { source: 'jupiter-tokens', bucket: 'jupiter' };
+const PRICE = { source: 'jupiter-price', bucket: 'jupiter' };
+const STAT_KEYS = {
+    m5: 'stats5m',
+    h1: 'stats1h',
+    h6: 'stats6h',
+    h24: 'stats24h',
+};
+export function launchpadFromJupiter(lp, mint) {
+    const s = (lp ?? '').toLowerCase();
+    if (s.includes('pump'))
+        return 'pump.fun';
+    if (s.includes('bonk'))
+        return 'bonk';
+    if (s.includes('dbc') || s.includes('dynamic-bonding'))
+        return 'dbc';
+    if (s.includes('launchlab') || s.includes('raydium'))
+        return 'raydium';
+    if (s.includes('meteora'))
+        return 'meteora';
+    if (!s && mint.endsWith('pump'))
+        return 'pump.fun';
+    return 'unknown';
+}
+function socials(raw) {
+    return { x: raw.twitter ?? null, tg: raw.telegram ?? null, web: raw.website ?? null };
+}
+function windowStats(s) {
+    if (!s)
+        return null;
+    return {
+        numTraders: numOrNull(s.numTraders),
+        numNetBuyers: numOrNull(s.numNetBuyers),
+        buyVol: numOrNull(s.buyOrganicVolume),
+        sellVol: numOrNull(s.sellOrganicVolume),
+    };
+}
+/** true = authority enabled. Jupiter sends `audit.*Disabled`, or omits it and sends the authority address. */
+function authority(disabled, address) {
+    if (disabled !== undefined)
+        return !disabled;
+    if (typeof address === 'string' && address.length > 0)
+        return true;
+    return null;
+}
+export function normalizeJupToken(raw, fetchedAt) {
+    const createdAt = isoToMs(raw.firstPool?.createdAt) ?? isoToMs(raw.createdAt);
+    const token = {
+        source: 'jupiter-tokens',
+        fetchedAt,
+        mint: raw.id,
+        symbol: raw.symbol,
+        name: raw.name,
+        decimals: numOrNull(raw.decimals),
+        launchpad: launchpadFromJupiter(raw.launchpad, raw.id),
+        createdAt,
+        image: raw.icon ?? null,
+        socials: socials(raw),
+        verified: raw.isVerified === true,
+        // audit.isSus is only present when flagged (docs): presence is the signal.
+        sus: raw.audit?.isSus !== undefined ? raw.audit.isSus !== false : false,
+    };
+    const perWindow = {};
+    const txns = {};
+    const volume = {};
+    const priceChange = {};
+    for (const w of Object.keys(STAT_KEYS)) {
+        const s = raw[STAT_KEYS[w]];
+        perWindow[w] = windowStats(s);
+        txns[w] = { buys: num(s?.numBuys), sells: num(s?.numSells) };
+        volume[w] = s && (s.buyVolume !== undefined || s.sellVolume !== undefined) ? num(s.buyVolume) + num(s.sellVolume) : null;
+        priceChange[w] = numOrNull(s?.priceChange);
+    }
+    const stats = {
+        source: 'jupiter-tokens',
+        fetchedAt,
+        mint: raw.id,
+        holderCount: numOrNull(raw.holderCount),
+        holders24hDelta: numOrNull(raw.stats24h?.holderChange),
+        organicScore: numOrNull(raw.organicScore),
+        perWindow,
+    };
+    const audit = {
+        source: 'jupiter-tokens',
+        fetchedAt,
+        mint: raw.id,
+        mintAuthority: authority(raw.audit?.mintAuthorityDisabled, raw.mintAuthority),
+        freezeAuthority: authority(raw.audit?.freezeAuthorityDisabled, raw.freezeAuthority),
+        // Jupiter's topHoldersPercentage (top-10 share as Jupiter computes it; SPEC §3.6 LP/CEX exclusion is not applied here).
+        top10Pct: numOrNull(raw.audit?.topHoldersPercentage),
+        devPct: numOrNull(raw.audit?.devBalancePercentage),
+        devMints: numOrNull(raw.audit?.devMints),
+        lpLockedPct: null,
+        rugRisks: [],
+        rugScore: null,
+    };
+    const pair = {
+        source: 'jupiter-tokens',
+        fetchedAt,
+        pairAddress: raw.firstPool?.id ?? '',
+        dex: 'unknown',
+        baseMint: raw.id,
+        quoteMint: '',
+        priceUsd: num(raw.usdPrice),
+        priceNative: 0,
+        liquidityUsd: numOrNull(raw.liquidity),
+        fdv: numOrNull(raw.fdv),
+        mcap: numOrNull(raw.mcap),
+        txns,
+        volume,
+        priceChange,
+        createdAt,
+    };
+    return { token, stats, audit, pair };
+}
+export class Jupiter {
+    http;
+    hosts;
+    hostIndex = 0;
+    constructor(http, hosts = JUPITER_HOSTS) {
+        this.http = http;
+        this.hosts = hosts;
+    }
+    get host() {
+        return this.hosts[this.hostIndex];
+    }
+    /** Search by mint list (batched ≤100), symbol or name. */
+    async search(query) {
+        const queries = Array.isArray(query) ? chunk([...new Set(query)], JUP_SEARCH_BATCH).map((b) => b.join(',')) : [query];
+        const out = [];
+        for (const q of queries) {
+            const r = await this.get(`/tokens/v2/search?query=${encodeURIComponent(q)}`, TOKENS);
+            for (const t of Array.isArray(r.data) ? r.data : [])
+                out.push(normalizeJupToken(t, r.fetchedAt));
+        }
+        return out;
+    }
+    /** Newest tokens by first-pool creation time (default 30). */
+    async recent() {
+        return this.list('/tokens/v2/recent');
+    }
+    async category(category, interval, limit) {
+        return this.list(`/tokens/v2/${category}/${interval}${limit ? `?limit=${limit}` : ''}`);
+    }
+    /** USD prices for up to N mints, batched 50 per call. Unknown mints are absent. */
+    async price(mints) {
+        const out = new Map();
+        for (const batch of chunk([...new Set(mints)], JUP_PRICE_BATCH)) {
+            const r = await this.get(`/price/v3?ids=${batch.join(',')}`, PRICE);
+            for (const [mint, p] of Object.entries(r.data ?? {})) {
+                if (!p || numOrNull(p.usdPrice) === null)
+                    continue;
+                out.set(mint, {
+                    mint,
+                    usdPrice: num(p.usdPrice),
+                    priceChange24h: numOrNull(p.priceChange24h),
+                    liquidity: numOrNull(p.liquidity),
+                    source: 'jupiter-price',
+                    fetchedAt: r.fetchedAt,
+                });
+            }
+        }
+        return out;
+    }
+    async list(path) {
+        const r = await this.get(path, TOKENS);
+        return (Array.isArray(r.data) ? r.data : []).map((t) => normalizeJupToken(t, r.fetchedAt));
+    }
+    async get(path, meta) {
+        for (;;) {
+            try {
+                return await this.http.getJson(`${this.host}${path}`, meta);
+            }
+            catch (err) {
+                const refused = err instanceof HttpError && (err.status === 401 || err.status === 403);
+                if (!refused || this.hostIndex >= this.hosts.length - 1)
+                    throw err;
+                this.hostIndex++; // sticky for the session
+            }
+        }
+    }
+}