KOL Identity Workflows

Conyr resolves source-asserted X and Telegram identities in both directions: a public handle can discover its active wallet associations, and a wallet 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.

The registry includes X handle-to-wallet mappings surfaced by Fomo’s public trader leaderboards. Those records carry source: "fomo"; other configured provenance labels can also appear, so agents must preserve and interpret source 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.

{
  "wallet_address": "WALLET",
  "primary": {
    "platform": "x",
    "username": "example_handle",
    "profile_url": "https://x.com/example_handle",
    "source": "manual",
    "verification": "source_asserted",
    "created_at": "2026-08-20T18:30:00Z",
    "updated_at": "2026-08-25T09:15:00Z"
  },
  "aliases": [
    {
      "platform": "x",
      "username": "example_handle",
      "profile_url": "https://x.com/example_handle",
      "source": "manual",
      "verification": "source_asserted",
      "created_at": "2026-08-20T18:30:00Z",
      "updated_at": "2026-08-25T09:15:00Z"
    }
  ]
}

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:

1. X before Telegram.
2. Most recently updated active record within a platform.
3. Most recently created record, then lexical username and source, as tie-breakers.

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",
  "primary": null,
  "aliases": []
}

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 outside the route’s accepted base58-form syntax 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; the compact response does not say which platform produced each match.

{
  "username": "example_handle",
  "wallets": ["WALLET_A", "WALLET_B"]
}

Wallets are sorted by address, not confidence, recency, performance, or “main wallet” status. Never treat the first wallet as canonical. A valid no-match returns HTTP 200 with the normalized username and "wallets": []. Invalid handle grammar or an unsupported platform 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, newer X alias, 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, source, verification, and timestamps 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 and kol_platform on wallet labels and leaderboard entries are convenient display fields, not the full registry contract.

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

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.

source_asserted does not establish:

• cryptographic ownership or control of the wallet;
• 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.