HEY for agents

Discover

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.

Connect

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 mcp add --transport http hey-research https://heyresearch.xyz/mcp

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

npx -y @hey-research-lab/mcp

MCP documentation

Choose

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.

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>"}}]}}}'

Access

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.

Verify

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>.

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

Monitor

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.

$HEY

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.

Receipts

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.

Boundaries

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.