HEY Research Lab Contracts API

openapi: 3.2.0
info:
  title: HEY Research Lab public Contracts API
  version: '1'
  summary: The public record of building on Robinhood Chain — every ship with its source.
  description: 'HEY Research Lab is the public record of building on Robinhood Chain (chain id 4663) — every ship with its source. 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. Use 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. Every path below begins with /api on https://heyresearch.xyz — an index answers at https://heyresearch.xyz/api — for Robinhood Chain (chainId 4663). Token identity is (chainId, contract), never a symbol. $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


    HEY Research Lab is the product''s brand name and the name of its own project record; it is spelled one way everywhere. **Semantic traps — read before using any figure:**

    - 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. - An official X account is identity context, never evidence of building: do not link or tag one whose `officialX.linkHeld` is set or whose `officialX.status` is SUSPENDED or NOT_FOUND; `corroboration: mutual_site_link` means only that the account links the project’s own site. - 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, valuation, liquidity and volume are context. Market figures (price, valuation, liquidity, volume) never feed activity status, Build Momentum or the Radar. The Discovery Gap is the one place market attention enters: it compares Build Momentum against market attention, measured on an active market only (elsewhere it is withheld, never 0). **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:, v4hook:, v4pool:, ponsgrad:) that /api/evidence/{id} resolves to a receipt. **What HEY does not do:**

    - 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. **Access.** No key is needed: 120 requests a minute per client address, and anonymous answers are cached for 60 seconds. An API key (`Authorization: Bearer ` or `x-api-key`) names your integration and unlocks the bulk reads; a free key keeps 120 a minute, in a bucket of its own rather than one shared by every caller on your address (holder keys: Holder 600, Holder+ 1200 a minute). Every key carries a monthly allowance (a spent allowance answers 429 `quota` until the month resets), and keyed answers are private (`cache-control: private, no-store`), never edge-cached. CORS is open for GET.'
  x-hey:
    brand: HEY Research Lab
    projectRecordName: HEY Research Lab
    nameNote: HEY Research Lab is the product's brand name and the name of its own project record; it is spelled one way everywhere.
    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
      researchEndpoint: https://heyresearch.xyz/mcp/research
      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
  termsOfService: https://heyresearch.xyz/terms
  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
servers:
- url: https://heyresearch.xyz
  description: heyresearch.xyz
security:
- {}
- bearerKey: []
- headerKey: []
tags:
- name: Contracts
  description: Contracts as research entities.
paths:
  /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][a-z0-9-]{0,79}$
          maxLength: 80
      responses:
        '200':
          description: Contracts.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            x-hey-api-version:
              $ref: '#/components/headers/ApiVersion'
            ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            ratelimit-policy:
              $ref: '#/components/headers/RateLimitPolicy'
            ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-hey-monthly-remaining:
              $ref: '#/components/headers/MonthlyRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /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. For a Uniswap v4 hook HEY stores, `uniswapV4Hook` adds its callbacks (what the PoolManager will call, not what the hook does), its attribution (a project only when HEY lists the hook; `NOT_READ` is not read yet, never "not tied"), pools on tokens HEY tracks and its `v4hook:` evidence id. 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.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            x-hey-api-version:
              $ref: '#/components/headers/ApiVersion'
            ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            ratelimit-policy:
              $ref: '#/components/headers/RateLimitPolicy'
            ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-hey-monthly-remaining:
              $ref: '#/components/headers/MonthlyRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/chain/contract-changes:
    get:
      operationId: listContractChanges
      summary: Evidence-backed contract changes on published projects
      description: 'Two families, newest first, each capped at 100 rows: upgrades and follow-up deployments (one row per project with a count, typed id `ship:`), and verification or interface changes HEY saw on the explorer (typed id `abi:`). `total` counts every row the listing holds and `truncated` says whether `items` shows fewer. Rows, not events.'
      tags:
      - Contracts
      parameters:
      - name: days
        in: query
        description: The window in days, 1–90; default 30. A value outside the range is clamped to it.
        schema:
          type: integer
          minimum: 1
          maximum: 90
      responses:
        '200':
          description: Contract changes with `total` and `truncated`.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            x-hey-api-version:
              $ref: '#/components/headers/ApiVersion'
            ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            ratelimit-policy:
              $ref: '#/components/headers/RateLimitPolicy'
            ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-hey-monthly-remaining:
              $ref: '#/components/headers/MonthlyRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v4-hooks:
    get:
      operationId: listV4Hooks
      summary: Uniswap v4 hooks HEY ties to a published project
      description: 'Attributed hooks only (founder ruling, 2026-10-01): a hook the account that launched a published project''s token created after the token, directly or through a deterministic deployer, while that follow-up deployment stands (`PROJECT_DEPLOYER`), or one the project''s own official contract listing names (`PROJECT_DECLARED`); since 2026-10-04 also one of the project''s qualified project-linked addresses created (`PROJECT_LINKED_CREATOR`, basis `linked`, the relationship named — listing only, never a ship), one HEY''s review confirmed (`PROJECT_REVIEWED`, basis `review`, never chain proof), and the hook instances a factory HEY ties to the project made (counted per factory in `projects[].factories`). Every other hook is counted in `aggregate` by attribution state and never listed or grouped by creator; no creator account is kept. Each row: the typed id (`v4hook:4663:`) and its receipt, how it is tied, the deployment ship id a deployer hook counts through, the creation block''s time when read (absent when not), the first pool''s block and time, pools on tokens HEY tracks, the callbacks its address declares (never what the code does or whether it is safe), and the project''s activity status with its canonical words. Newest deployment first, never ordered by pools or market; at most 100 rows. `total` counts every row the listing holds and `truncated` says whether `items` shows fewer. Market context only. Market figures (price, valuation, liquidity, volume) never feed activity status, Build Momentum or the Radar. The Discovery Gap is the one place market attention enters: it compares Build Momentum against market attention, measured on an active market only (elsewhere it is withheld, never 0). Served from HEY''s hourly copy (since 2026-10-11): `asOf` says when it was read, `readFrom` is `hourly_copy` or `live` (no copy yet; a bounded live read), and `stale` is true for a copy older than three hours. A live read that does not finish is a 503 `service_unavailable` — never an empty list.'
      tags:
      - Contracts
      parameters:
      - name: limit
        in: query
        description: Rows per page, 1–100; default 100.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: under
        in: query
        description: 'A reader''s market-context filter in USD: only projects whose printed valuation is below it. A project HEY prints no figure for is left out and counted in `filter.excludedNoFigure` (unknown is not small). Never an order.'
        schema:
          type: number
          exclusiveMinimum: 0
      - name: projects
        in: query
        description: '`shown` keeps only the shown rows'' projects in `projects` (`projectsShown` of `projectsTotal`); the default, `all`, holds every project matching the filter, since `limit` bounds rows, not projects. Factory instances stay counted in `aggregate.byBasis.factory`.'
        schema:
          type: string
          enum:
          - all
          - shown
          default: all
      responses:
        '200':
          description: Hooks with `answer`, `shown`, `total`, `truncated`, `order`, `filter` and `aggregate`.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            x-hey-api-version:
              $ref: '#/components/headers/ApiVersion'
            ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            ratelimit-policy:
              $ref: '#/components/headers/RateLimitPolicy'
            ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-hey-monthly-remaining:
              $ref: '#/components/headers/MonthlyRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v4-hooks/{address}:
    get:
      operationId: getV4Hook
      summary: 'One Uniswap v4 hook: who HEY ties it to, and what HEY does not know'
      description: 'One hook HEY holds on Robinhood Chain (2026-10-11), as `/integrations/uniswap/hooks/{address}` reads it: `answer`, one sentence; `listed`, whether HEY lists it under a published project — the only case in which `project` and `tie` are set (a hook tied to a project HEY does not list says `creation.state: "WITHHELD"` and names no project; no creator account is ever named); `creation.state` (`TIED`, `WITHHELD`, `LAUNCH_INSTANCE`, `NOT_TIED`, `NOT_READ`); the callbacks its address declares (never what the code does or whether it is safe); verified source and proxy as HEY''s contract read holds them (`NOT_READ` is never "unverified" or "not a proxy"); Uniswap''s hooklist entry as context (`LISTED`, `NOT_LISTED`, `NOT_READ`); `pools`, the pools on tokens HEY tracks — a count, the first and last init block and twelve ISO weeks counted by when HEY recorded them (basis `observed`; a week before `collectedFrom` is null, never zero) — context, never an order; the deployment record it counts through, if any; and `unknowns`, each null with its reason (routing allowlist, audit, dynamic fee from the chain: not read). The typed id is `v4hook:4663:`; its receipt stands only while `listed` is true. A malformed address is 400 `invalid_address`; a hook HEY does not hold is 404. Market context only. Market figures (price, valuation, liquidity, volume) never feed activity status, Build Momentum or the Radar. The Discovery Gap is the one place market attention enters: it compares Build Momentum against market attention, measured on an active market only (elsewhere it is withheld, never 0).'
      tags:
      - Contracts
      parameters:
      - name: address
        in: path
        required: true
        description: The hook contract, 0x and 40 hex characters; matched case-insensitively.
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]{40}$
      responses:
        '200':
          description: The hook, with `answer`, `listed`, `creation`, `pools` and `unknowns`.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            x-hey-api-version:
              $ref: '#/components/headers/ApiVersion'
            ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            ratelimit-policy:
              $ref: '#/components/headers/RateLimitPolicy'
            ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-hey-monthly-remaining:
              $ref: '#/components/headers/MonthlyRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  headers:
    RateLimitPolicy:
      description: The bucket as `<limit>;w=<seconds>`, e.g. `120;w=60` (2026-10-18). Pace by it.
      schema:
        type: string
    MonthlyRemaining:
      description: A keyed caller's monthly allowance left; absent without a key or without a cap.
      schema:
        type: integer
        minimum: 0
    RateLimitLimit:
      description: Requests the per-minute bucket that counted this request holds (2026-10-18).
      schema:
        type: integer
        minimum: 1
    ApiVersion:
      description: 'The contract the answer was written under: `1` for every `/api/*` read.'
      schema:
        type: string
    RequestId:
      description: The id HEY logged this request under; also `requestId` in an error body. Quote it when you write to HEY.
      schema:
        type: string
    RateLimitRemaining:
      description: What is left of your bucket; on a private (keyed) answer only — an anonymous answer is cached at the edge and served to other callers, so it never carries one caller's remainder (2026-10-18).
      schema:
        type: integer
        minimum: 0
  schemas:
    Object:
      type: object
      additionalProperties: true
      description: See https://heyresearch.xyz/docs/public-api for every field. Absent means unknown.
    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:
    NotFound:
      description: No published record answers this. A hidden project looks identical to one that never existed.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        x-hey-api-version:
          $ref: '#/components/headers/ApiVersion'
        ratelimit-limit:
          $ref: '#/components/headers/RateLimitLimit'
        ratelimit-policy:
          $ref: '#/components/headers/RateLimitPolicy'
        ratelimit-remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        x-hey-monthly-remaining:
          $ref: '#/components/headers/MonthlyRemaining'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        x-hey-api-version:
          $ref: '#/components/headers/ApiVersion'
        ratelimit-limit:
          $ref: '#/components/headers/RateLimitLimit'
        ratelimit-policy:
          $ref: '#/components/headers/RateLimitPolicy'
        ratelimit-remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        x-hey-monthly-remaining:
          $ref: '#/components/headers/MonthlyRemaining'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The database was busy for a moment (`service_unavailable`); ask again after `retry-after` seconds.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        x-hey-api-version:
          $ref: '#/components/headers/ApiVersion'
        ratelimit-limit:
          $ref: '#/components/headers/RateLimitLimit'
        ratelimit-policy:
          $ref: '#/components/headers/RateLimitPolicy'
        ratelimit-remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        x-hey-monthly-remaining:
          $ref: '#/components/headers/MonthlyRemaining'
        retry-after:
          description: Seconds to wait before asking again.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The API key is not valid (`unauthorized`), or a keyed-only form was called without one (`key_required`). Every read also answers without a key.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        x-hey-api-version:
          $ref: '#/components/headers/ApiVersion'
        ratelimit-limit:
          $ref: '#/components/headers/RateLimitLimit'
        ratelimit-policy:
          $ref: '#/components/headers/RateLimitPolicy'
        ratelimit-remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        x-hey-monthly-remaining:
          $ref: '#/components/headers/MonthlyRemaining'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key or its account is held, or a partner key is not granted this route group (`forbidden`); `reason` says which.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        x-hey-api-version:
          $ref: '#/components/headers/ApiVersion'
        ratelimit-limit:
          $ref: '#/components/headers/RateLimitLimit'
        ratelimit-policy:
          $ref: '#/components/headers/RateLimitPolicy'
        ratelimit-remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        x-hey-monthly-remaining:
          $ref: '#/components/headers/MonthlyRemaining'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests; wait `retry-after` seconds. A spent monthly allowance is `quota`, retryable when the month resets.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        x-hey-api-version:
          $ref: '#/components/headers/ApiVersion'
        ratelimit-limit:
          $ref: '#/components/headers/RateLimitLimit'
        ratelimit-policy:
          $ref: '#/components/headers/RateLimitPolicy'
        ratelimit-remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        x-hey-monthly-remaining:
          $ref: '#/components/headers/MonthlyRemaining'
        retry-after:
          description: Seconds to wait before the next request.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: HEY failed; retryable.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        x-hey-api-version:
          $ref: '#/components/headers/ApiVersion'
        ratelimit-limit:
          $ref: '#/components/headers/RateLimitLimit'
        ratelimit-policy:
          $ref: '#/components/headers/RateLimitPolicy'
        ratelimit-remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        x-hey-monthly-remaining:
          $ref: '#/components/headers/MonthlyRemaining'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.
externalDocs:
  description: 'The full public API reference. Changes, dated: https://heyresearch.xyz/developers/changelog'
  url: https://heyresearch.xyz/docs/public-api