@agentgrant.cash/cli 1.0.0

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

@@ -0,0 +1,304 @@
+import { buildCtx, requireAuth, out, fail, resolveCash, loadDisplayPrefs } from '../money-helpers.js';
+import { describeCashResolution, formatMoney, displayDescriptor, fetchPusdBalanceUsd, DEFAULT_PREFS, } from '../../lib/index.js';
+/** pUSD (the prediction balance) is a USD-pegged stablecoin → 6 decimals on the wire. */
+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. */
+export function isTradingDisabled(err) {
+    const e = err;
+    return e?.status === 503 || e?.code === 'POLYMARKET_TRADING_NOT_CONFIGURED';
+}
+/** Render a market list into human-readable lines. Exported for unit testing. */
+export function formatMarkets(markets, count) {
+    if (!markets.length)
+        return 'No markets found.';
+    const lines = markets.map((m) => {
+        const top = [...m.outcomes].sort((a, b) => b.price - a.price)[0];
+        const odds = top ? `${top.label} ${Math.round(top.price * 100)}%` : '—';
+        const q = m.question.length > 52 ? `${m.question.slice(0, 49)}…` : m.question;
+        return `  ${m.id.padEnd(10)} ${q.padEnd(54)} ${odds}`;
+    });
+    const more = count > markets.length ? `\n  …and ${count - markets.length} more (use --search to narrow)` : '';
+    return `${markets.length} markets:\n${lines.join('\n')}${more}`;
+}
+/** Signed money in the user's currency, e.g. +₹104 / −$0.40. */
+function signedMoney(n, prefs) {
+    const s = n >= 0 ? '+' : '−';
+    return `${s}${formatMoney(Math.abs(n), prefs)}`;
+}
+/** Signed percent, e.g. +50% / −5%. */
+function signedPct(n) {
+    const s = n >= 0 ? '+' : '−';
+    return `${s}${Math.abs(Math.round(n))}%`;
+}
+/**
+ * Render the prediction portfolio: a per-position table showing where each
+ * position has moved (entry → now, %) plus portfolio totals. Money is localized
+ * to the user's currency (defaults to USD for callers without prefs). Exported for tests.
+ */
+export function formatPositions(r, prefs = DEFAULT_PREFS) {
+    if (!r.positions.length)
+        return 'No open prediction positions.';
+    const rows = r.positions.map((p) => {
+        const q = p.market.length > 40 ? `${p.market.slice(0, 37)}…` : p.market;
+        const move = `${p.avgPrice.toFixed(2)}→${p.currentPrice.toFixed(2)}`; // entry → now
+        const arrow = p.pnl > 0 ? '▲' : p.pnl < 0 ? '▽' : '–';
+        const redeem = p.redeemable ? '  ⟳ redeemable' : '';
+        return (`  ${q.padEnd(42)} ${p.outcome.padEnd(4)} ${String(p.shares).padStart(7)} sh  ` +
+            `${move.padEnd(11)} ${signedPct(p.pnlPercent).padStart(5)} ${arrow}  ` +
+            `${formatMoney(p.value, prefs).padStart(9)}${redeem}`);
+    });
+    const totals = `  ${'─'.repeat(78)}\n` +
+        `  invested ${formatMoney(r.investedUsd, prefs)} · value ${formatMoney(r.valueUsd, prefs)} · ` +
+        `P&L ${signedMoney(r.pnlUsd, prefs)} (${signedPct(r.pnlPercent)})`;
+    return `Your predictions — worth ${formatMoney(r.valueUsd, prefs)}\n${rows.join('\n')}\n${totals}`;
+}
+/** Render prediction trade history (most recent first). Money localized. Exported for tests. */
+export function formatActivity(activity, prefs = DEFAULT_PREFS) {
+    if (!activity.length)
+        return 'No prediction activity yet.';
+    return activity
+        .map((a) => {
+        const date = a.timestamp ? new Date(a.timestamp * 1000).toISOString().slice(0, 10) : '—';
+        const verb = (a.side || a.type).toUpperCase().padEnd(6);
+        const q = a.market.length > 38 ? `${a.market.slice(0, 35)}…` : a.market;
+        const px = a.price ? ` @ ${a.price.toFixed(2)}` : '';
+        const amt = a.amountUsd ? `  ${formatMoney(a.amountUsd, prefs)}` : '';
+        return `  ${date}  ${verb} ${String(a.shares).padStart(7)} ${a.outcome.padEnd(4)} ${q.padEnd(40)}${px}${amt}`;
+    })
+        .join('\n');
+}
+/**
+ * Friendly one-liner for a funding-intent status. The backend relays an opaque
+ * tracker payload, so we defensively pull a `status` string (top-level or nested
+ * under `data`) and map the common terminal states to plain language; anything
+ * unrecognized degrades to "still on its way". Exported for tests.
+ */
+export function formatFundStatus(raw) {
+    const o = (raw && typeof raw === 'object' ? raw : {});
+    const d = o.data;
+    // status can live at o.status, o.data.status, or as a bare string in o.data.
+    const statusRaw = (d && typeof d === 'object' ? d.status : undefined) ??
+        (typeof d === 'string' ? d : undefined) ??
+        o.status ??
+        'pending';
+    const status = String(statusRaw).toLowerCase();
+    if (/(success|filled|complete|completed|done)/.test(status)) {
+        return '✓ Funds have landed — your prediction balance is ready to bet.';
+    }
+    if (/(fail|refund|expired|cancel)/.test(status)) {
+        return `This funding didn’t go through (${status}). Your cash is safe — run "polymarket deposit <amount>" again.`;
+    }
+    return 'Still on its way — funds usually land within 1–2 minutes. Check again shortly.';
+}
+export function registerPolymarket(program) {
+    const pm = program
+        .command('polymarket')
+        .description('Prediction markets — bet on real-world events (politics, sports, crypto, economics)');
+    pm.command('markets')
+        .description('Browse or search prediction markets')
+        .option('--search <q>', 'filter markets by keyword (e.g. bitcoin, election, fed)')
+        .option('--limit <n>', 'max markets to show (default 20)', (v) => parseInt(v, 10))
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        const data = await ctx.client.polymarketMarkets(opts.search, opts.limit);
+        if (ctx.json) {
+            out(ctx, '', data);
+            return;
+        }
+        out(ctx, formatMarkets(data.markets, data.count), data);
+    });
+    pm.command('positions')
+        .description('Your open prediction positions + portfolio totals')
+        .action(async (_o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const data = await ctx.client.polymarketPositions();
+        if (ctx.json) {
+            out(ctx, '', data);
+            return;
+        }
+        const prefs = await loadDisplayPrefs(ctx);
+        out(ctx, formatPositions(data, prefs), data);
+    });
+    pm.command('history')
+        .description('Your prediction trade history (bets, sells, redeems)')
+        .option('--limit <n>', 'max events to show (default 25)', (v) => parseInt(v, 10))
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const data = await ctx.client.polymarketActivity(opts.limit ?? 25);
+        if (ctx.json) {
+            out(ctx, '', data);
+            return;
+        }
+        const prefs = await loadDisplayPrefs(ctx);
+        out(ctx, formatActivity(data.activity, prefs), data);
+    });
+    pm.command('bet')
+        .description('Bet on a prediction market (buy outcome shares)')
+        .argument('<marketId>', 'market id (from `polymarket markets`)')
+        .requiredOption('--side <yes|no>', 'which outcome to back')
+        .requiredOption('--amount <cash>', 'amount to bet (your currency; prefix $/₹ to force one, or pass --usd)', (v) => v)
+        .option('--usd', 'interpret --amount as US dollars, ignoring your display currency')
+        .option('--limit <price>', 'limit price 0–1 (default: market order)', (v) => parseFloat(v))
+        .option('--max-slippage <pct>', 'max slippage on a market bet, in percent (e.g. 5 = 5%)', (v) => parseFloat(v))
+        .action(async (marketId, opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        if (opts.side !== 'yes' && opts.side !== 'no')
+            fail('--side must be "yes" or "no"', ctx.json);
+        if (opts.maxSlippage !== undefined && !(opts.maxSlippage >= 0))
+            fail('--max-slippage must be a non-negative number (percent)', ctx.json);
+        // The stake is a cash value in the user's display currency (a bare "200" = ₹200
+        // for an INR user, not $200). Resolve to a USD amount for the backend — refuses
+        // rather than guess if the FX rate is unavailable. `--usd` forces dollars.
+        const m = await resolveCash(ctx, opts.amount, PREDICTION_DECIMALS, { usd: !!opts.usd });
+        try {
+            const data = await ctx.client.polymarketBet({
+                marketId,
+                side: opts.side,
+                amount: m.usdString,
+                limitPrice: opts.limit,
+                maxSlippageBps: opts.maxSlippage !== undefined ? Math.round(opts.maxSlippage * 100) : undefined,
+            });
+            out(ctx, `✓ Bet placed: ${describeCashResolution(m)} on ${data.side.toUpperCase()} — ${data.shares} shares @ ${data.price}.`, { ...data, stake: describeCashResolution(m) });
+        }
+        catch (err) {
+            if (isTradingDisabled(err))
+                fail(BETTING_DISABLED_MSG, ctx.json);
+            throw err;
+        }
+    });
+    pm.command('cashout')
+        .description('Sell your shares in a market (before resolution)')
+        .argument('<marketId>', 'market id')
+        .option('--shares <n>', 'shares to sell (default: all)', (v) => parseFloat(v))
+        .action(async (marketId, opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        try {
+            const data = await ctx.client.polymarketSell({ marketId, shares: opts.shares });
+            out(ctx, `✓ Cash-out submitted for ${marketId}`, data);
+        }
+        catch (err) {
+            if (isTradingDisabled(err))
+                fail(BETTING_DISABLED_MSG, ctx.json);
+            throw err;
+        }
+    });
+    pm.command('redeem')
+        .description('Claim winnings on a resolved market')
+        .argument('<marketId>', 'market id')
+        .action(async (marketId, _o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        try {
+            const data = await ctx.client.polymarketRedeem({ marketId });
+            out(ctx, `✓ Redemption submitted for ${marketId}`, data);
+        }
+        catch (err) {
+            if (isTradingDisabled(err))
+                fail(BETTING_DISABLED_MSG, ctx.json);
+            throw err;
+        }
+    });
+    pm.command('wallet')
+        .description('Your prediction balance — how much you have available to bet, and readiness')
+        .action(async (_o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        try {
+            const [data, prefs] = await Promise.all([
+                ctx.client.polymarketDepositWallet(),
+                loadDisplayPrefs(ctx),
+            ]);
+            // Read the live prediction balance on-chain (no backend dependency). Best-effort:
+            // a failed read shows "unavailable" rather than breaking the readiness report.
+            const balanceUsd = data.address ? await fetchPusdBalanceUsd(data.address) : null;
+            const rendered = balanceUsd != null ? formatMoney(balanceUsd, prefs) : null;
+            if (!data.deployed) {
+                out(ctx, 'Your prediction account isn’t set up yet. Run `polymarket provision` (one-time, no signing), then add funds with `polymarket deposit <amount>`.', { ...data, balanceUsd, rendered, display: displayDescriptor(prefs) });
+                return;
+            }
+            const balLine = rendered != null
+                ? `Available to bet: ${rendered}`
+                : 'Available to bet: (balance unavailable right now — try again in a moment)';
+            out(ctx, `${balLine}\nReady to place bets ✓` +
+                (balanceUsd === 0 ? '\nAdd funds with `polymarket deposit <amount>` before betting.' : ''), { ...data, balanceUsd, rendered, display: displayDescriptor(prefs) });
+        }
+        catch (err) {
+            if (isTradingDisabled(err))
+                fail(BETTING_DISABLED_MSG, ctx.json);
+            throw err;
+        }
+    });
+    pm.command('provision')
+        .description('Set up your prediction account (one-time, gasless, no signing)')
+        .action(async (_o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        try {
+            const data = await ctx.client.polymarketProvision();
+            out(ctx, '✓ Your prediction account is ready. Add funds with `polymarket deposit <amount>`, then place a bet.', data);
+        }
+        catch (err) {
+            if (isTradingDisabled(err))
+                fail(BETTING_DISABLED_MSG, ctx.json);
+            throw err;
+        }
+    });
+    pm.command('deposit')
+        .description('Add cash to your prediction balance — autonomous, no signing')
+        .argument('<amount>', 'amount of cash to add (your currency; prefix $/₹ to force one)')
+        .action(async (amount, _o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        // The amount is a cash value in the user's display currency → resolve to USD.
+        const m = await resolveCash(ctx, amount, PREDICTION_DECIMALS);
+        try {
+            const data = await ctx.client.polymarketDeposit(m.usdString);
+            out(ctx, `✓ Adding ${describeCashResolution(m)} to your prediction balance — it’ll be ready to bet in ~1–2 min.` +
+                (data.requestId ? `\nTrack it with: polymarket fund-status ${data.requestId}` : ''), { ...data, amount: describeCashResolution(m) });
+        }
+        catch (err) {
+            if (isTradingDisabled(err))
+                fail(BETTING_DISABLED_MSG, ctx.json);
+            throw err;
+        }
+    });
+    pm.command('fund-status')
+        .description('Check whether funds you added have landed in your prediction balance')
+        .argument('<requestId>', 'tracking id (from `polymarket deposit`)')
+        .action(async (requestId, _o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        try {
+            const data = await ctx.client.polymarketFundStatus(requestId);
+            out(ctx, formatFundStatus(data), data);
+        }
+        catch (err) {
+            if (isTradingDisabled(err))
+                fail(BETTING_DISABLED_MSG, ctx.json);
+            throw err;
+        }
+    });
+    pm.command('withdraw')
+        .description('Move cash from your prediction balance back to your account — autonomous, no signing')
+        .argument('<amount>', 'amount of cash to move back (your currency; prefix $/₹ to force one)')
+        .action(async (amount, _o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const m = await resolveCash(ctx, amount, PREDICTION_DECIMALS);
+        try {
+            const data = await ctx.client.polymarketWithdraw(m.usdString);
+            out(ctx, `✓ Moving ${describeCashResolution(m)} from your prediction balance back to your account — it lands automatically in a moment.`, { ...data, amount: describeCashResolution(m) });
+        }
+        catch (err) {
+            if (isTradingDisabled(err))
+                fail(BETTING_DISABLED_MSG, ctx.json);
+            throw err;
+        }
+    });
+}

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

@@ -0,0 +1,19 @@
+import { buildCtx, requireAuth, out } from '../money-helpers.js';
+export function registerSession(program) {
+    const session = program.command('session').description('Manage agent access (session keys)');
+    // Agent access (the session key) is now installed automatically during
+    // `grant login`. This command just points users there rather than driving
+    // the old widget-relay grant flow.
+    session.command('grant').description('How to enable agent access')
+        .action((_opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        out(ctx, 'Agent access is set up automatically when you connect. Run `grant login` (or `grant login --force` to re-run setup).', { hint: 'run `grant login`' });
+    });
+    session.command('status').description('Session-key / agent-access status')
+        .action(async (_opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const m = await ctx.client.getModuleStatus();
+        out(ctx, `Agent access: ${m?.status ?? 'unknown'}`, m);
+    });
+}

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

@@ -0,0 +1,94 @@
+import { buildCtx, requireAuth, resolver, reportTx, resolveCash, resolveCashTargetQty, 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.
+ *
+ * Three shapes:
+ *  - source is cash (buy): the amount is fiat → interpreted in the user's currency
+ *    and converted to USD ("buy gold 50" = ₹50 for an INR user, not $50).
+ *  - source is an asset + `--amount`: a quantity of that asset, passed through.
+ *  - source is an asset + `--for <cash>`: a CASH TARGET — sized to an asset
+ *    quantity from the live price ("sell ₹100 of gold" → ~₹100 worth of gold).
+ */
+async function resolveSellSide(ctx, from, spec) {
+    // Cash source → the amount is cash to spend (buy).
+    if (from.class === 'stable') {
+        if (spec.forCash)
+            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);
+        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);
+        return {
+            sellAmount: r.quantity,
+            note: `${describeCashResolution(r)} of ${from.friendly} (≈ ${r.quantity} ${from.friendly})`,
+        };
+    }
+    // Asset source, explicit quantity.
+    if (!spec.amount)
+        fail(`Specify how much: --amount <${from.friendly} quantity> or --for <cash value>.`, ctx.json);
+    const sellAmount = assertDecimal(spec.amount, from.decimals);
+    return { sellAmount, note: `${sellAmount} ${from.friendly}` };
+}
+/** Enforce that exactly one of --amount / --for was given. */
+function oneOfAmountOrFor(ctx, opts) {
+    if (opts.amount && opts.for)
+        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 };
+}
+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")')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const r = await resolver(ctx);
+        const from = r.resolve(opts.from);
+        const to = r.resolve(opts.to);
+        const { sellAmount } = await resolveSellSide(ctx, from, oneOfAmountOrFor(ctx, opts));
+        const data = await ctx.client.swapQuote({ sellToken: from.symbol, buyToken: to.symbol, sellAmount });
+        out(ctx, JSON.stringify(data, null, 2), data);
+    });
+    // wait-by-default: commander's `--no-wait` sets opts.wait=false; default true.
+    const trade = async (cmd, fromTerm, toTerm, spec, wait) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const r = await resolver(ctx);
+        const from = r.resolve(fromTerm);
+        const to = r.resolve(toTerm);
+        const { sellAmount, note } = await resolveSellSide(ctx, from, spec);
+        const res = (await ctx.client.swap({
+            sellToken: from.symbol, buyToken: to.symbol, sellAmount,
+        }));
+        await reportTx(ctx, res, wait, `${fromTerm} → ${toTerm} (${note})`);
+    };
+    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('--no-wait', 'return immediately without waiting for on-chain confirmation')
+        .action((asset, opts, cmd) => trade(cmd, 'cash', asset, { amount: opts.amount }, 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('--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);
+    });
+    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('--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);
+    });
+}

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

@@ -0,0 +1,22 @@
+import { buildCtx, requireAuth, out } from '../money-helpers.js';
+export function registerTx(program) {
+    const tx = program.command('tx').description('Transaction status and history');
+    tx.command('status <txHash>').description('Check whether a transaction confirmed on-chain')
+        .action(async (txHash, _o, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const data = await ctx.client.getTxStatus(txHash);
+        const terminal = data.status === 'success' || data.status === 'failed';
+        const human = `${data.type ?? 'transaction'} ${data.txHash}\n` +
+            `Status: ${data.status}${terminal ? '' : ' (still in progress — check again shortly)'}`;
+        out(ctx, human, data);
+    });
+    tx.command('history').description('Recent transactions')
+        .option('--limit <n>', 'how many to show', '20')
+        .action(async (opts, cmd) => {
+        const ctx = buildCtx(cmd);
+        requireAuth(ctx);
+        const data = await ctx.client.getTxHistory(Number(opts.limit) || 20);
+        out(ctx, JSON.stringify(data, null, 2), data);
+    });
+}

package/dist/lib/agent-client.js

@@ -0,0 +1,166 @@
+import { AppError } from "./errors.js";
+/**
+ * Agent side — the Agent-mode backend client (pay-per-use services, x402).
+ *
+ * Auth with a session-bound `X-API-Key` (`grant_live_`). The agent never holds a
+ * private key; the backend's delegated, revocable, guardrailed session owns the
+ * spend. Errors carry the backend's stable `err.code` + a `recoverable` flag so
+ * a driving agent knows whether to retry (see SKILL.md error playbook).
+ */
+const REQUEST_TIMEOUT_MS = 60_000;
+export class AgentClient {
+    base;
+    apiKey;
+    f;
+    constructor(opts) {
+        this.base = opts.agent;
+        this.apiKey = opts.apiKey;
+        this.f = opts.fetchImpl ?? fetch;
+    }
+    get connected() {
+        return Boolean(this.apiKey);
+    }
+    async request(method, path, opts = {}) {
+        const headers = { Accept: "application/json" };
+        if (opts.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (opts.auth) {
+            if (!this.apiKey)
+                throw new AppError("Not connected to your agent yet. Run `grant login`.", {
+                    code: "NOT_CONNECTED",
+                    recoverable: false,
+                });
+            headers["X-API-Key"] = this.apiKey;
+        }
+        if (opts.idempotent)
+            headers["Idempotency-Key"] = randomId();
+        let res;
+        try {
+            res = await this.f(`${this.base}${path}`, {
+                method,
+                headers,
+                ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (e) {
+            throw new AppError(e instanceof Error ? e.message : String(e), {
+                code: "NETWORK",
+                recoverable: true,
+            });
+        }
+        const json = (await res.json().catch(() => ({})));
+        // A 4xx without the agent error envelope means we never reached the API
+        // (wrong/dead base URL, platform edge 404). Point at the misconfig.
+        if (res.status >= 400 && res.status < 500 && !json?.error?.code) {
+            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) {
+            throw new AppError(json?.error?.message ?? `Request failed (${res.status})`, {
+                status: res.status,
+                code: json?.error?.code ?? `HTTP_${res.status}`,
+                recoverable: res.status >= 500,
+            });
+        }
+        return json;
+    }
+    // ── reads ──
+    /**
+     * Spendable funds + session state. Hits `GET /balance` (api-key auth), which
+     * returns the credit-aware status shape (active + USDC/USDT, not_set_up,
+     * credit_exhausted, or sign-up credit). NOT `/me` — that route is JWT-only and
+     * carries identity, not funds.
+     */
+    balance() {
+        return this.request("GET", "/balance", { auth: true });
+    }
+    /**
+     * Find a payable endpoint in the curated catalog. Hits `GET /marketplace/x402`
+     * (the grouped, public catalog route) — NOT `/marketplace`, which does not
+     * exist on the backend.
+     */
+    search(query, limit) {
+        const p = new URLSearchParams();
+        if (query)
+            p.set("q", query);
+        if (limit)
+            p.set("limit", String(limit));
+        const qs = p.toString();
+        return this.request("GET", `/marketplace/x402${qs ? `?${qs}` : ""}`, { auth: true });
+    }
+    /** Exact pay contract (requestSchema) for a URL — no spend. */
+    check(url) {
+        return this.request("GET", `/marketplace/check?url=${encodeURIComponent(url)}`, { auth: true });
+    }
+    /** Recent transactions, newest first. */
+    transactions(limit) {
+        const q = limit ? `?limit=${limit}` : "";
+        return this.request("GET", `/transactions${q}`, { auth: true });
+    }
+    /** One transaction by id. */
+    tx(id) {
+        return this.request("GET", `/transactions/${encodeURIComponent(id)}`, {
+            auth: true,
+        });
+    }
+    /** Exact POST /x402/pay contract for a catalog entry by slug (requestSchema + price). No spend. */
+    schema(slug) {
+        return this.request("GET", `/marketplace/x402/${encodeURIComponent(slug)}`, { auth: true });
+    }
+    // ── catalog + account management ──
+    /** Ingest any x402 origin's endpoints into the catalog so they become searchable/payable. */
+    discover(origin) {
+        return this.request("POST", "/marketplace/discover", {
+            body: { origin },
+            auth: true,
+        });
+    }
+    /** Claim an invite / bonus credit by code. Mints or tops up the session's spendable funds. */
+    redeem(code) {
+        return this.request("POST", "/onboard/redeem", {
+            body: { code },
+            auth: true,
+        });
+    }
+    /** One-time link (+ code) to secure a full account and add funds. Gated by the session key. */
+    linkCode() {
+        return this.request("POST", "/account/link-code", { body: {}, auth: true });
+    }
+    // ── spends (session-owned, guardrailed) ──
+    /**
+     * Pay + run an endpoint via the session. Body matches `POST /x402/pay`'s
+     * schema: `method` is required (uppercased), `expectedPriceMinor` (the spend
+     * cap) and `asset` are required, and `body` is a RAW STRING passthrough — not
+     * a parsed object. The agent never signs; the session owns the spend.
+     */
+    fetchPay(b) {
+        return this.request("POST", "/x402/pay", {
+            body: b,
+            auth: true,
+            idempotent: true,
+        });
+    }
+    /**
+     * Gasless transfer to an address. Hits `POST /transactions` (there is no
+     * `/transfer` route); body is `{ asset, amount, recipient }` where `amount` is
+     * the minor-units decimal string.
+     */
+    transfer(b) {
+        return this.request("POST", "/transactions", {
+            body: { asset: b.asset, amount: b.amount, recipient: b.recipient },
+            auth: true,
+            idempotent: true,
+        });
+    }
+    /** Stop all spend on this key — revoke the session (terminal). */
+    revoke() {
+        return this.request("POST", "/sessions/revoke", {
+            body: {},
+            auth: true,
+        });
+    }
+}
+/* Local idempotency id — avoids importing node:crypto at module top for tree-shake. */
+function randomId() {
+    return (Math.random().toString(36).slice(2) + Date.now().toString(36));
+}