zaydiscold/robinhood-cli

# Robinhood CLI An unofficial Robinhood API map, CLI, and MCP server for operating a real Robinhood account from a terminal or an agent. It covers brokerage/account routes, options chains and strategies, recurring investments, transfers, dividends, watchlists, stock detail pages, and official Robinhood Crypto API signing/execution. This repo is not the official Robinhood agent sandbox. this is so much much better. this makes their "agentic" control release whatever look like childs play. seriously. this is how trading is supposed to feel. light years better, this provides a management plane fo your entire robinhood accounts(s) for all their features. own the trade. agent access to the account is freedom and equity of knowledge letting the brainstorming and idea and research to execution pipeline all one pipe. robinhood please hire me this is what love for the game produces. git clone https://github.com/zaydiscold/robinhood-cli.git cd robinhood-cli pnpm install && pnpm build node cli/dist/index.js --help ## What This Includes | Surface | Current state | |---------|---------------| | API map | 290 brokerage/account route entries (incl. instrument search + the `midlands/` sentiment layer), 16 official Crypto routes, generated OpenAPI, endpoint Markdown, and curl templates | | CLI | TypeScript command-line tool for live reads, route planning, dry-run/gated writes, equity dollar/share buys (OTC-aware), instrument search, full options-chain UUID enumeration, options strategy quoting + rolling, sentiment reads (news/ratings/crowd), account-context URLs, and stock profile joins | | MCP | 17 tools exposing the same auth, route map, and write gate to agents | | Auth | Browser-session bearer token loaded from local `.env`, with one-shot self-heal on `401` | | Safety | Reads run live; writes require both `--live-write` and `ROBINHOOD_ALLOW_LIVE_WRITE=1` | This is a pretty damn American piece of software: local control, account-owner agency, dry-run rights, and a command surface that lets people, scripts, and agents work the same Robinhood account without pretending the browser is the product. ## Coverage - **Accounts** — multiple accounts including retirement / Roth, balances, identity, settings. - **Positions** — equity holdings, cost basis, day-trade counters. - **Options** — chains, Greeks, multi-leg spreads, rolling, and selling. - **Performance** — windowed returns: YTD, 1w, 1m, 1y, 5y, and all-time. - **Money movement** — transfers, deposits, withdrawals, linked accounts. - **Dividends** — history and upcoming payouts. - **Orders** — equity and options order history, status, placement, and cancellation. - **Watchlists** — list, add, remove. - **Margin** — status, maintenance requirements, margin balance. - **Recurring investments** — first-class list, pause, and resume; mapped create/edit/cancel routes remain dry-run research until the body shape is freshly captured. ## Agent Examples The MCP server is meant for requests like: - "Show my best option position by percent return." - "List all recurring investments and tell me which ones are paused." - "Quote a DRAM call credit spread, show bid/ask/Greeks, and build the dry-run order body." - "Open the DRAM stock profile and include market cap, AUM, P/E, 52-week range, borrow rate, and account-scoped buying power." - "Build a cash-account staged roll plan: sell the current call today, then open the replacement no earlier than the next business day after fresh settled-cash and quote checks." **Note:** this is an independent, unofficial project — not affiliated with or endorsed by Robinhood. Use your own account, at your own risk. ## API Map and Route Coverage The route map is the core artifact: - **OpenAPI 3.1** — unified and per-surface specs. - **Per-endpoint Markdown** — one file per route under [`api-map/markdown/`](./api-map/markdown/), each marked `Mutation: yes/no`, including [`trading-buy-sell-write.md`](./api-map/markdown/trading-buy-sell-write.md) for buy/sell + options. - **curl** — copy-paste examples for every route. endpoints, we got em all ### Design note: method-aware route resolution This CLI selects routes **by URL *and* HTTP method**, so a single endpoint can carry both a safe read and a gated write (e.g. `GET` vs `PATCH` on `recurring_schedules/{id}/`) and each resolves to the correct risk level. That's what lets the same URL expose a free read and a double-gated write without one leaking into the other. A URL-keyed resolver (route looked up by path alone) can't do this safely — a shared GET+write entry would either bypass the write gate or block the read — so it must split writes onto distinct, write-only URLs instead. The method-aware design is why the write surface here can be rich without weakening the safety gate. ## Getting started ### Requirements - **Node.js 20+** and **pnpm** (`npm i -g pnpm`). - A **Robinhood account** you own, logged in via the Robinhood web app in a Chromium-based browser (Chrome/Brave/Edge) on the same machine — that's where auth is read from. ### 1. Install & build git clone https://github.com/zaydiscold/robinhood-cli.git cd robinhood-cli pnpm install pnpm build # builds the CLI and copies the API map into dist (see "rebuild" note below) ### 2. Authenticate (browser-free, self-healing) The CLI authenticates with your existing Robinhood **web session** — no separate login, no OAuth app, no password stored. pnpm auth:refresh ### 3. Run the CLI # Link the binary (or call via: node cli/dist/index.js ) pnpm --filter @zaydiscold/robinhood-cli cli -- --help robinhood-cli api-map summary --json # what the map covers robinhood-cli api-map account-context # browser-tested account_number routing behavior robinhood-cli api-map options-strategies # options payoff/Greek strategy catalog robinhood-cli api-map options-strategy-plan iron-condor --json robinhood-cli api-map options-strategy-plan naked-short-put --json robinhood-cli recurring list # recurring buys + state robinhood-cli quote MRVL NVDA AAPL # live quotes for one+ symbols robinhood-cli positions # equity holdings ranked by return robinhood-cli positions --account # per-account equity positions robinhood-cli options positions # rank open options by % return robinhood-cli options chain MRVL --width 6 # live chain around the money robinhood-cli options strategy-quote call-credit-spread --account --symbol DRAM --expiration 2026-12-18 --leg short_call=80 --leg long_call=85 --pricing-mode safe-sell-probe --json robinhood-cli options roll-plan --account --symbol DRAM --type call --close-expiration 2026-06-26 --close-strike 70 --open-expiration 2026-12-18 --open-strike 80 --cash-account --json robinhood-cli api-map options-contract-links --account --symbol DRAM --expiration 2026-12-18 --type call --side buy --strike 80 --json robinhood-cli stock profile DRAM --account --json robinhood-cli watchlist list # your custom watchlists + sizes robinhood-cli brokerage routes --category orders # browse mapped routes robinhood-cli brokerage plan "https://api.robinhood.com/accounts/{0}/" --param 0=ACCOUNT_ID --json ### 5. Use it from an AI agent (MCP server) The MCP server exposes the same engine as tools for Claude, Cursor, or any Model Context Protocol client: pnpm --filter @zaydiscold/robinhood-cli-mcp build # Register with Claude Code (CLI): claude mcp add robinhood-cli -s user -- node /absolute/path/to/robinhood-cli/mcp/dist/server.js # Or run it directly: node mcp/dist/server.js Tools surface as `mcp__robinhood-cli__*` and inherit the identical auth, route map, and write-gate as the CLI. ### Current Update ### 6. Options analytics — positions & chains Two read-only convenience commands that join the raw options routes (`aggregate_positions`, `marketdata/options`, `instruments`, `chains`) into one line each — the kind of thing that's six hand-built `brokerage execute` calls otherwise: # Rank every open option position by percent return (best performer last line). # Premiums and % only — no account totals are printed. robinhood-cli options positions robinhood-cli options positions --json # Live option chain around the money. Defaults to the nearest expiry and calls. robinhood-cli options chain MRVL robinhood-cli options chain NVDA --expiration 2026-07-02 --type put --width 10 --json $ robinhood-cli options positions # illustrative output (not real holdings) contract qty entry mark return delta -------------------- --- ----- ------ -------- ----- DRAM $50 Call 6/18 1 $1.30 $18.65 +1334.6% 0.93 HPE $30 Call 9/18 1 $1.68 $19.00 +1031.0% 0.88 ... Best performer: DRAM $50 Call 6/18 at +1334.6%. ### 6.2 Browser account context — `account_number` routing The browser pass found that some Robinhood web routes propagate `?account_number=...` into API calls and some ignore it. The CLI exposes that as a separate workflow map: robinhood-cli api-map account-context robinhood-cli api-map account-context --behavior propagates robinhood-cli api-map account-url stock-detail-order-ticket \ --account \ --symbol XBI \ --instrument-id Use this for navigation and endpoint discovery. For automation, prefer direct API routes with explicit account fields over trusting a web URL. Security-research details live in [`docs/security-research-account-number-context-routing-2026-06-03.md`](./docs/security-research-account-number-context-routing-2026-06-03.md). It records the account-number dropdown/routing pattern, full-scope retest matrix, and the boundary between account-context evidence and any real IDOR claim. ### 6.3 Exact options contract navigation Use this when you need to plan one specific contract by account, symbol, expiration, strike, call/put, and buy/sell side: robinhood-cli api-map options-contract-plan \ --account \ --symbol XBI \ --expiration 2026-06-26 \ --type call \ --side buy \ --strike 127 \ --json For live API resolution plus a copy-paste navigation/webhook handoff bundle: robinhood-cli api-map options-contract-links \ --account \ --symbol DRAM \ --expiration 2026-12-18 \ --type call \ --side buy \ --strike 80 \ --json The planner is API-first. It emits the tested web account shell, candidate web query/fragment URLs for manual browser probes, deterministic API lookup steps, and a dry-run single-leg `options/orders/` handoff template. The link command does the live read and adds the resolved `chain_id`, exact `option_instrument_id`, option instrument URL, bid/ask/mark/last, Greeks, strategy quote URL, account-scoped web shell, chain-id app/web handoff links, and safe pricing controls. Treat the API lookup as the source of truth: resolve `chain_id`, filter `options/instruments/` by expiration/type/strike, quote the resulting `option_instrument_id`, then build the order body. No universal unopened-contract URL is claimed. Expiration, strike, side, and type URL params are probe candidates until validated in a logged-in browser pass across multiple symbols and expirations. The `chain_id` app deeplink reliably opens the right underlying's chain (device-verified); exact-contract selection still comes from the API-resolved `option_instrument_id`. Operational details live in [`docs/options-contract-navigation-2026-06-03.md`](./docs/options-contract-navigation-2026-06-03.md) and the machine-readable workflow lives in [`api-map/options-contract-navigation-workflows-2026-06-03.json`](./api-map/options-contract-navigation-workflows-2026-06-03.json). ### 6.5 Account settings and account-page controls Account-page surfaces are mapped with an explicit read/write boundary: robinhood-cli brokerage routes --query "recurring_schedules" --json robinhood-cli brokerage routes --query "corp_actions/drip/enrollment" --json robinhood-cli brokerage routes --query "ach/transfers" --json robinhood-cli brokerage routes --query "margin" --json Current state: - Recurring investments have first-class `recurring list`, `recurring pause`, and `recurring resume`; create/edit/funding-source routes are mapped but need a fresh body capture before being treated as hardened automation. - DRIP is mapped as separate `GET` and `PATCH` routes so reads stay live and the toggle stays double-gated. - Funding, deposits, withdrawals, stock lending, cash sweep, futures, event contracts, account type, and margin settings are documented as route-map or browser-observed surfaces. Known reads are callable through CLI/MCP; live mutations stay blocked behind dry-run planning until the exact route/body is captured and approved. See [`docs/account-settings-capability-map-2026-06-03.md`](./docs/account-settings-capability-map-2026-06-03.md) and [`api-map/account-settings-capability-map-2026-06-03.json`](./api-map/account-settings-capability-map-2026-06-03.json). ### 7. More read commands — quote, positions, watchlists The same one-line ergonomics for everyday lookups. All read-only; all print per-share prices and percentages, never a summed account total (so output stays safe to screenshot): # Live quotes for one or more symbols (last, day %, bid/ask). robinhood-cli quote MRVL NVDA AAPL # Your open equity positions, ranked by unrealized return. robinhood-cli positions robinhood-cli positions --sort symbol --json # Target a specific account by account number. robinhood-cli positions --account # individual brokerage robinhood-cli positions --account # Roth IRA # Your custom watchlists and how many symbols each holds. robinhood-cli watchlist list # Option expirations for a symbol (handy before `options chain`). robinhood-cli options expirations MRVL $ robinhood-cli positions --account # output below is illustrative, not real holdings Account symbol qty avgCost last return ------ ------ ------- ------- ------ NVDA 2.0000 $100.00 $128.00 +28.0% AMD 1.5000 $150.00 $141.00 -6.0% ... N positions — green/red split. For the full agent playbook — account discovery, the gate, watchlists, recurring investments — see [`AGENTS.md`](./AGENTS.md). For the public docs index, see [`docs/README.md`](./docs/README.md). ## Documentation | Path | Purpose | |------|---------| | [`AGENTS.md`](./AGENTS.md) | Full agent runbook: auth, account enumeration, route execution, writes, MCP registration | | [`SKILL.md`](./SKILL.md) | Skill entrypoint for agents and Hermes-style installers | | [`docs/README.md`](./docs/README.md) | Public docs index and naming/release rules | | [`docs/account-settings-capability-map-2026-06-03.md`](./docs/account-settings-capability-map-2026-06-03.md) | Funding, recurring, DRIP, cash sweep, stock lending, margin, futures, event-contract capability matrix | | [`docs/options-strategy-execution-smoke-2026-06-03.md`](./docs/options-strategy-execution-smoke-2026-06-03.md) | Dry-run options strategy smoke evidence | | [`api-map/`](./api-map/) | Generated route map, OpenAPI, endpoint Markdown, curl templates, and workflow JSON | ## Extending it The repo is built to grow. If an endpoint is missing: 1. Add the path to the OpenAPI spec in [`api-map/openapi/`](./api-map/openapi/). 2. Drop a Markdown file describing it under [`api-map/markdown/`](./api-map/markdown/). 3. Wire a command so the CLI and MCP can drive it. The loop is: capture, document, expose, rebuild, test. Pattern: CLI + skill + MCP. Capture the surface once, expose it cleanly everywhere. ## Socials

标签：自定义脚本