{"openapi":"3.1.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"HEY Research Lab public API","version":"1","summary":"Evidence-backed Robinhood Chain research: builders, ships, contracts, changes, market context.","description":"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.\n\nUse HEY when you need evidence-backed information about Robinhood Chain projects: who is building, what they shipped, their contracts, what changed and when, market context with its reading date, and where HEY has no evidence.\n\nBase URL https://heyresearch.xyz/api on Robinhood Chain (chainId 4663). Token identity is (chainId, contract), never a symbol.\n\n$HEY is HEY's token: contract 0xb33eb16782776b4d738c0fd643577cb0284db610 on Robinhood Chain (chain id 4663). Research it like any token at https://heyresearch.xyz/api/hey/profile\n\nHEY Research Lab is the product's brand name; \"Hey Research Lab\" is the same entity as its own project record and social accounts spell it.\n\n**Semantic traps — read before using any figure:**\n- Unknown is not zero: an absent or null field means HEY does not know, never 0, false, [] or \"none\".\n- FDV is not market cap: a valuation carries `kind` (`marketCap` or `fdv`) and they are never compared as one figure.\n- Stale is not current: every market or source reading carries `observedAt`; an old reading describes then, not now.\n- A token is not a project: identity is (chainId, contract), and a token HEY has not published is not a researched project.\n- 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.\n\n**Evidence.** 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.\n\n**What HEY does not do:**\n- No wallet analytics, PnL, smart-money or whale labels, wallet profiles or \"follow this wallet\".\n- No investment advice, price prediction, valuation opinion or buy/sell signal.\n- No paid placement in organic ranking; holding $HEY never changes a ranking.\n- No provider call in a read: every answer comes from HEY's own tables.\n\n**Access.** No key is needed: 120 requests a minute per client. An API key (`Authorization: Bearer <key>` or `x-api-key`) raises it to 120 / 600 / 1200 a minute by tier and adds a monthly allowance; keyed answers are private (`cache-control: private`). Anonymous answers are cached for 60 seconds. CORS is open for GET.\n\n**Also:**\n- hosted MCP server (Streamable HTTP, read-only): https://heyresearch.xyz/mcp\n- A2A Agent Card: https://heyresearch.xyz/.well-known/agent-card.json\n- llms.txt: https://heyresearch.xyz/llms.txt\n- agent guide: https://heyresearch.xyz/developers/agents\n- monitor with `/api/changes` (cursor `after=`), webhooks documented at https://heyresearch.xyz/docs/webhooks or RSS at https://heyresearch.xyz/feed/ships.xml","x-hey":{"brand":"HEY Research Lab","projectRecordName":"Hey Research Lab","nameNote":"HEY Research Lab is the product's brand name; \"Hey Research Lab\" is the same entity as its own project record and social accounts spell it.","domain":"heyresearch.xyz","chain":{"name":"Robinhood Chain","chainId":4663},"token":{"symbol":"$HEY","chainId":4663,"status":"live","contract":"0xb33eb16782776b4d738c0fd643577cb0284db610","caip10":"eip155:4663:0xb33eb16782776b4d738c0fd643577cb0284db610","profile":"https://heyresearch.xyz/api/hey/profile"},"mcp":{"endpoint":"https://heyresearch.xyz/mcp","transport":"streamable-http","registryName":"io.github.hey-research-lab/hey-research","npmPackage":"@hey-research-lab/mcp"},"api":{"base":"https://heyresearch.xyz/api","openapi":"https://heyresearch.xyz/openapi.json"},"agentCard":"https://heyresearch.xyz/.well-known/agent-card.json","llmsTxt":"https://heyresearch.xyz/llms.txt"},"contact":{"name":"HEY Research Lab","url":"https://heyresearch.xyz/developers"},"license":{"name":"Terms of use: cite HEY and link the source","url":"https://heyresearch.xyz/docs/public-api"}},"externalDocs":{"description":"The full public API reference","url":"https://heyresearch.xyz/docs/public-api"},"servers":[{"url":"https://heyresearch.xyz","description":"heyresearch.xyz"}],"tags":[{"name":"projects","description":"Find and read published projects. A token is not a project; an unpublished record is not researched."},{"name":"research","description":"One project in depth: snapshot, coverage, explain, timeline, history, diff."},{"name":"evidence","description":"Typed evidence ids resolved to receipts, and the change ledger."},{"name":"market","description":"Market context. Never an input to activity status, Build Momentum, the Discovery Gap or the Radar."},{"name":"contracts","description":"Contracts as research entities."},{"name":"hey","description":"$HEY, researched like any other token."},{"name":"agents","description":"Machine interfaces: A2A and agent research receipts."},{"name":"partners","description":"Builder intelligence for another product, in one call by contract. Carry `project_link` wherever you render it."},{"name":"status","description":"HEY's own freshness."}],"paths":{"/api/projects":{"get":{"operationId":"listProjects","summary":"Search and browse published projects","description":"The published catalogue. `q` searches names, symbols and contracts. Market filters (`minMarketCap`, `sort=marketCap`) are the reader asking for context, not HEY ranking by price. A missing `marketCap` is unknown, never zero; `marketCap.kind` says whether it is a market cap or an FDV.","tags":["projects"],"parameters":[{"name":"q","in":"query","description":"Text search, 2–120 characters.","schema":{"type":"string"}},{"name":"tab","in":"query","description":"A discovery surface (e.g. `still-building`, `under-the-radar`, `shipping-now`).","schema":{"type":"string"}},{"name":"kind","in":"query","description":"Project kind.","schema":{"type":"string"}},{"name":"status","in":"query","description":"Activity status: SHIPPING, ACTIVE, QUIET, DORMANT, RESUMED, UNKNOWN. UNKNOWN is not inactive.","schema":{"type":"string"}},{"name":"narrative","in":"query","description":"Narrative slug.","schema":{"type":"string"}},{"name":"launchpad","in":"query","description":"Launchpad.","schema":{"type":"string"}},{"name":"has","in":"query","description":"Card facts the project must have, comma-separated.","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Reader-chosen order.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Rows per page, 1–48; default 24.","schema":{"type":"integer","minimum":1,"maximum":48}},{"name":"offset","in":"query","description":"Offset for paging; follow `nextOffset`.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"A page of project cards with `total`, `nextOffset` and a disclaimer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/search/suggest":{"get":{"operationId":"suggestProjects","summary":"Type-ahead over names, symbols and contracts","description":"Identity only (name, ticker, contract, route), for every reader. At most eight rows.","tags":["projects"],"parameters":[{"name":"q","in":"query","description":"2–64 characters.","schema":{"type":"string"}}],"responses":{"200":{"description":"Suggestions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}":{"get":{"operationId":"getProject","summary":"One project's dossier","description":"Description, token identity, every registered source with how it was established, and market context with its provider and `observedAt`.","tags":["projects"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}}],"responses":{"200":{"description":"The project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/snapshot":{"get":{"operationId":"getProjectSnapshot","summary":"One project's important state in one read","description":"Identity, build, market (with `kind`, provider and `observedAt` on every figure, and `valuationWithheld` when a dead market's valuation is withheld), on-chain use, verification, locks, the newest changes, freshness and coverage. Start here. `buildMomentum` is absent when not measured — absent is unknown, not zero. `latestChanges.available: false` means HEY cannot list them, not that there were none.","tags":["research"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}}],"responses":{"200":{"description":"The snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/coverage":{"get":{"operationId":"getProjectCoverage","summary":"What HEY knows and does not, per dimension","description":"States, never a score: MEASURED, NO_SOURCE, NOT_ENOUGH_YET, STALE, SOURCE_UNAVAILABLE, NOT_APPLICABLE, NOT_RESEARCHED, ERROR, WITHHELD. Read it before concluding anything from an absence; a zero under NO_SOURCE is not a finding.","tags":["research"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}}],"responses":{"200":{"description":"Coverage and freshness.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/explain":{"get":{"operationId":"explainProjectFact","summary":"Why HEY publishes a fact","description":"The value, the rule, the inputs, the lineage from source to public value, the evidence ids and what HEY does not know. Without `fact`, the facts HEY can explain for this project. Read from persisted evaluations; nothing is re-derived.","tags":["research"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}},{"name":"fact","in":"query","description":"The fact to explain.","schema":{"type":"string","enum":["market.valuation","market.status","activity.status","build.momentum","discovery_gap","still_building","research.level","token.verification","source.counted","market_integrity.state"]}},{"name":"source","in":"query","description":"For `source.counted`: a `source:<uuid>` id.","schema":{"type":"string"}}],"responses":{"200":{"description":"An explanation, or the index of explainable facts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/timeline":{"get":{"operationId":"getProjectTimeline","summary":"Every kind of evidence on one axis","description":"Newest first, with `totals`, `truncated` and a `nextCursor` to pass as `before`.","tags":["research"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}},{"name":"lens","in":"query","description":"Narrow to one kind of evidence.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Rows per page.","schema":{"type":"integer","minimum":1}},{"name":"before","in":"query","description":"Cursor from `nextCursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"A timeline page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/history":{"get":{"operationId":"getProjectHistory","summary":"The points HEY persisted","description":"Each series declares `collectedFrom` and `basis` (`knowledge`, `observed`, `reconstructed_from_chain`). A day HEY did not record is absent, never zero; the past is never recomputed with today's evidence.","tags":["research"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}},{"name":"series","in":"query","description":"Series names, comma-separated.","schema":{"type":"string"}},{"name":"from","in":"query","description":"YYYY-MM-DD.","schema":{"type":"string"}},{"name":"to","in":"query","description":"YYYY-MM-DD.","schema":{"type":"string"}}],"responses":{"200":{"description":"Series.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/diff":{"get":{"operationId":"getProjectDiff","summary":"Then and now, never a cause","description":"Two dates at most 400 days apart. A difference is not an explanation of why.","tags":["research"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}},{"name":"from","in":"query","description":"YYYY-MM-DD.","schema":{"type":"string"}},{"name":"to","in":"query","description":"YYYY-MM-DD.","schema":{"type":"string"}}],"responses":{"200":{"description":"The diff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/market":{"get":{"operationId":"getProjectMarket","summary":"HEY's own daily index of the project's token","description":"Context only. Every figure has its provider and reading date; an old reading describes then, not now. FDV and market cap are never mixed. Never an input to activity status, Build Momentum, the Discovery Gap or the Radar.","tags":["market"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}},{"name":"days","in":"query","description":"1–400; default 30.","schema":{"type":"integer","minimum":1,"maximum":400}}],"responses":{"200":{"description":"Daily market index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/relationships":{"get":{"operationId":"getProjectRelationships","summary":"What is connected to one project, and why HEY thinks so","description":"First-degree relationships from HEY's own records: the token, contracts and where their proxies point, official repositories, domain and docs, packages (official or claimed), the launchpad and registry that list it, corroborating readings and moderated project relationships. Every edge carries its state, typed evidence ids and when HEY observed it. No account is ever a node and no partnership edge exists; contract-to-contract interaction is not held yet and says so in `notHeld`.","tags":["research"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}}],"responses":{"200":{"description":"The relationship graph.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/projects/{slug}/contracts":{"get":{"operationId":"getProjectContracts","summary":"The project's contracts","description":"Each as `/api/contracts/{chainId}/{address}` serves it, with whether HEY measured each section.","tags":["contracts"],"parameters":[{"name":"slug","in":"path","required":true,"description":"A published project's slug. A renamed slug answers 308 to the current one.","schema":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"}}],"responses":{"200":{"description":"Contracts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/compare":{"get":{"operationId":"compareProjects","summary":"Two to four projects side by side","description":"The page's own figures and gates, no winner.","tags":["projects"],"parameters":[{"name":"slugs","in":"query","description":"Two to four slugs, comma-separated.","schema":{"type":"string"}}],"responses":{"200":{"description":"Columns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/changes":{"get":{"operationId":"listChanges","summary":"The change ledger","description":"One canonical event per meaningful change HEY recorded. Mirror with `after=<cursor>` (start at `c1.0`) and keep each page's `nextCursor` — never sync on a timestamp. `occurredAt` is set only when a source dates the event (else null, precision OBSERVED); `detectedAt` is when HEY first knew; `recordedAt` when it entered the ledger. A `retract` is a tombstone carrying only the id: delete your copy.","tags":["evidence"],"parameters":[{"name":"after","in":"query","description":"Sync forward from this cursor.","schema":{"type":"string"}},{"name":"before","in":"query","description":"Browse older than this cursor.","schema":{"type":"string"}},{"name":"detectedSince","in":"query","description":"Start a sync at the first event recorded at or after this ISO instant.","schema":{"type":"string"}},{"name":"project","in":"query","description":"A project slug.","schema":{"type":"string"}},{"name":"contract","in":"query","description":"`<chainId>:<address>`.","schema":{"type":"string"}},{"name":"domain","in":"query","description":"Comma-separated domains.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Comma-separated event types.","schema":{"type":"string"}},{"name":"since","in":"query","description":"Filter on `occurredAt`.","schema":{"type":"string"}},{"name":"until","in":"query","description":"Filter on `occurredAt`.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Rows per page, 1–100; default 50.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"A page of ChangeEvents with `nextCursor`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/evidence/{id}":{"get":{"operationId":"getEvidence","summary":"Resolve a typed evidence id to a receipt","description":"One published record by its typed id: `ship:`, `signal:`, `abi:`, `impl:`, `lock:`, `source:`, `claim:`, `state:`, `integrity:`, `narrative:`, `method:`, `sourcechange:`, `security:`. A withdrawn or hidden record answers `withdrawn: true` and names nothing it may not. A ChangeEvent id with a suffix (`source:<uuid>:added`) is not an evidence id.","tags":["evidence"],"parameters":[{"name":"id","in":"path","required":true,"description":"A typed evidence id, URL-encoded.","schema":{"type":"string","maxLength":240}}],"responses":{"200":{"description":"The receipt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/contracts/{chainId}/{address}":{"get":{"operationId":"getContract","summary":"One contract as a research entity","description":"Creation, deployer, proxy and implementation history, verified source, interface counts and seven-day activity, each section with whether HEY measured it. Identity is (chainId, address).","tags":["contracts"],"parameters":[{"name":"chainId","in":"path","required":true,"schema":{"type":"integer","const":4663}},{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"The contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/token/{chainId}/{address}":{"get":{"operationId":"lookupToken","summary":"Resolve a token contract to a published project","description":"`status: \"unknown\"` is an answer, not an error: HEY has not published a project for that contract. A token is not a project.","tags":["projects"],"parameters":[{"name":"chainId","in":"path","required":true,"schema":{"type":"integer","const":4663}},{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"The lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/builder":{"get":{"operationId":"getPartnerBuilderCard","summary":"The Partner Card: builder intelligence for one token","description":"Builder status, verified builder, latest meaningful ship, meaningful ships in 30 days, the latest builder-side change and signal, token verification, market status (context only), badge, project link and freshness — from HEY's own tables, no provider call. Explicit `null` means HEY does not hold it; a count HEY did not measure is `null`, never 0. An unpublished contract answers 404 with `scan_url`; another chain 400. A token is not a project: on `activity_applies_to_token: false` print the activity as the project's, never as this token's.","tags":["partners"],"parameters":[{"name":"chain","in":"query","description":"The chain id; optional, 4663 (the only chain HEY indexes).","schema":{"type":"integer","const":4663}},{"name":"token","in":"query","required":true,"description":"The token contract.","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"integration","in":"query","description":"Optional: your integration as `name` or `name/version` (lower-case letters, digits, `.`, `_`, `-`). Also accepted as the `x-hey-integration` header. Recorded as a self-declaration and used as `project_link`'s `utm_source`; anything else is ignored.","schema":{"type":"string","maxLength":65}}],"responses":{"200":{"description":"The Partner Card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerBuilderCard"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/scan":{"get":{"operationId":"getPartnerScanCard","summary":"The one-line scan card for a bot","description":"The by-contract lookup in a trading bot's card shape. `found: false` is a 200 for an unpublished token, another chain and the zero address (`reason: \"not_a_token\"`); a malformed token is a 400. `activity.commits_30d` is absent, never 0, without a readable repository; `activity_measured: false` means the zero counts are not findings. `project_link` carries HEY's attribution labels. `tokens=` (up to 30, keyed) is the bulk form.","tags":["partners"],"parameters":[{"name":"chain","in":"query","description":"The chain id; optional, 4663 (the only chain HEY indexes).","schema":{"type":"integer","const":4663}},{"name":"token","in":"query","required":false,"description":"The token contract (or `tokens=` for up to 30, keyed).","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"tokens","in":"query","description":"Comma-separated contracts, at most 30; requires a key and returns one item per input in order.","schema":{"type":"string"}},{"name":"integration","in":"query","description":"Optional: your integration as `name` or `name/version` (lower-case letters, digits, `.`, `_`, `-`). Also accepted as the `x-hey-integration` header. Recorded as a self-declaration and used as `project_link`'s `utm_source`; anything else is ignored.","schema":{"type":"string","maxLength":65}}],"responses":{"200":{"description":"The scan card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/ships":{"get":{"operationId":"listShips","summary":"What projects shipped","description":"A record of ships, each with the public source it was recorded from and how it is backed (self-reported, source-linked, source-verified).","tags":["projects"],"parameters":[{"name":"limit","in":"query","description":"Rows per page, 1–48; default 24.","schema":{"type":"integer","minimum":1,"maximum":48}},{"name":"offset","in":"query","description":"Offset.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"A page of ships.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/builders":{"get":{"operationId":"listBuilders","summary":"The Builder Radar","description":"Ranked by verified development, on-chain use and research standing, never by price, payment or $HEY holding.","tags":["projects"],"parameters":[{"name":"filter","in":"query","description":"A Radar filter, as on the page.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Text search, 2–80 characters.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Rows per page, 1–200; default 50.","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","description":"Offset.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Radar page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/hey/profile":{"get":{"operationId":"getHeyProfile","summary":"$HEY as research data","description":"Identity, contract (null before launch, with a reason), chain, supply read from the chain, launch, market with valuation `kind` and `observedAt`, locks, HEY's own project snapshot (researched by the same rules as every project), recent changes, holder tiers, and every documented utility with status LIVE / PLANNED / RETIRED / UNKNOWN derived from the gates the product opens on. Not investment advice; unknown stays null with a reason.","tags":["hey"],"parameters":[],"responses":{"200":{"description":"The profile (schema `hey.token-profile/v1`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/receipts/validate":{"post":{"operationId":"validateAgentResearchReceipt","summary":"Check an agent research receipt","description":"Stateless and read-only: checks a receipt's shape against the AgentResearchReceipt v1 schema (https://heyresearch.xyz/schemas/agent-research-receipt.v1.json) and whether each HEY evidence id it cites exists and is public: a change event against its cited revision, a snapshot only as project_exists (its asOf is not verified; its scoringVersion is compared with the current one). heyEvidenceStands is true only when every HEY reference was checked and stands, \"partial\" when some were not checked, and null when none was. Nothing is stored, nothing is fetched from URLs in the receipt, and the answer is never an endorsement of the receipt's conclusion.","tags":["agents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"responses":{"200":{"description":"The validation result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/a2a":{"post":{"operationId":"a2aJsonRpc","summary":"A2A JSON-RPC interface (SendMessage)","description":"The A2A 1.0 JSON-RPC binding described by https://heyresearch.xyz/.well-known/agent-card.json. Send `A2A-Version: 1.0`. Stateless: SendMessage answers with a Message (no task is stored), built from the same canonical reads as this API.","tags":["agents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"responses":{"200":{"description":"A JSON-RPC response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/status":{"get":{"operationId":"getStatus","summary":"HEY's own freshness and health","description":"When each pipeline last ran and whether it is fresh.","tags":["status"],"parameters":[],"responses":{"200":{"description":"Status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"An API key from the HEY account page. Optional: every read works without one."},"headerKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same key in a header."}},"schemas":{"Object":{"type":"object","additionalProperties":true,"description":"See https://heyresearch.xyz/docs/public-api for every field. Absent means unknown."},"PartnerBuilderCard":{"type":"object","additionalProperties":true,"required":["contract_address","chain_id","status","hey_status","hey_status_label","hey_status_help","hey_project_name","hey_project_url","project_link","token_verification","activity_applies_to_token","verified_builder","research_level","activity_measured","last_activity_at","latest_meaningful_ship","meaningful_ships_30d","latest_change","latest_change_state","latest_signal","repo_url","last_commit","last_code_activity","latest_release","latest_deployment","market_status","badge_url","as_of","disclaimer"],"properties":{"contract_address":{"type":"string","description":"The contract asked about, lower-cased."},"chain_id":{"type":"integer","description":"The chain HEY indexes: Robinhood Chain, 4663."},"status":{"type":"string","description":"`active`, `stale`, `dormant` or `unknown`. There is no `abandoned`: HEY sees silence, not intent. Unknown: `unknown`: not enough public sources to say either way."},"hey_status":{"type":"string","description":"HEY’s own activity status: SHIPPING, ACTIVE, RESUMED, QUIET, DORMANT or UNKNOWN. Derived from what the project ships, never from price."},"hey_status_label":{"type":"string","description":"The status in HEY’s words. Print this rather than a word of your own."},"hey_status_help":{"type":"string","description":"One sentence explaining the status."},"hey_project_name":{"type":"string","description":"The project’s name as HEY publishes it."},"hey_project_url":{"type":"string","description":"The canonical project page, without labels."},"project_link":{"type":"string","description":"The project page with HEY’s attribution labels (`utm_medium=partner_api`, `utm_source` = your declared integration or `hey_api`). Link this one."},"token_verification":{"type":"string","description":"`VERIFIED`, `UNVERIFIED` or `MISMATCH`: whether the project itself names this contract."},"activity_applies_to_token":{"type":"boolean","description":"False exactly on `MISMATCH`: then print the activity as the project’s, never as this token’s, and do not link the token to the project."},"verified_builder":{"type":"boolean","description":"HEY verified the project as a builder, source by source (the badge the project page shows)."},"research_level":{"type":"string","description":"`INDEXED`, `RESEARCHED` or `VERIFIED_BUILDER`: how far HEY’s research went."},"activity_measured":{"type":"boolean","description":"Whether HEY measured this project’s building at all. False means an `unknown` status is not a finding."},"last_activity_at":{"type":["string","null"],"description":"The project’s most recent meaningful activity HEY recorded (ISO 8601). Unknown: null when HEY holds none."},"latest_meaningful_ship":{"type":["object","null"],"description":"The newest ship HEY counts as building evidence now: `title`, `url`, `timestamp`, `kind` and its `ship:` evidence id. Unknown: null when HEY holds none."},"meaningful_ships_30d":{"type":["integer","null"],"description":"Meaningful ships in thirty days by the rule behind the status: a week of prereleases or code summaries counts once. Unknown: null — never 0 — when HEY did not measure building and holds none."},"latest_change":{"type":["object","null"],"description":"The newest builder-side event in HEY’s change ledger: `id`, `type`, `summary`, `occurred_at`, `precision`, `detected_at`, `evidence_id`, `url`. Only the builder story: market, usage, coverage and narrative events are left out. Unknown: null; `latest_change_state` says whether none was recorded or the ledger could not answer."},"latest_change_state":{"type":"string","description":"`recorded`, `none_recorded` or `unavailable`. Unknown: `unavailable`: the ledger has not run or could not be read — unknown, not none."},"latest_signal":{"type":["object","null"],"description":"The newest standing HEY Signal about building, contracts, launch or research, with its `signal:` evidence id. Market-group and address-count kinds are left out. Unknown: null when none stands."},"repo_url":{"type":["string","null"],"description":"A repository HEY counts as the project’s own evidence. Unknown: null when HEY counts none."},"last_commit":{"type":"null","description":"Always null: HEY aggregates commits into weekly summaries and stores no SHA. Read `last_code_activity`."},"last_code_activity":{"type":["object","null"],"description":"The newest weekly code summary, with `commits_30d` counted like the scan card’s. Unknown: null when HEY holds none."},"latest_release":{"type":["object","null"],"description":"The newest counted release: `title`, `version`, `url`, `timestamp`. Unknown: null when HEY holds none."},"latest_deployment":{"type":["object","null"],"description":"The newest counted post-launch deployment or upgrade. A launch itself is not a ship. Unknown: null when HEY holds none."},"market_status":{"type":"object","description":"This token’s market state (`status`, `observed_at`): context only, never a builder input and never a direction. Unknown: `INSUFFICIENT_DATA` with `observed_at: null` — not measured, not zero."},"badge_url":{"type":"string","description":"The project’s README badge (SVG)."},"as_of":{"type":["string","null"],"description":"When HEY last scored the project: the moment the status and counts describe. Unknown: null when never scored."},"disclaimer":{"type":"string","description":"HEY reports what a team shipped and how it knows; not a rating, not a verdict."}},"description":"The canonical Partner Card. Additive only: a key here never changes meaning."},"Error":{"type":"object","required":["error","message","retryable"],"properties":{"error":{"type":"string","description":"A stable machine code."},"message":{"type":"string","description":"A sentence for a person."},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"retryAfterSeconds":{"type":"integer"}}}},"responses":{"BadRequest":{"description":"The request was malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No published record answers this. A hidden project looks identical to one that never existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests; see `retry-after`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"HEY failed; retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{},{"bearerKey":[]},{"headerKey":[]}]}