robinhood-for-agents
AI-native Robinhood trading interface. No MCP server required — this skill works standalone via the TypeScript client API and bun.
How to Use
Run Robinhood operations by executing TypeScript code with bun. The robinhood-for-agents npm package provides a full client library — just import it and call methods:
bun -e '
import { getClient } from "robinhood-for-agents";
const rh = getClient();
await rh.restoreSession();
// call any method, print results as JSON
const holdings = await rh.buildHoldings();
console.log(JSON.stringify(holdings, null, 2));
'
See client-api.md for all available methods and signatures.
MCP users: If you have the robinhood-for-agents (standard mode) or robinhood-web (web mode) MCP server configured, you may use MCP tools instead. See reference.md for tool parameters. MCP is optional — the client API above does everything the web-mode tools do; only the standard-mode server (robinhood-for-agents) serves the standard-only tools. Pick one mode per session and stay in it: the web-mode MCP server and a bun -e script are two separate token-refreshing processes, and refresh tokens are single-use, so interleaving them can poison one of them. In MCP mode, robinhood_check_session is the session check — it probes the API rather than just reading the keychain.
CRITICAL SAFETY RULES
- Always confirm before placing any order — show order preview, get explicit "yes"
- Show current price before order confirmation so user knows the cost
- Never place orders without user confirmation
- Fund transfers and bank operations are BLOCKED — refuse these requests
- Never place bulk cancel operations — cancel orders one at a time
- Never turn a "sell" into a short.
sell closes a long; sell_short opens a short with unlimited loss potential. Only short when the user asked to short, and label it SHORT SELL when confirming. A negative position quantity is a short — close it by buying, never by selling more. See trade.md
- Name the trading session. Outside regular hours, only limit orders execute; an order tagged to the wrong session silently queues for the next open instead of filling. Check with
robinhood_get_market_hours / getMarketHours() — never infer the session from the local clock
BLOCKED Operations (never use)
- Bulk cancel operations
- Fund transfers (withdraw/deposit)
- Bank unlinking
Routing
| User Intent |
Domain File |
Example Triggers |
| Auth / login / connect |
setup.md |
"setup robinhood", "connect to robinhood", "robinhood login" |
| Portfolio / holdings / positions |
portfolio.md |
"show my portfolio", "my holdings", "account summary" |
| Stock research / analysis |
research.md |
"research AAPL", "analyze TSLA", "due diligence on NVDA" |
| Buy / sell / short / orders / cancel |
trade.md |
"buy 10 shares of AAPL", "sell my TSLA", "short 10 SPY", "cancel my order" |
| Options / calls / puts / chains |
options.md |
"show AAPL options", "SPX calls", "0DTE options", "covered calls" |
| Watchlists / lists / "add to my list" |
watchlists.md |
"my watchlists", "add NVDA to my tech list", "remove TSLA from watchlist" |
| Scanners / screeners / saved screens |
reference.md |
"my scanners", "my saved screens", "what filters can I scan on" |
| Realized P&L / gains / "how did my trades do" |
reference.md |
"my realized gains", "P&L this year", "how did my trades do" |
| Tax lots / cost basis per holding |
reference.md |
"tax lots for AAPL", "cost basis of my NVDA lots", "which lots are long-term" |
Read the corresponding domain file for detailed workflow instructions.
Authentication Prerequisite
Before any data-fetching or trading operation, verify the session actually works. restoreSession() only loads tokens from the store — it does not prove they are still valid, so probe with a real call:
bun -e '
import { getClient, AuthenticationError } from "robinhood-for-agents";
const rh = getClient();
try {
await rh.restoreSession();
await rh.getAccountProfile(); // the probe — this is what proves the token works
console.log("logged_in");
} catch (e) {
console.log(e instanceof AuthenticationError ? `expired: ${e.name}` : `unknown: ${e}`);
}
'
logged_in → proceed.
expired (TokenExpiredError / AuthenticationError) → the tokens are dead and could not be refreshed. Follow setup.md to re-authenticate.
unknown → a transient/network failure. The session may well be fine — do not send the user through a browser re-login on this; retry once first.
MCP mode: call robinhood_check_session instead — it probes the API and returns logged_in / expired / unknown / not_authenticated. Only expired and not_authenticated warrant robinhood_browser_login.
Client Methods
The client exposes 70+ async methods across auth, portfolio, research, options, orders, watchlists, scanners, P&L, and tax lots.
- client-api.md — full method reference (signatures, options, examples) and the MCP↔client mapping table
- reference.md — MCP tool parameters (if using MCP mode instead of the client)
Important Notes
- Do NOT use
phoenix.robinhood.com — use api.robinhood.com endpoints only
- Multi-account is first-class: always ask which account when multiple exist
- Session tokens renew themselves: the client refreshes proactively (
24h before expiry) and again on a 401, so a session in regular use stays alive without a re-login. Access-token TTL varies (6-8.5 days observed) — never quote a fixed number
- Refresh tokens are single-use: every renewal issues a new one and instantly kills the old (and revokes the previous access token). Run one client at a time — MCP server or a
bun -e script, not both; a second process gets poisoned. It self-heals by re-reading the token store, but there is no cross-process lock
- Renewal only happens while the client is being used. A session left idle past the refresh-token lifetime lapses and needs a new browser login — see setup.md
1---2name: robinhood-for-agents3description: Trade stocks, options, and crypto on Robinhood — MCP tools (standard mode relayed to Robinhood's hosted MCP, or web mode on the web API) or TypeScript client.4homepage: https://github.com/kevin1chun/robinhood-for-agents5allowed-tools: Bash(bun:*), Bash(bunx robinhood-for-agents:*), mcp__robinhood-for-agents__*, mcp__robinhood-web__*6install:7 - kind: node8 package: robinhood-for-agents9 bins: [robinhood-for-agents]10requires:11 bins: [bun]12metadata:13 source: https://skillmd.com/skills/jiayaoqijia/robinhood-for-agents14 credentials: "OAuth tokens stored via TokenStore adapters: KeychainTokenStore (OS keychain, default) or EncryptedFileTokenStore (for Docker/headless). restoreSession() loads tokens, injects Bearer auth directly, and registers both proactive renewal (a pre-request hook renews ~24h before expiry) and reactive refresh (on 401). Access-token lifetime varies (~6-8.5 days observed) — never assume a fixed number. Refresh tokens are single-use and rotate on every renewal, so only one client should drive a session at a time. Renewal happens only while the client is in use: a session left idle past the refresh-token lifetime lapses and needs a new browser login."15 chrome: Google Chrome is required only for initial login (bunx robinhood-for-agents login) — playwright-core drives the system Chrome; there is no Brave/Chromium fallback or BROWSER_PATH override. Not needed for subsequent API calls.16---1718# robinhood-for-agents1920AI-native Robinhood trading interface. **No MCP server required** — this skill works standalone via the TypeScript client API and `bun`.2122## How to Use2324Run Robinhood operations by executing TypeScript code with `bun`. The `robinhood-for-agents` npm package provides a full client library — just import it and call methods:2526```bash27bun -e '28import { getClient } from "robinhood-for-agents";29const rh = getClient();30await rh.restoreSession();31// call any method, print results as JSON32const holdings = await rh.buildHoldings();33console.log(JSON.stringify(holdings, null, 2));34'35```3637See [client-api.md](client-api.md) for all available methods and signatures.3839> **MCP users:** If you have the `robinhood-for-agents` (standard mode) or `robinhood-web` (web mode) MCP server configured, you may use MCP tools instead. See [reference.md](reference.md) for tool parameters. MCP is optional — the client API above does everything the web-mode tools do; only the standard-mode server (`robinhood-for-agents`) serves the standard-only tools. Pick **one** mode per session and stay in it: the web-mode MCP server and a `bun -e` script are two separate token-refreshing processes, and refresh tokens are single-use, so interleaving them can poison one of them. In MCP mode, `robinhood_check_session` is the session check — it probes the API rather than just reading the keychain.4041## CRITICAL SAFETY RULES421. **Always confirm before placing any order** — show order preview, get explicit "yes"432. **Show current price** before order confirmation so user knows the cost443. **Never place orders without user confirmation**454. **Fund transfers and bank operations are BLOCKED** — refuse these requests465. **Never place bulk cancel operations** — cancel orders one at a time476. **Never turn a "sell" into a short.** `sell` closes a long; `sell_short` opens a short with unlimited loss potential. Only short when the user asked to short, and label it **SHORT SELL** when confirming. A **negative** position quantity *is* a short — close it by **buying**, never by selling more. See [trade.md](trade.md#short-selling)487. **Name the trading session.** Outside regular hours, only limit orders execute; an order tagged to the wrong session silently queues for the next open instead of filling. Check with `robinhood_get_market_hours` / `getMarketHours()` — never infer the session from the local clock4950### BLOCKED Operations (never use)51- Bulk cancel operations52- Fund transfers (withdraw/deposit)53- Bank unlinking5455## Routing5657| User Intent | Domain File | Example Triggers |58|---|---|---|59| Auth / login / connect | [setup.md](setup.md) | "setup robinhood", "connect to robinhood", "robinhood login" |60| Portfolio / holdings / positions | [portfolio.md](portfolio.md) | "show my portfolio", "my holdings", "account summary" |61| Stock research / analysis | [research.md](research.md) | "research AAPL", "analyze TSLA", "due diligence on NVDA" |62| Buy / sell / short / orders / cancel | [trade.md](trade.md) | "buy 10 shares of AAPL", "sell my TSLA", "short 10 SPY", "cancel my order" |63| Options / calls / puts / chains | [options.md](options.md) | "show AAPL options", "SPX calls", "0DTE options", "covered calls" |64| Watchlists / lists / "add to my list" | [watchlists.md](watchlists.md) | "my watchlists", "add NVDA to my tech list", "remove TSLA from watchlist" |65| Scanners / screeners / saved screens | [reference.md](reference.md) | "my scanners", "my saved screens", "what filters can I scan on" |66| Realized P&L / gains / "how did my trades do" | [reference.md](reference.md) | "my realized gains", "P&L this year", "how did my trades do" |67| Tax lots / cost basis per holding | [reference.md](reference.md) | "tax lots for AAPL", "cost basis of my NVDA lots", "which lots are long-term" |6869Read the corresponding domain file for detailed workflow instructions.7071## Authentication Prerequisite72Before any data-fetching or trading operation, verify the session actually works. `restoreSession()` only loads tokens from the store — it does **not** prove they are still valid, so probe with a real call:73```bash74bun -e '75import { getClient, AuthenticationError } from "robinhood-for-agents";76const rh = getClient();77try {78 await rh.restoreSession();79 await rh.getAccountProfile(); // the probe — this is what proves the token works80 console.log("logged_in");81} catch (e) {82 console.log(e instanceof AuthenticationError ? `expired: ${e.name}` : `unknown: ${e}`);83}84'85```86- `logged_in` → proceed.87- `expired` (`TokenExpiredError` / `AuthenticationError`) → the tokens are dead and could not be refreshed. Follow [setup.md](setup.md) to re-authenticate.88- `unknown` → a transient/network failure. The session may well be fine — **do not** send the user through a browser re-login on this; retry once first.8990> **MCP mode:** call `robinhood_check_session` instead — it probes the API and returns `logged_in` / `expired` / `unknown` / `not_authenticated`. Only `expired` and `not_authenticated` warrant `robinhood_browser_login`.9192## Client Methods9394The client exposes 70+ async methods across auth, portfolio, research, options, orders, watchlists, scanners, P&L, and tax lots.9596- [client-api.md](client-api.md) — full method reference (signatures, options, examples) and the MCP↔client mapping table97- [reference.md](reference.md) — MCP tool parameters (if using MCP mode instead of the client)9899## Important Notes100- **Do NOT use `phoenix.robinhood.com`** — use `api.robinhood.com` endpoints only101- Multi-account is first-class: always ask which account when multiple exist102- Session tokens renew themselves: the client refreshes proactively (~24h before expiry) and again on a 401, so a session in regular use stays alive without a re-login. Access-token TTL varies (~6-8.5 days observed) — never quote a fixed number103- Refresh tokens are **single-use**: every renewal issues a new one and instantly kills the old (and revokes the previous access token). Run one client at a time — MCP server *or* a `bun -e` script, not both; a second process gets poisoned. It self-heals by re-reading the token store, but there is no cross-process lock104- Renewal only happens while the client is being used. A session left idle past the refresh-token lifetime lapses and needs a **new browser login** — see [setup.md](setup.md)