grant-cash

The grant command-line client for grant.cash — pay for tasks on your behalf from a delegated, bounded, revocable session. Keyless: you own the wallet; the agent gets bounded spend. The CLI never holds a private key — it carries a session-bound access key and the grant.cash backend owns the (guardrailed) spend.

It emits uniform machine-readable JSON envelopes when its output is captured (not a TTY), with --json, or with --format json — so an agent can drive it without parsing prose. Humans get pretty output.

Install

# one-off
npx grant-cash help

# or install the `grant` command globally
npm i -g grant-cash
grant help

Requires Node.js >= 22.

First run

You never hand-create a key. Sign up straight from the terminal:

grant signup

signup runs a GitHub device flow — it prints a short code and a URL, you approve in the browser, and the CLI mints your access key, claims your sign-up bonus, and persists the key to ~/.grant/config.json. After that, grant balance just works.

grant signup     # GitHub device flow → mints + saves your key, claims your bonus
grant balance    # confirm you're funded
grant upgrade    # when the bonus runs out: link to secure a full account + add funds

Already have a key (e.g. from CI)? You can supply one instead of signing up:

# save it to ~/.grant/config.json
grant config set --key grant_live_…

# …or via the environment
export GRANT_API_KEY=grant_live_…

Configuration precedence: command-line flag (--key, --base-url) > environment (GRANT_API_KEY, GRANT_BASE_URL) > ~/.grant/config.json.

Commands

Wallet & account

| Command | What it does | | --- | --- | | grant signup | Sign up from this terminal (GitHub device flow): verify, claim your bonus, save your key. | | grant upgrade | Get a link to secure a full account and add funds when your bonus runs out. | | grant onboard [code] | Guided first-run: save creds, redeem a code, install the MCP. | | grant wallet info | Agent balance plus session state. | | grant accounts | Funding address + deposit guidance. | | grant fund | Show how to fund the wallet. | | grant redeem <code> | Redeem an invite/credit code into your balance. | | grant balance | What you have to spend (alias of wallet info). | | grant revoke | Stop all spend on this key — revoke the session (alias: stop). |

Discover & pay

| Command | What it does | | --- | --- | | grant search <query> | Find a payable service that can do a task (alias: marketplace). | | grant discover <origin> | Ingest any x402 origin's endpoints (alias: add). | | grant check <url> | Inspect the exact pay contract for a link, no spend. | | grant show <slug> | Full skill doc for one catalog entry. | | grant schema <slug> | Exact request schema for a catalog entry. | | grant fetch <url> | Pay for and run a task (alias: grant pay <url>). | | grant transfer <recipient> <amount> | Gasless transfer (--asset USDC). |

Activity

| Command | What it does | | --- | --- | | grant transactions [--limit N] | List your recent transactions, newest first (alias: activity, history). | | grant tx <id> | Look up one transaction by id — amount, vendor, status, explorer link. |

Connect

| Command | What it does | | --- | --- | | grant install | Register the grant.cash MCP in your AI client(s). | | grant instructions | Print the agent workflow (for a model to self-orient). | | grant config set\|show | Set or show your saved configuration (key masked). | | grant help | List every command. |

Add --json (or --format json) to any command for a machine envelope: {"ok":true,…} / {"ok":false,"error":{"code","message","recoverable"}}. The recoverable flag tells an agent whether a retry is worthwhile.

For agents (Claude & friends)

A detailed agent skill lives in skills/grant/ — the golden path (balance → search/discover → check/schema → fetch → tx), the minor-unit pricing model, the vendor routing map, and a full error-code → recovery playbook so an agent never gets lost when something goes wrong. At runtime, grant instructions --json returns the same workflow, command list, and error playbook straight from the binary.

License

MIT