HEY Research Lab Market API

openapi: 3.2.0
info:
  title: HEY Research Lab public Market 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: Market
  description: '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).'
paths:
  /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. `current.valuationWithheld` says why `current` carries no valuation when the reading''s valuation is not plausible from the readings HEY has (`valuation_over_liquidity`, `unlisted_over_ceiling`, `chain_evidence_contradicts`, `sources_disagree`, `quote_side_thin`). 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). `archive` (additive, 2026-10-02) holds the days in the same window HEY never priced, from the provider''s daily archive (basis `provider_archive`, with its source, pool and read time): open, high, low, close and the day''s own volume, never liquidity or valuation, never merged into `days`.'
      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][a-z0-9-]{0,79}$
          maxLength: 80
      - name: days
        in: query
        description: 1–400; default 30.
        schema:
          type: integer
          minimum: 1
          maximum: 400
      responses:
        '200':
          description: Daily market index.
          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/projects/{slug}/market-moves:
    get:
      operationId: getProjectMarketMoves
      summary: Large day-on-day valuation moves, with what shipped before each
      description: 'Each day-on-day change in the market-cap close in HEY''s daily index of at least `min` percent either way, with the project''s meaningful events in the 7 days up to it: a sequence, never a cause. The newest 20 moves, newest first. `valuationKind: "fdv"` marks closes that are price × total supply, a fully diluted valuation and not a market cap. When the market is not live its valuations are withheld: `daysRead` is 0 and `withheldDays` with `withheldReason` says so — withheld, not a quiet market. 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:
      - 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][a-z0-9-]{0,79}$
          maxLength: 80
      - name: days
        in: query
        description: Days of the daily index to read, 7–365; default 90. A value outside the range is clamped to it.
        schema:
          type: integer
          minimum: 7
          maximum: 365
      - name: min
        in: query
        description: The smallest day-on-day change counted, in percent either way, 5–500; default 25. A value outside the range is clamped to it.
        schema:
          type: integer
          minimum: 5
          maximum: 500
      responses:
        '200':
          description: The moves, the threshold applied and the days read.
          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/projects/{slug}/market-integrity:
    get:
      operationId: getProjectMarketIntegrity
      summary: What happened to the tracked token market, beside the building
      description: 'Builder activity and the tracked token market as two objects side by side, the conflicts where they disagree, and the Market Integrity events the current evaluation stands behind — each with its typed id (`integrity:`), words, sources, facts, confidence and `detectedAt`; a state HEY observed has `at: null` and `precision: "observed"`. Nothing here is a score or a verdict, and market integrity describes the token market, not whether development has stopped. `marketIntegrity` is null when HEY holds no evaluation for the project. Answers 404 for every project unless the deployment publishes Market Integrity (`HEY_MARKET_INTEGRITY=public`); the exit-pattern classification appears only when `HEY_MARKET_INTEGRITY_EXIT_LABELS` is on as well. 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:
      - 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][a-z0-9-]{0,79}$
          maxLength: 80
      responses:
        '200':
          description: Builder activity, market integrity, conflicts and events.
          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:
    get:
      operationId: getChainDays
      summary: Robinhood Chain day by day
      description: 'Aggregates only, oldest day first: decoded DEX trades, DEX volume against the known quote assets (unpriced pairs are left out, not guessed), tokens and pools that traded, transactions, transfers, and what HEY recorded — launches, projects published, ships, builders shipping, builders verified. A figure absent from a day was not read that day: unknown, never zero. The day in progress is partial; `lastFullDay` names the newest complete one. Each day states its `basis` (HEY''s half is knowledge time; the chain half observed or reconstructed_from_chain), and `launchesFirstRead` / `launchesBackfill` mark the launches that came from a source''s first read — a backfill, not that day''s launches (`launchesNote`). `ships` counts each corroborated ship record of a Robinhood Chain builder once, so it can read above the weekly ship rule''s ''counted ships'' on the homepage; `shipsNote` names the units side by side. 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:
      - Market
      parameters:
      - name: days
        in: query
        description: Days to return, 1–400; default 14. A value outside the range is clamped to it.
        schema:
          type: integer
          minimum: 1
          maximum: 400
      responses:
        '200':
          description: The chain's days.
          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/unlocks:
    get:
      operationId: listUpcomingUnlocks
      summary: Scheduled unlocks at HoodLock
      description: 'HoodLock''s own schedule: locks still holding that reach their unlock time within `days`, each with the project, the asset kind (TOKEN or LP), the locked amount and share of supply where HEY knows them (absent when unknown, never zero), the proof and its typed id (`lock:4663:`) at precision SCHEDULED. `scope: "hoodlock"`: a token with no row here has no HoodLock lock, not "no lock". At most 100 rows; `total` counts every row the listing holds and `truncated` says whether `items` shows fewer. An unlock is a scheduled supply fact, not a market forecast.'
      tags:
      - Market
      parameters:
      - name: days
        in: query
        description: The window in days, 1–365; default 30. A value outside the range is clamped to it.
        schema:
          type: integer
          minimum: 1
          maximum: 365
      responses:
        '200':
          description: Unlocks with `total`, `truncated` and `scope`.
          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