@agentgrant.cash/cli 1.1.0 → 1.3.0

package/dist/cli/commands/portfolio.js

@@ -141,7 +141,7 @@ async function gatherExtras(ctx) {
 }
 async function gather(cmd) {
     const ctx = buildContext(cmd);
-    const [prefsR, moneyR, extrasR, agentR] = await Promise.allSettled([
+    const [prefsR, moneyR, extrasR, agentR, creditR] = await Promise.allSettled([
         ctx.money.connected ? loadDisplayPrefs(ctx) : Promise.resolve(DEFAULT_PREFS),
         ctx.money.connected
             ? ctx.money.getPortfolio("full")
@@ -150,6 +150,9 @@ async function gather(cmd) {
         ctx.agent.connected
             ? ctx.agent.balance()
             : Promise.resolve(null),
+        ctx.agent.connected
+            ? ctx.agent.credit()
+            : Promise.resolve(null),
     ]);
     return {
         ctx,
@@ -159,6 +162,7 @@ async function gather(cmd) {
         moneyFailed: moneyR.status === "rejected",
         agent: agentR.status === "fulfilled" ? agentR.value : null,
         agentFailed: agentR.status === "rejected",
+        credit: creditR.status === "fulfilled" ? creditR.value : null,
     };
 }
 /** Indent every line of a block by two spaces. */
@@ -171,7 +175,7 @@ function indent(block) {
 export function registerPortfolio(program) {
     const run = async (cmd) => {
         const g = await gather(cmd);
-        const { ctx, prefs, money, extras, moneyFailed, agent, agentFailed } = g;
+        const { ctx, prefs, money, extras, moneyFailed, agent, agentFailed, credit } = g;
         emit(ctx, {
             investments: money
                 ? {
@@ -186,6 +190,8 @@ export function registerPortfolio(program) {
                 }
                 : null,
             spending: agent,
+            // The free-credit / wallet split (parity with the app's Spending screen).
+            credit,
         }, () => {
             if (!ctx.money.connected && !ctx.agent.connected)
                 return "Not connected yet. Run `grant login`.";
@@ -208,7 +214,7 @@ export function registerPortfolio(program) {
                 lines.push(ui.dim("  Not connected."));
             }
             else if (agent) {
-                lines.push(formatAgentFunds(agent));
+                lines.push(formatAgentFunds(agent, credit));
             }
             else {
                 lines.push(ui.amber(`  ${agentFailed ? "Temporarily unavailable." : "—"}`));

package/dist/cli/money-helpers.js

@@ -121,15 +121,38 @@ export async function loadDisplayPrefs(ctx) {
         return DEFAULT_PREFS;
     }
 }
+/**
+ * Build the money-side SUCCESS envelope. The whole CLI — money and agent sides —
+ * speaks one contract: `{ ok: true, ...data }`. A plain object is spread in; an
+ * array / primitive is nested under `data` (spreading an array would splay its
+ * indices as keys). A redundant top-level `success` marker is dropped so `ok` is
+ * the single source of truth (closes the "trade cmds use {success:true}" gap).
+ * Pure + exported for unit testing.
+ */
+export function buildOutPayload(data) {
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+        const { success: _drop, ...rest } = data;
+        void _drop;
+        return { ok: true, ...rest };
+    }
+    return { ok: true, data };
+}
+/** Build the money-side FAILURE envelope: `{ ok:false, error:{code,message,recoverable} }`. */
+export function buildErrorPayload(msg, opts) {
+    return {
+        ok: false,
+        error: { code: opts?.code ?? "ERROR", message: msg, recoverable: opts?.recoverable ?? false },
+    };
+}
 export function out(ctx, human, data) {
     if (ctx.json)
-        console.log(JSON.stringify(data, null, 2));
+        console.log(JSON.stringify(buildOutPayload(data), null, 2));
     else
         console.log(human);
 }
-export function fail(msg, json) {
+export function fail(msg, json, opts) {
     if (json)
-        console.error(JSON.stringify({ success: false, error: msg }));
+        console.error(JSON.stringify(buildErrorPayload(msg, opts)));
     else
         console.error(pc.red(`✖ ${msg}`));
     process.exit(1);

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

@@ -10,24 +10,26 @@ export function registerBorrow(program) {
     };
     program.command('borrow').description('Borrow cash against an asset')
         .requiredOption('--against <asset>').requiredOption('--amount <cash>')
+        .option('--usd', 'interpret --amount as US dollars, ignoring your display currency')
         .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);
+        const m = await resolveCash(ctx, opts.amount, CASH_DECIMALS, { usd: !!opts.usd });
         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('--usd', 'interpret --amount as US dollars, ignoring your display currency')
         .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);
+        const m = await resolveCash(ctx, opts.amount, CASH_DECIMALS, { usd: !!opts.usd });
         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')
@@ -52,6 +54,7 @@ export function registerBorrow(program) {
     });
     program.command('leverage').description('Add collateral and borrow cash in one step')
         .requiredOption('--asset <asset>').requiredOption('--deposit <n>').requiredOption('--borrow <cash>')
+        .option('--usd', 'interpret --borrow as US dollars, ignoring your display currency')
         .option('--no-wait', 'return immediately without waiting for confirmation')
         .action(async (opts, cmd) => {
         const ctx = buildCtx(cmd);
@@ -59,7 +62,7 @@ export function registerBorrow(program) {
         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);
+        const borrow = await resolveCash(ctx, opts.borrow, CASH_DECIMALS, { usd: !!opts.usd });
         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)')

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

@@ -4,10 +4,20 @@ import { describeCashResolution, formatMoney, displayDescriptor, fetchPusdBalanc
 const PREDICTION_DECIMALS = 6;
 /** Friendly message shown when the betting path isn't enabled yet (503). */
 const BETTING_DISABLED_MSG = 'Prediction betting isn\'t available yet — market browsing is read-only for now.';
-/** True if an error is the backend "trading not configured" 503. Exported for unit testing. */
+/**
+ * True if an error means the betting path is unavailable, so BOTH `--side yes`
+ * and `--side no` surface the same friendly line. The configured-off state comes
+ * back as 503 / POLYMARKET_TRADING_NOT_CONFIGURED, but the disabled `no` path was
+ * observed returning a bare upstream 502 (and 504 is the same class of gateway
+ * outage) — treat those as unavailable too rather than leaking a raw "HTTP 502".
+ * Exported for unit testing.
+ */
 export function isTradingDisabled(err) {
     const e = err;
-    return e?.status === 503 || e?.code === 'POLYMARKET_TRADING_NOT_CONFIGURED';
+    return (e?.status === 502 ||
+        e?.status === 503 ||
+        e?.status === 504 ||
+        e?.code === 'POLYMARKET_TRADING_NOT_CONFIGURED');
 }
 /** Render a market list into human-readable lines. Exported for unit testing. */
 export function formatMarkets(markets, count) {

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

@@ -1,4 +1,4 @@
-import { buildCtx, requireAuth, resolver, reportTx, resolveCash, resolveCashTargetQty, out, fail } from '../money-helpers.js';
+import { buildCtx, requireAuth, resolver, reportTx, resolveCash, resolveCashTargetQty, forceUsdAmount, out, fail } from '../money-helpers.js';
 import { assertDecimal, describeCashResolution } from '../../lib/index.js';
 /**
  * Resolve the sell-side `sellAmount` (always in `from`-token units) for a trade.
@@ -17,12 +17,13 @@ async function resolveSellSide(ctx, from, spec) {
             fail('Use --amount for cash; --for is for selling an asset by cash value.', ctx.json);
         if (!spec.amount)
             fail('Missing --amount (cash to spend).', ctx.json);
-        const m = await resolveCash(ctx, spec.amount, from.decimals);
+        const m = await resolveCash(ctx, spec.amount, from.decimals, { usd: spec.usd });
         return { sellAmount: m.usdString, note: describeCashResolution(m) };
     }
     // Asset source, cash target → size the quantity from the live price.
     if (spec.forCash) {
-        const r = await resolveCashTargetQty(ctx, from, spec.forCash);
+        // `--usd` forces the cash target to dollars (prefix "$") before sizing.
+        const r = await resolveCashTargetQty(ctx, from, spec.usd ? forceUsdAmount(spec.forCash) : spec.forCash);
         return {
             sellAmount: r.quantity,
             note: `${describeCashResolution(r)} of ${from.friendly} (≈ ${r.quantity} ${from.friendly})`,
@@ -40,13 +41,14 @@ function oneOfAmountOrFor(ctx, opts) {
         fail('Pass either --amount (a quantity) or --for (a cash value), not both.', ctx.json);
     if (!opts.amount && !opts.for)
         fail('Specify --amount <quantity> or --for <cash value>.', ctx.json);
-    return { amount: opts.amount, forCash: opts.for };
+    return { amount: opts.amount, forCash: opts.for, usd: opts.usd };
 }
 export function registerTrade(program) {
     program.command('quote').description('Preview a trade (no execution)')
         .requiredOption('--from <asset>').requiredOption('--to <asset>')
         .option('--amount <n>', 'quantity of the "from" asset')
         .option('--for <cash>', 'cash value to sell (e.g. 100, "$50", "₹100")')
+        .option('--usd', 'interpret a cash --for value as US dollars, ignoring your display currency')
         .action(async (opts, cmd) => {
         const ctx = buildCtx(cmd);
         requireAuth(ctx);
@@ -72,23 +74,32 @@ export function registerTrade(program) {
     };
     program.command('buy <asset>').description('Buy an asset with cash')
         .requiredOption('--amount <cash>', 'amount of cash to spend (your currency; prefix $/₹ to force one)')
+        .option('--usd', 'interpret --amount as US dollars, ignoring your display currency')
         .option('--no-wait', 'return immediately without waiting for on-chain confirmation')
-        .action((asset, opts, cmd) => trade(cmd, 'cash', asset, { amount: opts.amount }, opts.wait !== false));
+        .action((asset, opts, cmd) => trade(cmd, 'cash', asset, { amount: opts.amount, usd: opts.usd }, opts.wait !== false));
     program.command('sell <asset>').description('Sell an asset — by quantity (--amount) or by cash value (--for)')
         .option('--amount <n>', 'quantity of the asset to sell (e.g. 0.1 bitcoin)')
         .option('--for <cash>', 'cash value to sell instead (e.g. 100, "$50", "₹100")')
+        .option('--usd', 'interpret a cash --for value as US dollars, ignoring your display currency')
         .option('--no-wait', 'return immediately without waiting for on-chain confirmation')
         .action((asset, opts, cmd) => {
         const ctx = buildCtx(cmd);
-        trade(cmd, asset, 'cash', oneOfAmountOrFor(ctx, opts), opts.wait !== false);
+        // MUST return the promise: commander's parseAsync(...).catch() only routes a
+        // rejection through the friendly {ok:false} envelope if the action returns it.
+        // Dropping it (a brace body without `return`) orphans the rejection → raw
+        // Node stack trace (the reported `convert`/`sell` crash on PAIR_NOT_SUPPORTED).
+        return trade(cmd, asset, 'cash', oneOfAmountOrFor(ctx, opts), opts.wait !== false);
     });
     program.command('convert').description('Convert one asset into another — by quantity (--amount) or cash value (--for)')
         .requiredOption('--from <asset>').requiredOption('--to <asset>')
         .option('--amount <n>', 'quantity of the "from" asset')
         .option('--for <cash>', 'cash value of "from" to convert (e.g. 100, "$50", "₹100")')
+        .option('--usd', 'interpret a cash --for value as US dollars, ignoring your display currency')
         .option('--no-wait', 'return immediately without waiting for on-chain confirmation')
         .action((opts, cmd) => {
         const ctx = buildCtx(cmd);
-        trade(cmd, opts.from, opts.to, oneOfAmountOrFor(ctx, opts), opts.wait !== false);
+        // Return the promise (see `sell` above) — without it a rejected convert
+        // (e.g. PAIR_NOT_SUPPORTED) escapes as an unhandled rejection / raw stack.
+        return trade(cmd, opts.from, opts.to, oneOfAmountOrFor(ctx, opts), opts.wait !== false);
     });
 }

package/dist/lib/agent-client.js

@@ -8,6 +8,16 @@ import { AppError } from "./errors.js";
  * a driving agent knows whether to retry (see SKILL.md error playbook).
  */
 const REQUEST_TIMEOUT_MS = 60_000;
+/**
+ * 4xx codes that are nonetheless safe to retry, per the SKILL error playbook.
+ * Without this, recoverability was inferred purely from `status >= 500`, so a
+ * free-reject like SCHEMA_VALIDATION_FAILED (422) was wrongly tagged
+ * `recoverable:false` even though the fix is "correct the body and retry".
+ */
+const RECOVERABLE_CODES = new Set([
+    "SCHEMA_VALIDATION_FAILED", // free reject — fix the body, retry
+    "X402_FACILITATOR_TIMEOUT", // transient settlement timeout — retry
+]);
 export class AgentClient {
     base;
     apiKey;
@@ -56,10 +66,14 @@ export class AgentClient {
             throw new AppError(`No Grant Cash agent API at ${this.base} (HTTP ${res.status}) — check GRANTCASH_AGENT_URL.`, { status: res.status, code: "BACKEND_UNREACHABLE", recoverable: false });
         }
         if (!res.ok || json?.error?.code) {
+            const code = json?.error?.code ?? `HTTP_${res.status}`;
+            // Honor an explicit backend `recoverable` if present; otherwise infer it —
+            // 5xx (transient) OR a known-recoverable 4xx code (e.g. a free reject).
+            const recoverable = json?.error?.recoverable ?? (res.status >= 500 || RECOVERABLE_CODES.has(code));
             throw new AppError(json?.error?.message ?? `Request failed (${res.status})`, {
                 status: res.status,
-                code: json?.error?.code ?? `HTTP_${res.status}`,
-                recoverable: res.status >= 500,
+                code,
+                recoverable,
             });
         }
         return json;
@@ -74,6 +88,15 @@ export class AgentClient {
     balance() {
         return this.request("GET", "/balance", { auth: true });
     }
+    /**
+     * The chain-agnostic spendable split — sign-up free credit + funds you added +
+     * total. Hits `GET /credit` (dual-auth, so the api-key works). This is the same
+     * figure the app shows on the Spending screen; `balance()` (/balance) carries
+     * the session status, so the portfolio uses both.
+     */
+    credit() {
+        return this.request("GET", "/credit", { auth: true });
+    }
     /**
      * Find a payable endpoint in the curated catalog. Hits `GET /marketplace/x402`
      * (the grouped, public catalog route) — NOT `/marketplace`, which does not

package/dist/lib/client.js

@@ -70,13 +70,23 @@ export class PerfolioClient {
         if (res.status === 428)
             throw new NoSessionError();
         if (!res.ok || json.success === false) {
-            const err = new Error(json.error || json.message || `HTTP ${res.status}`);
+            // The `error` field comes in two shapes across backends: a flat string, or a
+            // nested `{ code, message, recoverable }` object (kyc / beneficiaries / fiat).
+            // Normalize BOTH — never let an object reach `new Error()`, which would
+            // stringify it to the useless "[object Object]" the report flagged.
+            const rawErr = json.error;
+            const nested = rawErr && typeof rawErr === "object"
+                ? rawErr
+                : undefined;
+            const errString = typeof rawErr === "string" ? rawErr : undefined;
+            const message = nested?.message || errString || json.message || `HTTP ${res.status}`;
+            const err = new Error(message);
             err.status = res.status;
-            // Prefer the backend's machine code (e.g. 'MIN_ORDER_NOT_MET'); fall back to
-            // the legacy convention where the `error` field carried a code-like string
-            // (e.g. 'GRANT_REQUIRED', 'REGISTRY_UNAVAILABLE') for endpoints not yet on
-            // the structured contract.
-            err.code = json.code ?? json.error;
+            // Prefer the backend's machine code (e.g. 'MIN_ORDER_NOT_MET' / a nested
+            // error.code); fall back to the legacy convention where the `error` field
+            // itself carried a code-like string (e.g. 'GRANT_REQUIRED').
+            err.code = json.code ?? nested?.code ?? errString;
+            err.recoverable = json.recoverable ?? nested?.recoverable;
             err.details = json.details;
             throw err;
         }
@@ -251,7 +261,12 @@ export class PerfolioClient {
     hlTpsl(b) {
         return this.post(this.urls.api, '/hl/tpsl', b);
     }
-    hlCancelOrder(b) { return this.post(this.urls.api, '/hl/cancel-order', b); }
+    hlCancelOrder(b) {
+        // The backend route reads `req.body.orderId`; send BOTH `orderId` (canonical)
+        // and `oid` (alias) so a cancel works regardless of which name the deployed
+        // backend expects — fixes the "Missing orderId" the report hit.
+        return this.post(this.urls.api, '/hl/cancel-order', { orderId: b.oid, oid: b.oid, asset: b.asset });
+    }
     /**
      * Autonomous USDT → Hyperliquid deposit. Hits POST /tx/bridge-deposit, which
      * builds the USDT-approve + Across bridge calls and executes them via the

package/dist/lib/money-client.js

@@ -84,11 +84,18 @@ export class MoneyClient {
         if (res.status === 428)
             throw new NoSessionError();
         if (!res.ok || json.success === false) {
-            throw new AppError(json.error || json.message || `HTTP ${res.status}`, {
+            // `error` may be a flat string or a nested { code, message, recoverable }
+            // object — normalize both so an object never becomes "[object Object]".
+            const rawErr = json.error;
+            const nested = rawErr && typeof rawErr === "object"
+                ? rawErr
+                : undefined;
+            const errString = typeof rawErr === "string" ? rawErr : undefined;
+            throw new AppError(nested?.message || errString || json.message || `HTTP ${res.status}`, {
                 status: res.status,
-                code: json.code ?? json.error,
+                code: json.code ?? nested?.code ?? errString,
                 details: json.details,
-                recoverable: res.status >= 500,
+                recoverable: json.recoverable ?? nested?.recoverable ?? res.status >= 500,
             });
         }
         return json.data;

package/dist/lib/money-input.js

@@ -77,6 +77,34 @@ function roundToDecimalString(n, decimals) {
 export function defaultInputCurrency(prefs) {
     return usesLocalCurrency(prefs) ? prefs.currency.toUpperCase() : 'USD';
 }
+/**
+ * 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 const MAX_CASH_USD = 10_000_000;
+/** Tag an error with a machine code + recoverable flag for the {ok:false} envelope. */
+function amountError(message, code) {
+    const e = new Error(message);
+    e.code = code;
+    e.recoverable = true; // the user can simply re-enter a sane amount
+    return e;
+}
+/**
+ * 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 function assertUsdInBounds(usd, describe) {
+    if (!(usd > 0)) {
+        throw amountError(`${describe()} is too small to transact — please enter a larger amount.`, 'AMOUNT_TOO_SMALL');
+    }
+    if (usd > MAX_CASH_USD) {
+        throw amountError(`${describe()} exceeds the $${MAX_CASH_USD.toLocaleString('en-US')} per-transaction safety limit. ` +
+            `If that's really intended, split it into smaller amounts.`, 'AMOUNT_TOO_LARGE');
+    }
+}
 /**
  * Resolve a user-entered cash amount into a USD decimal string for the backend.
  *
@@ -90,6 +118,10 @@ export async function resolveCashToUsd(raw, prefs, decimals, fetchRate) {
     const sourceCurrency = (parsed.currency ?? defaultInputCurrency(prefs)).toUpperCase();
     if (sourceCurrency === 'USD') {
         const usdString = assertDecimal(roundToDecimalString(parsed.amount, decimals), decimals);
+        // Guard BEFORE returning: a sub-cent USD dust amount rounds to "0" here and
+        // would otherwise reach the backend as an opaque SWAP_QUOTE_FAILED; a giant
+        // amount is a fat-finger. The rounded value catches both (0 → too-small).
+        assertUsdInBounds(Number(usdString), () => fmtCurrency(parsed.amount, 'USD'));
         return {
             usd: Number(usdString),
             usdString,
@@ -112,9 +144,9 @@ export async function resolveCashToUsd(raw, prefs, decimals, fetchRate) {
     }
     const usd = parsed.amount / rate;
     const usdString = roundToDecimalString(usd, decimals);
-    if (Number(usdString) <= 0) {
-        throw new Error(`${parsed.amount} ${sourceCurrency} is too small to transact (≈ $0 at the current rate).`);
-    }
+    // Same dust + fat-finger guard as the USD branch, but described in the user's
+    // own currency (e.g. "₹50.00 is too small…").
+    assertUsdInBounds(Number(usdString), () => fmtCurrency(parsed.amount, sourceCurrency));
     return {
         usd: Number(usdString),
         usdString: assertDecimal(usdString, decimals),

package/dist/lib/portfolio-format.js

@@ -189,8 +189,15 @@ function usdcMinorPlain(minor) {
     const n = Number(minor) / 1e6;
     return `$${n.toFixed(n !== 0 && Math.abs(n) < 0.01 ? 4 : 2)}`;
 }
-/** Render the agent (spending) funds block as indented lines (no section title). */
-export function formatAgentFunds(bal) {
+/**
+ * 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 function formatAgentFunds(bal, credit) {
     const status = bal.status;
     if (status === "not_set_up" || status === "no_active_session") {
         return [
@@ -203,10 +210,22 @@ export function formatAgentFunds(bal) {
     }
     if (status === "credit_exhausted") {
         return [
-            `  Sign-up credit used up — balance ${usdcMinorPlain(bal.totalMinor)}`,
+            `  Sign-up credit used up — balance ${usdcMinorPlain(bal.totalMinor ?? credit?.totalMinor)}`,
             "  Add funds to keep spending (`grant fetch`/`grant transfer` need a balance).",
         ].join("\n");
     }
+    // Prefer the chain-agnostic credit split (free credit + funds you added) when
+    // available — this is the same figure the app shows on the Spending screen.
+    if (credit && credit.totalMinor !== undefined) {
+        const lines = [`  Spendable: ${usdcMinorPlain(credit.totalMinor)}`];
+        lines.push(`    Free credit: ${usdcMinorPlain(credit.grantMinor)}`);
+        if (credit.walletMinor !== undefined) {
+            lines.push(`    Your wallet: ${usdcMinorPlain(credit.walletMinor)}`);
+        }
+        if (bal.address)
+            lines.push(`  Address:   ${bal.address}`);
+        return lines.join("\n");
+    }
     // active. A funded on-chain session carries live USDC/USDT; a grant-only user
     // carries the chain-agnostic sign-up credit total in minor units.
     if (bal.USDC !== undefined || bal.USDT !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentgrant.cash/cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Grant Cash — one CLI for your money (gold) and your agent (pay-per-use services). Routes to the Perfolio backend and the Agent-mode backend behind a single, plain-language surface.",
   "type": "module",
   "bin": {

package/skills/grant-cash/SKILL.md

@@ -34,13 +34,17 @@ Throughout this skill, **`grant <command>` is shorthand for `npx @agentgrant.cas
 ## Output (for assistants driving this CLI)
 
 - Output is **JSON** when stdout is not a TTY (you captured it) or with `--json`; pretty for people otherwise.
-- Success → `{"ok":true, ...}`. Failure → `{"ok":false,"error":{"code","message","recoverable"}}`.
+- Success → `{"ok":true, ...}`. Failure → `{"ok":false,"error":{"code","message","recoverable"}}`. This is uniform across **every** command — Investments and Spending alike — so always key off `ok`, never a per-command field.
 - `recoverable:true` → safe to retry. `recoverable:false` → STOP; don't retry blindly.
 
 ## Money amounts (important)
 
 Every **cash** amount is in the user's display currency — a bare `50` means ₹50 for an INR user, $50 for a USD user. Force a currency by prefixing: `"$50"`, `"₹100"`, `"100 EUR"`. This applies everywhere cash is entered: `buy --amount`, `borrow --amount`, prediction bets/deposits, `withdraw`, and so on. Asset *quantities* (e.g. `sell bitcoin --amount 0.1`) are not currency.
 
+- **Force US dollars with `--usd`.** Every cash command accepts `--usd` to interpret a bare amount as dollars regardless of display currency: `buy`, `sell --for`, `convert --for`, `quote --for`, `borrow`, `repay`, `leverage --borrow`, `hl deposit/withdraw/open`, and `polymarket bet/deposit`. (`--usd` + an already-prefixed amount like `"₹50"` leaves the explicit currency untouched.)
+- **The CLI echoes what it interpreted.** When a conversion happens, responses show both sides — e.g. `"₹50.00 (≈ $0.60)"` — so the display-currency default never silently surprises anyone. Relay that to the user.
+- **Bounds.** A dust amount that rounds to ~$0 is refused cleanly (`AMOUNT_TOO_SMALL`, recoverable — enter more), and an implausibly large amount is refused as a fat-finger guard (`AMOUNT_TOO_LARGE`, recoverable).
+
 ## Workflow
 
 1. `grant status` — confirm you're connected (both Investments and Spending).
@@ -126,10 +130,24 @@ Every **cash** amount is in the user's display currency — a bare `50` means
 - `grant schema <slug>` — the exact pay contract for a catalogued service (no charge).
 - `grant fetch <url> [-m POST] [-b '<json>'] [--price <amount>] [--asset USDC|USDT]` (alias `pay`) — pay for and run a service.
 - `grant transfer <recipient> <amount>` — send money to an address.
+
+**Calling a service with `grant fetch` — what to know:**
+- **The response body is base64-encoded.** `result.upstreamResponse.body` is base64 — decode it to read the service's JSON/text. (It's encoded so binary or non-JSON responses survive transit intact.)
+- **POST-with-body is the most reliable shape.** For a POST service, build the JSON `-b '<json>'` from the contract `grant check <url>` / `grant schema <slug>` returns.
+- **GET services with required query params:** run `grant check <url>` first; if the price can't be inferred, pass it explicitly with `--price <amount>` (the value comes from `check`). Put the query params in the URL itself; do **not** send them in `-b` (a GET has no body, so that fails `SCHEMA_VALIDATION_FAILED`).
+- **Payment guardrails (so you don't hit them blind):** `fetch` only pays **https** origins that are **public** — `http://`, `localhost`, `127.0.0.1`, LAN/private IPs and metadata IPs are blocked (anti-SSRF). And the origin must be in the catalog or one you've added via `grant discover` — an un-allowlisted origin returns `MARKETPLACE_NOT_ALLOWED`. A failed call that never settled does not charge you.
+- `grant spending deposit --amount <cash>` (aliases `add`, `top-up`) — move cash from the Investments side into the Spending balance (the agent's pay-per-use money). Amount is in the user's currency — a bare `50` means ₹50 for an INR user, $50 for a USD user. Funds land a few minutes after submitting. There is no reverse: Spending is funded from cash, not the other way around.
 - `grant redeem <code>` — claim an invite or bonus credit toward spending.
 - `grant upgrade` — get a one-time link to secure a full account and add spending funds.
 - `grant revoke` (alias `stop`) — stop all agent spending immediately.
 
+**Keeping Spending funded (assistant guidance).** The Spending balance only goes down as the agent pays for services — top it up from the user's cash with `grant spending deposit`:
+- **User asks explicitly** ("move ₹2,000 to spending", "top up my spending balance") → run `grant spending deposit --amount <cash>` directly. No need to ask again.
+- **Running low** (a paid action is about to exceed — or only barely fits — the remaining Spending balance) → before paying, tell the user the balance is low and ask whether to transfer some cash over first. Don't transfer without a yes.
+- **Empty / zero balance** (a `grant fetch`/pay fails for lack of funds, or `grant portfolio` shows Spending at 0) → tell the user their Spending account is empty and suggest moving some money in, **quoted in their local currency** — e.g. *"Your spending balance is empty — shall I move ₹2,000 (≈ $24) over from your cash?"* Then, on confirmation, run `grant spending deposit`.
+
+Always state amounts in the user's display currency (never raw USD/USDT or chains), and only transfer proactively after the user agrees — an explicit request is the go-ahead; a low/empty balance is a prompt to ask.
+
 ### Transactions & self-orientation
 - `grant tx status <txHash>` — check whether a transaction confirmed. `grant tx history [--limit <n>]` — recent transactions.
 - `grant session status` / `grant session grant` — your agent-access (session) status and how to enable it.
@@ -145,6 +163,9 @@ Every **cash** amount is in the user's display currency — a bare `50` means
 | `GUARDRAIL_DENIED` | no | STOP. This is outside the limits the user set — don't retry. Tell the user. |
 | `SIGNER_REVOKED` | no | STOP. Spending was stopped — re-authorize with `grant login`. |
 | `SCHEMA_VALIDATION_FAILED` | yes | Free reject. Run `grant check <url>`, fix the `--body`, then retry. |
+| `MARKETPLACE_NOT_ALLOWED` | no | Origin isn't catalogued/allowlisted — add it with `grant discover <origin>` first (must be public https). |
+| `AMOUNT_TOO_SMALL` | yes | Amount rounds to ~$0 — enter a larger amount. |
+| `AMOUNT_TOO_LARGE` | yes | Above the per-transaction safety limit — split into smaller amounts (or re-check the currency). |
 | `BACKEND_UNREACHABLE` | no | Wrong or unreachable address — check the connection with `grant config show`. |
 | `NETWORK` | yes | Temporary — retry once. |
 
@@ -164,6 +185,7 @@ grant polymarket bet 0x1234 --side yes --amount 25    # bet $25 on "yes"
 grant search "web search" --limit 5                   # find a live service (Spending)
 grant check https://api.example.com/run               # what it costs + needs, no charge
 grant fetch https://api.example.com/run -b '{"q":"gold news today"}'   # pay + run
+grant spending deposit --amount 25                    # move $25 of cash into Spending
 grant activity --json                                 # full combined history
 grant revoke                                           # stop all agent spending
 ```