Layer 2 — Wallet Intelligence

FIFO cost-basis PnL, 30-dimensional behavior profiling, wallet similarity, focused classification, position-correct skill, and funding provenance.

Includes all Layer 1 endpoints.

Rate limits: 300 REST req/min, 20 WebSocket connections, 500 tracked wallets, 1,000 similarity queries/day, full PnL history.

WebSocket Streams

`events.wallet.{addr}.pnl`

Channel: wallet:{addr}:pnl

Real-time realized PnL events, published on every sell.

Rich event payload: entry/exit timestamps, signatures, slots, prices, amounts
Fee allocation: entry fees (pro-rata) + exit fees
PnL in both USD and SOL, percentage gain, position type (Full/DCA)
Exit classification: Full/Partial, exit number, remaining cost basis
Bot detection flags, DEX info

`events.wallet.{addr}.position`

Channel: wallet:{addr}:positions

Live position deltas — every open/close/partial-exit as it happens.

FIFO cost-basis accounting: buys create entries, sells pop from front of queue
Handles partial exits with pro-rata fee allocation
Transfer-out detection: inventory consumed without PnL attribution

`events.wallet.{addr}.labels`

Channel: wallet:{addr}:labels

Enriched wallet-label payload published when the analytics emitter processes wallet activity and detects a label-state change. The live event may contain more analytics fields than the focused REST label object.

Deduplicated — only publishes on actual state change
Rate limited to prevent flooding
Fields include: kol_username, kol_platform, trader type, performance level, badges, and activity metrics
An alias-table update alone does not guarantee an event for a dormant wallet. Use GET /v1/wallet/{addr}/identity when identity freshness is required.
Empty-string kol_username / kol_platform values explicitly clear cached identity state; do not ignore them as absent patch fields. REST compact projections use JSON null for absence.

REST Endpoints

For endpoint selection, exact empty-result semantics, platform-safe links, and handle-to-wallet workflows, see Public KOL Identity.

GET /v1/wallet/{addr}/identity

Returns a wallet’s preferred public KOL identity plus every active alias. This endpoint is independent of trading-label coverage, so an alias-only wallet can resolve before it has enough activity for classification.

Parameters

Parameter	In	Type	Required	Description
`addr`	path	string	yes	32–44 characters from the Solana base58 alphabet; route-level syntax check

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.conyr.ai/v1/wallet/$WALLET_ADDRESS/identity"

Response

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

primary is null and aliases is empty when no active association exists. X is preferred when a wallet has both X and Telegram aliases. source_asserted describes the provenance of the association; it is not cryptographic proof that the account owner controls the wallet.

GET /v1/kol-wallets/{username}

Resolves a normalized public username to every actively associated Solana wallet. The leading @ is optional and matching is case-insensitive.

Parameters

Parameter	In	Type	Required	Description
`username`	path	string	yes	X or Telegram username, with or without `@`
`platform`	query	string	no	Restrict results to `x` or `telegram`

Example

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

Response

{
  "username": "frankdegods",
  "wallets": ["A5SEXYJY4jTEi6sjMLfZs5KAP8SVFvLDPDV67GgSSZSk"]
}

An unknown username returns 200 with an empty wallets array. The response username is normalized to lowercase, and wallets are sorted by address rather than relevance or performance. Use the wallet identity endpoint to retrieve platform-correct profile URLs and alias provenance for a returned address.

GET /v1/wallet/{addr}/profile

Multi-dimensional behavior vector breakdown with raw and normalized values.

Feature Groups

Group	Covers
Hold timing	Exit timing patterns and hold duration
Exit discipline	Win rate, exit behavior, DCA patterns
Performance	Return metrics, risk-adjusted performance
Velocity & sizing	Trading frequency, position sizing, diversification
Infrastructure	DEX usage, automation level, tool patterns
Provenance	Funding origin, account history

Gating

A wallet must meet minimum activity thresholds to have a profile (minimum closed positions, activity span, and trade count).

Parameters

Parameter	In	Type	Required	Description
`addr`	path	string	yes	Solana wallet address

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.conyr.ai/v1/wallet/7xKXtg.../profile"

Response

{
  "wallet": "7xKXtg...",
  "has_vector": true,
  "trader_type": "DAY_TRADER",
  "performance_level": "EARNER",
  "features": {
    "hold_first_exit_p50": { "raw": 1200.0, "normalized": 0.45 },
    "win_rate": { "raw": 0.63, "normalized": 0.72 },
    "profit_factor": { "raw": 2.1, "normalized": 0.68 },
    "trade_frequency": { "raw": 12.5, "normalized": 0.55 },
    "bot_share": { "raw": 0.05, "normalized": 0.05 },
    "is_cex_funded": { "raw": 1.0, "normalized": 1.0 }
  },
  "trade_badges": ["CONSISTENT_WINNER", "RUNNER_KEEPER"],
  "identity_badges": ["ROOT_CEX"]
}

Features are normalized to a 0-1 scale for comparability. Cache TTL: 60 seconds.

GET /v1/wallet/{addr}/similar

k-NN wallet similarity search powered by Qdrant.

Parameters

Parameter	In	Type	Required	Default	Description
`addr`	path	string	yes	—	Solana wallet address
`limit`	query	integer	no	`20`	Max results (max 100)
`min_trades`	query	integer	no	—	Minimum trade count filter
`performance_level`	query	string	no	—	Filter: `EARNER`, `BREAK_EVEN`, `UNPROFITABLE`, `UNRATED`, `DORMANT`

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.conyr.ai/v1/wallet/7xKXtg.../similar?limit=10&performance_level=EARNER"

Response

{
  "query_wallet": "7xKXtg...",
  "results": [
    {
      "wallet": "4mNqR...",
      "similarity": 0.94,
      "trader_type": "DAY_TRADER",
      "performance_level": "EARNER",
      "total_pnl_usd": 45000.0,
      "win_rate": 0.65,
      "shared_traits": ["high win rate", "runner keeper", "quick exit timing"],
      "key_differences": ["larger position sizing", "more DEX diversity"]
    }
  ],
  "count": 10
}

Returns similar wallets ranked by behavioral similarity. Includes explainability: top shared traits and key differences.

GET /v1/wallet/{addr}/provenance

Funding chain resolution — where did this wallet’s SOL come from?

Parameters

Parameter	In	Type	Required	Description
`addr`	path	string	yes	Solana wallet address

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.conyr.ai/v1/wallet/7xKXtg.../provenance"

Response

{
  "wallet": "7xKXtg...",
  "root_entity": "Binance",
  "root_source": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
  "hops": 3,
  "direct_funder": "9aBcD...",
  "last_funded_ts": "2026-03-01T08:30:00Z"
}

Traces funding chain back to originating CEX or known entity
Curated root wallet database covering major exchanges
When no known root is found, the response is { "wallet": ..., "root_entity": null, "hops": null, "funding_path": null } — the root_source, direct_funder, and last_funded_ts keys appear only when a root is resolved

Cache TTL: 300 seconds.

GET /v1/wallet/{addr}/trades

Historical realized-PnL trade records for a wallet — one row per closed or partial exit.

There is no separate /pnl endpoint. A wallet’s realized-PnL trade history is served here at /trades; aggregate stats live on /performance.

Parameters

Parameter	In	Type	Required	Default	Constraints
`addr`	path	string	yes	—	—
`limit`	query	integer	no	`50`	—
`offset`	query	integer	no	`0`	—
`token`	query	string	no	—	Filter by token mint

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.conyr.ai/v1/wallet/7xKXtg.../trades?limit=20&token=EPjFWd..."

Response

{
  "trades": [
    {
      "wallet_address": "7xKXtg...",
      "token_mint": "EPjFWd...",
      "entry_signature": "5vGk...",
      "exit_signature": "3mPq...",
      "entry_timestamp": "2026-03-05 14:30:00",
      "exit_timestamp": "2026-03-05 15:45:00",
      "hold_time_seconds": 4500,
      "entry_price_usd": 0.00234,
      "exit_price_usd": 0.00312,
      "realized_pnl_usd": 78.50,
      "realized_pnl_sol": 0.52,
      "percentage_gain": 33.33,
      "position_type": "FULL_POSITION",
      "exit_type": "FULL",
      "exit_dex": "raydium",
      "entry_dex": "raydium"
    }
  ],
  "limit": 20,
  "offset": 0
}

Full FIFO cost-basis accounting. Includes entry/exit signatures for on-chain verification.

GET /v1/wallet/{addr}/positions

Current open positions with FIFO cost basis. Mark-to-market unrealized PnL is not part of this response — derive it client-side by combining remaining_amount * entry_price_usd (cost basis) against the latest tick from GET /v1/token/{mint}/ohlcv?timeframe=1s&limit=1.

Parameters

Parameter	In	Type	Required	Default	Description
`addr`	path	string	yes	—	Solana wallet address
`status`	query	string	no	`all`	`open`, `closed`, or `all`

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.conyr.ai/v1/wallet/7xKXtg.../positions?status=open"

Response

{
  "positions": [
    {
      "wallet_address": "7xKXtg...",
      "token_mint": "EPjFWd...",
      "entry_signature": "5vGk...",
      "entry_timestamp": 1709654400,
      "entry_price_usd": 0.00234,
      "original_amount": 1000000.0,
      "remaining_amount": 500000.0,
      "price_per_token": 0.00000234,
      "status": "PARTIAL",
      "exit_count": 2,
      "entry_dex": "pumpfun"
    }
  ]
}

FIFO-ordered position entries with entry price, remaining amount, and per-token cost basis. Aggregated by token mint. (No mark-to-market / current value is included — see the note above.)

GET /v1/wallet/{addr}/labels

Focused classification object. For broader agent reasoning, use the MCP query_wallet_xray or wallet_overview tools, which compose labels with performance, provenance, and profile data.

Parameters

Parameter	In	Type	Required	Description
`addr`	path	string	yes	Solana wallet address

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.conyr.ai/v1/wallet/7xKXtg.../labels"

Response

{
  "wallet": "7xKXtg...",
  "kol_username": "frankdegods",
  "kol_platform": "x",
  "trader_type": "DAY_TRADER",
  "performance_level": "EARNER",
  "size_class": "SHARK",
  "exit_style": "DCA_OUT",
  "automation_label": "ORGANIC",
  "primary_terminal": "photon",
  "primary_tool": "photon",
  "primary_tool_pct": 0.85,
  "is_fresh_6h": 0,
  "is_fresh_24h": 0,
  "funded_by_farm": 0,
  "trade_badges": ["CONSISTENT_WINNER", "RUNNER_KEEPER", "STOP_LOSS_USER"],
  "identity_badges": ["ROOT_CEX", "TOOL_PHOTON"],
  "special_labels": [],
  "description": "Earner day trader, DCA exits, funded by a known CEX root.",
  "label_hash": "a1b2c3d4e5f6"
}

Freshness: the compact KOL pair first passes through a ClickHouse dictionary with a 30–60 second refresh lifetime; the complete labels response is then cached for 60 seconds.

kol_username and kol_platform are nullable. This endpoint is backed by the wallet-label snapshot and may return null for an alias-only wallet with no classification row; use /v1/wallet/{addr}/identity for a lookup independent of trading activity. Build x.com/{kol_username} links only when kol_platform is x, and t.me/{kol_username} links when it is telegram.

GET /v1/wallet/{addr}/quality

The position-correct skill signal. Conyr keeps the fully closed FIFO entry-lot win rate separate from the per-exit-row rate because a DCA-out can emit several profitable rows from one lot. This endpoint exposes both units and their non-negative gap. Read the 194,610-wallet temporal study for the current method, results, sensitivity analysis, and closed-only limitations.

Parameters

Parameter	In	Type	Required	Description
`addr`	path	string	yes	Solana wallet address

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.conyr.ai/v1/wallet/7xKXtg.../quality"

Response

Returns 200 with the object below, or 200 with literal null when the wallet has no snapshot row yet.

{
  "wallet": "7xKXtg...",
  "rated": true,
  "skill_score": 72.4,
  "performance_level": "EARNER",
  "trader_type": "SWING_TRADER",
  "exit_style": "RUNNER_KEEPER",
  "size_class": "SHARK",
  "closed_positions": 184,
  "position_win_rate_pct": 41.2,
  "raw_exit_win_rate_pct": 63.7,
  "win_rate_inflation_pts": 22.5,
  "disposition_index": 0.84,
  "conviction_sizing": 1.32,
  "profit_factor": 2.1,
  "sharpe_ratio": 1.8,
  "runner_score": 0.61,
  "avg_loss_roi_pct": -18.3,
  "loss_consistency_stddev": 12.4,
  "roi_p10_pct": -42.0,
  "roi_p50_pct": 6.1,
  "roi_p90_pct": 88.0,
  "big_wins": 14,
  "big_losses": 6,
  "realized_pnl_usd": 18243.55,
  "trade_badges": ["RUNNER_KEEPER", "CONSISTENT_WINNER"]
}

rated is true when closed_positions >= 10.
skill_score (0–100) = 0.40·position_win_rate + 0.30·profit_factor + 0.15·disposition + 0.15·runner, each normalized and clamped — heuristic and explainable, not a calibrated probability.
position_win_rate_pct is the fully closed FIFO entry-lot rate; raw_exit_win_rate_pct is the per-exit-row rate; win_rate_inflation_pts = raw_exit − position, floored at 0.

Cache TTL: 60 seconds.

GET /v1/token/{mint}/buyer-quality

Buyer-quality is a Free-tier endpoint, available on every tier (higher tiers include all lower endpoints). The response is identical at all tiers — there is no Layer-2-specific enrichment. Supports ?window_hours= (default 1).

See Free Tier → Buyer Quality for the full response schema.

Public KOL Identity Security Intelligence