@alphafox/cli 0.3.6 → 0.3.8

package/dist/auth/refresh.d.ts

@@ -8,6 +8,8 @@ import type { ProfileConfig } from "../config/profiles";
 import { type StoredTokens } from "../keychain/store";
 /** Refresh when access token expires within this window. */
 export declare const ACCESS_TOKEN_REFRESH_SKEW_MS = 60000;
+/** Drop a stale inter-process refresh lock after this long. */
+export declare const REFRESH_LOCK_STALE_MS = 30000;
 export type RefreshOutcome = {
     readonly status: "refreshed";
     readonly tokens: StoredTokens;
@@ -40,5 +42,6 @@ export declare function refreshStoredTokensOrNull(profile: ProfileConfig, env?:
     readonly now?: number;
     readonly force?: boolean;
 }): Promise<StoredTokens | null>;
+export declare function refreshLockFilePath(profile: string, env?: NodeJS.ProcessEnv): string;
 /** Test helper: clear in-flight map between cases. */
 export declare function clearRefreshInflightForTests(): void;

package/dist/auth/refresh.js

@@ -6,15 +6,21 @@
  * Outcomes are explicit: callers must not treat a failed refresh as a healthy session.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACCESS_TOKEN_REFRESH_SKEW_MS = void 0;
+exports.REFRESH_LOCK_STALE_MS = exports.ACCESS_TOKEN_REFRESH_SKEW_MS = void 0;
 exports.accessTokenNeedsRefresh = accessTokenNeedsRefresh;
 exports.refreshStoredTokens = refreshStoredTokens;
 exports.refreshStoredTokensOrNull = refreshStoredTokensOrNull;
+exports.refreshLockFilePath = refreshLockFilePath;
 exports.clearRefreshInflightForTests = clearRefreshInflightForTests;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
 const version_1 = require("../version");
 const store_1 = require("../keychain/store");
 /** Refresh when access token expires within this window. */
 exports.ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;
+/** Drop a stale inter-process refresh lock after this long. */
+exports.REFRESH_LOCK_STALE_MS = 30_000;
 /** In-flight refresh promises so concurrent API calls share one rotation. */
 const inflightByProfile = new Map();
 function accessTokenNeedsRefresh(tokens, now = Date.now()) {
@@ -36,20 +42,38 @@ async function refreshStoredTokens(profile, env = process.env, fetchImpl = fetch
             tokens: null,
         };
     }
-    if (!options.force &&
-        !accessTokenNeedsRefresh(existing, options.now ?? Date.now())) {
+    const now = options.now ?? Date.now();
+    if (!options.force && !accessTokenNeedsRefresh(existing, now)) {
         return { status: "unchanged", tokens: existing };
     }
-    const key = profile.name;
-    const pending = inflightByProfile.get(key);
-    if (pending) {
-        return pending;
-    }
-    const work = performRefresh(profile, existing, env, fetchImpl).finally(() => {
-        inflightByProfile.delete(key);
+    return withRefreshLock(profile.name, env, async () => {
+        const latest = (0, store_1.loadTokens)(profile.name, env) ?? existing;
+        if (!latest?.refreshToken?.trim()) {
+            return {
+                status: "no_session",
+                reason: "no_refresh_token",
+                tokens: null,
+            };
+        }
+        const someoneElseRefreshed = latest.refreshToken !== existing.refreshToken ||
+            latest.expiresAt > existing.expiresAt;
+        if (someoneElseRefreshed && !accessTokenNeedsRefresh(latest, now)) {
+            return { status: "unchanged", tokens: latest };
+        }
+        if (!options.force && !accessTokenNeedsRefresh(latest, now)) {
+            return { status: "unchanged", tokens: latest };
+        }
+        const key = profile.name;
+        const pending = inflightByProfile.get(key);
+        if (pending) {
+            return pending;
+        }
+        const work = performRefresh(profile, latest, env, fetchImpl).finally(() => {
+            inflightByProfile.delete(key);
+        });
+        inflightByProfile.set(key, work);
+        return work;
     });
-    inflightByProfile.set(key, work);
-    return work;
 }
 /**
  * Convenience for callers that only need tokens on successful refresh/unchanged.
@@ -62,6 +86,68 @@ async function refreshStoredTokensOrNull(profile, env = process.env, fetchImpl =
     }
     return null;
 }
+function refreshLockFilePath(profile, env = process.env) {
+    const base = env.ALPHAFOX_KEYCHAIN_DIR?.trim() ||
+        (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "alphafox", "keychain");
+    return (0, node_path_1.join)(base, `${profile}.refresh.lock`);
+}
+async function withRefreshLock(profile, env, work) {
+    const path = refreshLockFilePath(profile, env);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    const started = Date.now();
+    while (true) {
+        try {
+            const fd = (0, node_fs_1.openSync)(path, node_fs_1.constants.O_CREAT | node_fs_1.constants.O_EXCL | node_fs_1.constants.O_WRONLY);
+            try {
+                (0, node_fs_1.writeFileSync)(fd, `${process.pid}\n${Date.now()}\n`);
+            }
+            finally {
+                (0, node_fs_1.closeSync)(fd);
+            }
+            try {
+                return await work();
+            }
+            finally {
+                try {
+                    (0, node_fs_1.unlinkSync)(path);
+                }
+                catch {
+                    // another process stole a stale lock
+                }
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST") {
+                throw err;
+            }
+            try {
+                if (Date.now() - (0, node_fs_1.statSync)(path).mtimeMs > exports.REFRESH_LOCK_STALE_MS) {
+                    (0, node_fs_1.unlinkSync)(path);
+                    continue;
+                }
+            }
+            catch {
+                // lock disappeared; retry acquire
+            }
+            if (Date.now() - started > exports.REFRESH_LOCK_STALE_MS + 5_000) {
+                try {
+                    (0, node_fs_1.unlinkSync)(path);
+                }
+                catch {
+                    // raced
+                }
+                continue;
+            }
+            await sleep(50);
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
 async function performRefresh(profile, existing, env, fetchImpl) {
     const origin = profile.apiBaseUrl.replace(/\/$/, "").replace(/\/api\/v1$/, "");
     const url = `${origin}/api/auth/oauth/token`;

package/dist/catalog/omit.d.ts

@@ -1,5 +1,7 @@
 /**
- * Chat-attached `/api/v1/backtests` jobs are not a CLI surface.
+ * Not a CLI surface:
+ * - Web `/api/v1/backtests` jobs (`backtests` / `backtests.*`)
+ * - Chat product (`chats` / `chats.*`, `chat_summaries` / `chat_summaries.*`)
  * Local Engine WASM (`engine-backtest run`) and `engine_backtest.*` stay.
  * Match `backtests` / `backtests.*` only — never `engine_backtest.*`.
  */

package/dist/catalog/omit.js

@@ -2,10 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isOmittedCatalogOperation = isOmittedCatalogOperation;
 /**
- * Chat-attached `/api/v1/backtests` jobs are not a CLI surface.
+ * Not a CLI surface:
+ * - Web `/api/v1/backtests` jobs (`backtests` / `backtests.*`)
+ * - Chat product (`chats` / `chats.*`, `chat_summaries` / `chat_summaries.*`)
  * Local Engine WASM (`engine-backtest run`) and `engine_backtest.*` stay.
  * Match `backtests` / `backtests.*` only — never `engine_backtest.*`.
  */
 function isOmittedCatalogOperation(operationId) {
-    return operationId === "backtests" || operationId.startsWith("backtests.");
+    return (operationId === "backtests" ||
+        operationId.startsWith("backtests.") ||
+        operationId === "chats" ||
+        operationId.startsWith("chats.") ||
+        operationId === "chat_summaries" ||
+        operationId.startsWith("chat_summaries."));
 }

package/dist/commands/run.js

@@ -9,6 +9,7 @@ const allowlist_1 = require("../catalog/allowlist");
 const profiles_1 = require("../config/profiles");
 const envelope_1 = require("../envelope");
 const browser_login_1 = require("../auth/browser-login");
+const refresh_1 = require("../auth/refresh");
 const client_1 = require("../http/client");
 const store_1 = require("../keychain/store");
 const confirmation_1 = require("../safety/confirmation");
@@ -101,7 +102,7 @@ async function runCli(argv, env = process.env) {
                 "alphafox api METHOD PATH [--body JSON|--config @file]",
                 "alphafox engine-backtest run --experiment <uuid> --definition <id> --config @file --exchange <id> --range FROM..TO --initial-equity N",
                 "alphafox engine-backtest sweep --experiment <uuid> --definition <id> --config @file --axes @file --exchange <id> --range FROM..TO --initial-equity N --no-persist",
-                "alphafox resolve-symbols <query...> [--exchange binance]",
+                "alphafox resolve-symbols <query...> [--exchange binance] [--asset-class equity_perp]",
                 "alphafox <domain> <resource> <action> [flags]",
             ],
         }, { format: flags.format, jq: flags.jq });
@@ -351,15 +352,30 @@ async function cmdAuth(args, flags, env) {
     });
     if (sub === "status") {
         const verify = args.includes("--verify");
-        const tokens = (0, store_1.loadTokens)(profile.name, env);
+        let tokens = (0, store_1.loadTokens)(profile.name, env);
         if (!tokens) {
             (0, envelope_1.writeSuccess)({
                 authenticated: false,
+                session: "none",
                 profile: profile.name,
                 verified: false,
+                refresh: "no_session",
+                accessTokenExpired: null,
+                hasRefreshToken: false,
             }, { format: flags.format, jq: flags.jq });
             return 0;
         }
+        let refresh = "skipped";
+        if ((0, refresh_1.accessTokenNeedsRefresh)(tokens)) {
+            const outcome = await (0, refresh_1.refreshStoredTokens)(profile, env);
+            refresh = outcome.status;
+            if (outcome.status === "refreshed" || outcome.status === "unchanged") {
+                tokens = outcome.tokens;
+            }
+            else {
+                tokens = (0, store_1.loadTokens)(profile.name, env) ?? tokens;
+            }
+        }
         let verified = null;
         let whoami = null;
         if (verify) {
@@ -370,9 +386,18 @@ async function cmdAuth(args, flags, env) {
             }, env);
             verified = res.status >= 200 && res.status < 300;
             whoami = verified ? res.json : { status: res.status, body: res.json };
+            tokens = (0, store_1.loadTokens)(profile.name, env) ?? tokens;
         }
+        const accessTokenExpired = tokens.expiresAt <= Date.now();
+        const hasRefreshToken = Boolean(tokens.refreshToken?.trim());
+        const session = !accessTokenExpired
+            ? "active"
+            : refresh === "failed"
+                ? "refresh_failed"
+                : "expired";
         (0, envelope_1.writeSuccess)({
-            authenticated: true,
+            authenticated: session === "active",
+            session,
             profile: profile.name,
             environment: tokens.environment,
             issuer: tokens.issuer,
@@ -381,6 +406,9 @@ async function cmdAuth(args, flags, env) {
             scopes: tokens.scopes,
             accessTokenFingerprint: (0, store_1.tokenFingerprint)(tokens.accessToken),
             expiresAt: tokens.expiresAt,
+            accessTokenExpired,
+            hasRefreshToken,
+            refresh,
             verified,
             whoami,
         }, { format: flags.format, jq: flags.jq });

package/dist/resolve-symbols/catalog.d.ts

@@ -1,3 +1,9 @@
+import type { SymbolMetadata } from "./types";
 export declare const MARKET_SYMBOLS_PATH = "/api/v1/market/symbols";
 export declare function marketSymbolsPath(exchangeId: string): string;
+export interface MarketCatalogPayload {
+    readonly symbols: string[];
+    readonly symbolMetadata: Readonly<Record<string, SymbolMetadata>>;
+}
 export declare function extractCatalogSymbols(json: unknown): string[];
+export declare function extractMarketCatalog(json: unknown): MarketCatalogPayload;

package/dist/resolve-symbols/catalog.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MARKET_SYMBOLS_PATH = void 0;
 exports.marketSymbolsPath = marketSymbolsPath;
 exports.extractCatalogSymbols = extractCatalogSymbols;
+exports.extractMarketCatalog = extractMarketCatalog;
 const errors_1 = require("./errors");
 exports.MARKET_SYMBOLS_PATH = "/api/v1/market/symbols";
 function marketSymbolsPath(exchangeId) {
@@ -10,6 +11,9 @@ function marketSymbolsPath(exchangeId) {
     return `${exports.MARKET_SYMBOLS_PATH}?${query}`;
 }
 function extractCatalogSymbols(json) {
+    return extractMarketCatalog(json).symbols;
+}
+function extractMarketCatalog(json) {
     const root = asRecord(json);
     const payload = asRecord(root?.data) ?? root;
     const symbols = payload?.symbols;
@@ -40,8 +44,47 @@ function extractCatalogSymbols(json) {
             details: json,
         });
     }
+    return {
+        symbols: out,
+        symbolMetadata: extractSymbolMetadata(payload?.symbolMetadata),
+    };
+}
+function extractSymbolMetadata(value) {
+    const rec = asRecord(value);
+    if (!rec)
+        return {};
+    const out = {};
+    for (const [rawKey, rawMeta] of Object.entries(rec)) {
+        const key = rawKey.trim();
+        const meta = parseSymbolMetadata(rawMeta);
+        if (!key || !meta)
+            continue;
+        out[key] = meta;
+    }
     return out;
 }
+function parseSymbolMetadata(value) {
+    const rec = asRecord(value);
+    if (!rec)
+        return undefined;
+    const meta = {};
+    if (typeof rec.isTradFiRwa === "boolean") {
+        meta.isTradFiRwa = rec.isTradFiRwa;
+    }
+    if (typeof rec.assetClass === "string" && rec.assetClass.trim()) {
+        meta.assetClass = rec.assetClass.trim();
+    }
+    if (isFiniteNumber(rec.minAmount))
+        meta.minAmount = rec.minAmount;
+    if (isFiniteNumber(rec.minCost))
+        meta.minCost = rec.minCost;
+    if (isFiniteNumber(rec.contractSize))
+        meta.contractSize = rec.contractSize;
+    return Object.keys(meta).length > 0 ? meta : undefined;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
 function asRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return undefined;

package/dist/resolve-symbols/exchanges.js

@@ -42,12 +42,15 @@ for (const exchange of exports.RESOLVE_SYMBOLS_EXCHANGES) {
         EXCHANGE_BY_ALIAS.set(alias.toLowerCase(), exchange);
     }
 }
+const PASSTHROUGH_EXCHANGE_ID = /^[a-z][a-z0-9_]{1,63}$/;
 function resolveSymbolsExchangeId(raw) {
     const key = raw.trim().toLowerCase();
     const exchange = EXCHANGE_BY_ALIAS.get(key);
-    if (!exchange) {
-        const allowed = exports.RESOLVE_SYMBOLS_EXCHANGES.map((item) => item.aliases[0]).join("|");
-        throw new Error(`--exchange must be ${allowed} (got ${raw.trim() || "<empty>"})`);
+    if (exchange)
+        return exchange;
+    if (PASSTHROUGH_EXCHANGE_ID.test(key)) {
+        return { id: key, label: raw.trim(), aliases: [key] };
     }
-    return exchange;
+    const allowed = exports.RESOLVE_SYMBOLS_EXCHANGES.map((item) => item.aliases[0]).join("|");
+    throw new Error(`--exchange must be ${allowed} or a market.symbols.list catalog id (got ${raw.trim() || "<empty>"})`);
 }

package/dist/resolve-symbols/match.d.ts

@@ -1,6 +1,7 @@
-import type { CatalogSymbol, ResolveSymbolsQueryResult } from "./types";
+import type { CatalogSymbol, ResolveAssetClassFilter, ResolveSymbolsQueryResult, SymbolMetadata } from "./types";
 export declare function normalizeSymbolSearchKey(value: string): string;
 export declare function parseCatalogSymbol(symbol: string): CatalogSymbol | null;
-export declare function indexCatalogSymbols(symbols: readonly string[]): readonly CatalogSymbol[];
-export declare function resolveQueryAgainstCatalog(query: string, catalog: readonly CatalogSymbol[], limit?: number): ResolveSymbolsQueryResult;
+export declare function indexCatalogSymbols(symbols: readonly string[], metadata?: Readonly<Record<string, SymbolMetadata>>): readonly CatalogSymbol[];
+export declare function catalogMatchesAssetClass(item: CatalogSymbol, assetClass: ResolveAssetClassFilter): boolean;
+export declare function resolveQueryAgainstCatalog(query: string, catalog: readonly CatalogSymbol[], limit?: number, assetClass?: ResolveAssetClassFilter): ResolveSymbolsQueryResult;
 export declare function levenshtein(left: string, right: string): number;

package/dist/resolve-symbols/match.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeSymbolSearchKey = normalizeSymbolSearchKey;
 exports.parseCatalogSymbol = parseCatalogSymbol;
 exports.indexCatalogSymbols = indexCatalogSymbols;
+exports.catalogMatchesAssetClass = catalogMatchesAssetClass;
 exports.resolveQueryAgainstCatalog = resolveQueryAgainstCatalog;
 exports.levenshtein = levenshtein;
 const LINEAR_PERP_PATTERN = /^([\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*)\/(USDT|USDC|USD):\2$/u;
@@ -69,7 +70,7 @@ function parseCatalogSymbol(symbol) {
         compactKey: normalizeSymbolSearchKey(upper),
     };
 }
-function indexCatalogSymbols(symbols) {
+function indexCatalogSymbols(symbols, metadata = {}) {
     const seen = new Set();
     const indexed = [];
     for (const raw of symbols) {
@@ -79,64 +80,59 @@ function indexCatalogSymbols(symbols) {
         if (seen.has(parsed.symbol))
             continue;
         seen.add(parsed.symbol);
-        indexed.push(parsed);
+        indexed.push({
+            ...parsed,
+            metadata: metadata[raw] ?? metadata[parsed.symbol],
+        });
     }
     return indexed;
 }
-function resolveQueryAgainstCatalog(query, catalog, limit = 8) {
+function catalogMatchesAssetClass(item, assetClass) {
+    if (assetClass === "all")
+        return true;
+    const cls = item.metadata?.assetClass;
+    const tradfi = item.metadata?.isTradFiRwa === true;
+    if (assetClass === "equity_perp")
+        return cls === "equity_perp";
+    if (assetClass === "rwa_perp")
+        return cls === "rwa_perp";
+    return !tradfi && cls !== "equity_perp" && cls !== "rwa_perp";
+}
+function resolveQueryAgainstCatalog(query, catalog, limit = 8, assetClass = "all") {
     const trimmed = query.trim();
-    const matches = rankMatches(trimmed, catalog);
+    const scoped = catalog.filter((item) => catalogMatchesAssetClass(item, assetClass));
+    const matches = rankMatches(trimmed, scoped);
     const exact = matches.filter((item) => EXACT_REASONS.has(item.reason));
     const close = matches.filter((item) => !EXACT_REASONS.has(item.reason));
     const capped = (items) => items.slice(0, Math.max(1, limit));
     if (exact.length === 1) {
-        return {
-            query: trimmed,
-            status: "exact",
-            resolved: exact[0].symbol,
-            needsConfirmation: false,
-            matches: exact,
-            matchCount: exact.length,
-        };
+        return result("exact", exact[0].symbol, false, exact, exact.length);
     }
     if (exact.length > 1) {
-        return {
-            query: trimmed,
-            status: "ambiguous",
-            resolved: null,
-            needsConfirmation: true,
-            matches: capped(exact),
-            matchCount: exact.length,
-        };
+        return result("ambiguous", null, true, capped(exact), exact.length);
     }
     if (close.length === 1) {
-        return {
-            query: trimmed,
-            status: "close",
-            resolved: close[0].symbol,
-            needsConfirmation: true,
-            matches: close,
-            matchCount: 1,
-        };
+        return result("close", close[0].symbol, true, close, 1);
     }
     if (close.length > 1) {
+        return result("ambiguous", null, true, capped(close), close.length);
+    }
+    return result("none", null, false, [], 0);
+    function result(status, resolved, needsConfirmation, matches, matchCount) {
+        const chosen = resolved
+            ? matches.find((item) => item.symbol === resolved)
+            : undefined;
         return {
             query: trimmed,
-            status: "ambiguous",
-            resolved: null,
-            needsConfirmation: true,
-            matches: capped(close),
-            matchCount: close.length,
+            status,
+            resolved,
+            assetClass: chosen?.assetClass ?? null,
+            isTradFiRwa: chosen?.isTradFiRwa ?? false,
+            needsConfirmation,
+            matches,
+            matchCount,
         };
     }
-    return {
-        query: trimmed,
-        status: "none",
-        resolved: null,
-        needsConfirmation: false,
-        matches: [],
-        matchCount: 0,
-    };
 }
 function rankMatches(query, catalog) {
     const canonicalQuery = query.trim().toUpperCase();
@@ -161,21 +157,21 @@ function rankMatches(query, catalog) {
 }
 function rankCatalogSymbol(item, canonicalQuery, queryKey, queryBaseKey) {
     if (item.symbol === canonicalQuery) {
-        return match(item.symbol, "exact_canonical", 100);
+        return match(item, "exact_canonical", 100);
     }
     if (item.pair === canonicalQuery) {
-        return match(item.symbol, "exact_pair", 96);
+        return match(item, "exact_pair", 96);
     }
     if (item.compactKey === queryKey || item.searchKey === queryKey) {
-        return match(item.symbol, "exact_compact", 98);
+        return match(item, "exact_compact", 98);
     }
     if (item.baseKey === queryKey || item.baseKey === queryBaseKey) {
-        return match(item.symbol, "exact_base", 95);
+        return match(item, "exact_base", 95);
     }
     let best = null;
     const consider = (reason, score) => {
         if (!best || score > best.score) {
-            best = match(item.symbol, reason, score);
+            best = match(item, reason, score);
         }
     };
     if (queryBaseKey.length >= 2 && item.baseKey.startsWith(queryBaseKey)) {
@@ -219,8 +215,14 @@ function isCloseDistance(left, right, distance) {
         return distance === 1;
     return distance <= 2;
 }
-function match(symbol, reason, score) {
-    return { symbol, reason, score };
+function match(item, reason, score) {
+    return {
+        symbol: item.symbol,
+        reason,
+        score,
+        assetClass: item.metadata?.assetClass ?? null,
+        isTradFiRwa: item.metadata?.isTradFiRwa === true,
+    };
 }
 function clampScore(score) {
     return Math.max(1, Math.min(94, score));

package/dist/resolve-symbols/parse-args.d.ts

@@ -1,5 +1,6 @@
 import type { ResolveSymbolsRunArgs } from "./types";
 export declare const RESOLVE_SYMBOLS_DEFAULT_LIMIT = 8;
 export declare const RESOLVE_SYMBOLS_MAX_LIMIT = 25;
+export declare const RESOLVE_SYMBOLS_ASSET_CLASSES: readonly ["all", "equity_perp", "rwa_perp", "crypto"];
 export declare const RESOLVE_SYMBOLS_USAGE: string[];
 export declare function parseResolveSymbolsArgs(args: readonly string[]): ResolveSymbolsRunArgs;

package/dist/resolve-symbols/parse-args.js

@@ -1,14 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESOLVE_SYMBOLS_USAGE = exports.RESOLVE_SYMBOLS_MAX_LIMIT = exports.RESOLVE_SYMBOLS_DEFAULT_LIMIT = void 0;
+exports.RESOLVE_SYMBOLS_USAGE = exports.RESOLVE_SYMBOLS_ASSET_CLASSES = exports.RESOLVE_SYMBOLS_MAX_LIMIT = exports.RESOLVE_SYMBOLS_DEFAULT_LIMIT = void 0;
 exports.parseResolveSymbolsArgs = parseResolveSymbolsArgs;
 const errors_1 = require("./errors");
 const exchanges_1 = require("./exchanges");
 exports.RESOLVE_SYMBOLS_DEFAULT_LIMIT = 8;
 exports.RESOLVE_SYMBOLS_MAX_LIMIT = 25;
+exports.RESOLVE_SYMBOLS_ASSET_CLASSES = [
+    "all",
+    "equity_perp",
+    "rwa_perp",
+    "crypto",
+];
 exports.RESOLVE_SYMBOLS_USAGE = [
-    "alphafox resolve-symbols <query...> [--exchange binance] [--limit 8]",
+    "alphafox resolve-symbols <query...> [--exchange binance] [--asset-class all] [--limit 8]",
     "alphafox resolve-symbols --query BTC --query ETH --exchange okx",
+    "alphafox resolve-symbols NVDA AAPL TSLA --exchange binance --asset-class equity_perp",
 ];
 function usage(message, subtype = "invalid_args") {
     throw new errors_1.ResolveSymbolsError({
@@ -30,6 +37,7 @@ function parseResolveSymbolsArgs(args) {
     const queries = [];
     let exchange = exchanges_1.RESOLVE_SYMBOLS_DEFAULT_EXCHANGE;
     let limit = exports.RESOLVE_SYMBOLS_DEFAULT_LIMIT;
+    let assetClass = "all";
     let help = false;
     for (let i = 0; i < args.length; i += 1) {
         const a = args[i];
@@ -59,6 +67,14 @@ function parseResolveSymbolsArgs(args) {
             case "--exchange":
                 exchange = read();
                 break;
+            case "--asset-class": {
+                const value = read().trim().toLowerCase();
+                if (!exports.RESOLVE_SYMBOLS_ASSET_CLASSES.includes(value)) {
+                    usage(`--asset-class must be ${exports.RESOLVE_SYMBOLS_ASSET_CLASSES.join("|")}`, "invalid_asset_class");
+                }
+                assetClass = value;
+                break;
+            }
             case "--limit": {
                 const n = Number(read());
                 if (!Number.isInteger(n) || n <= 0 || n > exports.RESOLVE_SYMBOLS_MAX_LIMIT) {
@@ -72,7 +88,7 @@ function parseResolveSymbolsArgs(args) {
         }
     }
     if (help) {
-        return { help: true, queries: [], exchange, limit };
+        return { help: true, queries: [], exchange, limit, assetClass };
     }
     const normalizedQueries = queries.map((item) => item.trim()).filter(Boolean);
     if (normalizedQueries.length === 0) {
@@ -90,6 +106,7 @@ function parseResolveSymbolsArgs(args) {
         queries: uniqueQueries(normalizedQueries),
         exchange: resolvedExchange,
         limit,
+        assetClass,
     };
 }
 function uniqueQueries(queries) {

package/dist/resolve-symbols/run-command.js

@@ -41,10 +41,12 @@ function resolveSymbolsHelpData() {
         name: "resolve-symbols",
         usage: parse_args_1.RESOLVE_SYMBOLS_USAGE,
         notes: [
-            "Resolves user-mentioned tickers against the public linear-perp catalog from market.symbols.list",
-            "Default --exchange is binance (binance_perp_usdt). Aliases: binance|okx|bybit|bitget|hyperliquid|aster",
-            "Do not guess CCXT symbols. Exact match may be used directly; a single close match needs user confirmation; multiple close matches must be chosen by the user",
-            "Catalog CRUD remains alphafox market symbols list --exchange <id>",
+            "Resolves user-mentioned tickers against market.symbols.list for the chosen catalog",
+            "Default --exchange is binance (binance_perp_usdt). Built-in aliases: binance|okx|bybit|bitget|hyperliquid|aster",
+            "US stock perps live in the same catalog (NVDA/USDT:USDT) and are tagged symbolMetadata.assetClass=equity_perp / isTradFiRwa",
+            "For 美股 use --asset-class equity_perp. For gold/silver RWAs use rwa_perp. Crypto perps are untagged or --asset-class crypto",
+            "Each match includes assetClass and isTradFiRwa. Do not treat an equity_perp as a crypto coin",
+            "Catalog dump remains alphafox market symbols list --exchange <id>",
         ],
     };
 }
@@ -77,12 +79,22 @@ async function executeResolveSymbols(args, flags, env = process.env, deps = {})
             details: res.json,
         });
     }
-    const catalog = (0, match_1.indexCatalogSymbols)((0, catalog_1.extractCatalogSymbols)(res.json));
+    const payload = (0, catalog_1.extractMarketCatalog)(res.json);
+    const catalog = (0, match_1.indexCatalogSymbols)(payload.symbols, payload.symbolMetadata);
+    if (args.assetClass !== "all" &&
+        !catalog.some((item) => item.metadata?.assetClass)) {
+        throw new errors_1.ResolveSymbolsError({
+            type: "runtime",
+            subtype: "metadata_missing",
+            message: "market.symbols.list did not include symbolMetadata; cannot apply --asset-class",
+            hint: "Retry without --asset-class, or use a catalog that returns symbolMetadata.assetClass.",
+        });
+    }
     return {
         exchange: exchange.id,
         exchangeLabel: exchange.label,
         catalogSize: catalog.length,
-        queries: args.queries.map((query) => (0, match_1.resolveQueryAgainstCatalog)(query, catalog, args.limit)),
+        queries: args.queries.map((query) => (0, match_1.resolveQueryAgainstCatalog)(query, catalog, args.limit, args.assetClass)),
     };
 }
 async function cmdResolveSymbols(args, flags, env = process.env, deps = {}) {
@@ -119,6 +131,7 @@ async function cmdResolveSymbols(args, flags, env = process.env, deps = {}) {
             path: (0, catalog_1.marketSymbolsPath)(exchange.id),
             exchange: exchange.id,
             exchangeLabel: exchange.label,
+            assetClass: parsed.assetClass,
             queries: parsed.queries,
         }, { format: flags.format, jq: flags.jq });
         return 0;