hoodgrow-mcp

MCP (Model Context Protocol) server for the HoodGrow Robinhood Chain stock token API — live price, corporate-action adjusted supply (ERC-8056, correct through stock splits), Morpho/Uniswap DeFi depth, corporate actions (splits, dividends), holder analytics, trade price-impact/slippage estimates, OHLC price candles for backtesting, market movers, a large-trade ("whale") feed, and a Base mainnet B20 native-equity-token registry, exposed as tools for any MCP client (Claude Desktop, Claude Code, etc). Built on the hoodgrow SDK — pays per call via x402 (USDC on Base) or uses a bearer API key, your choice.

Fastest: the hosted server (no install, no key)

HoodGrow runs the MCP server for you at https://www.hoodgrow.com/api/mcp. Every tool is read-only, so you can point an assistant at it and start asking with no install, no signup, no key:

claude mcp add --transport http hoodgrow https://www.hoodgrow.com/api/mcp

or in mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "hoodgrow": { "type": "http", "url": "https://www.hoodgrow.com/api/mcp" }
  }
}

Then ask your assistant things like:

• "What's the corporate-action adjusted supply and 24h volume for NVDA on Robinhood Chain?"
• "Any pending stock splits or dividends in the next week?"
• "Top gainers and biggest whale trades today."

get_catalog — every listed token with live price, 24h change and adjusted supply — answers anonymously and unmetered, no key at all. The per-symbol tools ask for a free API key or an x402 payment on the first call. Anonymous access is capped at 20 requests/minute per IP, which is abuse shaping rather than billing and applies to the catalog too.

There used to be an anonymous daily budget in front of the per-symbol tools. It is gone: a budget keyed on the caller's IP is a fresh budget per address to anything calling from pooled egress, so it never actually led anyone to the paywall. Prefer running the server yourself, or need x402 pay-per-call? Use the npm package instead:

Run it yourself (npm — your own credentials)

Credentials are optional. With none set, the server starts and works: get_catalog is free and unmetered. Every other tool returns the API's 402 on its first call, as a readable tool error naming the alternatives. Set one of these to get past it:

• API key, free, self-serve — HOODGROW_API_KEY from hoodgrow.com/profile. A larger daily allowance, and a budget nobody behind the same IP can spend.
• x402, pay per call, no signup — a wallet private key (HOODGROW_PRIVATE_KEY), funded with USDC on Base. $0.05/call for the paid endpoints; no daily cap.

This package never bundles a shared HoodGrow credential, so you control what gets spent and who's billed.

Claude Desktop / Claude Code

Add to your MCP config (Claude Desktop: claude_desktop_config.json; Claude Code: claude mcp add):

{
  "mcpServers": {
    "hoodgrow": {
      "command": "npx",
      "args": ["-y", "hoodgrow-mcp"],
      "env": {
        "HOODGROW_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Or with an API key instead:

{
  "mcpServers": {
    "hoodgrow": {
      "command": "npx",
      "args": ["-y", "hoodgrow-mcp"],
      "env": {
        "HOODGROW_API_KEY": "..."
      }
    }
  }
}

Never hardcode a real private key in a committed config file — only fund that wallet with what you're willing to spend on this API.

Optionally, once you've bought a credit balance with the buy_credits tool, add "HOODGROW_USE_CREDITS": "true" alongside HOODGROW_PRIVATE_KEY to have every data tool spend that balance (a cheap wallet signature) instead of paying x402 per call. See "Prepaid credits" below.

Tools

| Tool | Price (x402) | Description | | --- | --- | --- | | get_catalog | free | Every listed token: symbol, name, address, price, source, 24h change, corporate-action adjusted supply, plus catalog-wide pending/recent corporate actions. No per-token DeFi — see get_token / get_defi | | get_token | $0.05 | One token by symbol (e.g. NVDA), same fields plus its DeFi depth | | get_corporate_actions | uses get_token/get_catalog above | Pending + recent corporate actions; pass a symbol to scope, omit for every tracked token | | get_defi | $0.05 | Every Morpho market a token participates in (loan OR collateral role) plus its Uniswap V3 pools — not just the single best-APY figure in get_token | | get_holders | $0.05 | Holder-count trend, 24h net supply change (real mint/burn), and top-holder concentration (optional limit, 1-50, defaults to 10) | | get_slippage | $0.05 | How much a USD-sized trade (side: "buy" \| "sell") would move the price, per Uniswap V3 pool — includes bestPoolAddress/bestEffectivePrice picking the best one for you | | get_ohlc | $0.05 | OHLC price candles for backtesting (interval: "1h" \| "4h" \| "1d", optional from/to/limit, defaults to the last 30 days). Each candle carries volumeUsd/swapCount — USD swap volume across the token's Uniswap V3 pools — null for buckets older than the volume indexer's backfill window | | get_base_tokens | $0.05 | Base mainnet (chain 8453) B20 native-equity-token registry — a much smaller sibling of get_catalog. Pre-launch: check each token's status before treating it as tradable — "pre_launch" means no price, no DEX liquidity, no holders exist for it yet | | get_markets | $0.05 | Market movers across the whole catalog: top gainers/losers (24h change), highest 24h swap volume, and deepest Uniswap V3 liquidity (TVL). Optional limit (1-50, default 10); gainers/losers can be empty on a flat market | | get_trades | $0.05 | Recent large ("whale") trades in the stock-token Uniswap V3 pools, newest first — each with side ("buy" \| "sell"), USD size, and txHash. Omit symbol for the global feed; optional limit (1-100, default 20) | | list_credit_bundles | free | Current prepaid credit bundle catalog ({id: {priceUsd, creditUsd}}) — no credentials needed | | buy_credits | one x402 payment | Pays for one bundle (bundleId arg); requires HOODGROW_PRIVATE_KEY. Balance lands once settlement confirms — check with get_credit_balance | | get_credit_balance | free | This wallet's current credit balance; requires HOODGROW_PRIVATE_KEY | | register_credit_webhook | free to register, then per delivered event | Register a credit-funded corporate-action webhook (url, optional symbols); requires HOODGROW_PRIVATE_KEY. HoodGrow POSTs each corporate_action.* event to url, signed x-hoodgrow-signature. symbols restricts delivery (and per-event billing) to those tokens — omit for all. Returns webhookSecret (shown once). Builder-subscription webhooks are set from the website instead |

Each call returns the API's JSON response as the tool's text content. A failed request (unknown symbol, server error) comes back as an MCP tool error (isError: true) rather than crashing the server.

Prepaid credits

Buy a dollar-denominated credit balance once via x402 (buy_credits), then set HOODGROW_USE_CREDITS=true (alongside HOODGROW_PRIVATE_KEY) and restart the server: every data tool above then spends the balance with a cheap, gas-free wallet signature instead of a fresh on-chain x402 payment per call. list_credit_bundles/get_credit_balance never spend anything; only the metered data tools (get_catalog, get_token, etc.) and buy_credits itself move money.

Payment safety

x402 payments are real money and are not idempotent — a retried timed-out call can pay twice. HoodGrow's paywall only ever asks for USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) on Base mainnet (eip155:8453), paid to 0x8520B3693a2Cf3c2bEa3a505Af3A9c1b093954c7, capped at $0.05/call — the underlying hoodgrow/@x402 dependencies handle protocol-level verification, but you're responsible for how much you fund the signing wallet with.

Rate limits

30 requests/minute per IP by default for pay-per-call use.

With no credentials at all, get_catalog still answers — it is free and unmetered — and every other tool returns a 402 on the first call.

With a free API key, the daily allowance is 40 units:

| Call | Units | Free-tier calls/day | |---|---|---| | get_catalog (every token in one response) | 0 | unmetered — it is free | | Any single-symbol tool | 1 | 40 | | Liveness check | 0 | unmetered |

Still prefer get_token over get_catalog when you want one symbol — not because it is cheaper now, but because it returns far less to parse and carries that token's DeFi depth, which the catalog does not.

x402 pay-per-call has no daily cap at all ($0.05 per paid endpoint; the catalog is free either way), and Builder removes the cap and raises the per-minute limit to 300 — see docs.hoodgrow.com.

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (mocked fetch + real in-memory MCP client/server, no network)

License

MIT