# robinhood-chain-mcp

**The intelligence layer for Robinhood Chain agents.** An MCP server any Claude / agent
can query against live [Robinhood Chain](https://docs.robinhood.com/chain) (chain id 4663)
data: tokens, wallets, Chainlink feeds, heat scores — and the one signal nobody else
surfaces: **live tracking error on tokenized equities**.

Robinhood's official [Trading MCP](https://robinhood.com/us/en/agentic-trading/)
(`agent.robinhood.com/mcp/trading`) gives agents **hands** — portfolio reads and order
placement on the brokerage. This server gives them **eyes on the chain itself**: what's
hot on the L2, who holds it, and whether a tokenized stock is trading rich to its
Chainlink feed. Different layer, same agent config — the eyes find the premium, the
hands place the order, the human approves.

```
you  → "is NVDA on Robinhood Chain trading rich to the real stock?"
agent → entity_signals("nvda")
      → { market_price_usd: 202.62, feed_price_usd: 202.615, premium_bps: 0,
          feed_age_seconds: 15188, score: { value: 73, label: "hot" } }
```

Zero API keys. Read-only by construction — public Blockscout GETs and RPC `eth_call`
only. No signing, no positions, no money.

## Running in 5 minutes

```bash
git clone https://github.com/arambarnett/robinhood-chain-mcp
cd robinhood-chain-mcp && npm install && npm run build

# Claude Code
claude mcp add robinhood-chain -- node $(pwd)/dist/index.js

# or any MCP client (stdio)
node dist/index.js

# or remote (streamable HTTP, stateless, rate-limited)
MCP_TRANSPORT=http PORT=8080 node dist/index.js
```

Then ask your agent things like *"what's hot on Robinhood Chain right now"*,
*"who are the top holders of tokenized TSLA"*, or *"map the whole ecosystem"* —
the full-chain index (every ERC-20, risk-flagged and scored) is also served as
a plain JSON API with a visual map at
[labs.arambarnett.com/demo/robinhood](https://labs.arambarnett.com/demo/robinhood)
(`/api/rhc-ecosystem`).

Running it next to Robinhood's official Trading MCP closes the loop —
intelligence from the chain, execution on the brokerage:

```json
{
  "mcpServers": {
    "robinhood-chain": { "command": "node", "args": ["/path/to/robinhood-chain-mcp/dist/index.js"] },
    "robinhood-trading": { "url": "https://agent.robinhood.com/mcp/trading" }
  }
}
```

## The four tools

| Tool | Question it answers | Example |
|---|---|---|
| `lookup_entity` | who/what is X? | `"NVDA"` → official tokenized equity, contract, price, holders, its Chainlink feed |
| `entity_connections` | what is X connected to? | token → chain, feed, underlying equity, top holders; wallet → holdings |
| `related_markets` | what moves with X? | `"top"` → the heat board; `"ecosystem"` (or `"ecosystem:community"`) → the full-chain index; a token → its feed + category peers |
| `entity_signals` | is anything happening? | heat 0–100 with components + `premium_bps` vs the Chainlink feed |

## Receipts (live values, 2026-07-10)

- **Heat board**: USDG 96/100 · Ethena USDe 90 · WETH 81 · Cash Cat (yes, a memecoin) 80
- **Tracking error**: NVDA token +0 bps vs its onchain Chainlink feed — arbitrage-tight 9 days after launch
- **The chain**: 762,748 addresses, 101ms blocks, average gas 0.11 gwei
- **Coverage**: every ERC-20 on the chain resolves by contract address (RAS §7 —
  permissionless, no allowlist), ~100 kept warm in the 60s cache, 42 Chainlink USD
  feeds mapped — and the memecoin economy included: a token named 🪶 has a third of
  all addresses holding it
- **Onchain**: [`BuildReceipt.sol` deployed & source-verified on Robinhood Chain testnet](https://explorer.testnet.chain.robinhood.com/address/0x09b7764f47c682225d641c7144ec82bff436c934) —
  `cast call 0x09B7764F47C682225d641c7144Ec82BFF436C934 "MESSAGE()(string)"` reads this repo's URL back from the chain

## How the score works

Heat 0–100, components always spelled out, never hidden:
24h volume (40) + holders (25) + market cap (20) + oracle-backed (15).

**Freshness doctrine:** every response carries `as_of` and `stale_seconds`. The token
universe cache is 60s — answers are never more than a minute behind the chain and say
exactly how far behind they are. Stock feeds run 24/5; off market hours the feed age
is reported honestly (`feed_age_seconds`), not hidden.

## Why `premium_bps` matters

Tokenized equities have two prices: the **onchain market price** (what the token trades
at) and the **Chainlink feed** (underlying share price × Robinhood's corporate-action
multiplier). The spread between them is the token's tracking error. Wide premium =
demand outrunning mint capacity; wide discount = exits outrunning redemption. It's
computed live, per query, from both sources.

## Standard

This server is the **reference read-plane implementation of the
[RHC Agent Schema](https://github.com/arambarnett/rhc-agent-schema)** — an
open MIT standard for MCP agent tooling on Robinhood Chain (common entity
types, object shapes, read-vs-execute separation, freshness and neutrality
rules). Per the standard's §7: indexing is permissionless — **any** token on
the chain resolves by contract address, no allowlist, and every score's
components are disclosed. Build a conforming server (launch tooling, DEX
routing, portfolio analytics…) and it composes with this one in the same
agent toolbelt automatically.

## Architecture

Everything domain-specific lives behind one interface (`src/adapter.ts`) — the MCP
layer (tools, transports, rate limiting) is vertical-agnostic. This same server core
fronts a prediction-market graph, a creator-matching graph, and an inbox relationship
graph at [Barnett Labs](https://labs.arambarnett.com/demo). A new vertical is ~150
lines. This repo's vertical is `src/adapters/robinhoodChain.ts`.

Data sources: [Blockscout](https://robinhoodchain.blockscout.com) REST ·
`rpc.mainnet.chain.robinhood.com` · Chainlink AggregatorV3 proxies
([source of truth](https://docs.chain.link/data-feeds/price-feeds/addresses?network=robinhood)).

`contracts/` holds the Foundry toolchain-validation contract for the chain.

## Not investment advice

Showcase infrastructure. Scores describe onchain activity, not asset quality.

---

Built by [Barnett Labs](https://labs.arambarnett.com) — the lab takes two builds a
quarter. MIT.