TokenLookup

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/heyresearch-xyz/json-schema/heyresearch-xyz-token-lookup-schema.json",
  "title": "TokenLookup",
  "description": "A token contract resolved to a published project. See https://heyresearch.xyz/docs/public-api for every field. Absent means unknown, never zero.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/heyresearch-xyz-openapi.json#/components/schemas/TokenLookup",
  "type": "object",
  "additionalProperties": true,
  "required": [
    "chainId",
    "contractAddress",
    "status",
    "scanUrl",
    "disclaimer"
  ],
  "properties": {
    "chainId": {
      "type": "integer"
    },
    "contractAddress": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "published",
        "unknown"
      ],
      "description": "`unknown` is an answer, not an error: HEY has not published a project for this contract."
    },
    "project": {
      "type": "object",
      "additionalProperties": true,
      "description": "The published project behind the token; absent when `status` is `unknown`.",
      "required": [
        "slug",
        "name",
        "url",
        "activityStatus",
        "activityLabel",
        "activityHelp",
        "shipsLast30Days",
        "activityMeasured",
        "tokenVerification",
        "activityAppliesToToken",
        "badgeUrl"
      ],
      "properties": {
        "slug": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "symbol": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "activityStatus": {
          "type": "string"
        },
        "activityLabel": {
          "type": "string",
          "description": "The project page's own words for the status. Print this."
        },
        "activityHelp": {
          "type": "string"
        },
        "researchLevel": {
          "type": "string"
        },
        "shipsLast30Days": {
          "type": "integer",
          "description": "Ship records in 30 days — a legacy count, 0 where HEY measured nothing. Read it only beside `activityMeasured: true`."
        },
        "activityMeasured": {
          "type": "boolean"
        },
        "meaningfulShipsLast30Days": {
          "type": "integer",
          "description": "Meaningful ships in 30 days by the rule behind the status; absent, never 0, when not measured and none."
        },
        "asOf": {
          "type": "string",
          "format": "date-time"
        },
        "lastShipAt": {
          "type": "string",
          "format": "date-time"
        },
        "lastShip": {
          "type": "object",
          "additionalProperties": true,
          "description": "The newest ship: `title` (a running code week names absolute days), `publishedAt`, `sourceUrl`."
        },
        "deployedAt": {
          "type": "string",
          "format": "date-time"
        },
        "tokenVerification": {
          "type": "object",
          "additionalProperties": true,
          "description": "`status` (VERIFIED, UNVERIFIED, MISMATCH) and its `reason`."
        },
        "activityAppliesToToken": {
          "type": "boolean"
        },
        "badgeUrl": {
          "type": "string"
        }
      }
    },
    "scanUrl": {
      "type": "string"
    },
    "issuer": {
      "type": "object",
      "additionalProperties": true,
      "description": "An issuer's own token (a Robinhood stock token), never a project's; with `status: unknown` only."
    },
    "publishedNamesakes": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additive (2026-10-18), with `status: unknown` only: published projects carrying this token’s name or ticker on another contract — `total`, `items` (slug, name, symbol, contractAddress, shares, sharesAddressEnding, url) and `line`, the one sentence HEY prints. Facts, never which token is real."
    },
    "disclaimer": {
      "type": "string"
    }
  }
}