@agentgrant.cash/cli 1.0.0

package/dist/cli/perfolio-commands/account.js

@@ -0,0 +1,272 @@
+import { buildCtx, requireAuth, out, fail, runSignFlow, resolveCash } from '../money-helpers.js';
+import { assertDecimal, describeCashResolution, baseUrls, openBrowser } from '../../lib/index.js';
+import { isKycApproved, isKycSubmitted, classifyKyc } from '../../lib/kyc-status.js';
+/** Decide whether deposit details can be shown, or what's blocking. */
+export function decideDepositGate(status, accounts) {
+    const statusStr = typeof status === 'string' ? status : 'unknown';
+    if (!isKycApproved(status))
+        return { ok: false, reason: 'KYC_REQUIRED', status: statusStr };
+    if (mapDepositAccounts(accounts).length === 0)
+        return { ok: false, reason: 'PROVISIONING', status: statusStr };
+    return { ok: true, status: statusStr };
+}
+/**
+ * A real fiat deposit target = a non-empty IBAN or account number. Crypto accounts
+ * (USDT_ETH/USDC_ETH) come back with a bankDetails object full of EMPTY strings, so a
+ * mere "object exists / has keys" check is not enough — test the actual wire target.
+ */
+export function hasDepositDetails(a) {
+    const b = a.bankDetails;
+    if (!b)
+        return false;
+    return ((b.iban ?? b.accountNumber ?? '').trim().length > 0);
+}
+/** Keep only accounts you can actually wire money to (skips crypto accounts), optionally filtered by currency. */
+export function mapDepositAccounts(accounts, currency) {
+    const want = currency?.trim().toLowerCase();
+    return accounts
+        .filter(hasDepositDetails)
+        .filter((a) => !want || a.currency.toLowerCase() === want);
+}
+/** Render a single account's bank-transfer details, tolerating both field-name variants. */
+export function formatBankDetails(a) {
+    const b = a.bankDetails ?? {};
+    const holder = b.accountHolderName ?? b.beneficiaryName;
+    const account = b.iban ?? b.accountNumber;
+    const swift = b.swiftCode ?? b.swift;
+    const lines = [
+        `  ${a.currency} account`,
+        holder ? `    Account holder : ${holder}` : '',
+        b.bankName ? `    Bank           : ${b.bankName}` : '',
+        account ? `    IBAN / Account : ${account}` : '',
+        swift ? `    SWIFT / BIC    : ${swift}` : '',
+        b.bankAddress ? `    Bank address   : ${b.bankAddress}` : '',
+    ].filter(Boolean);
+    return lines.join('\n');
+}
+/** Poll a KYC status fetcher until approved or a hard timeout. Never blocks past timeoutMs. */
+export async function gracePollKyc(getStatus, opts) {
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? Date.now;
+    const start = now();
+    let last = classifyKyc(undefined);
+    for (;;) {
+        last = classifyKyc(await getStatus());
+        if (last.approved)
+            return last;
+        if (now() - start >= opts.timeoutMs)
+            return last;
+        await sleep(opts.intervalMs);
+    }
+}
+export function registerAccount(program) {
+    const kyc = program.command('kyc').description('KYC verification');
+    kyc.command('status').action(async (_o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const data = await ctx.client.kycStatus();
+        if (ctx.json) {
+            out(ctx, '', data);
+            return;
+        }
+        const { status, approved } = classifyKyc(data);
+        const human = approved
+            ? '✓ Identity verified — you can deposit cash and cash out to your bank.'
+            : isKycSubmitted(status)
+                ? `Identity verification is under review (${status}). Check back shortly.`
+                : `Identity not verified yet (${status}). Run \`grant kyc start\` to begin.`;
+        out(ctx, human, data);
+    });
+    kyc.command('start')
+        .description('Begin identity verification (opens the KYC screen in your browser)')
+        .option('--no-open', 'do not open the browser, just print the URL')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        const creds = requireAuth(ctx);
+        const current = classifyKyc(await ctx.client.kycStatus().catch(() => null));
+        if (current.approved) {
+            out(ctx, '✓ KYC already approved. Run `grant fiat deposit` to see your bank details.', { success: true, status: current.status, approved: true });
+            return;
+        }
+        const url = `${baseUrls().app}/kyc`;
+        // Only ever hand http(s) URLs to the OS opener (PERFOLIO_APP_URL is an env knob).
+        if (!/^https?:\/\//i.test(url))
+            fail(`Refusing to open a non-http(s) URL: ${url}`, ctx.json);
+        if (opts.open === false) {
+            out(ctx, `Open this to verify your identity:\n\n  ${url}\n`, { status: current.status, kycUrl: url, approved: false });
+            return;
+        }
+        openBrowser(url);
+        // Identity binding: the browser session is whoever logs in there — tell the
+        // user which Perfolio account this CLI is bound to so they verify the right one.
+        if (!ctx.json)
+            console.log(`\nVerifying KYC for ${creds.money?.email}.\nOpening KYC in your browser:\n\n  ${url}\n\nLog in as ${creds.money?.email}, complete the steps, then we'll check status…`);
+        const r = await gracePollKyc(() => ctx.client.kycStatus(), { timeoutMs: 75_000, intervalMs: 5_000 });
+        if (r.approved) {
+            out(ctx, '✓ KYC approved. Run `grant fiat deposit` to see your bank details.', { success: true, status: r.status, approved: true });
+        }
+        else {
+            out(ctx, `Current status: ${r.status}. Verification can take a while — run \`grant kyc status\` later to check.`, { success: true, status: r.status, approved: false, kycUrl: url });
+        }
+    });
+    const fiat = program.command('fiat').description('Fiat (cash-out) info');
+    fiat.command('quote').requiredOption('--amount <cash>').requiredOption('--currency <code>')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        // --amount is the cash you want to cash out (USDT ≈ USD on the wire), entered in
+        // the user's currency by default; --currency is the destination fiat for the quote.
+        const m = await resolveCash(ctx, opts.amount, 6);
+        const data = await ctx.client.fiatQuote({ sourceAmount: m.usdString, sourceCurrencyCode: 'USDT_ETH', destinationCurrencyCode: opts.currency });
+        out(ctx, JSON.stringify(data, null, 2), data);
+    });
+    fiat.command('deposit')
+        .description('Show your bank-transfer details for depositing cash')
+        .option('--currency <code>', 'filter to a single currency (e.g. AED)')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        // Don't swallow fetch failures into a misleading "KYC not complete" message —
+        // let network/auth errors bubble to the top-level handler (like `kyc status`).
+        const status = classifyKyc(await ctx.client.kycStatus()).status;
+        const accounts = await ctx.client.getAccounts();
+        const gate = decideDepositGate(status, accounts);
+        if (!gate.ok && gate.reason === 'KYC_REQUIRED') {
+            if (ctx.json) {
+                out(ctx, '', { success: false, error: 'KYC_REQUIRED', data: { status: gate.status, next: 'kyc start' } });
+                return;
+            }
+            fail(`KYC not complete (status: ${gate.status}). Run: grant kyc start`, false);
+        }
+        if (!gate.ok && gate.reason === 'PROVISIONING') {
+            out(ctx, 'Your account is approved — bank details are being provisioned. Check back in a few minutes.', { success: true, kycApproved: true, accounts: [] });
+            return;
+        }
+        const list = mapDepositAccounts(accounts, opts.currency);
+        if (list.length === 0) {
+            out(ctx, `No bank account found${opts.currency ? ` for ${opts.currency}` : ''}.`, { success: true, kycApproved: true, accounts: [] });
+            return;
+        }
+        const human = [
+            'Wire funds to your Perfolio account using the details below.',
+            'Reference any incoming transfer with your registered name.\n',
+            ...list.map(formatBankDetails),
+        ].join('\n');
+        out(ctx, human, { success: true, kycApproved: true, accounts: list });
+    });
+    program.command('beneficiaries').description('List payout bank accounts')
+        .action(async (_o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const data = await ctx.client.beneficiaries();
+        out(ctx, JSON.stringify(data, null, 2), data);
+    });
+    const settings = program.command('settings').description('Account preferences');
+    settings.command('set')
+        .option('--currency <code>', 'local currency code (e.g. USD, INR, AED, EUR)')
+        .option('--country <code>')
+        .option('--display <usd|local>', 'show amounts in USD or your local currency')
+        .option('--gold-unit <oz|g>')
+        .option('--mode <simple|advanced>', 'experience mode: simple (plain language) or advanced (crypto-native)')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        // Validate enum-ish flags locally so a typo fails fast with a clear message
+        // (the backend also validates, but a 400 round-trip is a worse UX).
+        if (opts.display && !['usd', 'local'].includes(String(opts.display).toLowerCase())) {
+            fail('Invalid --display. Use "usd" or "local".', ctx.json);
+        }
+        if (opts.goldUnit && !['oz', 'g'].includes(String(opts.goldUnit).toLowerCase())) {
+            fail('Invalid --gold-unit. Use "oz" or "g".', ctx.json);
+        }
+        if (opts.mode && !['simple', 'advanced'].includes(String(opts.mode).toLowerCase())) {
+            fail('Invalid --mode. Use "simple" or "advanced".', ctx.json);
+        }
+        const body = {};
+        if (opts.currency)
+            body.currency = String(opts.currency).toUpperCase();
+        if (opts.country)
+            body.country = String(opts.country).toUpperCase();
+        if (opts.display)
+            body.displayCurrency = String(opts.display).toLowerCase() === 'local' ? 'local' : 'USD';
+        if (opts.goldUnit)
+            body.goldDisplayUnit = String(opts.goldUnit).toLowerCase();
+        if (opts.mode)
+            body.experienceMode = String(opts.mode).toLowerCase();
+        if (Object.keys(body).length === 0) {
+            fail('Nothing to update. Pass at least one of --currency --country --display --gold-unit --mode.', ctx.json);
+        }
+        const data = await ctx.client.updateSettings(body);
+        out(ctx, 'Settings updated.', data);
+    });
+    program.command('gifts').description('Gifts sent and received')
+        .action(async (_o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const [sent, received] = await Promise.all([ctx.client.giftsSent(), ctx.client.giftsReceived()]);
+        out(ctx, JSON.stringify({ sent, received }, null, 2), { sent, received });
+    });
+    // ── user-signed: withdraw cash to an external wallet (browser approval) ──
+    program.command('withdraw').description('Withdraw cash to an external wallet address (opens the browser to approve)')
+        .requiredOption('--to <address>', 'destination wallet address (0x…)')
+        .requiredOption('--amount <cash>', 'amount of cash to withdraw')
+        .option('--token <symbol>', 'token to withdraw', 'USDT')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        if (!/^0x[a-fA-F0-9]{40}$/.test(opts.to))
+            fail('Invalid destination address. Expected a 0x… wallet address.', ctx.json);
+        const assets = await ctx.client.getAssets();
+        const sym = String(opts.token).toUpperCase();
+        const tok = assets.find((a) => a.symbol === sym);
+        if (!tok)
+            fail(`Unknown token "${opts.token}".`, ctx.json);
+        // Cash withdrawals (USDT/USDC) are fiat — interpret in the user's currency and
+        // convert to USD. Withdrawing a non-stable token treats the amount as a quantity.
+        let amount;
+        let label;
+        if (tok.class === 'stable') {
+            const m = await resolveCash(ctx, opts.amount, tok.decimals);
+            amount = m.usdString;
+            label = `Withdraw ${describeCashResolution(m)} (${sym}) to ${opts.to}`;
+        }
+        else {
+            amount = assertDecimal(opts.amount, tok.decimals);
+            label = `Withdraw ${amount} ${sym} to ${opts.to}`;
+        }
+        const prepared = await ctx.client.prepareWithdrawal({ token: tok.address, recipient: opts.to, amount });
+        await runSignFlow(ctx, {
+            label,
+            task: {
+                type: 'withdrawal', signMode: 'personal', signatureFormat: 'hex',
+                payload: prepared.payloadToSign, executePath: '/tx/execute',
+                executeBody: { quoteId: prepared.quoteId }, preview: prepared.preview,
+            },
+        });
+    });
+    // ── user-signed: send a gold gift (browser approval) ──
+    const gift = program.command('gift').description('Send a gold gift');
+    gift.command('send').description('Send gold to someone by email or phone (opens the browser to approve)')
+        .requiredOption('--to <email|phone>', 'recipient email or phone number')
+        .requiredOption('--amount <gold>', 'amount of gold to send')
+        .option('--message <text>', 'optional message')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const isEmail = opts.to.includes('@');
+        const amountXaut = assertDecimal(opts.amount, 6); // XAUT has 6 decimals
+        const prepared = await ctx.client.prepareGiftSend({
+            ...(isEmail ? { recipientEmail: opts.to } : { recipientPhone: opts.to }),
+            amountXaut,
+            message: opts.message,
+        });
+        await runSignFlow(ctx, {
+            label: `Gift ${opts.amount} gold to ${opts.to}`,
+            task: {
+                type: 'gift', signMode: 'personal', signatureFormat: 'hex',
+                payload: prepared.payloadToSign, executePath: '/gift/execute-send',
+                executeBody: { quoteId: prepared.quoteId }, preview: prepared.preview,
+            },
+        });
+    });
+}

package/dist/cli/perfolio-commands/borrow.js

@@ -0,0 +1,75 @@
+import { buildCtx, requireAuth, resolver, reportTx, resolveCash } from '../money-helpers.js';
+import { assertDecimal, describeCashResolution } from '../../lib/index.js';
+const CASH = 'USDT';
+const CASH_DECIMALS = 6;
+export function registerBorrow(program) {
+    // Run a write then report its on-chain outcome (wait-by-default via reportTx).
+    const exec = async (ctx, fn, wait, label) => {
+        const res = (await fn());
+        await reportTx(ctx, res, wait, label);
+    };
+    program.command('borrow').description('Borrow cash against an asset')
+        .requiredOption('--against <asset>').requiredOption('--amount <cash>')
+        .option('--no-wait', 'return immediately without waiting for confirmation')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const r = await resolver(ctx);
+        const collateral = r.resolve(opts.against).symbol;
+        const m = await resolveCash(ctx, opts.amount, CASH_DECIMALS);
+        await exec(ctx, () => ctx.client.borrow({ collateral, loan: CASH, amount: m.usdString }), opts.wait !== false, `Borrow ${describeCashResolution(m)} against ${opts.against}`);
+    });
+    program.command('repay').description('Repay borrowed cash')
+        .requiredOption('--against <asset>').requiredOption('--amount <cash>')
+        .option('--no-wait', 'return immediately without waiting for confirmation')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const r = await resolver(ctx);
+        const collateral = r.resolve(opts.against).symbol;
+        const m = await resolveCash(ctx, opts.amount, CASH_DECIMALS);
+        await exec(ctx, () => ctx.client.repay({ collateral, loan: CASH, amount: m.usdString }), opts.wait !== false, `Repay ${describeCashResolution(m)} against ${opts.against}`);
+    });
+    program.command('add-collateral').description('Add collateral')
+        .requiredOption('--asset <asset>').requiredOption('--amount <n>')
+        .option('--no-wait', 'return immediately without waiting for confirmation')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const r = await resolver(ctx);
+        const a = r.resolve(opts.asset);
+        await exec(ctx, () => ctx.client.supply({ collateral: a.symbol, amount: assertDecimal(opts.amount, a.decimals) }), opts.wait !== false, `Add ${opts.asset} collateral`);
+    });
+    program.command('remove-collateral').description('Remove collateral')
+        .requiredOption('--asset <asset>').requiredOption('--amount <n>')
+        .option('--no-wait', 'return immediately without waiting for confirmation')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const r = await resolver(ctx);
+        const a = r.resolve(opts.asset);
+        await exec(ctx, () => ctx.client.withdrawCollateral({ collateral: a.symbol, amount: assertDecimal(opts.amount, a.decimals) }), opts.wait !== false, `Remove ${opts.asset} collateral`);
+    });
+    program.command('leverage').description('Add collateral and borrow cash in one step')
+        .requiredOption('--asset <asset>').requiredOption('--deposit <n>').requiredOption('--borrow <cash>')
+        .option('--no-wait', 'return immediately without waiting for confirmation')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const r = await resolver(ctx);
+        const a = r.resolve(opts.asset);
+        // --deposit is a quantity of the collateral asset; --borrow is cash (currency-aware).
+        const borrow = await resolveCash(ctx, opts.borrow, CASH_DECIMALS);
+        await exec(ctx, () => ctx.client.supplyAndBorrow({ collateral: a.symbol, loan: CASH, collateralAmount: assertDecimal(opts.deposit, a.decimals), borrowAmount: borrow.usdString }), opts.wait !== false, `Leverage ${opts.asset} (borrow ${describeCashResolution(borrow)})`);
+    });
+    program.command('close').description('Close a loan (repay all + withdraw collateral)')
+        .requiredOption('--against <asset>')
+        .option('--no-wait', 'return immediately without waiting for confirmation')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const r = await resolver(ctx);
+        const collateral = r.resolve(opts.against).symbol;
+        await exec(ctx, () => ctx.client.closePosition({ collateral, loan: CASH }), opts.wait !== false, `Close ${opts.against} loan`);
+    });
+}

package/dist/cli/perfolio-commands/discover.js

@@ -0,0 +1,30 @@
+import { buildCtx, resolver, out } from '../money-helpers.js';
+import { FRIENDLY_TERMS } from '../../lib/index.js';
+export function registerDiscover(program) {
+    program.command('assets').description('List assets you can hold (gold, cash, bitcoin, ethereum)')
+        .action(async (_o, cmd) => {
+        const ctx = buildCtx(cmd);
+        const r = await resolver(ctx);
+        const resolved = [];
+        const lines = [];
+        for (const t of FRIENDLY_TERMS) {
+            try {
+                const a = r.resolve(t);
+                resolved.push(a);
+                lines.push(`• ${t} (${a.symbol})`);
+            }
+            catch { /* not in registry yet */ }
+        }
+        out(ctx, lines.join('\n') || 'No assets available.', resolved);
+    });
+    program.command('markets').description('Where you can borrow cash against your assets')
+        .action(async (_o, cmd) => {
+        const ctx = buildCtx(cmd);
+        const [markets, r] = await Promise.all([ctx.client.getMarkets(), resolver(ctx)]);
+        // v1 surfaces only canonical assets — hide variant collaterals (cbBTC, wstETH)
+        // whose raw symbols have no friendly word yet.
+        const shown = markets.filter((m) => r.isFriendly(m.collateral));
+        const human = shown.map((m) => `• Borrow cash against ${r.label(m.collateral)} — up to ${m.safeMaxLtvPercent}% LTV (max ${m.lltvPercent}%)`).join('\n');
+        out(ctx, human || 'No markets available.', shown);
+    });
+}

package/dist/cli/perfolio-commands/earn.js

@@ -0,0 +1,193 @@
+import { buildCtx, requireAuth, reportTx, out, fail, resolveCash } from '../money-helpers.js';
+import { assertDecimal, describeCashResolution, } from '../../lib/index.js';
+/**
+ * Whether an earn asset is a stablecoin (cash). Stable amounts are MONEY — entered
+ * in the user's currency and FX-resolved to USD (so "100" = ₹100 for an INR user,
+ * consistent with buy/borrow). Non-stable assets (WETH) keep asset-QUANTITY input
+ * (0.5 WETH = 0.5 WETH), like selling an asset by quantity. Exported for testing.
+ */
+export function isStableEarnAsset(symbol) {
+    return symbol.toUpperCase() === 'USDT' || symbol.toUpperCase() === 'USDC';
+}
+/**
+ * Earn — deposit cash/crypto into Morpho Vault V2 to earn yield, and withdraw.
+ *
+ * Runs on the same DeFi session grant as borrow/swap (rev-19 folded the vault
+ * actions in), so it needs no separate session install — if the grant is stale
+ * or missing the user is told to reconnect, exactly like borrow.
+ *
+ * Asset accepts friendly words (cash → USDT, ethereum → WETH) AND raw symbols
+ * (USDT / USDC / WETH) — the friendly resolver only knows the canonical-per-class
+ * symbol, so earn (which has two stablecoin vaults) resolves symbols directly.
+ */
+const FRIENDLY_TO_SYMBOL = {
+    cash: 'USDT',
+    usdt: 'USDT',
+    usdc: 'USDC',
+    ethereum: 'WETH',
+    eth: 'WETH',
+    weth: 'WETH',
+};
+async function resolveEarnAsset(ctx, input) {
+    const assets = (await ctx.client.getAssets());
+    const wanted = (FRIENDLY_TO_SYMBOL[input.trim().toLowerCase()] ?? input.trim()).toUpperCase();
+    const match = assets.find((a) => a.symbol.toUpperCase() === wanted);
+    if (!match) {
+        fail(`I don't recognize "${input}" for earn. Try: cash (USDT), USDC, or ethereum (WETH).`, ctx.json);
+    }
+    return { symbol: match.symbol, decimals: match.decimals };
+}
+function pct(n) {
+    return n == null ? '—' : `${(n * 100).toFixed(2)}%`;
+}
+function usd(n) {
+    return n == null ? '—' : `$${n.toLocaleString('en-US', { maximumFractionDigits: 0 })}`;
+}
+/** Already-percent number (e.g. earnedPct 1.2) → "1.20%". */
+function pctRaw(n) {
+    return n == null ? '—' : `${n.toFixed(2)}%`;
+}
+export function registerEarn(program) {
+    const earn = program.command('earn').description('Earn yield on cash & crypto via Morpho vaults');
+    earn
+        .command('list')
+        .description('List earn vaults with current APY and size')
+        .option('--asset <asset>', 'filter to one asset (cash, USDC, ethereum)')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        const assetArg = opts.asset
+            ? (await resolveEarnAsset(ctx, opts.asset)).symbol
+            : undefined;
+        const { vaults } = await ctx.client.getVaults(assetArg);
+        if (ctx.json) {
+            out(ctx, '', { vaults });
+            return;
+        }
+        if (!vaults.length) {
+            out(ctx, 'No earn vaults available.', { vaults });
+            return;
+        }
+        const lines = vaults.map((v) => {
+            const feeStr = v.performanceFee != null ? `${(v.performanceFee * 100).toFixed(0)}%` : '—';
+            return (`• ${v.asset ?? v.symbol} — ${v.name}  ·  curated by ${v.curator}\n` +
+                `    Net APY:    ${pct(v.netApy)}${v.apy != null && v.apy !== v.netApy ? `  (gross ${pct(v.apy)})` : ''}\n` +
+                `    Vault size: ${usd(v.tvlUsd)}   ·   Available now: ${usd(v.liquidityUsd)}\n` +
+                `    Perf. fee:  ${feeStr}   ·   Share price: ${v.sharePrice != null ? v.sharePrice.toFixed(4) : '—'}`);
+        });
+        out(ctx, `Earn vaults — deposit to earn yield (APY is variable):\n\n${lines.join('\n\n')}\n\n` +
+            `Deposit with:  grant earn deposit --asset <cash|usdc|ethereum> --amount <n>`, { vaults });
+    });
+    earn
+        .command('position')
+        .description('Your earn position for an asset — current value, principal, and earnings')
+        .requiredOption('--asset <asset>', 'cash, USDC, or ethereum')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const a = await resolveEarnAsset(ctx, opts.asset);
+        const p = (await ctx.client.getEarnPosition(a.symbol));
+        // JSON: emit the full payload (exact strings — assetsFormatted, earnedFormatted, raw wei).
+        if (ctx.json) {
+            out(ctx, '', p);
+            return;
+        }
+        // Human: a fuller card (mirrors the borrow position detail) — value +
+        // earnings to full precision (formatUnits is exact; a 0.000001 gain shows,
+        // never rounded), plus live vault context (APY, size, liquidity, fee).
+        const lines = [
+            `${a.symbol} earn position`,
+            `  Vault:      ${p.vaultName}  ·  curated by ${p.curator}`,
+            `  Value:      ${p.assetsFormatted} ${a.symbol}`,
+        ];
+        if (p.earnedFormatted != null && p.principalFormatted != null) {
+            lines.push(`  Deposited:  ${p.principalFormatted} ${a.symbol}`);
+            lines.push(`  Earned:     +${p.earnedFormatted} ${a.symbol}${p.earnedPct != null ? `  (+${pctRaw(p.earnedPct)})` : ''}`);
+        }
+        else {
+            lines.push('  Earned:     — (no Perfolio deposit on record to compare against)');
+        }
+        lines.push(`  Net APY:    ${pct(p.netApy)}${p.apy != null && p.apy !== p.netApy ? `  (gross ${pct(p.apy)})` : ''}`);
+        lines.push(`  Shares:     ${p.shares} (${p.shareDecimals} dec)`);
+        if (p.sharePrice != null)
+            lines.push(`  Share price: ${p.sharePrice.toFixed(6)} ${a.symbol}/share`);
+        lines.push(`  Vault size: ${usd(p.tvlUsd)}   ·   Available now: ${usd(p.liquidityUsd)}` +
+            (p.performanceFee != null ? `   ·   Perf. fee: ${(p.performanceFee * 100).toFixed(0)}%` : ''));
+        out(ctx, lines.join('\n'), p);
+    });
+    // `deposit` IS the "create / add to a position" command — a single call.
+    // (`earn position` is just a read to view it later, not a required second step.)
+    earn
+        .command('deposit')
+        .alias('open')
+        .description('Create or add to an earn position (deposit an asset into its vault)')
+        .requiredOption('--asset <asset>', 'cash, USDC, or ethereum')
+        .requiredOption('--amount <n>', 'cash to stake (your currency) for cash/USDC; a WETH quantity for ethereum')
+        .option('--no-wait', 'return immediately without waiting for confirmation')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const a = await resolveEarnAsset(ctx, opts.asset);
+        // Stable (cash/USDC) deposits are MONEY → interpret in the user's currency and
+        // convert to USD. Ethereum (WETH) is an asset QUANTITY → pass through.
+        let amount;
+        let label;
+        if (isStableEarnAsset(a.symbol)) {
+            const m = await resolveCash(ctx, opts.amount, a.decimals);
+            amount = m.usdString;
+            label = `Deposit ${describeCashResolution(m)} into earn`;
+        }
+        else {
+            amount = assertDecimal(opts.amount, a.decimals);
+            label = `Deposit ${amount} ${a.symbol} into earn`;
+        }
+        const res = await ctx.client.earnDeposit({ asset: a.symbol, amount });
+        await reportTx(ctx, res, opts.wait !== false, label);
+        // One command = create + show the resulting position. Only when we waited
+        // for confirmation (human mode); --json callers read the tx result + can
+        // call `earn position` themselves. Best-effort — never fail the deposit.
+        if (opts.wait !== false && !ctx.json) {
+            try {
+                const p = (await ctx.client.getEarnPosition(a.symbol));
+                const earnedTail = p.earnedFormatted != null ? `, earned so far +${p.earnedFormatted} ${a.symbol}` : '';
+                console.log(`Your ${a.symbol} earn position is now ${p.assetsFormatted} ${a.symbol} in ${p.vaultName} ` +
+                    `(APY ${pct(p.netApy)}${earnedTail}).`);
+            }
+            catch {
+                /* position read is a courtesy — the deposit already reported its outcome */
+            }
+        }
+    });
+    earn
+        .command('withdraw')
+        .description('Withdraw from an earn vault')
+        .requiredOption('--asset <asset>', 'cash, USDC, or ethereum')
+        .option('--amount <n>', 'cash to withdraw (your currency) for cash/USDC; a WETH quantity for ethereum (omit + use --all for a full exit)')
+        .option('--all', 'withdraw the entire position')
+        .option('--no-wait', 'return immediately without waiting for confirmation')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const a = await resolveEarnAsset(ctx, opts.asset);
+        if (!opts.all && !opts.amount) {
+            fail('Provide --amount <n> or --all.', ctx.json);
+        }
+        let body;
+        let label;
+        if (opts.all) {
+            body = { asset: a.symbol, all: true };
+            label = `Withdraw all ${a.symbol} from earn`;
+        }
+        else if (isStableEarnAsset(a.symbol)) {
+            const m = await resolveCash(ctx, opts.amount, a.decimals);
+            body = { asset: a.symbol, amount: m.usdString };
+            label = `Withdraw ${describeCashResolution(m)} from earn`;
+        }
+        else {
+            const amount = assertDecimal(opts.amount, a.decimals);
+            body = { asset: a.symbol, amount };
+            label = `Withdraw ${amount} ${a.symbol} from earn`;
+        }
+        const res = await ctx.client.earnWithdraw(body);
+        await reportTx(ctx, res, opts.wait !== false, label);
+    });
+}