@agentgrant.cash/cli 1.0.0

package/dist/lib/agent-device.js

@@ -0,0 +1,173 @@
+import { createHash, randomBytes } from "node:crypto";
+import { AppError } from "./errors.js";
+/**
+ * Generate a PKCE S256 pair. The verifier is 43 base64url chars (32 random
+ * bytes), well within RFC 7636's 43–128 range.
+ */
+export function generatePkce() {
+    const verifier = base64url(randomBytes(32)); // 32 bytes → 43 base64url chars
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge, method: "S256" };
+}
+function base64url(buf) {
+    return buf
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+const JSON_HEADERS = { "Content-Type": "application/json", Accept: "application/json" };
+/**
+ * POST /onboard/privy-cli/device/start — open the agent-side handshake.
+ * Sends only the public challenge; keep the returned `sid` paired with the
+ * verifier from the same {@link generatePkce} call.
+ */
+export async function startAgentDevice(agent, pkce, clientName, f = fetch) {
+    const base = agent.replace(/\/$/, "");
+    let res;
+    try {
+        res = await f(`${base}/onboard/privy-cli/device/start`, {
+            method: "POST",
+            headers: JSON_HEADERS,
+            body: JSON.stringify({
+                clientName,
+                code_challenge: pkce.challenge,
+                code_challenge_method: pkce.method,
+            }),
+        });
+    }
+    catch (e) {
+        throw new AppError(e instanceof Error ? e.message : String(e), {
+            code: "NETWORK",
+            recoverable: true,
+        });
+    }
+    const j = (await res.json().catch(() => ({})));
+    // A 4xx without a recognizable body means we never reached the agent API
+    // (wrong/dead base URL) — point at the misconfig, same as AgentClient.
+    if (res.status >= 400 && res.status < 500 && !j?.sid) {
+        throw new AppError(`No Grant Cash agent API at ${base} (HTTP ${res.status}) — check GRANTCASH_AGENT_URL.`, { status: res.status, code: "BACKEND_UNREACHABLE", recoverable: false });
+    }
+    if (!res.ok || !j?.sid) {
+        throw new AppError(j?.error?.message || `Could not start spending setup (HTTP ${res.status})`, { status: res.status, code: j?.error?.code ?? "AGENT_DEVICE_START_FAILED" });
+    }
+    return {
+        sid: j.sid,
+        pollInterval: typeof j.pollInterval === "number" ? j.pollInterval : 3,
+        expiresIn: typeof j.expiresIn === "number" ? j.expiresIn : 300,
+    };
+}
+/**
+ * POST /onboard/privy-cli/device/poll — one poll with the secret verifier.
+ *
+ * Resolves a single tick:
+ *   - 200 { status:"pending" | "complete" | "expired" } → returned as-is
+ *     (complete may omit `apiKey` = already provisioned → keep existing key).
+ *   - 401 PRIVY_DEVICE_PKCE_FAILED → throw (terminal; the verifier was rejected).
+ *   - 429 → throw a RATE_LIMITED AppError carrying `retryInMs` from details so
+ *     {@link waitForAgentDevice} can back off instead of hammering.
+ */
+export async function pollAgentDevice(agent, sid, verifier, f = fetch) {
+    const base = agent.replace(/\/$/, "");
+    let res;
+    try {
+        res = await f(`${base}/onboard/privy-cli/device/poll`, {
+            method: "POST",
+            headers: JSON_HEADERS,
+            body: JSON.stringify({ sid, code_verifier: verifier }),
+        });
+    }
+    catch (e) {
+        throw new AppError(e instanceof Error ? e.message : String(e), {
+            code: "NETWORK",
+            recoverable: true,
+        });
+    }
+    const j = (await res.json().catch(() => ({})));
+    if (res.status === 429) {
+        const retryInMs = j?.details?.retryInMs;
+        throw new AppError("Too many attempts — backing off.", {
+            status: 429,
+            code: "RATE_LIMITED",
+            recoverable: true,
+            details: retryInMs ? { retryInMs } : undefined,
+        });
+    }
+    if (res.status === 401) {
+        throw new AppError(j?.error?.message || "Spending setup could not be verified (PKCE check failed).", {
+            status: 401,
+            code: j?.error?.code || j?.code || "PRIVY_DEVICE_PKCE_FAILED",
+            recoverable: false,
+        });
+    }
+    if (!res.ok) {
+        throw new AppError(j?.error?.message || `Spending poll failed (HTTP ${res.status})`, {
+            status: res.status,
+            code: j?.error?.code ?? `HTTP_${res.status}`,
+            recoverable: res.status >= 500,
+        });
+    }
+    if (j.status === "complete") {
+        return { status: "complete", apiKey: j.apiKey, sessionStatus: j.sessionStatus };
+    }
+    if (j.status === "expired")
+        return { status: "expired" };
+    return { status: "pending" };
+}
+/**
+ * Poll the agent device until a terminal status or the link expires.
+ *
+ * Never throws on the network/rate-limit path: a transient network blip or a
+ * 429 (honoring `details.retryInMs`) just backs off and retries within the
+ * window. A 401 PRIVY_DEVICE_PKCE_FAILED is terminal and DOES propagate. On
+ * window exhaustion returns `{ status: "expired" }`.
+ */
+export async function waitForAgentDevice(agent, sid, verifier, intervalMs, timeoutMs, f = fetch, signal) {
+    // When a signal is supplied, thread it into each fetch AND check it in the
+    // loop guard — so `grant login` can stop waiting on the best-effort spending
+    // side the moment money (the primary identity) settles, instead of letting
+    // this loop keep the process alive until the full timeout.
+    const ff = signal
+        ? ((input, init) => f(input, { ...init, signal }))
+        : f;
+    const start = Date.now();
+    while (!signal?.aborted && Date.now() - start < timeoutMs) {
+        try {
+            const r = await pollAgentDevice(agent, sid, verifier, ff);
+            if (r.status !== "pending")
+                return r;
+            await sleep(intervalMs);
+        }
+        catch (e) {
+            if (signal?.aborted)
+                break;
+            const err = e;
+            // PKCE failure is terminal — surface it.
+            if (err?.code === "PRIVY_DEVICE_PKCE_FAILED")
+                throw err;
+            // Rate-limited: back off by the server hint (or the normal interval).
+            if (err?.code === "RATE_LIMITED") {
+                const retryInMs = err.details?.retryInMs ?? intervalMs;
+                await sleep(Math.max(intervalMs, retryInMs));
+                continue;
+            }
+            // Transient network error: wait one interval and retry within the window.
+            await sleep(intervalMs);
+        }
+    }
+    return { status: "expired" };
+}
+function sleep(ms) {
+    return new Promise((res) => setTimeout(res, ms));
+}
+/**
+ * Resolve the agent-side poll interval in MILLISECONDS.
+ *
+ * The Agent-mode backend (`onboard/privy-cli/device/start`) reports
+ * `pollInterval` in SECONDS (e.g. 2), so it is multiplied by 1000. This differs
+ * from the money backend, which already reports milliseconds (see
+ * `moneyPollIntervalMs` in `device.ts`). Falls back to 3s.
+ */
+export function agentPollIntervalMs(pollInterval) {
+    return (typeof pollInterval === "number" && pollInterval > 0 ? pollInterval : 3) * 1000;
+}

package/dist/lib/amounts.js

@@ -0,0 +1,45 @@
+/**
+ * Validate a human decimal amount without converting it. The Perfolio backend
+ * accepts decimal strings directly (it runs parseUnits server-side), so the
+ * CLI must NOT pre-convert to base units — passing base units would be
+ * misread by the Enso heuristic. This gives the same early "too many decimal
+ * places" feedback toBaseUnits would, then returns the trimmed decimal string.
+ */
+export function assertDecimal(value, decimals) {
+    const v = value.trim();
+    if (!/^\d+(\.\d+)?$/.test(v))
+        throw new Error(`Invalid amount: "${value}"`);
+    const frac = v.split('.')[1] ?? '';
+    if (frac.length > decimals)
+        throw new Error(`Too many decimal places for this asset (max ${decimals}).`);
+    return v;
+}
+/** Convert a human decimal string to integer base units (no floats). */
+export function toBaseUnits(value, decimals) {
+    if (!/^\d+(\.\d+)?$/.test(value))
+        throw new Error(`Invalid amount: "${value}"`);
+    const [whole, frac = ''] = value.split('.');
+    if (frac.length > decimals)
+        throw new Error(`Too many decimal places for this asset (max ${decimals}).`);
+    const padded = frac.padEnd(decimals, '0');
+    const combined = `${whole}${padded}`.replace(/^0+(?=\d)/, '');
+    return combined === '' ? '0' : combined;
+}
+/** Convert integer base units back to a trimmed decimal string. */
+export function fromBaseUnits(base, decimals) {
+    const neg = base.startsWith('-');
+    const digits = (neg ? base.slice(1) : base).padStart(decimals + 1, '0');
+    const whole = digits.slice(0, digits.length - decimals);
+    const frac = digits.slice(digits.length - decimals).replace(/0+$/, '');
+    const out = frac ? `${whole}.${frac}` : whole;
+    return neg ? `-${out}` : out;
+}
+/** Friendly display. Cash renders as currency; other assets as "<n> <friendly>". */
+export function formatAmount(base, decimals, friendly) {
+    const dec = fromBaseUnits(base, decimals);
+    if (friendly === 'cash') {
+        const n = Number(dec);
+        return `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+    }
+    return `${dec} ${friendly}`;
+}

package/dist/lib/assets.js

@@ -0,0 +1,47 @@
+/** class → friendly word (v1 vocabulary). */
+const FRIENDLY_BY_CLASS = {
+    gold: 'gold',
+    stable: 'cash',
+    btc: 'bitcoin',
+    eth: 'ethereum',
+};
+/** When a class has >1 active member, pick this canonical symbol for v1. */
+const CANONICAL_SYMBOL_BY_CLASS = {
+    gold: 'XAUT',
+    stable: 'USDT',
+    btc: 'WBTC',
+    eth: 'WETH',
+};
+export const FRIENDLY_TERMS = ['gold', 'cash', 'bitcoin', 'ethereum'];
+export class AssetResolver {
+    byFriendly = new Map();
+    friendlyBySymbol = new Map();
+    constructor(assets) {
+        for (const [cls, friendly] of Object.entries(FRIENDLY_BY_CLASS)) {
+            const canonical = CANONICAL_SYMBOL_BY_CLASS[cls];
+            const match = assets.find((a) => a.class === cls && a.symbol === canonical)
+                ?? assets.find((a) => a.class === cls);
+            if (!match)
+                continue;
+            const resolved = { friendly, symbol: match.symbol, decimals: match.decimals, class: cls };
+            this.byFriendly.set(friendly, resolved);
+            this.friendlyBySymbol.set(match.symbol, friendly);
+        }
+    }
+    resolve(input) {
+        const key = input.trim().toLowerCase();
+        const hit = this.byFriendly.get(key);
+        if (!hit) {
+            throw new Error(`I don't recognize "${input}". Try: gold, cash, bitcoin, or ethereum.`);
+        }
+        return hit;
+    }
+    /** Friendly word for a backend symbol; falls back to the symbol itself. */
+    label(symbol) {
+        return this.friendlyBySymbol.get(symbol) ?? symbol;
+    }
+    /** True when a backend symbol maps to a v1 friendly term (canonical asset). */
+    isFriendly(symbol) {
+        return this.friendlyBySymbol.has(symbol);
+    }
+}

package/dist/lib/client.js

@@ -0,0 +1,284 @@
+import { NoSessionError } from './errors.js';
+import { refreshCliToken } from './device.js';
+/** Per-request network timeout. Generous enough for MEE submit, short enough to not hang. */
+const REQUEST_TIMEOUT_MS = 30_000;
+export class PerfolioClient {
+    urls;
+    token;
+    refreshToken;
+    onRefresh;
+    f;
+    constructor(opts) {
+        this.urls = opts.urls;
+        this.token = opts.token;
+        this.refreshToken = opts.refreshToken;
+        this.onRefresh = opts.onRefresh;
+        this.f = opts.fetchImpl ?? fetch;
+    }
+    headers(auth) {
+        const h = { 'Content-Type': 'application/json' };
+        if (auth && this.token)
+            h.Authorization = `Bearer ${this.token}`;
+        return h;
+    }
+    /** fetch with an abort-based timeout + one retry on a transient network failure. */
+    async fetchWithTimeout(url, init) {
+        const attempt = async () => {
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+            try {
+                return await this.f(url, { ...init, signal: ctrl.signal });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        try {
+            return await attempt();
+        }
+        catch {
+            // One backoff retry for a dropped connection / timeout — not for HTTP errors
+            // (an HTTP error is a resolved Response, not a throw, so it won't reach here).
+            await new Promise((r) => setTimeout(r, 800));
+            return attempt();
+        }
+    }
+    async request(base, path, init, auth, retried = false) {
+        const res = await this.fetchWithTimeout(`${base}${path}`, { ...init, headers: this.headers(auth) });
+        // Silent refresh: an expired CLI access token (pfk_) → rotate once and retry.
+        if (res.status === 401 &&
+            auth &&
+            !retried &&
+            this.refreshToken &&
+            this.token?.startsWith('pfk_')) {
+            try {
+                const t = await refreshCliToken(this.urls.api, this.refreshToken, this.f);
+                this.token = t.token;
+                this.refreshToken = t.refreshToken;
+                this.onRefresh?.(t.token, t.refreshToken, t.expiresAt);
+                return this.request(base, path, init, auth, true);
+            }
+            catch {
+                /* refresh failed — fall through to the normal error below */
+            }
+        }
+        let json = { success: false };
+        try {
+            json = (await res.json());
+        }
+        catch { /* non-JSON */ }
+        if (res.status === 428)
+            throw new NoSessionError();
+        if (!res.ok || json.success === false) {
+            const err = new Error(json.error || json.message || `HTTP ${res.status}`);
+            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;
+            err.details = json.details;
+            throw err;
+        }
+        return json.data;
+    }
+    get(base, path, auth = true) {
+        return this.request(base, path, { method: 'GET' }, auth);
+    }
+    post(base, path, body, auth = true) {
+        return this.request(base, path, { method: 'POST', body: JSON.stringify(body) }, auth);
+    }
+    // ── reads ──
+    getUser() { return this.get(this.urls.api, '/user'); }
+    getModuleStatus() { return this.get(this.urls.api, '/sessions/module-status'); }
+    getAssets() { return this.get(this.urls.api, '/assets', false); }
+    getMarkets() { return this.get(this.urls.api, '/markets', false); }
+    /** Balances for the authenticated user's own wallet (no wallet-id needed). */
+    getBalance() { return this.get(this.urls.api, '/balances/me'); }
+    /**
+     * Portfolio summary. Pass `'full'` to additionally fetch the multi-asset +
+     * perps breakdown (`multiAsset` block) used by the CLI/MCP; the default
+     * (gold + cash) matches what the web app reads.
+     */
+    getPortfolio(view) {
+        const q = view === 'full' ? '?view=full' : '';
+        return this.get(this.urls.api, `/portfolio/summary${q}`);
+    }
+    getPosition(collateral, loan) {
+        return this.get(this.urls.api, `/protocol/position?protocolId=morpho&market=${collateral}/${loan}`);
+    }
+    getGoldPrice() { return this.get(this.urls.api, '/prices/gold', false); }
+    /**
+     * FX rate for a fiat currency: local units per 1 USD (public endpoint).
+     * Used to convert USD-denominated amounts into the user's display currency.
+     */
+    getFiatRate(currency) {
+        return this.get(this.urls.api, `/prices/fiat/${encodeURIComponent(currency.toUpperCase())}`, false);
+    }
+    getCryptoPrices() { return this.get(this.urls.api, '/prices/crypto', false); }
+    getBorrowRate() { return this.get(this.urls.api, '/borrow/rate', false); }
+    getMarketStats() { return this.get(this.urls.api, '/borrow/market-stats', false); }
+    getTxHistory(limit = 20) { return this.get(this.urls.api, `/tx/history?limit=${limit}`); }
+    /** Authoritative per-tx status — backend re-checks the MEE explorer for non-terminal states. */
+    getTxStatus(txHash) { return this.get(this.urls.api, `/tx/status/${txHash}`); }
+    // ── Polymarket prediction markets (read-only) ──
+    /** Discover/search active prediction markets (public). */
+    polymarketMarkets(query, limit) {
+        const params = new URLSearchParams();
+        if (query)
+            params.set('q', query);
+        if (limit)
+            params.set('limit', String(limit));
+        const qs = params.toString();
+        return this.get(this.urls.api, `/polymarket/markets${qs ? `?${qs}` : ''}`, false);
+    }
+    /** One market's detail + live prices (public). */
+    polymarketMarket(id) {
+        return this.get(this.urls.api, `/polymarket/markets/${encodeURIComponent(id)}`, false);
+    }
+    /** The authenticated user's open prediction positions + portfolio totals. */
+    polymarketPositions() {
+        return this.get(this.urls.api, '/polymarket/positions');
+    }
+    /** The authenticated user's prediction trade history (most recent first). */
+    polymarketActivity(limit) {
+        const q = limit ? `?limit=${limit}` : '';
+        return this.get(this.urls.api, `/polymarket/activity${q}`);
+    }
+    /** Whether the betting (write) path is provisioned + enabled. */
+    polymarketTradingStatus() {
+        return this.get(this.urls.api, '/polymarket/trading-status');
+    }
+    /** Place a bet (buy outcome shares). Returns 503 until trading is enabled. */
+    polymarketBet(b) {
+        return this.post(this.urls.api, '/polymarket/bet', b);
+    }
+    /** Sell shares (cash out). `shares` omitted = sell all. */
+    polymarketSell(b) {
+        return this.post(this.urls.api, '/polymarket/sell', b);
+    }
+    /** Redeem winnings on a resolved market. */
+    polymarketRedeem(b) {
+        return this.post(this.urls.api, '/polymarket/redeem', b);
+    }
+    /** Deposit-wallet address + deployed status (read-only). */
+    polymarketDepositWallet() {
+        return this.get(this.urls.api, '/polymarket/deposit-wallet');
+    }
+    /** Deploy + approve the deposit wallet (gasless, autonomous via the signer). */
+    polymarketProvision() {
+        return this.post(this.urls.api, '/polymarket/provision', {});
+    }
+    /** Build a Relay USDT→pUSD funding quote to the deposit wallet (execution is separate). */
+    polymarketFundQuote(amount) {
+        return this.get(this.urls.api, `/polymarket/fund-quote?amount=${encodeURIComponent(amount)}`);
+    }
+    /** Execute USDT→pUSD funding to the deposit wallet autonomously via the DeFi session. */
+    polymarketDeposit(amount) {
+        return this.post(this.urls.api, '/polymarket/deposit', { amount });
+    }
+    /** Withdraw pUSD from the deposit wallet back to your wallet (USDT on Ethereum). */
+    polymarketWithdraw(amount) {
+        return this.post(this.urls.api, '/polymarket/withdraw', { amount });
+    }
+    /** Poll a Relay funding intent (pUSD delivery on Polygon). */
+    polymarketFundStatus(requestId) {
+        return this.get(this.urls.api, `/polymarket/fund-status?requestId=${encodeURIComponent(requestId)}`);
+    }
+    // ── swap / trade (session key) ──
+    swapQuote(b) {
+        return this.post(this.urls.api, '/swap/quote', b);
+    }
+    swap(b) {
+        return this.post(this.urls.api, '/tx/swap', b);
+    }
+    // ── borrow / collateral (session key) ──
+    supply(b) { return this.post(this.urls.api, '/tx/supply', b); }
+    borrow(b) { return this.post(this.urls.api, '/tx/borrow', b); }
+    repay(b) { return this.post(this.urls.api, '/tx/repay', b); }
+    withdrawCollateral(b) { return this.post(this.urls.api, '/tx/withdraw', b); }
+    supplyAndBorrow(b) {
+        return this.post(this.urls.api, '/tx/supply-and-borrow', b);
+    }
+    closePosition(b) { return this.post(this.urls.api, '/tx/close-position', b); }
+    // ── earn / vaults (Morpho Vault V2, session key) ──
+    /** List earn vaults (public read). Pass an asset symbol to filter. */
+    getVaults(asset) {
+        const q = asset ? `?asset=${encodeURIComponent(asset)}` : '';
+        return this.get(this.urls.api, `/protocol/vaults${q}`, false);
+    }
+    /** The authenticated user's earn position for an asset (on-chain shares + value). */
+    getEarnPosition(asset) {
+        return this.get(this.urls.api, `/protocol/vault-position?asset=${encodeURIComponent(asset)}`);
+    }
+    /** Deposit an asset into its canonical earn vault (agent-signed via the DeFi session). */
+    earnDeposit(b) { return this.post(this.urls.api, '/tx/earn-deposit', b); }
+    /** Withdraw from an earn vault — exact `amount`, or the whole position with `all: true`. */
+    earnWithdraw(b) { return this.post(this.urls.api, '/tx/earn-withdraw', b); }
+    // ── user-signed ops: prepare (CLI authed, no signing) + hand off to browser-sign ──
+    prepareWithdrawal(b) {
+        return this.post(this.urls.api, '/tx/prepare', { operation: 'withdrawal', ...b });
+    }
+    prepareGiftSend(b) {
+        return this.post(this.urls.api, '/gift/prepare-send', b);
+    }
+    /** Hand a self-describing sign task to the browser-sign relay. Returns the approve URL + sid. */
+    signStart(b) {
+        return this.post(this.urls.api, '/cli/sign/start', b);
+    }
+    // ── Hyperliquid perps (reads + trade are autonomous via the server-held agent key) ──
+    hlStatus() { return this.get(this.urls.api, '/hl/status'); }
+    /** Discover tradeable HL markets (crypto + equities/commodities/fx/indices). */
+    hlMarkets(search) {
+        const q = search ? `?search=${encodeURIComponent(search)}` : '';
+        return this.get(this.urls.api, `/hl/markets${q}`);
+    }
+    hlPositions() { return this.get(this.urls.api, '/hl/positions'); }
+    hlOrders() { return this.get(this.urls.api, '/hl/orders'); }
+    hlOrderHistory() { return this.get(this.urls.api, '/hl/order-history'); }
+    hlTradeHistory(limit) {
+        const qs = limit && limit > 0 ? `?limit=${Math.floor(limit)}` : '';
+        return this.get(this.urls.api, `/hl/history${qs}`);
+    }
+    hlPrice(asset) {
+        const q = asset ? `?asset=${encodeURIComponent(asset)}` : '';
+        return this.get(this.urls.api, `/hl/price${q}`);
+    }
+    hlSetup() { return this.post(this.urls.api, '/hl/setup', {}); }
+    hlOpen(b) { return this.post(this.urls.api, '/hl/open', b); }
+    hlClose(b) { return this.post(this.urls.api, '/hl/close', b); }
+    hlSetLeverage(b) { return this.post(this.urls.api, '/hl/leverage', b); }
+    hlTpsl(b) {
+        return this.post(this.urls.api, '/hl/tpsl', b);
+    }
+    hlCancelOrder(b) { return this.post(this.urls.api, '/hl/cancel-order', b); }
+    /**
+     * Autonomous USDT → Hyperliquid deposit. Hits POST /tx/bridge-deposit, which
+     * builds the USDT-approve + Across bridge calls and executes them via the
+     * Biconomy session grant (agent-signed) — no user signature, no browser.
+     * (The old /hl/deposit/one-click only PREPARED calldata and executed nothing,
+     * so its "submitted" was a false positive that moved no funds.)
+     */
+    hlDeposit(b) { return this.post(this.urls.api, '/tx/bridge-deposit', b); }
+    /** Autonomous HL → Ethereum withdrawal (server-signs via Privy; no browser). */
+    hlWithdraw(b) {
+        return this.post(this.urls.api, '/hl/withdraw-to-evm/execute', b);
+    }
+    /** Poll a HL→Ethereum withdrawal to completion (Relay canonical status + delivery tx hashes). */
+    hlWithdrawStatus(requestId) {
+        return this.get(this.urls.api, `/hl/withdraw-to-evm/status/${encodeURIComponent(requestId)}`);
+    }
+    // ── fiat / account (reads + settings) ──
+    kycStatus() { return this.get(this.urls.fiat, '/kyc/status'); }
+    /** Provider (Roma) accounts — fiat accounts carry bankDetails for deposits. Auto-provisioned after KYC. */
+    getAccounts() { return this.get(this.urls.fiat, '/accounts'); }
+    beneficiaries() { return this.get(this.urls.fiat, '/beneficiaries'); }
+    fiatQuote(b) {
+        return this.post(this.urls.fiat, '/payout/quote', b);
+    }
+    giftsSent() { return this.get(this.urls.api, '/gift/sent'); }
+    giftsReceived() { return this.get(this.urls.api, '/gift/received'); }
+    updateSettings(b) {
+        return this.request(this.urls.api, '/user', { method: 'PATCH', body: JSON.stringify(b) }, true);
+    }
+}

package/dist/lib/config.js

@@ -0,0 +1,46 @@
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+/**
+ * Backend base URLs — env-overridable, production defaults.
+ *
+ * Money side = Perfolio backend; Agent side = Agent-mode backend. Set the env
+ * vars (e.g. in the package-root `.env`) to repoint at dev/staging without
+ * touching code. You don't need final URLs to build — the agent default is a
+ * placeholder; override GRANTCASH_AGENT_URL when it's known.
+ */
+export function baseUrls(env = process.env) {
+    return {
+        api: env.GRANTCASH_API_URL || "https://api.perfolio.ai/api",
+        fiat: env.GRANTCASH_FIAT_URL || "https://api-fiat.perfolio.ai/api",
+        app: env.GRANTCASH_APP_URL || "https://app.perfolio.ai",
+        agent: env.GRANTCASH_AGENT_URL || "https://api-agent.perfolio.ai",
+    };
+}
+export function resolveCredsPath(flag, env = process.env) {
+    if (flag)
+        return flag;
+    if (env.GRANTCASH_CREDS_FILE)
+        return env.GRANTCASH_CREDS_FILE;
+    return join(homedir(), ".grant-cash", "credentials.json");
+}
+export function loadCredentials(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveCredentials(creds, path) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+}
+export function clearCredentials(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* already gone */
+    }
+}

package/dist/lib/context.js

@@ -0,0 +1,35 @@
+import { baseUrls, resolveCredsPath, loadCredentials, saveCredentials, } from "./config.js";
+import { MoneyClient } from "./money-client.js";
+import { AgentClient } from "./agent-client.js";
+import { isJsonMode } from "./output.js";
+export function buildContext(cmd) {
+    // Global opts live on the root program; optsWithGlobals merges them in.
+    const opts = cmd.optsWithGlobals();
+    const urls = baseUrls();
+    const credsPath = resolveCredsPath(opts.credsFile);
+    const creds = loadCredentials(credsPath);
+    const json = isJsonMode(opts.json);
+    const save = (next) => {
+        saveCredentials(next, credsPath);
+        ctx.creds = next;
+    };
+    const money = new MoneyClient({
+        api: urls.api,
+        fiat: urls.fiat,
+        token: creds.money?.token,
+        refreshToken: creds.money?.refreshToken,
+        onRefresh: (token, refreshToken, expiresAt) => {
+            const next = {
+                ...ctx.creds,
+                money: { ...ctx.creds.money, token, refreshToken, expiresAt },
+            };
+            save(next);
+        },
+    });
+    const agent = new AgentClient({
+        agent: urls.agent,
+        apiKey: creds.agent?.apiKey,
+    });
+    const ctx = { urls, creds, credsPath, json, money, agent, save };
+    return ctx;
+}