PartnerBuilderCard

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/heyresearch-xyz/json-schema/heyresearch-xyz-partner-builder-card-schema.json",
  "title": "PartnerBuilderCard",
  "description": "The canonical Partner Card. Additive only: a key here never changes meaning.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/heyresearch-xyz-openapi.json#/components/schemas/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",
    "uniswap_v4_hooks",
    "uniswap_v4_hooks_state",
    "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 — the project page’s chip, the scan card’s `status_label` and the token lookup’s `activityLabel` print the same (since 2026-10-18 an UNKNOWN says why where the page does; since 2026-10-28 under one head, “Not measured — no builder source linked”). 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`, its `ship:` evidence id and `evidence_link` (since 2026-10-05: the reader’s receipt page with your attribution labels — link this as “Evidence”). 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 latest builder-side event in HEY’s change ledger, by the Research Summary’s rule (the project’s own change before HEY’s reclassifications; 2026-10-20): `id`, `type`, `summary`, `occurred_at`, `precision`, `detected_at`, `evidence_id`, `url`, and `explanation` (2026-10-20, additive: `headline`, `stage`, `reported_by`, `corroboration`, `release_deployment` — established only by an exact address in the release text, never by timing — `activity`, `call_success` always `not_measured`, `time_basis`, `standing`, `unknowns`, `explain_url`; null when HEY could not read it). Only the builder story: market, usage, lock, 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. Its `summary` names a week still running as “week starting <Monday> (to <today>)”, never a range ending in days that have not happened (2026-10-16). Its `commits` and `active_days` are that week’s own counts, as the week’s receipt counts them (`codeWeek.commits`), never the read window behind it (2026-10-18); `commits_partial` says they are floors. Unknown: null when HEY holds none; `commits` and `active_days` null when HEY holds no count for the week."
    },
    "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`; since 2026-10-19 also `reason`, the classifier’s reason or null, and `label`, the status in HEY’s canonical words — “Launch pool only” for an active launch pool, “Readings not confirmed” for a depth reading over a week old; print `label`): 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)."
    },
    "uniswap_v4_hooks": {
      "type": [
        "object",
        "null"
      ],
      "description": "The project’s publicly listed Uniswap v4 hooks, under the rule HEY’s hook list applies: `listed` (every listed hook, factory instances included), `basis_counts` (`chain`, `project`, `linked`, `factory`, `review`: what each tie rests on), `items` (at most ten hooks with a row of their own, newest deployment first: `address`, `basis`, `basis_label`, `page_url`, the `v4hook:` `evidence_id`), `shown` of `total`, and `list_url`. Contracts and counts only: contract context, never a builder input or an order. Unknown: null; `uniswap_v4_hooks_state` says whether HEY lists none under the project or has decoded no hook on the chain."
    },
    "uniswap_v4_hooks_state": {
      "type": "string",
      "description": "`listed`, `none_listed` or `not_read`. `none_listed` is a reading of HEY’s listing: a hook whose creation HEY has not read yet is tied to no project so far. Unknown: `not_read`: HEY has decoded no Uniswap v4 hook on the chain — unknown, not none."
    },
    "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."
    }
  }
}