# HEY for agents

> HEY Research Lab is an evidence-backed research layer for Robinhood Chain (chain id 4663). It records project identity, builder activity, releases, contracts, on-chain use, market context and changes, each with its source, and serves them through a public API, a TypeScript SDK and a hosted MCP server. This page is for an autonomous agent or its developer: how to find HEY, connect, verify what it says, and monitor it. Nothing here is investment advice or an instruction to trade.

## Entry points

- [Hosted MCP](https://heyresearch.xyz/mcp): Streamable HTTP, stateless, read-only
- [Public API](https://heyresearch.xyz/api): OpenAPI 3.1 at https://heyresearch.xyz/openapi.json
- [A2A Agent Card](https://heyresearch.xyz/.well-known/agent-card.json): JSON-RPC at https://heyresearch.xyz/api/a2a
- [llms.txt](https://heyresearch.xyz/llms.txt): what HEY is, in one file
- [$HEY research profile](https://heyresearch.xyz/api/hey/profile): researched like any token
- [Change ledger](https://heyresearch.xyz/api/changes): poll with a cursor

## How an agent finds HEY

From the domain heyresearch.xyz alone, a plain HTTP client with no JavaScript and no cookies can reach every entry point.

- https://heyresearch.xyz/llms.txt (llmstxt.org): what HEY is, what it will not do, and every machine entry point. Pages point to it with a `Link: <…/llms.txt>; rel="describedby"` header.
- https://heyresearch.xyz/.well-known/agent-card.json: the A2A Agent Card (A2A 1.0), at the well-known URI the specification registers.
- https://heyresearch.xyz/openapi.json: the OpenAPI 3.1 description of the public API.
- The Official MCP Registry name is `io.github.hey-research-lab/hey-research`; the npm packages are `@hey-research-lab/mcp` and `@hey-research-lab/sdk`; the public source is https://github.com/hey-research-lab/hey-research-open.
- Robinhood Chain is chain id 4663. HEY is itself a project on it and is researched by the same rules as every other one — no ranking bonus for hosting the MCP, being used, or holding $HEY.

## MCP quickstart

The hosted server needs no install and no key. It reads the same public API, so it can say nothing the API does not.

Claude Code (hosted):

```
claude mcp add --transport http hey-research https://heyresearch.xyz/mcp
```

Any MCP client (Streamable HTTP):

```
{
  "mcpServers": {
    "hey-research": {
      "type": "http",
      "url": "https://heyresearch.xyz/mcp"
    }
  }
}
```

Local (stdio, Node 20+):

```
npx -y @hey-research-lab/mcp
```

- [MCP documentation](https://heyresearch.xyz/docs/mcp)

## Which interface to use

One record, four doors. Pick by what you are building; the answers are the same.

- MCP — tools an assistant calls while it answers someone. Tool-oriented: find_projects, get_project_snapshot, get_changes, explain_fact and the rest.
- A2A — delegate a research task to HEY as an agent. Skills: research_project, compare_projects, what_changed, explain_fact, check_project_coverage, investigate_contract. Send `A2A-Version: 1.0`; each message is answered directly, nothing is stored.
- REST API + OpenAPI — any language, any HTTP client; JSON with provenance on every figure.
- SDK — `@hey-research-lab/sdk` for TypeScript: typed calls, cursor helpers, webhook verification.

A2A SendMessage:

```
curl -s https://heyresearch.xyz/api/a2a -H 'content-type: application/json' -H 'A2A-Version: 1.0' \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"messageId":"m1","role":"ROLE_USER","parts":[{"data":{"skill":"research_project","project":"<slug>"}}]}}}'
```

## What is public, what needs a key, the limits

Every read is public: no account, no key, no cookie. CORS is open for reads.

- Without a key: 120 requests a minute per client address; answers are cached for 60 seconds.
- With an API key (`Authorization: Bearer <key>`): 120 / 600 / 1200 a minute by tier, a monthly allowance, and private (uncached) answers. Bulk reads and webhooks require a key.
- A2A: 60 messages a minute per client. Receipt validation: 30 a minute per client, 64 KB per receipt.
- The hosted MCP is metered as you: the same per-minute limits, and your key's allowance if you send one.

## How to verify what HEY says

Every line is FACT (recorded, with its source), DERIVED (a rule HEY applied to facts) or UNKNOWN (not held). Every published claim has a typed evidence id (ship:, signal:, abi:, impl:, lock:, source:, claim:, state:, integrity:, narrative:, method:, sourcechange:, security:) that /api/evidence/{id} resolves to a receipt.

- Unknown is not zero: an absent or null field means HEY does not know, never 0, false, [] or "none".
- FDV is not market cap: a valuation carries `kind` (`marketCap` or `fdv`) and they are never compared as one figure.
- Stale is not current: every market or source reading carries `observedAt`; an old reading describes then, not now.
- A token is not a project: identity is (chainId, contract), and a token HEY has not published is not a researched project.
- Market is not building: price, liquidity and volume are context and never an input to activity status, Build Momentum, the Discovery Gap or the Radar.
- Before concluding anything from an absence, read https://heyresearch.xyz/api/projects/<slug>/coverage — states, never a score.
- To see why a figure is what it is: https://heyresearch.xyz/api/projects/<slug>/explain?fact=<fact>.

Resolve an evidence id:

```
curl -s "https://heyresearch.xyz/api/evidence/<id>"
```

## How to stay in step

One canonical ChangeEvent per meaningful change. Every surface — API, MCP, RSS, webhooks — reads the same ledger.

- Poll https://heyresearch.xyz/api/changes?after=<cursor>, starting at `c1.0`; apply each page and keep its `nextCursor`. Never sync on a timestamp.
- occurredAt is when a source dates the event (null when only HEY observed it); detectedAt is when HEY first knew; recordedAt is when the ledger recorded it.
- Or subscribe with webhooks: https://heyresearch.xyz/docs/webhooks.
- RSS: https://heyresearch.xyz/feed/ships.xml.

## How to research $HEY

$HEY is researched like any Robinhood Chain token. https://heyresearch.xyz/api/hey/profile answers with research data, not marketing copy.

- Contract: 0xb33eb16782776b4d738c0fd643577cb0284db610 on chain 4663.
- Supply and market readings carry their provider, observation time and valuation kind; a stale reading is flagged; unknown stays null with a reason.
- Every documented utility carries LIVE, PLANNED, RETIRED or UNKNOWN, derived from the gates the product itself opens on — planned utility is never reported as live.
- The associated project is https://heyresearch.xyz/project/<slug> with its own snapshot; the profile links it. Holding $HEY never changes a ranking.
- Documentation: https://heyresearch.xyz/hey and https://heyresearch.xyz/docs/research-economy.

## Record your own research

An AgentResearchReceipt says "I reached this conclusion from these facts at this time" — for any project, in the agent's own vocabulary, without a reasoning trace.

- Schema: https://heyresearch.xyz/schemas/agent-research-receipt.v1.json. Documentation and examples: https://heyresearch.xyz/docs/agent-research-receipts.
- POST https://heyresearch.xyz/api/receipts/validate checks the shape and that each cited HEY id exists. HEY stores nothing, fetches nothing the receipt names, and never endorses a conclusion.
- Outcomes such as PASS, MONITOR or RESEARCH_MORE are the agent's own decision under its own mandate.

## What HEY does not do

HEY provides evidence and interoperability, never market direction.

- No wallet analytics, PnL, smart-money or whale labels, wallet profiles or "follow this wallet".
- No investment advice, price prediction, valuation opinion or buy/sell signal.
- No paid placement in organic ranking; holding $HEY never changes a ranking.
- No provider call in a read: every answer comes from HEY's own tables.
- No coordinated buying, no copy-trade loop, no agent consensus presented as a signal.

This page: https://heyresearch.xyz/developers/agents. Everything about HEY in one file: https://heyresearch.xyz/llms.txt.