@agentgrant.cash/cli 1.0.0

package/dist/lib/verify.js

@@ -0,0 +1,38 @@
+/** Terminal backend states. (Source: backend TxStatus = submitted|processing|executing|success|failed.) */
+const TERMINAL = new Set(['success', 'failed']);
+/**
+ * After a session-key write, never trust "submitted". Poll the authoritative
+ * per-tx status endpoint (which re-checks the MEE explorer for non-terminal
+ * states) for THIS exact txHash until it reaches success/failed or we time out.
+ *
+ * Correlating by txHash is essential: reading "the latest history row" can
+ * confirm a different transaction. MEE/cross-chain settlement can take a while,
+ * so the timeout is generous.
+ */
+export async function waitForTx(client, txHash, opts = {}) {
+    if (!txHash)
+        return { status: 'timeout' };
+    const timeout = opts.timeoutMs ?? 180_000; // 3 min — MEE/cross-chain headroom
+    const interval = opts.intervalMs ?? 4_000;
+    // A just-submitted tx isn't queryable for a beat (the DB row commits slightly
+    // after the submit response). Wait once up front so the FIRST poll doesn't 404
+    // — the backend logs every 404 as a client-error warning otherwise.
+    const initialDelay = opts.initialDelayMs ?? 2_500;
+    const start = Date.now();
+    let last;
+    if (initialDelay > 0)
+        await new Promise((r) => setTimeout(r, initialDelay));
+    while (Date.now() - start < timeout) {
+        try {
+            last = await client.getTxStatus(txHash);
+            if (last && TERMINAL.has(last.status)) {
+                return { status: last.status, txHash, receipt: last.receipt };
+            }
+        }
+        catch {
+            // 404 right after submit (row not indexed yet) or a transient blip — keep polling.
+        }
+        await new Promise((r) => setTimeout(r, interval));
+    }
+    return { status: last?.status === 'failed' ? 'failed' : 'timeout', txHash, receipt: last?.receipt };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@agentgrant.cash/cli",
+  "version": "1.0.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": {
+    "grant": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".env.example",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "dev": "tsx src/cli/index.ts",
+    "start": "node dist/cli/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/skills/grant-cash/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: grant-cash
+description: One assistant for your money — Grant Cash. Grow and hold money (gold, bitcoin, ethereum, cash, borrowing, earning yield, leveraged trading, prediction markets) and spend it (have your agent find and pay for live services, send money) — all in plain language, one sign-in. Check your worth, invest, cash out, and manage spending limits without any jargon, keys, or addresses.
+---
+
+# Grant Cash
+
+Grant Cash is **one** assistant for your money. There is only ever one Grant Cash — one sign-in, one combined worth, one history. Inside it, money does two things:
+
+- **Investments** — grow and hold money. Hold gold, bitcoin, ethereum and cash; borrow cash against what you hold; earn yield; trade with leverage; and bet on real-world outcomes (prediction markets). All valued in your own currency.
+- **Spending** — get things done. Your agent finds and pays for live services on demand (search the web, read the news, research a company, generate images, and more), and you can send money. It pays a few cents only when it actually does something, inside the limits you set.
+
+These are **two sides of the same Grant Cash account**, not two separate apps or services. `grant portfolio` shows both together: an **Investments** section and a **Spending** section. The user never deals with anything technical — no jargon, no keys, no addresses, no chains. **Money can only ever come back to the user.** `grant revoke` stops all agent spending instantly.
+
+> Note for assistants: do **not** describe this as a "portfolio service" plus an "agent service", and never mention internal system names. It is one product — Grant Cash — with an Investments side and a Spending side. Speak plainly: gold, cash, bitcoin, ethereum, "your worth", "spending money".
+
+## 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"}}`.
+- `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.
+
+## Workflow
+
+1. `grant status` — confirm you're connected (both Investments and Spending).
+2. `grant portfolio` — combined worth: the Investments side (gold, cash, bitcoin, ethereum, leveraged positions, prediction balance, earnings) and the Spending side, in one place.
+3. Invest: `grant prices`, then `grant buy <asset> --amount <cash>` / `grant sell <asset> --for <cash>`.
+4. Spend: `grant search "<q>"` → `grant check <url>` (no charge) → `grant fetch <url> -b '<json>'`.
+5. `grant activity` — one feed of everything that's happened, newest first.
+6. `grant revoke` — stop all agent spending immediately.
+
+## Commands
+
+### Connect (one sign-in for the whole account)
+- `grant login` — sign in and approve your spending limits in the browser; connects both Investments and Spending in one step.
+- `grant logout` — sign out and clear what's stored on this machine.
+- `grant status` (alias `whoami`) — show what's connected and where.
+- `grant devices list` — list the agents/devices connected to your account.
+- `grant devices revoke <deviceId>` — disconnect one device.
+
+### Your worth
+- `grant portfolio` (alias `balance`) — combined worth: Investments + Spending, in your currency. Includes gold, cash, bitcoin, ethereum, leveraged positions, your prediction balance and open bets, and anything you're earning.
+- `grant prices` — current prices for gold, bitcoin, ethereum, cash.
+- `grant price` (alias `gold`) — today's gold price.
+- `grant assets` — what you can hold. `grant markets` — what you can borrow against. `grant rate [--against <asset>]` — the current borrow rate.
+- `grant activity` (alias `history`) — everything that's happened, newest first.
+
+### Investments — buy, sell, convert
+- `grant buy <asset> --amount <cash>` — buy gold, bitcoin or ethereum with cash. (e.g. `grant buy gold --amount 50`)
+- `grant sell <asset> --amount <qty>` or `--for <cash>` — sell by quantity or by cash value.
+- `grant convert --from <asset> --to <asset> --amount <qty>|--for <cash>` — move directly between assets.
+- `grant quote --from <asset> --to <asset> --amount <qty>|--for <cash>` — preview a trade, no execution.
+
+### Investments — borrow cash against what you hold
+- `grant borrow --against <asset> --amount <cash>` — borrow cash against an asset.
+- `grant repay --against <asset> --amount <cash>` — repay borrowed cash.
+- `grant add-collateral --asset <asset> --amount <qty>` / `grant remove-collateral --asset <asset> --amount <qty>`.
+- `grant leverage --asset <asset> --deposit <qty> --borrow <cash>` — add collateral and borrow in one step.
+- `grant close --against <asset>` — repay everything and withdraw the collateral.
+- `grant loans` — your open "cash borrowed against X" positions. `grant position --against <asset>` — detail for one.
+
+### Investments — earn yield
+- `grant earn list [--asset <asset>]` — vaults with current rates and size.
+- `grant earn position --asset <asset>` — what you have staked, plus earnings.
+- `grant earn deposit --asset <asset> --amount <n>` (alias `open`) — start or add to an earning position.
+- `grant earn withdraw --asset <asset> [--amount <n> | --all]` — take money back out.
+
+### Investments — trade with leverage (long or short, many markets)
+- `grant hl markets [--search <q>]` — discover what you can trade (stocks, crypto, commodities, fx, indices).
+- `grant hl status` / `grant hl positions` / `grant hl orders` / `grant hl history` — your trading state.
+- `grant hl price [--asset <symbol>]` — live price for a market.
+- `grant hl setup [--fund <cash>]` — turn on leveraged trading (one-time, funds first if needed).
+- `grant hl deposit --amount <cash>` / `grant hl withdraw --amount <cash>` — move cash in and out of trading.
+- `grant hl open --side <long|short> --size <usd> --leverage <n> [--asset <symbol>]` — open a position.
+- `grant hl close [--asset <symbol>]` — close a position.
+- `grant hl leverage --set <n> [--isolated]` — set leverage.
+- `grant hl tpsl --asset <symbol> --side <long|short> --size <n> [--tp <price>] [--sl <price>]` — take-profit / stop-loss.
+- `grant hl cancel <orderId> [--asset <symbol>]` — cancel an order.
+
+### Investments — prediction markets (bet on real-world outcomes)
+- `grant polymarket markets [--search <q>] [--limit <n>]` — browse or search markets.
+- `grant polymarket wallet` — your **prediction balance** (cash available to bet) and readiness.
+- `grant polymarket provision` — set up your prediction account (one-time, no signing).
+- `grant polymarket deposit <cash>` — add cash to your prediction balance.
+- `grant polymarket bet <marketId> --side <yes|no> --amount <cash> [--limit <price>]` — place a bet.
+- `grant polymarket cashout <marketId> [--shares <n>]` — sell your shares before the market resolves.
+- `grant polymarket redeem <marketId>` — claim winnings on a resolved market.
+- `grant polymarket positions` — your open bets and totals. `grant polymarket history` — your prediction trades.
+- `grant polymarket withdraw <cash>` — move cash from your prediction balance back to your account.
+- `grant polymarket fund-status <requestId>` — check whether added funds have landed.
+
+### Investments — cash, identity, gifts
+- `grant deposit` — your address for adding funds to your account.
+- `grant kyc status` / `grant kyc start` — verify your identity (opens the browser).
+- `grant fiat deposit [--currency <code>]` — bank-transfer details for adding cash. `grant fiat quote --amount <cash> --currency <code>` — a cash-out quote.
+- `grant withdraw --to <address> --amount <cash>` — withdraw cash to an external wallet (browser approval).
+- `grant gift send --to <email|phone> --amount <gold> [--message <text>]` — send a gold gift. `grant gifts` — gifts sent and received.
+- `grant beneficiaries` — your payout bank accounts.
+- `grant settings set [--currency <code>] [--country <code>] [--display <usd|local>] [--gold-unit <oz|g>] [--mode <simple|advanced>]` — preferences.
+
+### Spending — your agent gets things done
+- `grant search "<query>" [--limit <n>]` (alias `marketplace`) — find a live service your agent can use.
+- `grant discover <origin>` (alias `add`) — add any new service origin so its endpoints become findable.
+- `grant check <url>` — see exactly what a service costs and needs, before paying (no charge).
+- `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.
+- `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.
+
+### 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.
+- `grant instructions` — this workflow + how to recover from errors (machine-readable with `--json`).
+- `grant config show` — where things route and what's connected. `grant install` — connect this to an AI assistant you already use.
+
+## When something goes wrong
+
+| code | retry? | what to do |
+|---|---|---|
+| `NOT_CONNECTED` | no | Run `grant login`. |
+| `NO_SESSION` | no | No spending permission set — `grant login` and approve your limits. |
+| `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. |
+| `BACKEND_UNREACHABLE` | no | Wrong or unreachable address — check the connection with `grant config show`. |
+| `NETWORK` | yes | Temporary — retry once. |
+
+## Examples
+
+```
+grant status                                          # are we connected?
+grant portfolio                                       # combined worth — Investments + Spending
+grant prices                                          # gold, bitcoin, ethereum, cash
+grant buy gold --amount 50                            # invest $50 in gold
+grant sell bitcoin --for 100                          # sell $100 of bitcoin
+grant borrow --against gold --amount 200              # borrow $200 against gold
+grant earn deposit --asset cash --amount 500          # earn yield on cash
+grant hl open --side long --size 100 --leverage 3 --asset BTC   # leveraged trade
+grant polymarket markets --search election            # browse prediction markets
+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 activity --json                                 # full combined history
+grant revoke                                           # stop all agent spending
+```