@elizaos/agent 2.0.0-alpha.97 → 2.0.0-beta.1

package/dist/packages/agent/src/api/wallet-trading-profile.js

@@ -0,0 +1,544 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { writeJsonAtomicSync } from "../utils/atomic-json.js";
+const WALLET_PROFILE_LEDGER_VERSION = 1;
+const MAX_WALLET_PROFILE_LEDGER_ENTRIES = 2000;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const FLOAT_EPSILON = 1e-12;
+const TRADE_STATUS_SET = new Set([
+    "pending",
+    "success",
+    "reverted",
+    "not_found",
+]);
+const ALLOWED_STATUS_TRANSITIONS = {
+    pending: new Set(["pending", "success", "reverted", "not_found"]),
+    not_found: new Set(["pending", "success", "reverted", "not_found"]),
+    success: new Set(["success"]),
+    reverted: new Set(["reverted"]),
+};
+const TRADE_SIDE_SET = new Set(["buy", "sell"]);
+function nowIso() {
+    return new Date().toISOString();
+}
+function toFiniteNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : 0;
+    if (typeof value === "string") {
+        const parsed = Number.parseFloat(value.trim());
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+function toBnbString(value) {
+    if (!Number.isFinite(value) || Math.abs(value) < FLOAT_EPSILON)
+        return "0";
+    const fixed = value.toFixed(8).replace(/\.?0+$/, "");
+    return fixed === "-0" ? "0" : fixed;
+}
+function toRatePercent(numerator, denominator) {
+    if (!Number.isFinite(denominator) || denominator <= 0)
+        return null;
+    if (!Number.isFinite(numerator) || numerator <= 0)
+        return 0;
+    return (numerator / denominator) * 100;
+}
+function normalizeStatus(value) {
+    if (typeof value !== "string")
+        return "pending";
+    const normalized = value.trim().toLowerCase();
+    if (!TRADE_STATUS_SET.has(normalized))
+        return "pending";
+    return normalized;
+}
+function canTransitionTradeStatus(current, next) {
+    return ALLOWED_STATUS_TRANSITIONS[current].has(next);
+}
+function normalizeSide(value) {
+    if (typeof value !== "string")
+        return "buy";
+    const normalized = value.trim().toLowerCase();
+    if (!TRADE_SIDE_SET.has(normalized))
+        return "buy";
+    return normalized;
+}
+function normalizeSource(value) {
+    if (typeof value !== "string")
+        return "manual";
+    return value.trim().toLowerCase() === "agent" ? "agent" : "manual";
+}
+function normalizeIsoDate(value) {
+    if (typeof value !== "string")
+        return nowIso();
+    const trimmed = value.trim();
+    if (!trimmed)
+        return nowIso();
+    const timestamp = Date.parse(trimmed);
+    if (!Number.isFinite(timestamp))
+        return nowIso();
+    return new Date(timestamp).toISOString();
+}
+function normalizeNullableInteger(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string" && !value.trim())
+        return null;
+    const parsed = toFiniteNumber(value);
+    if (!Number.isFinite(parsed))
+        return null;
+    return Math.floor(parsed);
+}
+function normalizeAddress(value) {
+    if (typeof value !== "string")
+        return "";
+    return value.trim().toLowerCase();
+}
+function normalizeLeg(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const symbol = typeof record.symbol === "string" ? record.symbol.trim() : "";
+    const amount = typeof record.amount === "string"
+        ? record.amount.trim()
+        : toFiniteNumber(record.amount).toString();
+    const amountWei = typeof record.amountWei === "string" ? record.amountWei.trim() : "";
+    if (!symbol || !amount || !amountWei)
+        return null;
+    return { symbol, amount, amountWei };
+}
+function normalizeLedgerEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const hash = typeof record.hash === "string" ? record.hash.trim() : "";
+    const tokenAddress = normalizeAddress(record.tokenAddress);
+    const quoteIn = normalizeLeg(record.quoteIn);
+    const quoteOut = normalizeLeg(record.quoteOut);
+    if (!hash || !tokenAddress || !quoteIn || !quoteOut)
+        return null;
+    const routeRaw = Array.isArray(record.route) ? record.route : [];
+    const route = routeRaw
+        .map((item) => (typeof item === "string" ? item.trim() : ""))
+        .filter((item) => item.length > 0);
+    const explorerUrl = typeof record.explorerUrl === "string"
+        ? record.explorerUrl.trim()
+        : `https://bscscan.com/tx/${hash}`;
+    return {
+        hash,
+        createdAt: normalizeIsoDate(record.createdAt),
+        updatedAt: normalizeIsoDate(record.updatedAt),
+        source: normalizeSource(record.source),
+        side: normalizeSide(record.side),
+        tokenAddress,
+        slippageBps: Math.max(0, Math.round(toFiniteNumber(record.slippageBps))),
+        route,
+        quoteIn,
+        quoteOut,
+        status: normalizeStatus(record.status),
+        confirmations: Math.max(0, Math.floor(toFiniteNumber(record.confirmations))),
+        nonce: (() => {
+            const nonce = normalizeNullableInteger(record.nonce);
+            return nonce === null ? null : Math.max(0, nonce);
+        })(),
+        blockNumber: (() => {
+            const blockNumber = normalizeNullableInteger(record.blockNumber);
+            return blockNumber === null ? null : Math.max(0, blockNumber);
+        })(),
+        gasUsed: typeof record.gasUsed === "string" && record.gasUsed.trim()
+            ? record.gasUsed.trim()
+            : null,
+        effectiveGasPriceWei: typeof record.effectiveGasPriceWei === "string" &&
+            record.effectiveGasPriceWei.trim()
+            ? record.effectiveGasPriceWei.trim()
+            : null,
+        ...(typeof record.reason === "string" && record.reason.trim()
+            ? { reason: record.reason.trim() }
+            : {}),
+        explorerUrl,
+    };
+}
+function sortAndTrimEntries(entries) {
+    const sorted = [...entries].sort((a, b) => {
+        const aMs = Date.parse(a.createdAt);
+        const bMs = Date.parse(b.createdAt);
+        if (Number.isFinite(aMs) && Number.isFinite(bMs) && aMs !== bMs) {
+            return aMs - bMs;
+        }
+        return a.hash.localeCompare(b.hash);
+    });
+    if (sorted.length <= MAX_WALLET_PROFILE_LEDGER_ENTRIES)
+        return sorted;
+    return sorted.slice(sorted.length - MAX_WALLET_PROFILE_LEDGER_ENTRIES);
+}
+function defaultLedgerStore() {
+    return {
+        version: WALLET_PROFILE_LEDGER_VERSION,
+        updatedAt: nowIso(),
+        entries: [],
+    };
+}
+export function resolveWalletTradingProfileFilePath(stateDir = resolveStateDir()) {
+    return path.join(stateDir, "wallet", "trading-profile.v1.json");
+}
+export function readWalletTradeLedgerStore(stateDir = resolveStateDir()) {
+    const filePath = resolveWalletTradingProfileFilePath(stateDir);
+    if (!fs.existsSync(filePath))
+        return defaultLedgerStore();
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const rawEntries = Array.isArray(parsed.entries) ? parsed.entries : [];
+        const entries = rawEntries
+            .map((item) => normalizeLedgerEntry(item))
+            .filter((item) => item !== null);
+        return {
+            version: WALLET_PROFILE_LEDGER_VERSION,
+            updatedAt: normalizeIsoDate(parsed.updatedAt),
+            entries: sortAndTrimEntries(entries),
+        };
+    }
+    catch {
+        try {
+            const corruptPath = `${filePath}.corrupt-${Date.now()}.json`;
+            fs.renameSync(filePath, corruptPath);
+        }
+        catch {
+            // Best effort backup; continue with empty store.
+        }
+        return defaultLedgerStore();
+    }
+}
+export function writeWalletTradeLedgerStore(store, stateDir = resolveStateDir()) {
+    const filePath = resolveWalletTradingProfileFilePath(stateDir);
+    const normalized = {
+        version: WALLET_PROFILE_LEDGER_VERSION,
+        updatedAt: nowIso(),
+        entries: sortAndTrimEntries(store.entries),
+    };
+    writeJsonAtomicSync(filePath, normalized);
+    return normalized;
+}
+export function recordWalletTradeLedgerEntry(input, stateDir = resolveStateDir()) {
+    const store = readWalletTradeLedgerStore(stateDir);
+    const entry = {
+        hash: input.hash.trim(),
+        createdAt: normalizeIsoDate(input.createdAt ?? nowIso()),
+        updatedAt: normalizeIsoDate(input.updatedAt ?? nowIso()),
+        source: normalizeSource(input.source),
+        side: normalizeSide(input.side),
+        tokenAddress: normalizeAddress(input.tokenAddress),
+        slippageBps: Math.max(0, Math.round(toFiniteNumber(input.slippageBps))),
+        route: (input.route ?? [])
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0),
+        quoteIn: {
+            symbol: input.quoteIn.symbol.trim(),
+            amount: input.quoteIn.amount.trim(),
+            amountWei: input.quoteIn.amountWei.trim(),
+        },
+        quoteOut: {
+            symbol: input.quoteOut.symbol.trim(),
+            amount: input.quoteOut.amount.trim(),
+            amountWei: input.quoteOut.amountWei.trim(),
+        },
+        status: normalizeStatus(input.status),
+        confirmations: Math.max(0, Math.floor(toFiniteNumber(input.confirmations))),
+        nonce: input.nonce === null ? null : Math.floor(toFiniteNumber(input.nonce)),
+        blockNumber: input.blockNumber === null
+            ? null
+            : Math.max(0, Math.floor(toFiniteNumber(input.blockNumber))),
+        gasUsed: input.gasUsed?.trim() || null,
+        effectiveGasPriceWei: input.effectiveGasPriceWei?.trim() || null,
+        ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+        explorerUrl: input.explorerUrl.trim() || `https://bscscan.com/tx/${input.hash.trim()}`,
+    };
+    const existingIndex = store.entries.findIndex((item) => item.hash === entry.hash);
+    if (existingIndex >= 0) {
+        store.entries[existingIndex] = entry;
+    }
+    else {
+        store.entries.push(entry);
+    }
+    writeWalletTradeLedgerStore(store, stateDir);
+    return entry;
+}
+export function updateWalletTradeLedgerEntryStatus(hash, patch, stateDir = resolveStateDir()) {
+    const normalizedHash = hash.trim();
+    if (!normalizedHash)
+        return null;
+    const store = readWalletTradeLedgerStore(stateDir);
+    const index = store.entries.findIndex((entry) => entry.hash === normalizedHash);
+    if (index < 0)
+        return null;
+    const current = store.entries[index];
+    const nextStatus = normalizeStatus(patch.status);
+    if (!canTransitionTradeStatus(current.status, nextStatus)) {
+        return current;
+    }
+    const updated = {
+        ...current,
+        status: nextStatus,
+        confirmations: Math.max(0, Math.floor(toFiniteNumber(patch.confirmations))),
+        nonce: patch.nonce === null ? null : Math.floor(toFiniteNumber(patch.nonce)),
+        blockNumber: patch.blockNumber === null
+            ? null
+            : Math.max(0, Math.floor(toFiniteNumber(patch.blockNumber))),
+        gasUsed: patch.gasUsed?.trim() || null,
+        effectiveGasPriceWei: patch.effectiveGasPriceWei?.trim() || null,
+        ...(patch.explorerUrl?.trim()
+            ? { explorerUrl: patch.explorerUrl.trim() }
+            : {}),
+        updatedAt: normalizeIsoDate(patch.updatedAt ?? nowIso()),
+    };
+    if (typeof patch.reason === "string") {
+        const reason = patch.reason.trim();
+        if (reason) {
+            updated.reason = reason;
+        }
+        else {
+            delete updated.reason;
+        }
+    }
+    else if (updated.status === "success" || updated.status === "pending") {
+        delete updated.reason;
+    }
+    store.entries[index] = updated;
+    writeWalletTradeLedgerStore(store, stateDir);
+    return updated;
+}
+function resolveWindow(window) {
+    if (window === "24h" ||
+        window === "7d" ||
+        window === "30d" ||
+        window === "all")
+        return window;
+    return "30d";
+}
+function resolveSource(source) {
+    if (source === "all" || source === "agent" || source === "manual")
+        return source;
+    return "all";
+}
+function resolveTokenSymbol(entry) {
+    return entry.side === "buy" ? entry.quoteOut.symbol : entry.quoteIn.symbol;
+}
+function toDayBucket(isoDate) {
+    const timestamp = Date.parse(isoDate);
+    if (!Number.isFinite(timestamp))
+        return new Date().toISOString().slice(0, 10);
+    return new Date(timestamp).toISOString().slice(0, 10);
+}
+function consumeLots(lots, qtyToSell) {
+    if (!Number.isFinite(qtyToSell) || qtyToSell <= FLOAT_EPSILON)
+        return 0;
+    let remaining = qtyToSell;
+    let matchedCost = 0;
+    while (remaining > FLOAT_EPSILON && lots.length > 0) {
+        const lot = lots[0];
+        if (lot.qty <= FLOAT_EPSILON) {
+            lots.shift();
+            continue;
+        }
+        const take = Math.min(remaining, lot.qty);
+        const ratio = take / lot.qty;
+        const consumedCost = lot.costBnb * ratio;
+        matchedCost += consumedCost;
+        lot.qty -= take;
+        lot.costBnb -= consumedCost;
+        remaining -= take;
+        if (lot.qty <= FLOAT_EPSILON || lot.costBnb <= FLOAT_EPSILON) {
+            lots.shift();
+        }
+    }
+    return matchedCost;
+}
+function toRecentSwap(entry) {
+    return {
+        hash: entry.hash,
+        createdAt: entry.createdAt,
+        source: entry.source,
+        side: entry.side,
+        status: entry.status,
+        tokenAddress: entry.tokenAddress,
+        tokenSymbol: resolveTokenSymbol(entry),
+        inputAmount: entry.quoteIn.amount,
+        inputSymbol: entry.quoteIn.symbol,
+        outputAmount: entry.quoteOut.amount,
+        outputSymbol: entry.quoteOut.symbol,
+        explorerUrl: entry.explorerUrl || `https://bscscan.com/tx/${entry.hash}`,
+        confirmations: entry.confirmations,
+        ...(entry.reason ? { reason: entry.reason } : {}),
+    };
+}
+export function buildWalletTradingProfile(entries, options = {}) {
+    const window = resolveWindow(options.window);
+    const source = resolveSource(options.source);
+    const now = Date.now();
+    const cutoffMs = window === "24h"
+        ? now - ONE_DAY_MS
+        : window === "7d"
+            ? now - 7 * ONE_DAY_MS
+            : window === "30d"
+                ? now - 30 * ONE_DAY_MS
+                : 0;
+    const filtered = entries
+        .filter((entry) => {
+        if (source !== "all" && entry.source !== source)
+            return false;
+        if (cutoffMs > 0) {
+            const createdAtMs = Date.parse(entry.createdAt);
+            if (!Number.isFinite(createdAtMs) || createdAtMs < cutoffMs)
+                return false;
+        }
+        return true;
+    })
+        .sort((a, b) => {
+        const aMs = Date.parse(a.createdAt);
+        const bMs = Date.parse(b.createdAt);
+        if (Number.isFinite(aMs) && Number.isFinite(bMs) && aMs !== bMs) {
+            return aMs - bMs;
+        }
+        return a.hash.localeCompare(b.hash);
+    });
+    let buyCount = 0;
+    let sellCount = 0;
+    let successCount = 0;
+    let revertedCount = 0;
+    let settledCount = 0;
+    let winningTrades = 0;
+    let evaluatedTrades = 0;
+    let realizedPnlBnb = 0;
+    let volumeBnb = 0;
+    const tokenMap = new Map();
+    const seriesMap = new Map();
+    for (const entry of filtered) {
+        if (entry.side === "buy")
+            buyCount += 1;
+        else
+            sellCount += 1;
+        if (entry.status === "success")
+            successCount += 1;
+        if (entry.status === "reverted")
+            revertedCount += 1;
+        if (entry.status === "success" || entry.status === "reverted")
+            settledCount += 1;
+        if (entry.status !== "success")
+            continue;
+        const tokenAddress = entry.tokenAddress;
+        const tokenSymbol = resolveTokenSymbol(entry);
+        let token = tokenMap.get(tokenAddress);
+        if (!token) {
+            token = {
+                tokenAddress,
+                symbol: tokenSymbol,
+                buyCount: 0,
+                sellCount: 0,
+                realizedPnlBnb: 0,
+                volumeBnb: 0,
+                winningTrades: 0,
+                evaluatedTrades: 0,
+                lots: [],
+            };
+            tokenMap.set(tokenAddress, token);
+        }
+        else if (!token.symbol && tokenSymbol) {
+            token.symbol = tokenSymbol;
+        }
+        const day = toDayBucket(entry.createdAt);
+        let series = seriesMap.get(day);
+        if (!series) {
+            series = {
+                day,
+                realizedPnlBnb: 0,
+                volumeBnb: 0,
+                swaps: 0,
+            };
+            seriesMap.set(day, series);
+        }
+        if (entry.side === "buy") {
+            const qtyBought = toFiniteNumber(entry.quoteOut.amount);
+            const spendBnb = toFiniteNumber(entry.quoteIn.amount);
+            token.buyCount += 1;
+            token.volumeBnb += spendBnb;
+            if (qtyBought > FLOAT_EPSILON && spendBnb >= 0) {
+                token.lots.push({ qty: qtyBought, costBnb: spendBnb });
+            }
+            volumeBnb += spendBnb;
+            series.volumeBnb += spendBnb;
+            series.swaps += 1;
+            continue;
+        }
+        const qtySold = toFiniteNumber(entry.quoteIn.amount);
+        const proceedsBnb = toFiniteNumber(entry.quoteOut.amount);
+        const matchedCostBnb = consumeLots(token.lots, qtySold);
+        const tradePnlBnb = proceedsBnb - matchedCostBnb;
+        token.sellCount += 1;
+        token.volumeBnb += proceedsBnb;
+        token.realizedPnlBnb += tradePnlBnb;
+        token.evaluatedTrades += 1;
+        if (tradePnlBnb > 0)
+            token.winningTrades += 1;
+        evaluatedTrades += 1;
+        if (tradePnlBnb > 0)
+            winningTrades += 1;
+        realizedPnlBnb += tradePnlBnb;
+        volumeBnb += proceedsBnb;
+        series.realizedPnlBnb += tradePnlBnb;
+        series.volumeBnb += proceedsBnb;
+        series.swaps += 1;
+    }
+    const tokenBreakdown = [
+        ...tokenMap.values(),
+    ]
+        .map((token) => ({
+        tokenAddress: token.tokenAddress,
+        symbol: token.symbol || "TOKEN",
+        buyCount: token.buyCount,
+        sellCount: token.sellCount,
+        realizedPnlBnb: toBnbString(token.realizedPnlBnb),
+        volumeBnb: toBnbString(token.volumeBnb),
+        tradeWinRate: toRatePercent(token.winningTrades, token.evaluatedTrades),
+        winningTrades: token.winningTrades,
+        evaluatedTrades: token.evaluatedTrades,
+    }))
+        .sort((a, b) => Number.parseFloat(b.volumeBnb) - Number.parseFloat(a.volumeBnb));
+    const pnlSeries = [...seriesMap.values()]
+        .sort((a, b) => a.day.localeCompare(b.day))
+        .map((point) => ({
+        day: point.day,
+        realizedPnlBnb: toBnbString(point.realizedPnlBnb),
+        volumeBnb: toBnbString(point.volumeBnb),
+        swaps: point.swaps,
+    }));
+    const recentSwaps = [...filtered]
+        .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt))
+        .slice(0, 20)
+        .map(toRecentSwap);
+    return {
+        window,
+        source,
+        generatedAt: nowIso(),
+        summary: {
+            totalSwaps: filtered.length,
+            buyCount,
+            sellCount,
+            settledCount,
+            successCount,
+            revertedCount,
+            tradeWinRate: toRatePercent(winningTrades, evaluatedTrades),
+            txSuccessRate: toRatePercent(successCount, settledCount),
+            winningTrades,
+            evaluatedTrades,
+            realizedPnlBnb: toBnbString(realizedPnlBnb),
+            volumeBnb: toBnbString(volumeBnb),
+        },
+        pnlSeries,
+        tokenBreakdown,
+        recentSwaps,
+    };
+}
+export function loadWalletTradingProfile(options = {}) {
+    const store = readWalletTradeLedgerStore(options.stateDir);
+    return buildWalletTradingProfile(store.entries, options);
+}

package/dist/packages/agent/src/api/wallet.d.ts

@@ -0,0 +1,64 @@
+import type { KeyValidationResult, SolanaTokenBalance, WalletAddresses, WalletChain, WalletGenerateResult, WalletImportResult, WalletKeys } from "@elizaos/shared";
+export type { BscTradeExecuteRequest, BscTradeExecuteResponse, BscTradeExecutionResult, BscTradePreflightRequest, BscTradePreflightResponse, BscTradeQuoteRequest, BscTradeQuoteResponse, BscTradeSide, BscTradeTxStatus, BscTradeTxStatusResponse, BscTransferExecuteRequest, BscTransferExecuteResponse, BscTransferExecutionResult, BscUnsignedApprovalTx, BscUnsignedTradeTx, BscUnsignedTransferTx, EvmChainBalance, EvmTokenBalance, KeyValidationResult, SolanaTokenBalance, TradePermissionMode, WalletAddresses, WalletBalancesResponse, WalletChain, WalletConfigStatus, WalletGenerateResult, WalletImportResult, WalletKeys, WalletTradeLedgerEntry, WalletTradeSource, WalletTradingProfileResponse, WalletTradingProfileSourceFilter, WalletTradingProfileWindow, } from "@elizaos/shared";
+export { computeValueUsd, DEX_PRICE_TIMEOUT_MS, DEXPAPRIKA_CHAIN_MAP, DEXSCREENER_CHAIN_MAP, type DexScreenerPair, type DexTokenMeta, fetchDexPaprikaPrices, fetchDexPrices, fetchDexScreenerPrices, WRAPPED_NATIVE, } from "./wallet-dex-prices.ts";
+export { type AnkrTokenAsset, DEFAULT_EVM_CHAINS, type EvmProviderKeys, fetchEvmBalances, resolveEvmProviderKeys, } from "./wallet-evm-balance.ts";
+export declare const MANAGED_EVM_ADDRESS_ENV_KEY = "ELIZA_MANAGED_EVM_ADDRESS";
+export declare const MANAGED_SOLANA_ADDRESS_ENV_KEY = "ELIZA_MANAGED_SOLANA_ADDRESS";
+export declare const CLOUD_EVM_ADDRESS_ENV_KEY = "ELIZA_CLOUD_EVM_ADDRESS";
+export declare const CLOUD_SOLANA_ADDRESS_ENV_KEY = "ELIZA_CLOUD_SOLANA_ADDRESS";
+export declare const WALLET_SOURCE_EVM_ENV_KEY = "WALLET_SOURCE_EVM";
+export declare const WALLET_SOURCE_SOLANA_ENV_KEY = "WALLET_SOURCE_SOLANA";
+export declare function deriveEvmAddress(privateKeyHex: string): string;
+export declare function deriveSolanaAddress(privateKeyString: string): string;
+export declare function validateEvmPrivateKey(key: string): KeyValidationResult;
+export declare function validateSolanaPrivateKey(key: string): KeyValidationResult;
+/** Auto-detect chain from key format and validate. */
+export declare function validatePrivateKey(key: string): KeyValidationResult;
+/** Mask a secret string for safe display (e.g. logs, UI). */
+export declare function maskSecret(value: string): string;
+export declare function generateWalletKeys(): WalletKeys;
+export declare function generateWalletForChain(chain: WalletChain): WalletGenerateResult;
+export { syncSolanaPublicKeyEnv } from "./wallet-env-sync.ts";
+export declare function setSolanaWalletEnv(privateKey: string): string | null;
+/** Validate key, store in process.env. Caller persists to config if needed. */
+export declare function importWallet(chain: WalletChain, privateKey: string): WalletImportResult;
+export declare const STEWARD_EVM_ADDRESS_ENV_KEY = "STEWARD_EVM_ADDRESS";
+export declare const STEWARD_SOLANA_ADDRESS_ENV_KEY = "STEWARD_SOLANA_ADDRESS";
+/**
+ * Initialise the steward wallet address cache.
+ *
+ * Call once during server startup.  Fetches addresses from the steward API
+ * and writes them to `process.env.STEWARD_EVM_ADDRESS` /
+ * `process.env.STEWARD_SOLANA_ADDRESS` so the synchronous
+ * `getWalletAddresses()` can use them without hitting the network.
+ */
+export declare function initStewardWalletCache(): Promise<void>;
+/**
+ * Derive addresses from env keys.  Works without a running runtime.
+ *
+ * Resolution order (steward-first):
+ *   1. Steward cached addresses  (`STEWARD_EVM_ADDRESS` / `STEWARD_SOLANA_ADDRESS`)
+ *   2. Local private key derivation  (`EVM_PRIVATE_KEY` / `SOLANA_PRIVATE_KEY`)
+ *   3. Managed address env vars  (`ELIZA_MANAGED_EVM_ADDRESS` / `ELIZA_MANAGED_SOLANA_ADDRESS`)
+ */
+export declare function getWalletAddresses(): WalletAddresses;
+/**
+ * Extended wallet addresses including steward-managed wallets.
+ * Calls steward API (async) to discover additional addresses.
+ * Key-derived addresses are always preferred; steward addresses fill gaps.
+ */
+export declare function getWalletAddressesWithSteward(): Promise<WalletAddresses & {
+    stewardEvmAddress?: string | null;
+    stewardSolanaAddress?: string | null;
+}>;
+export declare function fetchSolanaBalances(address: string, heliusKey: string): Promise<{
+    solBalance: string;
+    solValueUsd: string;
+    tokens: SolanaTokenBalance[];
+}>;
+export declare function fetchSolanaNativeBalanceViaRpc(address: string, rpcUrls: string[]): Promise<{
+    solBalance: string;
+    solValueUsd: string;
+    tokens: SolanaTokenBalance[];
+}>;
+//# sourceMappingURL=wallet.d.ts.map

package/dist/packages/agent/src/api/wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../../../../src/api/wallet.ts"],"names":[],"mappings":"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"}