KOL Identity Workflows

Conyr resolves X and Telegram identities in both directions: a public handle can discover its active wallet associations, and a wallet (Solana or EVM) can return its preferred identity plus every active alias. Identity is a discovery and attribution layer; combine it with on-chain evidence before making a decision about the wallet.

Both routes read Conyr’s identity registry: pump.fun’s public profiles, SNS, kolscan, Axiom’s wallet maps, FOMO’s public profiles, the original KOL registry (rows from Fomo’s trader leaderboards, kolscan, KOLlector (dethective.com) and manual curation) and Conyr’s operator file. Each alias carries its source, basis, tier and reason, so agents must preserve and interpret them per alias.

Both direct identity routes require a Layer 2 API key.

Choose the endpoint from the evidence you have

There is no dedicated KOL resolver in the current MCP catalog. Resolve handles and inspect identity through REST, then pass each exact wallet address to MCP or the focused REST intelligence endpoints. Do not send a social handle to a wallet-analysis tool that expects a Solana address.

Wallet to current identity

GET /v1/wallet/{address}/identity reads active registry records independently of the ClickHouse behavioral-label snapshot. An abridged response (two of four aliases, one of three tags, one of seven receipts):

{
  "wallet_address": "CyaE1VxvBrahnPWkqm5VsdCvyS2QmNht2UFrKJHga54o",
  "chain": "solana",
  "primary": {
    "platform": "x",
    "username": "Cented7",
    "profile_url": "https://x.com/Cented7",
    "source": "pumpfun",
    "verification": "source_asserted",
    "created_at": "2026-09-29T00:00:00Z",
    "updated_at": "2026-09-29T00:00:00Z",
    "tier": "verified",
    "basis": "app_binding",
    "reason": "x linked on pump.fun",
    "claim_id": 26
  },
  "aliases": [
    {
      "platform": "x",
      "username": "Cented7",
      "profile_url": "https://x.com/Cented7",
      "source": "pumpfun",
      "verification": "source_asserted",
      "created_at": "2026-09-29T00:00:00Z",
      "updated_at": "2026-09-29T00:00:00Z",
      "tier": "verified",
      "basis": "app_binding",
      "reason": "x linked on pump.fun",
      "claim_id": 26
    },
    {
      "platform": "x",
      "username": "Cented7",
      "profile_url": "https://x.com/Cented7",
      "source": "kolscan",
      "verification": "source_asserted",
      "created_at": "2026-09-29T00:00:00Z",
      "updated_at": "2026-09-29T00:00:00Z",
      "tier": "predicted",
      "basis": "tracker",
      "reason": "x listed by kolscan",
      "claim_id": 39
    }
  ],
  "person": {
    "id": "person:x:cented7",
    "name": "Cented7",
    "handles": [
      {
        "platform": "x",
        "username": "Cented7",
        "profile_url": "https://x.com/Cented7"
      }
    ],
    "formerly": []
  },
  "tier": "verified",
  "reason": "verified: x linked on pump.fun, plain wallet at slot 7; x listed by kolscan and x listed by Axiom and x alias (kolscan) agree",
  "conflict": false,
  "tags": [
    {
      "platform": "pumpfun",
      "username": "cented69420",
      "source": "pumpfun",
      "basis": "self_attested",
      "tier": "predicted",
      "reason": "pump.fun name",
      "flags": [
        "default_name"
      ],
      "hidden": true,
      "claim_id": 25
    }
  ],
  "receipts": {
    "26": {
      "source": "pumpfun",
      "first_check": {
        "state": "plain_wallet",
        "slot": 7,
        "checked_at": "2026-09-29T00:00:00Z"
      },
      "run_id": "20260927T182156Z-soak",
      "lane": "batch",
      "linked": null,
      "lines": [
        {
          "url": "https://frontend-api-v3.pump.fun/users/batch",
          "fetched_at": "2026-09-27T21:16:31.049Z",
          "copy_sha256": "a257a64a55b7fa6f42e0e8c4c92b3b6bd99446e8b4a23f2e35c5146d8001bd43"
        }
      ]
    }
  },
  "denials": []
}

username never includes @. Prefer the returned profile_url to constructing a URL. created_at and updated_at describe the registry record, not when wallet control was proven on-chain or on the social platform.

The primary selection is deterministic: primary is the alias the registry chose for the wallet’s label.

1. Verified before predicted.
2. Then the operator, the SNS registry, pump.fun’s X link, FOMO’s X link, the original KOL registry’s FOMO rows, trackers (kolscan before Axiom), then the original KOL registry’s other rows (kolscan, KOLlector, manual).

primary is null when the label names no person, even when tags are present. aliases lists X before Telegram, each in that precedence order. Each alias is one source’s association, so the same handle can appear once per source; for display, dedupe by platform and username. primary is selected from aliases; it is not an additional association. When the exact alias matters, inspect the full list instead of assuming the primary is the alias that led you to the wallet.

A syntactically accepted wallet identifier with no active registry record returns HTTP 200:

{
  "wallet_address": "WALLET",
  "chain": "solana",
  "primary": null,
  "aliases": [],
  "person": null,
  "tier": null,
  "reason": null,
  "conflict": false,
  "tags": [],
  "receipts": {},
  "denials": []
}

This is a stable no-match result, not a 404. It means only “no active association in the current registry.” It does not establish that the wallet is anonymous, is not a KOL wallet, or is safe. An identifier that is neither a base58-form Solana key nor an EVM address (0x and 40 hex digits) returns 400; a registry failure returns an HTTP error and must not be collapsed into this empty state.

Handle to wallets

GET /v1/kol-wallets/{username} performs an exact, case-insensitive active-alias lookup. The server trims whitespace, removes leading @ characters, and lowercases the returned username. After normalization, a handle must contain 1–32 ASCII letters, digits, or underscores.

curl -sS \
  -H "Authorization: Bearer $CONYR_API_KEY" \
  "https://api.conyr.ai/v1/kol-wallets/example_handle?platform=x"

Pass platform=x or platform=telegram whenever the source platform is known. The filter is case-insensitive. Without it, Conyr unions matches from both platforms and de-duplicates the same wallet address; no response field says which platform produced each match (only each match’s reason, in words). chain selects Solana wallets (the default), EVM wallets (evm) or both (all).

A response, here for orangie?chain=evm:

{
  "username": "orangie",
  "wallets": [
    "0x0fd94b02867a7311c87c5b995793e9a3dca5c565",
    "0xb3fd97526020fbf5560857b7dca5dd2f1652422f"
  ],
  "person": {
    "id": "person:x:orangie",
    "name": "orangie"
  },
  "matches": [
    {
      "address": "0x0fd94b02867a7311c87c5b995793e9a3dca5c565",
      "chain": "evm",
      "tier": "predicted",
      "basis": "tracker",
      "source": "axiom",
      "reason": "x listed by Axiom",
      "conflict": false
    },
    {
      "address": "0xb3fd97526020fbf5560857b7dca5dd2f1652422f",
      "chain": "evm",
      "tier": "predicted",
      "basis": "tracker",
      "source": "axiom",
      "reason": "x listed by Axiom",
      "conflict": false
    }
  ]
}

Wallets are sorted by address, not confidence, recency, performance, or “main wallet” status. Never treat the first wallet as canonical. person is the entity that currently holds the handle’s profile, or null; matches has one entry per wallet, in the same order, with the tier, basis, source and reason of the first association on that wallet that names the handle. A handle the operator denied on a wallet does not match it. An unknown handle returns HTTP 200 with the normalized username, "wallets": [], "person": null and "matches": []. A known handle with no wallet on the asked chain or platform keeps its person, with empty wallets and matches; try chain=all. Invalid handle grammar, an unsupported platform or an unsupported chain returns 400.

Workflow: social mention to evidence-backed wallets

1. Preserve the platform from the mention and call the handle endpoint with that filter.
2. If wallets is empty, report “no active registry match” and stop; do not retry without the platform and silently broaden the identity claim.
3. Fetch /identity for every returned address when provenance, timestamps, or a profile URL matter.
4. Confirm the normalized (platform, username) is still present in aliases. primary may be a different alias the registry ranks higher, and the association could change between the two requests.
5. Join /quality, /performance, /provenance, wallet_overview, or other evidence by the exact wallet address.
6. Keep results wallet-scoped. Do not combine PnL across every returned wallet unless the product explicitly declares an actor-level aggregation and its time window.

For consequential or publishable output, re-read /identity near decision time. If the expected alias is no longer in aliases, treat the earlier lookup as stale rather than carrying the attribution forward.

Workflow: wallet to a safe display identity

1. Call /identity, even when /labels returned null.
2. If primary is present, display @username, platform, and the returned profile_url while retaining the wallet address.
3. If primary is null, fall back to a shortened wallet address; do not invent a handle from unrelated labels or cached search text.
4. Preserve aliases with their source, tier, basis and reason, the timestamps, and the receipts in exports or audit records.

Personal wallet names and user-authored notes should remain separate from public KOL identity. One should not overwrite the other.

Compact attribution is a projection

kol_username, kol_platform and kol_tier on wallet labels and leaderboard entries are convenient display fields, not the full registry contract. They name every person the registry names for a wallet, not only people on KOL rosters; kol_tier says whether that name is verified or predicted.

Treat a compact identity as opportunistic attribution. When it matters whether an alias is active now, follow it with /identity. Conversely, an absent compact identity does not override a non-empty direct identity response.

Interpret source_asserted safely

verification is always source_asserted; it is kept for existing clients and says nothing about how strong an association is. Read tier and basis instead: verified is owner-proven; predicted means a tracker, a roster or a single source lists it.

Safe uses include rendering a public attribution with provenance, discovering candidate wallets from a known social handle, and selecting wallets for further on-chain analysis.

A predicted association does not establish ownership or control of the wallet. Neither tier establishes:

• continued control by the current social-account owner;
• endorsement by Conyr or the named person;
• common control of every wallet returned for a handle;
• profitability, skill, trustworthiness, or safety;
• intent behind any trade.

For higher-stakes conclusions, corroborate identity with the wallet’s transaction signatures, position-correct quality, funding provenance, entity membership, follow evidence, and bundle or campaign evidence. Preserve disagreements instead of upgrading an assertion into a verified fact.

See Public KOL Identity for client examples and field-level REST reference, and Coverage for the broader absence and evidence contract.