@agentgrant.cash/cli 1.4.3 → 1.4.4

package/dist/lib/money-input.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Money INPUT resolution — the safety-critical counterpart to currency.ts
+ * (which handles money OUTPUT/display).
+ *
+ * The backend operates entirely in USD (the "cash" stablecoin ≈ 1 USD, and all
+ * trade/borrow/withdraw amounts are USD-denominated decimal strings). But a user
+ * thinks in their own currency: an INR user who says "buy ₹50 of gold" means ₹50,
+ * NOT $50. Sending the raw number through would overspend by the FX rate (~83×).
+ *
+ * This module resolves a user-entered amount into a USD decimal string for the
+ * backend, with two rules:
+ *   1. A bare number is interpreted in the currency the user is *viewing*
+ *      (their display currency) — local if they view local, else USD.
+ *   2. An explicit currency on the amount ("$10", "100 EUR", "₹50") always wins.
+ *
+ * Hard safety property: if the amount is in a non-USD currency and we cannot get
+ * an authoritative FX rate, we THROW rather than guess — a wrong-currency money
+ * transaction is never acceptable.
+ */
+import { type DisplayPrefs } from './currency.js';
+export interface ParsedMoney {
+    amount: number;
+    /** Explicit ISO currency the user attached to the amount, if any. */
+    currency?: string;
+}
+/**
+ * Parse a money input that may carry an explicit currency:
+ *   "50"  "$50"  "₹50"  "€10.5"  "50 INR"  "50inr"  "usd 10"  "$1,234.56"
+ * Returns the numeric amount and the explicit currency (uppercased) if present.
+ * Throws on anything that isn't a positive number.
+ */
+export declare function parseMoneyInput(raw: string): ParsedMoney;
+/** The currency a bare (unitless) amount is assumed to be in — matches what the user sees. */
+export declare function defaultInputCurrency(prefs: DisplayPrefs): string;
+/**
+ * Per-transaction USD ceiling — a fat-finger guard, NOT a product limit. Combined
+ * with the display-currency default (a bare "100" can mean a large local amount),
+ * an un-bounded input is a real over-spend risk, so anything above this is refused
+ * with a recoverable error rather than quietly accepted.
+ */
+export declare const MAX_CASH_USD = 10000000;
+/**
+ * Reject amounts that resolved to dust (rounds to $0 → opaque SWAP_QUOTE_FAILED
+ * downstream) or to an implausibly large value (fat-finger). `describe` renders
+ * the user's own amount for the message.
+ */
+export declare function assertUsdInBounds(usd: number, describe: () => string): void;
+export interface MoneyResolution {
+    /** Amount in USD for the backend. */
+    usd: number;
+    /** USD as a decimal string, rounded to the token's decimals and validated. */
+    usdString: string;
+    /** The original amount the user typed. */
+    sourceAmount: number;
+    /** The currency the amount was interpreted in (ISO). */
+    sourceCurrency: string;
+    /** Local-units-per-USD used for the conversion (1 for USD). */
+    rate: number;
+    /** True when a non-USD → USD conversion was applied. */
+    converted: boolean;
+}
+/**
+ * Resolve a user-entered cash amount into a USD decimal string for the backend.
+ *
+ * `fetchRate(currency)` must return local-units-per-USD for that currency. For any
+ * non-USD source currency we ALWAYS fetch an authoritative rate (we never trust a
+ * possibly-stale `prefs.rate`, which falls back to 1 when FX is unavailable — and a
+ * rate of 1 would silently treat ₹50 as $50). If the rate can't be obtained, we throw.
+ */
+export declare function resolveCashToUsd(raw: string, prefs: DisplayPrefs, decimals: number, fetchRate: (currency: string) => Promise<number>): Promise<MoneyResolution>;
+/**
+ * Human description of a resolved cash amount — shows the source amount and its
+ * USD equivalent when a conversion happened, so the user can see exactly what
+ * will be transacted (e.g. "₹50.00 (≈ $0.60)").
+ */
+export declare function describeCashResolution(m: MoneyResolution): string;
+export interface CashTargetResolution extends MoneyResolution {
+    /** Asset quantity to sell to realize ~the cash target, as a decimal string. */
+    quantity: string;
+    quantityNum: number;
+    /** Live USD unit price used to size the sale. */
+    unitPriceUsd: number;
+}
+/**
+ * Resolve a cash-denominated SELL target into a quantity of the asset to sell.
+ *
+ * "Sell ₹100 of gold" means: realize ~₹100 of cash by selling gold. Swaps are
+ * exact-input (you specify how much to sell), so we size the sale from the live
+ * USD unit price: `quantity = targetUSD / unitPriceUsd`. The result is therefore
+ * an approximation of the cash proceeds (slippage/fees move the exact figure) —
+ * hence "~₹100 worth", which is what the user means.
+ *
+ * `unitPriceUsd` is the live USD price per asset unit (gold price/oz for XAUT,
+ * BTC price for WBTC, ETH price for WETH, 1 for stables). If it isn't available
+ * (≤ 0) we throw rather than guess — a mis-sized money sale is never acceptable.
+ */
+export declare function resolveCashTargetToAssetQty(raw: string, prefs: DisplayPrefs, decimals: number, fetchRate: (currency: string) => Promise<number>, unitPriceUsd: number): Promise<CashTargetResolution>;

package/dist/lib/output.d.ts

@@ -0,0 +1,22 @@
+/**
+ * One output model for both engines. Pretty for humans; a single JSON object per
+ * command for agents. JSON mode auto-engages when stdout is not a TTY (an agent
+ * captured it) or with `--json`, matching the agent CLI's LLM-friendly contract:
+ *   success → {"ok":true, ...data}
+ *   failure → {"ok":false, error:{code, message, recoverable}}
+ */
+export interface OutCtx {
+    json: boolean;
+}
+export declare function isJsonMode(flag: boolean | undefined): boolean;
+export declare function emit(ctx: OutCtx, data: Record<string, unknown>, human: () => string): void;
+/** Print a failure in the active mode and return the process exit code. */
+export declare function printError(json: boolean, err: unknown): number;
+export declare const ui: {
+    title: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    amber: (s: string) => string;
+    red: (s: string) => string;
+    label: (s: string) => string;
+};

package/dist/lib/polygon-balance.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Read a deposit wallet's prediction-balance (pUSD) on Polygon — client-side,
+ * with no backend change and no web3 dependency.
+ *
+ * The prediction balance lives as pUSD (Polymarket USD: a standard ERC-20 on
+ * Polygon, 6 decimals, USDC-backed) in the user's Polymarket deposit wallet.
+ * The Perfolio backend only exposes the wallet ADDRESS, not its balance, and we
+ * are not allowed to change the backend — so we read the balance directly from a
+ * public Polygon RPC with a single `eth_call` to `balanceOf`, encoded/decoded by
+ * hand (no viem). The CLI ships only `commander` + `picocolors`; this keeps it
+ * that way.
+ *
+ * Everything here is best-effort: a balance read must NEVER break a command, so
+ * `fetchPusdBalanceUsd` returns `null` on any failure rather than throwing.
+ */
+/** pUSD (Polymarket USD) — ERC-20 on Polygon mainnet, 6 decimals. */
+export declare const PUSD_ADDRESS = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB";
+export declare const PUSD_DECIMALS = 6;
+/**
+ * ABI-encode `balanceOf(address)` calldata: the 4-byte selector followed by the
+ * address left-padded to a 32-byte word. Throws on a malformed address so the
+ * caller (which swallows failures) reports "unavailable" rather than querying junk.
+ */
+export declare function encodeBalanceOf(address: string): string;
+/** Decode a 32-byte hex word (an eth_call uint256 result) to a bigint. `0x`/empty → 0n. */
+export declare function decodeUint(hex: unknown): bigint;
+/** Convert a base-unit bigint to a decimal number given the token's decimals. */
+export declare function baseUnitsToNumber(units: bigint, decimals: number): number;
+interface FetchOpts {
+    rpcUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Read the pUSD balance (in USD; 1 pUSD ≈ $1) for a Polygon address via an
+ * `eth_call` to `balanceOf`. Returns the USD amount, or `null` on ANY failure —
+ * a balance read must never throw or break the command that called it.
+ *
+ * Endpoint selection: an explicit `opts.rpcUrl` or `PERFOLIO_POLYGON_RPC` pins a
+ * single endpoint; otherwise we try the public defaults in order and return the
+ * first that answers (so one endpoint going dark doesn't kill the feature).
+ */
+export declare function fetchPusdBalanceUsd(address: string, opts?: FetchOpts): Promise<number | null>;
+export {};

package/dist/lib/portfolio-format.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Friendly multi-asset portfolio rendering for the MONEY (investment) side —
+ * ported from the standalone Perfolio CLI so the merged Grant Cash CLI shows the
+ * same rich breakdown.
+ *
+ * Consumes the `GET /api/portfolio/summary?view=full` shape. When the optional
+ * `multiAsset` block is present it renders every spot asset (gold, cash, bitcoin,
+ * ethereum, …) plus the Hyperliquid perps bucket and its per-category breakdown.
+ * When it is absent (gold-only response) it degrades to a gold + cash summary so
+ * the command never shows raw JSON.
+ *
+ * All money is rendered through `formatMoney`, which applies the user's display
+ * currency. Callers pass USD values straight through — never pre-convert.
+ */
+import { type DisplayPrefs } from "./currency.js";
+import type { PortfolioSummary } from "./types.js";
+/**
+ * Money pools the backend's portfolio summary does NOT know about (prediction
+ * balance + open bets, earn/vault positions), read client-side and folded into
+ * the net-worth picture. Kept as a type so the extras pipeline is a drop-in
+ * later; the merged CLI does not yet gather these.
+ */
+export interface PortfolioExtras {
+    predictionAvailableUsd?: number;
+    predictionPositionsUsd?: number;
+    predictionPnlUsd?: number;
+    earn?: Array<{
+        label: string;
+        valueUsd: number;
+        earnedUsd?: number | null;
+        apy?: number | null;
+    }>;
+}
+export declare function formatPortfolioView(summary: PortfolioSummary, prefs?: DisplayPrefs, extras?: PortfolioExtras): string;
+/**
+ * The single, honest net worth (USD) including ALL pools: holdings (or gold+cash),
+ * perps equity, earning, and predictions — minus debt.
+ *
+ * The backend exposes `multiAsset.totalUsd` / `multiAsset.netWorthUsd` /
+ * `current.netWorthUsd`, but ALL of them EXCLUDE predictions and earn — which
+ * caused a real ~$190 under-report. This is the one number a programmatic consumer
+ * should trust, and it's emitted as `netWorthUsd` in `portfolio --json`.
+ */
+export declare function computeNetWorthUsd(summary: PortfolioSummary, extras: PortfolioExtras): number;
+/**
+ * Spending (agent) side — status-aware funds, ported from the standalone Agent
+ * CLI's `balance` rendering. The agent backend's `GET /balance` (api-key auth)
+ * returns one of: `not_set_up` (nothing to spend yet), `credit_exhausted`
+ * (sign-up credit used up), or `active` — and an active user carries either live
+ * on-chain USDC/USDT or a chain-agnostic sign-up credit total (minor units, 1e6).
+ */
+export interface AgentBalance {
+    status?: string;
+    address?: string;
+    USDC?: string | number;
+    USDT?: string | number;
+    grantMinor?: string | number;
+    totalMinor?: string | number;
+}
+/**
+ * The chain-agnostic spendable from `GET /credit` (dual-auth — the CLI's api-key
+ * can read it). Splits the single spendable into the sign-up "free credit"
+ * (grant) and the funds the user added (wallet). `walletMinor` is absent for a
+ * grant-only user. Mirrors the app's credit split (agent-mode-ui CreditCard).
+ */
+export interface CreditBalance {
+    grantMinor?: string | number;
+    walletMinor?: string | number;
+    totalMinor?: string | number;
+}
+/**
+ * Render the agent (spending) funds block as indented lines (no section title).
+ *
+ * When the chain-agnostic `credit` read (GET /credit) is supplied, we render the
+ * full split — total spendable, the sign-up free credit, and (if the user has
+ * funded a wallet) the funds they added — for parity with the app. Without it we
+ * fall back to the `/balance` status shape (USDC/USDT or sign-up-credit total).
+ */
+export declare function formatAgentFunds(bal: AgentBalance, credit?: CreditBalance | null): string;

package/dist/lib/relay.d.ts

@@ -0,0 +1,8 @@
+export declare function newSid(): string;
+interface PollOpts {
+    fetchImpl?: typeof fetch;
+    intervalMs?: number;
+    timeoutMs?: number;
+}
+export declare function pollRelay<T = unknown>(widgetBase: string, sid: string, opts?: PollOpts): Promise<T | null>;
+export {};

package/dist/lib/sign.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Browser-sign poll helper for user-signed operations (withdrawal, gift).
+ *
+ * The CLI prepares the operation and hands the payload to the sign relay
+ * (via PerfolioClient.signStart), opens the browser, then polls here until the
+ * user signs + executes in the browser. Poll is public (the sid is the secret).
+ */
+import type { SignPoll } from './types.js';
+export declare function pollSign(api: string, sid: string, f?: typeof fetch): Promise<SignPoll>;
+/** Poll until the browser signs (complete), the user cancels (denied), or it expires. */
+export declare function waitForSign(api: string, sid: string, intervalMs: number, timeoutMs: number, f?: typeof fetch): Promise<SignPoll>;

package/dist/lib/tx-wait.d.ts

@@ -0,0 +1,19 @@
+import type { MoneyClient } from "./money-client.js";
+import type { TxStatus } from "./types.js";
+export interface WaitResult {
+    status: TxStatus | "timeout";
+    txHash?: string;
+    receipt?: unknown;
+}
+/**
+ * After a session-key write (buy/sell), never trust "submitted". Poll the
+ * authoritative per-tx status endpoint for THIS exact txHash until it reaches
+ * success/failed or we time out. MEE/cross-chain settlement can take a while, so
+ * the timeout is generous. Ported from the standalone Perfolio CLI so the merged
+ * CLI reports honestly — never a premature "✓ done".
+ */
+export declare function waitForTx(money: MoneyClient, txHash: string | undefined, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+    initialDelayMs?: number;
+}): Promise<WaitResult>;

package/dist/lib/types.d.ts

@@ -0,0 +1,377 @@
+/**
+ * Shared types for the merged Grant Cash CLI.
+ *
+ * One identity, one credential (unified auth): `grant login` runs a single
+ * perfolio device flow and stores the perfolio-signed access JWT (`accessJwt`)
+ * plus the opaque `pfr_` refresh token. That ONE JWT is sent as
+ * `Authorization: Bearer <accessJwt>` to BOTH backends — the MONEY side
+ * (Perfolio — gold, portfolio, cash) and the AGENT side (Agent-mode — pay-per-use
+ * services). The retired `grant_live_` X-API-Key path is gone.
+ */
+/** The single perfolio credential — minted by the login handshake. */
+export interface MoneyCredentials {
+    /** perfolio-signed access JWT — the Bearer sent to BOTH backends (TTL ~15min). */
+    accessJwt?: string;
+    /** opaque `pfr_` refresh token (Redis, revocable) — re-issues the access JWT. */
+    refreshToken?: string;
+    /** access-token expiry, ms epoch */
+    expiresAt?: number;
+    email?: string;
+    walletAddress?: string;
+    /** server device id — lets logout revoke this exact device */
+    deviceId?: string;
+}
+/** The credentials file written to ~/.grant-cash/credentials.json. */
+export interface Credentials {
+    money?: MoneyCredentials;
+}
+/** Resolved backend base URLs (env-overridable — see config.ts). */
+export interface BaseUrls {
+    /** Perfolio API (money side) */
+    api: string;
+    /** Perfolio fiat microservice (money side) */
+    fiat: string;
+    /** Perfolio web app (hosts the /connect browser screen) */
+    app: string;
+    /** Agent-mode backend (agent side) */
+    agent: string;
+}
+export interface NetWorthChange {
+    amount: number;
+    percentage: number;
+}
+export type HoldingClass = "gold" | "stable" | "btc" | "eth" | "other";
+/** A single spot holding in the multi-asset view. */
+export interface MultiAssetHolding {
+    symbol: string;
+    class: HoldingClass;
+    label: string;
+    balance: number;
+    valueUsd: number;
+    allocationPct: number;
+}
+export interface PerpsCategoryRollup {
+    category: "crypto" | "stock" | "commodity" | "fx" | "index" | "other";
+    label: string;
+    valueUsd: number;
+    unrealizedPnlUsd: number;
+    positions: number;
+}
+export interface PerpsBucket {
+    equityUsd: number;
+    unrealizedPnlUsd: number;
+    marginUsedUsd: number;
+    allocationPct: number;
+    byCategory: PerpsCategoryRollup[];
+}
+/** Additive block returned only when `?view=full` is requested. */
+export interface MultiAssetView {
+    holdings: MultiAssetHolding[];
+    perps: PerpsBucket | null;
+    totalUsd: number;
+    netWorthUsd: number;
+    generatedAt: string;
+}
+/** Shape of GET /api/portfolio/summary (with optional multi-asset block). */
+export interface PortfolioSummary {
+    current: {
+        netWorthUsd: number;
+        goldValueUsd: number;
+        usdtBalance: number;
+        totalCollateralUsd: number;
+        totalDebtUsd: number;
+    };
+    changes?: {
+        "24h": NetWorthChange | null;
+        "7d": NetWorthChange | null;
+        "30d": NetWorthChange | null;
+    };
+    multiAsset?: MultiAssetView | null;
+}
+/**
+ * Backend transaction lifecycle (money side). Terminal states are `success` and
+ * `failed`; everything else is in-flight. Mirrors perfolio-backend-api TxStatus.
+ */
+export type TxStatus = "submitted" | "processing" | "executing" | "success" | "failed";
+/** What a write endpoint (/tx/swap, …) returns at submit time. */
+export interface TxResult {
+    txHash?: string;
+    status?: TxStatus;
+}
+/** Shape of GET /api/tx/status/:txHash. */
+export interface TxStatusResult {
+    txHash: string;
+    type?: string;
+    status: TxStatus;
+    receipt?: unknown;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** A standard Perfolio API envelope: { success, data?, error?, code? }. */
+export interface ApiResponse<T = unknown> {
+    success?: boolean;
+    data?: T;
+    /**
+     * Backend error field. Most endpoints send a flat string, but some (kyc /
+     * beneficiaries / fiat) nest the whole thing as `{ code, message, recoverable }`.
+     * Typed as a union so the client normalizes both shapes instead of stringifying
+     * an object into "[object Object]".
+     */
+    error?: string | {
+        code?: string;
+        message?: string;
+        recoverable?: boolean;
+    };
+    message?: string;
+    code?: string;
+    recoverable?: boolean;
+    details?: Record<string, unknown>;
+}
+export type AssetClass = "gold" | "btc" | "eth" | "stable" | "other";
+/** Asset DTO as returned by GET /api/assets. */
+export interface AssetDto {
+    symbol: string;
+    name: string;
+    decimals: number;
+    class: AssetClass;
+    chain: string;
+    logoUrl: string | null;
+    address: string;
+    explorerUrl: string | null;
+}
+/** Market DTO as returned by GET /api/markets. */
+export interface MarketDto {
+    pair: string;
+    collateral: string;
+    loan: string;
+    protocol: string;
+    chain: string;
+    lltvPercent: number;
+    safeMaxLtvPercent: number;
+    tier: "canonical" | "conservative" | "aggressive";
+    marketIdOnchain: string;
+}
+/** One earn vault. Live fields (apy/tvl/etc) are null when the Morpho API is unavailable. */
+export interface VaultDto {
+    asset: string | null;
+    assetDecimals: number | null;
+    vaultAddress: string;
+    name: string;
+    symbol: string;
+    version: string;
+    curator: string;
+    shareDecimals: number;
+    chainId: number;
+    netApy: number | null;
+    apy: number | null;
+    tvlUsd: number | null;
+    sharePrice: number | null;
+    liquidityUsd: number | null;
+    performanceFee: number | null;
+}
+/** The user's position in an asset's canonical earn vault. */
+export interface EarnPositionDto {
+    asset: string;
+    vaultAddress: string;
+    vaultName: string;
+    curator: string;
+    shares: string;
+    shareDecimals: number;
+    assets: string;
+    assetsFormatted: string;
+    assetDecimals: number;
+    netApy: number | null;
+    apy: number | null;
+    sharePrice: number | null;
+    tvlUsd: number | null;
+    liquidityUsd: number | null;
+    performanceFee: number | null;
+    principalWei: string | null;
+    principalFormatted: string | null;
+    earnedWei: string | null;
+    earnedFormatted: string | null;
+    earnedPct: number | null;
+}
+/** One outcome of a prediction market; price is the implied probability (0..1). */
+export interface PolymarketOutcome {
+    label: string;
+    price: number;
+}
+/** A market as returned by GET /api/polymarket/markets. */
+export interface PolymarketMarket {
+    id: string;
+    question: string;
+    slug: string;
+    outcomes: PolymarketOutcome[];
+    volume24h: number;
+    totalVolume: number;
+    endDate: string | null;
+}
+/** GET /api/polymarket/markets envelope payload. */
+export interface PolymarketMarketsResult {
+    markets: PolymarketMarket[];
+    count: number;
+}
+/** Full detail (GET /api/polymarket/markets/:id) — adds outcome token ids + meta. */
+export interface PolymarketMarketDetail {
+    id: string;
+    question: string;
+    slug: string;
+    description: string | null;
+    outcomes: Array<PolymarketOutcome & {
+        tokenId: string;
+    }>;
+    volume24h: number;
+    totalVolume: number;
+    liquidity: number;
+    endDate: string | null;
+    active: boolean;
+    closed: boolean;
+    category: string | null;
+}
+/** One open prediction position (GET /api/polymarket/positions). */
+export interface PolymarketPosition {
+    market: string;
+    outcome: string;
+    shares: number;
+    avgPrice: number;
+    currentPrice: number;
+    initialValue: number;
+    value: number;
+    pnl: number;
+    pnlPercent: number;
+    redeemable: boolean;
+    endDate: string | null;
+    conditionId: string | null;
+    slug: string;
+}
+/** GET /api/polymarket/positions — positions + portfolio totals. */
+export interface PolymarketPositionsResult {
+    positions: PolymarketPosition[];
+    count: number;
+    investedUsd: number;
+    valueUsd: number;
+    pnlUsd: number;
+    pnlPercent: number;
+    /**
+     * Spendable pUSD cash in the deposit wallet (deposited-but-unbet funds),
+     * read on-chain server-side — the same value the predictions screen shows.
+     * Optional: older backends don't return it, so callers fall back to a direct
+     * on-chain read of the deposit wallet.
+     */
+    cashUsd?: number;
+}
+/** One prediction trade/activity event (GET /api/polymarket/activity). */
+export interface PolymarketActivity {
+    type: string;
+    side: string | null;
+    market: string;
+    outcome: string;
+    shares: number;
+    price: number;
+    amountUsd: number;
+    timestamp: number;
+    txHash: string | null;
+    conditionId: string | null;
+    slug: string;
+}
+/** GET /api/polymarket/activity envelope payload. */
+export interface PolymarketActivityResult {
+    activity: PolymarketActivity[];
+    count: number;
+}
+/** GET /api/polymarket/trading-status — betting (write) path readiness. */
+export interface PolymarketTradingStatus {
+    enabled: boolean;
+    configured: boolean;
+    missing: string[];
+}
+/** POST /api/polymarket/bet|sell result at submit time. */
+export interface PolymarketBetResult {
+    orderId: string;
+    status: string;
+    side: "yes" | "no";
+    shares: number;
+    price: number;
+}
+/** A prepared MEE quote awaiting a user signature (from /tx/prepare, /gift/prepare-send). */
+export interface PrepareResult {
+    quoteId: string;
+    payloadToSign: string;
+    operation?: string;
+    preview?: unknown;
+}
+/** A self-describing sign task handed to the browser-sign relay. */
+export interface SignTaskInput {
+    type: string;
+    signMode: "personal" | "typed";
+    signatureFormat: "hex" | "rsv";
+    payload: unknown;
+    executePath: string;
+    executeBody: Record<string, unknown>;
+    preview?: unknown;
+}
+/** Response of POST /api/hl/setup. */
+export interface HlSetup {
+    agentAddress: string;
+    approvalAction: {
+        type: string;
+        signatureChainId: string;
+        nonce: number;
+        [k: string]: unknown;
+    };
+    approvalTypedData: unknown;
+    alreadyExists: boolean;
+    isApproved: boolean;
+    hlBalance?: string;
+    needsDeposit?: boolean;
+    minDeposit?: number;
+}
+/** Response of POST /api/cli/sign/start. */
+export interface SignStart {
+    sid: string;
+    approveUrl: string;
+    pollInterval: number;
+    expiresIn: number;
+}
+/** Poll result of the browser-sign relay. */
+export type SignPoll = {
+    status: "pending" | "denied" | "expired";
+} | {
+    status: "complete";
+    result: {
+        txHash?: string;
+        status?: TxStatus;
+    };
+};
+/** Friendly term ↔ resolved asset. */
+export interface ResolvedAsset {
+    friendly: string;
+    symbol: string;
+    decimals: number;
+    class: AssetClass;
+}
+/** Bank-transfer details for a fiat deposit account (mirrors ms-fiat-payments AccountData.bankDetails). */
+export interface BankDetails {
+    bankName?: string;
+    bankCountry?: string;
+    beneficiaryName?: string;
+    accountHolderName?: string;
+    accountNumber?: string;
+    iban?: string;
+    swift?: string;
+    swiftCode?: string;
+    bankAddress?: string;
+}
+/** A provider (Roma) account from GET /accounts. Fiat accounts carry bankDetails; crypto accounts do not. */
+export interface FiatAccount {
+    id?: string;
+    providerAccountId?: string;
+    type?: string;
+    currency: string;
+    status?: string;
+    ownerType?: string;
+    bankDetails?: BankDetails;
+    balance?: number;
+    availableBalance?: number;
+}

package/dist/lib/verify.d.ts

@@ -0,0 +1,21 @@
+import type { PerfolioClient } from './client.js';
+import type { TxStatus } from './types.js';
+export interface WaitResult {
+    status: TxStatus | 'timeout';
+    txHash?: string;
+    receipt?: unknown;
+}
+/**
+ * After a session-key write, never trust "submitted". Poll the authoritative
+ * per-tx status endpoint (which re-checks the MEE explorer for non-terminal
+ * states) for THIS exact txHash until it reaches success/failed or we time out.
+ *
+ * Correlating by txHash is essential: reading "the latest history row" can
+ * confirm a different transaction. MEE/cross-chain settlement can take a while,
+ * so the timeout is generous.
+ */
+export declare function waitForTx(client: PerfolioClient, txHash: string | undefined, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+    initialDelayMs?: number;
+}): Promise<WaitResult>;