hood-cli

The command-line toolkit for Robinhood Chain (chain ID 4663).

Instant reads with zero config, guarded writes with an encrypted local wallet. Prices, portfolios, launches, swaps, transfers, transaction decoding — the gh/vercel of Robinhood Chain. Built on hoodchain and viem.

Who it's for: anyone tracking Stock Tokens (tokenized equities on Robinhood Chain), watching NOXA/Odyssey memecoin launches, or scripting swaps and transfers from a terminal or CI job. Read commands (price, stocks, coins, launches, tx, token, portfolio, watch) work immediately with no wallet or API key. Write commands (swap, transfer, deploy-token) need a wallet and always stop for an explicit confirmation before signing.

Docs + a live animated terminal demo (a REAL captured session, not invented output): https://nirholas.github.io/hood-cli/ · full flag-by-flag command reference: https://nirholas.github.io/hood-cli/commands.html (generated straight from hood <command> --help — never hand-written, never drifts from the shipped binary).

Install

npm install -g hood-cli

This installs two equivalent binaries: hood and hoodc.

Run without installing:

npx hood-cli price AAPL

From a checkout:

git clone https://github.com/nirholas/hood-cli.git
cd hood-cli
npm install
npm run build
node dist/cli.js price AAPL

Requires Node ≥ 20.

Quickstart

$ hood price AAPL
◈ AAPL · Robinhood Chain mainnet
Oracle    $315.50
Updated   1d 18h ago
DEX       no pool
Premium   —
Token     0xaF3D…93f9

$ hood stocks --sort premium --dex --limit 6
◈ Stock Tokens · mainnet · 6 shown · 6 priced
SYMBOL    PRICE      DEX  PREMIUM     AGE  NAME                      ADDRESS
────────────────────────────────────────────────────────────────────────────────
CLSK     $12.86   $15.51  +20.58%  1d 17h  CleanSpark                0xcBB9…Cee3
IONQ     $43.08   $49.44  +14.76%  1d 18h  IonQ                      0x5583…0EfE
NBIS    $219.24  $248.41  +13.31%  1d 17h  Nebius Group               0x9D9c…7931

$ hood portfolio 0x9701fb0aDe1E269c8f64Ec0C7b3cfADB31A13A52
◈ Portfolio · 0x9701…3A52 · mainnet
ETH      0.003784
USDG     $0.0550
Stocks   $0.00
Total    $0.0550

No Stock Token positions. Fund with `hood swap --sell USDG --buy <ticker>`.

$ hood swap --sell USDG --buy WETH --amount 250
◈ Swap quote · mainnet · add --execute to send
Sell            250 USDG
Buy             ~0.138501866807990729 WETH
Min. received   0.137809357473950775 WETH (0.50% slippage)
Rate            1 USDG ≈ 0.000554 WETH
Route           direct pool

Every command supports --json for machine-readable output — pipe it into jq or a script.

Global options

These apply to every command and must come before the subcommand name (hood --json price AAPL):

| Flag | Description | | --- | --- | | -v, --version | print the CLI version | | --json | machine-readable JSON output instead of the human-formatted view | | --network <net> | mainnet (default) or testnet | | --rpc <url> | override the RPC endpoint for this invocation | | --verbose | show the raw underlying error cause on failure | | --yes | skip the interactive yes/no confirmation on writes (still requires --execute) | | --acknowledge-eligibility | affirm Stock Token acquisition eligibility (you are not a US/CA/UK/CH person) | | --no-color | disable ANSI colour in human output | | -h, --help | show help for the command |

Command reference

| Command | Description | | --- | --- | | price <symbol> | Chainlink oracle price + DEX price + premium for a Stock Token | | stocks | The full Stock Token board with live Chainlink prices | | coins | Memecoin screener — newest or trending launches | | launches | Recent memecoin launches from NOXA and The Odyssey | | portfolio <address> | Multiplier-correct Stock Token positions + USD totals for an address | | tx <hash> | Decode a transaction: status, transfers, gas, method | | token <address> | Inspect a token: metadata, supply, multiplier, price | | watch <addrOrToken> | Live activity stream for an address or a token (ERC-20 transfers + native ETH) | | swap | Quote (default) or execute a Uniswap v3 swap between two tokens | | transfer | Send ETH or an ERC-20 token to an address | | faucet | Print testnet faucet instructions + current testnet balances | | deploy-token | Deploy a fixed-supply ERC-20 from a JSON config (direct-rail, no launchpad) | | config | Manage hood-cli settings (rpc, wallet, network) |

Every argument below is a real, implemented flag — run hood <command> --help at any time to see it straight from the CLI.

hood price <symbol>

Chainlink oracle price, DEX price, and the premium/discount between them for one Stock Token.

| Flag | Description | | --- | --- | | symbol (arg) | ticker (AAPL) or token address | | --watch | live-updating view that repaints in place | | --interval <ms> | refresh interval for --watch (default 4000) | | --max-age <seconds> | max acceptable Chainlink answer age | | --no-dex | skip the Uniswap price probe (oracle only) |

hood price AAPL
hood price 0xaF3D... --no-dex
hood price TSLA --watch --interval 2000

hood stocks

The full Stock Token board — every canonical, verified Stock Token with a live Chainlink feed.

| Flag | Description | | --- | --- | | --sort <key> | symbol | price | premium (premium implies --dex); default symbol | | --dex | also probe Uniswap for DEX price + premium (slower) | | --priced | only show tokens with a live Chainlink feed | | --limit <n> | show at most n rows |

hood stocks
hood stocks --sort premium --dex --limit 10
hood stocks --priced --json

hood coins

Screener over the NOXA/Odyssey bonding-curve launchpads: newest launches, or ranked by trade activity.

| Flag | Description | | --- | --- | | --new | newest launches (default) | | --trending | rank by bonding-curve trade activity | | --lookback <blocks> | blocks to scan (default 50000) | | --limit <n> | rows to show (default 20) | | --names | resolve token symbols on-chain |

Mainnet only — the launchpads don't exist on testnet.

hood coins --names
hood coins --trending --lookback 100000 --limit 10

hood launches

The raw launch feed for NOXA and The Odyssey, or a live stream of new ones.

| Flag | Description | | --- | --- | | --follow | stream new launches live instead of a snapshot | | --launchpad <name> | noxa | odyssey (default: both) | | --lookback <blocks> | blocks to scan for the snapshot (default 30000) | | --limit <n> | max rows in the snapshot (default 25) | | --names | resolve each token symbol on-chain |

hood launches --lookback 2000000 --limit 5 --names
hood launches --follow --launchpad odyssey

hood portfolio <address>

Multiplier-correct Stock Token positions (share-equivalents, not raw balances) plus ETH, USDG, and a USD grand total.

| Flag | Description | | --- | --- | | address (arg) | wallet address to inspect | | --max-age <seconds> | max acceptable Chainlink answer age |

hood portfolio 0x9701fb0aDe1E269c8f64Ec0C7b3cfADB31A13A52

hood tx <hash>

Decodes a transaction: status, from/to, value, method selector, gas, fee, block time, and every ERC-20 Transfer log inside it (symbols resolved for known Stock Tokens and read on-chain for anything else).

hood tx 0x870a3bee3070f10e3c4f34271cfde70fd5aa0dc2eade6f07d01ae6c9a00285bd

hood token <address>

Token metadata: name, decimals, total supply, holder count, the uiMultiplier for Stock Tokens, Chainlink oracle price (if it has a feed), and DEX price.

| Flag | Description | | --- | --- | | address (arg) | token address or ticker |

hood token AAPL
hood token 0xcBB9...

hood watch <addrOrToken>

Streams live activity until Ctrl-C. Without --token, a wallet address streams native ETH in/out plus every USDG transfer touching it (mainnet only — it needs the Stock Token registry). With --token, or when the argument isn't a valid address, it streams every transfer of that token.

| Flag | Description | | --- | --- | | addrOrToken (arg) | wallet address, token address, or ticker to watch | | --token | treat the argument as a token (stream ALL transfers of it) |

hood watch 0x9701fb0aDe1E269c8f64Ec0C7b3cfADB31A13A52
hood watch AAPL --token

hood swap

Quotes a Uniswap v3 swap by default; add --execute to sign and send it. Recognizes USDG, WETH/ETH, any Stock Token ticker, or a raw 0x address for both --sell and --buy.

| Flag | Description | | --- | --- | | --sell <token> | ticker or address to sell (e.g. USDG) — required | | --buy <token> | ticker or address to buy — required | | --amount <amount> | amount of --sell to spend, in whole tokens — required | | --slippage <bps> | slippage tolerance in basis points (default 50 = 0.5%) | | --execute | sign and send (default: quote only) |

hood swap --sell USDG --buy WETH --amount 250
hood swap --sell USDG --buy AAPL --amount 500 --slippage 100 --execute

--execute prints a confirmation table and stops for an explicit y/N unless --yes is passed. It also checks the configured maxSpendUsd cap (see Configuration below) and Stock Token acquisition eligibility — a swap that mints/acquires a Stock Token for a non-affirmed operator fails with a guard error until you pass --acknowledge-eligibility.

hood transfer

Sends native ETH or an ERC-20 token to an address.

| Flag | Description | | --- | --- | | --to <address> | recipient address — required | | --amount <amount> | amount to send, in whole tokens — required | | --token <token> | ticker or address to send (default: native ETH) |

hood transfer --to 0x9701fb0aDe1E269c8f64Ec0C7b3cfADB31A13A52 --amount 0.01
hood transfer --to 0x9701... --amount 100 --token USDG

Same confirmation gate and maxSpendUsd cap as swap.

hood faucet

Prints the testnet faucet URL and instructions, plus your current testnet balances if a wallet is configured. Testnet-only (--network testnet); each claim (browser-only — it requires Cloudflare Turnstile + Google Sign-In and can't be automated) drips testnet ETH plus 5 each of TSLA, AMZN, PLTR, NFLX, AMD.

hood faucet --network testnet

hood deploy-token

Deploys a fixed-supply ERC-20 (not a Stock Token, not launchpad-listed — a plain direct-rail token) from a JSON config.

| Flag | Description | | --- | --- | | --config <path> | path to a JSON file: { name, symbol, decimals?, initialSupply } — required | | --execute | sign and send (default: print the deploy plan only) |

Config file example:

{
  "name": "My Token",
  "symbol": "MTK",
  "decimals": 18,
  "initialSupply": 1000000
}

hood deploy-token --config ./mytoken.json
hood deploy-token --config ./mytoken.json --execute

hood config

Manages the persistent CLI config at ~/.config/hood/config.json (or $HOOD_CONFIG_DIR).

| Subcommand | Description | | --- | --- | | config set <key> [value] | set a config value: network, rpc, testnetRpc, alchemyKey, maxSpendUsd, or wallet | | config get <key> | print one config value | | config list | print the full config (secrets masked) |

hood config set network testnet
hood config set rpc https://your-rpc.example.com
hood config set alchemyKey <your-alchemy-key>
hood config set maxSpendUsd 500
hood config set wallet
hood config get walletAddress
hood config list

config set wallet with no value generates a new private key (or, if ROBINHOOD_CHAIN_IMPORT_KEY is set, imports it), prompts twice for a password, and writes an AES-256-GCM keystore (scrypt KDF, Node's built-in crypto — the same primitive set as the Web3 Secret Storage spec) to ~/.config/hood/keystore.json. The private key never touches the config file or plaintext disk.

hood init

The one-command onboarding wizard for the whole trading stack: this CLI's wallet, the hood-traders llm-strategist (bring your own key — Claude, OpenAI, Groq, or OpenRouter), and the hood-alerts Telegram bot / Discord bot / X (Twitter) auto-posting. Every step is optional — skip anything you don't need with n or Enter.

hood init

It writes hood-traders.env and hood-alerts.env into the current directory (--out <dir> to choose another). Copy each into the matching package as .env and run it:

cp hood-traders.env hood-traders/.env && cd hood-traders && npx hood-traders
cp hood-alerts.env  hood-alerts/.env  && cd hood-alerts  && npx hood-alerts

Needs an interactive terminal (secrets are typed, not passed as flags) — in CI or a non-interactive shell, copy hood-traders/.env.example and hood-alerts/.env.example by hand instead.

Wallet & signing

Every write command (swap --execute, transfer, deploy-token --execute, config set wallet) needs a signer. Precedence:

1. ROBINHOOD_CHAIN_PRIVATE_KEY env var — a hex private key (with or without 0x prefix). Best for CI or power users; bypasses the keystore entirely.
2. The encrypted keystore created by hood config set wallet, unlocked by a password prompt (or the HOOD_WALLET_PASSWORD env var, so scripts never need an interactive TTY).

No wallet is required for any read command (price, stocks, coins, launches, tx, token, portfolio, watch).

Configuration & environment variables

| Variable | Purpose | | --- | --- | | HOOD_CONFIG_DIR | overrides the config/keystore directory (default ~/.config/hood) | | HOOD_WALLET_PASSWORD | wallet keystore password, read non-interactively (for scripts/CI) | | ROBINHOOD_CHAIN_PRIVATE_KEY | sign with this private key directly, skipping the keystore | | ROBINHOOD_CHAIN_IMPORT_KEY | private key to import when running hood config set wallet (instead of generating a new one) |

Persistent config keys (hood config set <key> <value>):

| Key | Purpose | | --- | --- | | network | default network for every command: mainnet or testnet | | rpc | custom mainnet RPC URL | | testnetRpc | custom testnet RPC URL | | alchemyKey | Alchemy API key — builds https://robinhood-mainnet.g.alchemy.com/v2/{key} automatically | | maxSpendUsd | hard USD ceiling on a single swap/transfer; the write is refused if the estimated spend exceeds it (unpriceable tokens are never blocked, only warned about) | | wallet | special: runs the interactive wallet setup flow described above |

Resolution order for RPC URL: --rpc flag → alchemyKey (mainnet) / testnetRpc → rpc → the SDK's public default.

Networks

| Network | Chain ID | Notes | | --- | --- | --- | | mainnet (default) | 4663 | Stock Tokens, Chainlink feeds, NOXA/Odyssey launchpads, Uniswap v3 pools all live here | | testnet | 46630 | TSLA, AMZN, PLTR, NFLX, AMD faucet tokens; no launchpads, no Chainlink feeds |

Pass --network testnet on any command, or set it once with hood config set network testnet.

Exit codes

| Code | Meaning | | --- | --- | | 0 | success | | 1 | generic runtime failure | | 2 | bad usage / invalid arguments | | 3 | network / RPC unreachable or timed out | | 4 | a guard rail refused the action (eligibility, spend cap, unconfirmed prompt) | | 5 | requested resource not found (unknown symbol, missing transaction) | | 6 | wallet required but not configured, or wrong password |

Every error also prints a human hint on how to fix it; add --verbose to see the raw underlying cause, or --json to get { error, hint, exitCode } for scripting.

Safety notes

• Stock Token eligibility. Stock Tokens are tokenized securities and may not be acquired by US/CA/UK/CH persons. Any write that would acquire one refuses to run unless you pass --acknowledge-eligibility, affirming you are not a person from a restricted jurisdiction.
• Confirmation gate. swap --execute, transfer, and deploy-token --execute always print a confirmation table and require an explicit y before signing, unless --yes is passed. On a non-interactive stdin without --yes, the command fails closed rather than hanging or silently proceeding.
• Spend cap. Set maxSpendUsd once (hood config set maxSpendUsd 500) to have every swap and transfer checked against it before signing.

Development

npm install
npm run build       # tsup → dist/cli.js (single self-contained ESM file)
npm run typecheck
npm test             # vitest run tests/unit — parsing, formatting, guard rails (offline)
npm run e2e          # scripts/e2e.mjs — exercises the BUILT binary against live chain data

npm run compile-erc20 regenerates src/generated/erc20.ts from contracts/ERC20.sol (the fixed-supply token deploy-token deploys) — only needed if you change the contract.

Docs site

The docs/ folder is a static site (GitHub Pages, deploy-from-branch, no build step on Pages itself) whose content is generated, never hand-written:

npm run capture        # drives the built binary against live mainnet, saves docs/session.json
npm run docs:commands  # generates docs/commands-data.json from the CLI's own --help output
npm run docs:build     # stitches both into docs/index.html + docs/commands.html
npm run docs           # runs all three in order

docs/index.template.html and docs/commands.template.html are the editable sources; docs/index.html and docs/commands.html are the generated, real-data-inlined output that Pages actually serves — re-run npm run docs after any command change to keep them in sync.

Where it's hosted: GitHub Pages is the default (Settings → Pages → Deploy from a branch → main → /docs) → https://nirholas.github.io/robinhood-chain-cli/. The Deploy to Cloudflare and Deploy with Vercel buttons at the top of this README are one-click alternatives — wrangler.json/vercel.json at the repo root both point at docs/ as a plain static folder, no build command needed. There's no server component to this tool (it's a local CLI), so only the docs site is deployable — npm install -g hood-cli is how you get the tool itself.

Publishing

npm run build
npm test
npm pack               # verify the tarball installs clean: npm i -g ./hood-cli-*.tgz
npm publish --access public

License

All rights reserved. See LICENSE.

Built by nirholas · three.ws