HEY Research Lab Hey API

openapi: 3.2.0
info:
  title: Research Lab public Hey 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: hey
  description: $HEY, researched like any other token.
paths:
  /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. Additively: `liquidityLock` (the launch position the Pons V2 locker holds; `locks.tokenLock.pairLocked` reads HoodLock only), `treasury.reconciliation` (the daily balance reads against the ledger, computed) and `receipts` (one aggregate per use over HEY''s own tables). Not investment advice; unknown stays null with a reason.'
      tags:
      - hey
      parameters: []
      responses:
        '200':
          description: The profile (schema `hey.token-profile/v1`).
          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