v1.0.0
OpenAPI 3.1.0

HoodGrow API

HoodGrow reads Robinhood Chain (chain id 4663) stock-token contracts directly: live price, ERC-8056 corporate-action adjusted supply (so numbers stay correct through stock splits, not just raw token balances), and both pending (on-chain) and historical (official Robinhood ledger) corporate actions. A companion Base-mainnet (chain id 8453) surface covers the pre-launch B20 stock-token registry and a $BNKR price quote used by HoodGrow's own payment flows.

Authentication

Every priced endpoint accepts any of three ways in, decided per request — there is no mode you "pick" in advance, and they're tried in this order:

  1. Authorization: Bearer <token> — a free self-serve key (40 requests/day, no payment, see /builders) or a paid Builder key (300 requests/minute, no daily cap, plus webhooks). When present and valid, the full response is served for free.
  2. Prepaid credits — three X-HoodGrow-Credit-* headers spending down a balance bought once via x402 (see "Prepaid credits" below). Cheaper per call once you're past the initial bundle purchase, since it's an off-chain signature check, not a fresh on-chain settlement every time.
  3. x402 — send none of the above and the endpoint responds 402 Payment Required with a machine-readable challenge (see below); pay it and resubmit with a PAYMENT-SIGNATURE header to get the real response. No signup, no API key, one on-chain settlement per call.

If none of the three apply (and, for a couple of endpoints, if x402 isn't configured on this deployment at all), you get a bare 401.

/api/mcp is the one exception: it requires a bearer token (free or paid key) on every call — neither prepaid credits nor x402 apply to MCP tool calls.

The x402 challenge (402 Payment Required)

The response body for a 402 is {} — the real payload rides in a response header, PAYMENT-REQUIRED, base64-encoded JSON shaped like: 

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": { "url": "...", "description": "...", "mimeType": "application/json" },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "100000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "<treasury address>",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

amount is atomic USDC (6 decimals) as a string. network is Base mainnet (eip155:8453) in production; a deployment without live payment facilitator credentials falls back to Base Sepolia (eip155:84532) for testing. Resubmit the original request with a PAYMENT-SIGNATURE: <base64 payment payload> header; on success you get your normal response plus a PAYMENT-RESPONSE header (the settlement receipt). See the x402 spec or the hoodgrow-ts/hoodgrow-py/hoodgrow-mcp SDKs, which handle this loop for you.

Prepaid credits

Buy a bundle once via x402 (POST /api/agent/credits/purchase?bundle=<id> — 10/50/200 USD bundles, each with a bonus: $10 → $11 credit, $50 → $60, $200 → $260), then spend it down over many calls afterward without a fresh on-chain settlement each time. Every priced GET endpoint accepts it via three request headers sent together:

  • X-HoodGrow-Credit-Wallet: the wallet spending its balance
  • X-HoodGrow-Credit-Timestamp: unix seconds, must be within 60s of the server's clock
  • X-HoodGrow-Credit-Signature: an EIP-191 personal_sign signature over `HoodGrow credit spend\nmethod: <METHOD>\npath: <pathname>\ntimestamp: <timestamp>`, binding the signature to exactly this method+path+timestamp so it can never be replayed against a different (differently priced) endpoint or reused after the freshness window.

Debits the same price as that endpoint's own x402 price — a credit spend and an x402 payment for the same call always cost exactly the same. An empty/insufficient balance gets 402 with { "error": "insufficient credit balance", "balanceUsd": ..., "requiredUsd": ..., "topUp": "POST /api/agent/credits/purchase" }. Check your balance for free (no charge) via GET /api/agent/credits/balance using the same three headers.

Credit-funded webhooks are also possible without a Builder subscription: POST /api/agent/credits/webhook registers a delivery URL for free — nothing is charged for having a webhook registered. Each event that actually fires is billed $0.15 at delivery time (deliberately priced above every per-call GET, since a push does more for you than any single poll); automatic delivery retries never re-charge, and if the balance can't cover an event at send time, that one delivery is simply skipped (no charge, no retry queued).

Rate limits

Every endpoint enforces a flat per-IP limit (shown per operation below) on top of whatever your key's own limit is. A 429 includes Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers. A free key that has used its 40 requests for the UTC day gets a dedicated 429 explaining exactly that, with Retry-After set to seconds until UTC midnight.

Errors

Every non-x402 JSON error response across this API is the same one-field shape: { "error": "<human-readable message>" } — there is no code or nested error object anywhere.

More

Server:https://www.hoodgrow.com

Production

Client Libraries
Shell Curl