v1.0.1
OpenAPI 3.1.0

HoodGrow API docs

Proprietary

Verified stock-token data for Robinhood Chain (chain 4663) — live price, ERC-8056 corporate-action adjusted supply, splits & dividends, and Morpho/Uniswap DeFi depth. Plus Base (chain 8453): the pre-launch B20 registry and a live $BNKR quote.

Every data endpoint is reachable three ways — a free API key, prepaid credits, or x402 pay-per-call (USDC on Base, no signup). Pick one and you're done.

Quickstart — first call in 5 minutes

1. Get a free key at hoodgrow.com/profile (40 calls/day), or skip the key entirely and pay per call with x402 (step 4).

2. Call the catalog — every tracked token in one request:

curl https://www.hoodgrow.com/api/agent/tokens \
  -H "Authorization: Bearer $HOODGROW_API_KEY"

3. Or use a typed SDK — both packages are named hoodgrow (hoodgrow-ts · hoodgrow-py): 

import { HoodGrowClient } from "hoodgrow"; // npm i hoodgrow

const client = new HoodGrowClient({ apiKey: process.env.HOODGROW_API_KEY });
const { tokens } = await client.getCatalog();
const nvda = await client.getToken("NVDA");

import os
from hoodgrow import HoodGrowClient  # pip install hoodgrow

client = HoodGrowClient(api_key=os.environ["HOODGROW_API_KEY"])
catalog = client.get_catalog()
nvda = client.get_token("NVDA")

4. No key? Pay per call via x402 — fund a wallet with USDC on Base and the SDK settles each call for you, no signup: 

import { HoodGrowClient } from "hoodgrow";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const client = new HoodGrowClient({ signer }); // pays $0.10/catalog, $0.05/token in USDC
const catalog = await client.getCatalog();

Auth (tried in order)

  1. Authorization: Bearer <key> — free key (40/day) or Builder (300/min) from hoodgrow.com/profile. Invalid key → 401. Missing → next.
  2. Prepaid credits — buy a dollar balance once via x402, then spend it down with a signed header per call (no gas, no on-chain tx). Send all three headers: X-HoodGrow-Credit-Wallet, X-HoodGrow-Credit-Timestamp, X-HoodGrow-Credit-Signature (EIP-191 over HoodGrow credit spend\nmethod: …\npath: …\ntimestamp: …, ±60s). Buy: POST /api/agent/credits/purchase?bundle=10|50|200. Balance: GET /api/agent/credits/balance. The SDKs do all of this for you — pass useCredits: true / use_credits=True.
  3. x402 — no auth → 402 with a base64 PAYMENT-REQUIRED challenge; retry with PAYMENT-SIGNATURE. Body is {} for the challenge. The paywall only ever asks for USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) on Base mainnet, capped at $0.10/call. SDKs handle the loop.

/api/mcp requires bearer only (no credits/x402). Errors are always { "error": "…" }. Rate limits return 429 with Retry-After — back off, don't blind-retry a paid call (a retry can pay twice).

Concepts

Adjusted supply (ERC-8056 uiMultiplier)

A stock token's on-chain balance doesn't move on a split — an ERC-8056 uiMultiplier does (WAD-scaled, 1e18 = 1.0× / no adjustment). HoodGrow reads it directly, so:

  • supply is the corporate-action-adjusted display quantity: raw on-chain supply × the token's current multiplier — the number a holder should actually see after a split.
  • supplyAdjusted is true when that multiplier was read on-chain, false when HoodGrow fell back to raw totalSupply (multiplier unavailable). Every live token's multiplier is 1.0 today, so adjusted == raw right now — but the field is already correct for the first day one isn't.
  • priceUsd from a Chainlink feed already bakes the multiplier in (it's a Total-Return value), so HoodGrow never applies it twice. Don't re-adjust supply × priceUsd yourself.

Two corporate-action signals

They are not redundant — read both:

  • pendingCorporateActions — the on-chain ERC-8056 signal: a multiplier already staged with a future effectiveAt. Rare; only large, price-discontinuity actions (a split) need it.
  • recentCorporateActions — the official Robinhood ledger: the near-continuous feed, including dividends, which apply immediately with no oracle pause and so never appear in the first field. Relying on pendingCorporateActions alone will miss routine dividends.

For a filterable, paginated event log across every symbol, use GET /api/corporate-actions.

Real-time delivery (webhooks, not WebSockets)

Don't poll for corporate actions — subscribe and HoodGrow pushes each event to your URL. Register a credit-funded webhook (POST /api/agent/credits/webhook, billed per event) or a Builder webhook on your self-serve key (PATCH /api/builder/key). Deliveries are POSTs signed with x-hoodgrow-signature: sha256=<hex> (HMAC-SHA256 over the raw body) — verify it before trusting the payload. There is no WebSocket transport: a persistent-socket layer isn't offered, so webhooks (or the paginated feed above) are the real-time path. A ready consumer is in examples/webhook-starter.

null vs 0

A null means "no data / not applicable", never a real zero. morphoBestSupplyApy: null means the token isn't a loan asset in any Morpho market — distinct from a genuine 0% APY. change24hPercent: null means no 24h-ago reference exists yet, not that the price was flat.

Price sources

priceSource is chainlink (a Chainlink Total-Return feed), legacy (the older RHJ feed), or null when no price is available. Prefer chainlink where present.

Data sources

  • Price — Chainlink Total-Return feeds on Robinhood Chain (chainlink), RHJ fallback (legacy).
  • Adjusted supply — the token's own ERC-8056 uiMultiplier, read on-chain.
  • Corporate actions — on-chain ERC-8056 events (splits/pauses) + the official Robinhood ledger (dividends).
  • DeFi — Morpho Blue markets and Uniswap V3 pools, indexed on Robinhood Chain.
  • Holders — periodic on-chain holder snapshots.
  • Base B20 / $BNKR — Base mainnet (chain 8453) contract reads and the most-liquid $BNKR/WETH Uniswap V3 pool.

Docs: https://docs.hoodgrow.com · Pricing: https://www.hoodgrow.com/pricing · SDKs: hoodgrow-ts · hoodgrow-py · hoodgrow-mcp

Server:https://www.hoodgrow.com

Production

Client Libraries
Shell Curl