<div align="center">

# hoodr

**The open-source agent for trading tokenized stocks on-chain.**

Spot & perpetuals on [Robinhood Chain](https://robinhoodchain.blockscout.com) — from your terminal, from any AI chat, or as a hosted service. Non-custodial by design: your keys stay on your machine (or in your own Turnkey session), encrypted, never sent to a model.

[![npm](https://img.shields.io/npm/v/@hoodrhq/cli?color=c5ff00&label=%40hoodrhq%2Fcli)](https://www.npmjs.com/package/@hoodrhq/cli)
[![ci](https://github.com/hoodrHQ/hoodr-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/hoodrHQ/hoodr-cli/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/@hoodrhq/cli?color=blue)](LICENSE)
[![node](https://img.shields.io/node/v/@hoodrhq/cli)](https://nodejs.org)

[Quick start](#quick-start) · [Commands](#commands) · [AI chat](#drive-it-from-any-ai-chat) · [Hosting](docs/HOSTED.md) · [Architecture](docs/ARCHITECTURE.md)

</div>

---

```bash
npm i -g @hoodrhq/cli      # or: npx @hoodrhq/cli
```

## Why hoodr

- **Trade real assets, not memecoins** — tokenized NVDA, TSLA, GOOGL, SPY, QQQ and more, priced on-chain.
- **Non-custodial** — a local encrypted keystore, or per-user Turnkey delegated sessions. hoodr never holds your funds.
- **Hard spending caps** — enforced in code (and in-enclave for hosted mode); a misbehaving script or model can't exceed them.
- **Drive it however you like** — deterministic CLI, background automation daemon, local MCP, or a hosted remote-MCP + REST/OpenAPI server that any AI chat can call.

## Quick start

```bash
hoodr wallet new                 # create an encrypted local wallet
hoodr balance                    # ETH + stock positions
hoodr quote buy NVDA 0.05        # preview a trade (read-only, no wallet needed)
hoodr buy NVDA 0.05              # spend 0.05 ETH on NVDA
hoodr sell NVDA 50%              # sell half your NVDA back to ETH
```

Supported stocks today: **NVDA, TSLA, GOOGL** (or pass any tokenized-stock `0x` address).
Every trade routes through the on-chain **StockRouter** (`ETH ↔ USDG ↔ stock`) over the deep 0.3% USDG pools.

## Commands

| Command | What it does |
|---|---|
| `hoodr wallet new [--import <key>]` | Create/import an encrypted wallet (`~/.hoodr/keystore.json`) |
| `hoodr wallet address` | Show your address |
| `hoodr wallet export` | Reveal the private key (asks to confirm) |
| `hoodr balance [--address 0x…]` | ETH + stock balances |
| `hoodr quote <buy\|sell> <TICKER> <amount>` | Read-only price preview |
| `hoodr buy <TICKER> <ethAmount\|$usd>` | Buy a stock (amount in ETH **or** USD, e.g. `$50`) |
| `hoodr sell <TICKER> <amount\|NN%>` | Sell a stock for ETH |
| `hoodr send <ETH\|TICKER> <amount> <to>` | Send ETH or a stock to an address |
| `hoodr usdg <ethAmount\|$usd>` | Swap ETH → USDG (perp collateral) |
| `hoodr positions [--address 0x…]` | List open perp positions |
| `hoodr long <TICKER> --lev 3 --margin 50` | Open a leveraged long (USDG collateral) |
| `hoodr short <TICKER> --lev 3 --margin 50` | Open a leveraged short |
| `hoodr close <id>` | Close a perp position |
| `hoodr dca <TICKER> <$usd> --every 1d` | Schedule a recurring buy |
| `hoodr limit <buy\|sell> <TICKER> --at <usd> …` | Schedule a limit order |
| `hoodr stop <TICKER> --at <usd> --amount <n\|NN%>` | Schedule a stop-loss |
| `hoodr jobs` / `hoodr jobs rm <id>` | List / remove scheduled jobs |
| `hoodr daemon` | Run the automation loop (executes the above) |
| `hoodr mcp` | Run as an MCP server so an AI client can drive hoodr |

Global flags: `--json` (machine output), `-y/--yes` (skip confirmations), `--slippage <bps>`.

Amounts for `buy` / `usdg` / `send ETH` accept **ETH** (`0.05`) or **USD** (`$50` / `50usd`) — USD converts on-chain via the WETH/USDG pool. `balance` shows live USD values.

Perp markets: NVDA, TSLA, AAPL, AMZN, GOOGL, META, MSFT, COIN, PLTR, AMD, INTC, MU, ORCL, CRCL, CRWV, QQQ, SPY, SLV. Perps settle in **USDG** collateral.

## Automation (recurring, limit, stop)

Schedule orders, then run the daemon to execute them — all local, using your key, capped:

```bash
hoodr dca NVDA $50 --every 1d               # buy $50 of NVDA daily
hoodr limit buy TSLA --at 240 --usd 100     # buy $100 when TSLA ≤ $240
hoodr limit sell NVDA --at 250 --amount 50% # sell half when NVDA ≥ $250
hoodr stop NVDA --at 180 --amount 100%      # stop-loss: sell all if NVDA ≤ $180
hoodr jobs                                  # list scheduled jobs
hoodr daemon                                # run the loop (Ctrl-C to stop)
```

Jobs live in `~/.hoodr/jobs.json`; the daemon re-reads them each poll, so you can add/remove while it runs. Triggers are one-shot; DCAs repeat. Every fill goes through the same spending caps. An AI (via MCP) can schedule these too — but a local `hoodr daemon` must be running to execute them.

## Drive it from any AI chat

**Local** — `hoodr mcp` exposes every command as [MCP](https://modelcontextprotocol.io) tools for **Claude Desktop, Claude Code, Cursor**, or any MCP host; the key stays on your machine. Point the assistant at [`SKILL.md`](SKILL.md) and talk:

> "read the hoodr skill — what's my balance? Quote 0.05 ETH into NVDA and buy it if it looks good."

Setup: [`docs/SETUP.md`](docs/SETUP.md).

**Hosted (any chat)** — `hoodr serve` runs one server exposing **remote MCP** (`/mcp`) *and* a **REST + OpenAPI** surface (`/api/*`, `/openapi.json`) behind a bearer token. That covers every way chats call tools: MCP connectors (Claude, ChatGPT, Cursor), custom GPT Actions (OpenAPI), and code-execution chats (Grok etc. `curl` the REST API). Same tool code, same caps, key stays on the server.

```bash
export HOODR_PRIVATE_KEY=0x…  HOODR_API_TOKEN=$(openssl rand -hex 24)
hoodr serve --port 8790
```

**Multi-tenant** — set `HOODR_MULTI_TENANT=1` and one server signs for many users, each via their **own non-custodial Turnkey delegated session** (the server holds no root, no funds). Enroll users with `hoodr tenants add …` → each gets a Bearer token that maps to their capped session.

Per-platform connect steps, the multi-tenant flow, and security in [`docs/HOSTED.md`](docs/HOSTED.md).

## Spending limits (the safety leash)

Every trade is capped, enforced in code — a misbehaving script or AI cannot exceed them:

```bash
HOODR_MAX_TRADE_ETH=0.5    # max ETH per buy/send
HOODR_DAILY_CAP_ETH=2      # max ETH per UTC day
HOODR_MAX_MARGIN_USD=100   # max USDG margin per perp
```

## Headless / AI-agent mode

The CLI is built to be driven by scripts and AI agents. Run it non-interactively:

```bash
export HOODR_PRIVATE_KEY=0x…     # sign from an env key (use a scoped/burner key!)
export HOODR_JSON=1              # JSON on stdout
export HOODR_YES=1               # no prompts
hoodr buy NVDA 0.05
# → {"ok":true,"action":"buy","stock":"NVDA","tx":"0x…","explorer":"https://…"}
```

Or keep the encrypted keystore and just supply its password: `HOODR_KEYSTORE_PASSWORD=…`.

## Safety

- Private key is AES-256-GCM encrypted at rest, decrypted only at signing time, **never** transmitted.
- Every mutating command confirms first (bypass with `--yes`) and enforces on-chain `minOut` slippage.
- For agent use, prefer a **burner/scoped key** with limited funds — treat any AI that can call `buy`/`sell` as able to spend the whole balance.

## Config

All optional; Robinhood Chain mainnet defaults are baked in. See [`.env.example`](.env.example).

## Development

```bash
npm install
npm run dev -- balance          # run the CLI from source (tsx)
npm test                        # unit tests (node:test) — pure logic, no network
npm run typecheck && npm run build
```

Tests cover the deterministic paths (stock/market resolution, keystore round-trip, spending-cap ledger, perp sizing, USD parsing). Trading paths are exercised against live mainnet via the CLI.

### Publishing

`prepublishOnly` runs typecheck + tests + build. To release:

```bash
npm publish --access public     # publishes @hoodrhq/cli (run `npm login` as hoodrhq first)
```

The tarball ships only `dist/` + docs (no source or tests) — ~22 kB.

## License

MIT — see [LICENSE](LICENSE).