# Conyr — Full Agent Context Conyr is the Solana intelligence API built for autonomous agents. It exposes 46 MCP tools, 39 live `/v1` REST operations, and 13 WebSocket channel families over one raw-chain intelligence engine. Canonical machine contract: https://docs.conyr.ai/openapi.yaml Agent docs: https://docs.conyr.ai/agents MCP endpoint: https://mcp.conyr.ai/mcp REST base: https://api.conyr.ai WebSocket: wss://api.conyr.ai/ws ## Authentication Send this header to MCP, every `/v1/*` REST operation, and the WebSocket upgrade: ``` Authorization: Bearer YOUR_API_KEY ``` Only `GET /health`, `GET /ready`, and `GET /metrics` are unauthenticated. The Free tier cannot open a WebSocket connection. ## Interface selection - Broad natural-language token investigation: use `token_deep_dive` or `token_coordination_report` over MCP. - Broad wallet investigation: use `wallet_overview` or `wallet_network_report` over MCP. - Focused model tool call: use one `query_*` MCP tool. - Deterministic typed execution: generate a REST client from OpenAPI. - Continuous observation: establish state with MCP/REST, then subscribe over WebSocket. - Do not treat the WebSocket as a replayable or guaranteed-delivery log. ## MCP result contract The hosted MCP catalog has 42 focused tools plus four composite tools. Each object result includes `evidenceUrl`. The MCP response carries the full result as structured content, a one-line text summary, and an evidence resource link. Tier failure: ```json { "error": "tier_insufficient", "tool": "token_deep_dive", "requiredTier": "Layer 3", "yourTier": "Layer 2" } ``` Composite result: ```json { "partial": false, "sections": {}, "errors": {}, "evidenceUrl": "https://conyr.ai/terminal/..." } ``` If an independent source fails, its section is `null`, `partial` becomes true, and the source appears in `errors`. Other sections remain usable. ## Complete MCP catalog ### Free - `query_buyer_quality` - `query_token_bundle_summary` - `resolve_token_identifier` ### Layer 2 focused tools - `query_wallet_performance` - `query_wallet_quality` - `query_wallet_trades` - `query_wallet_positions` - `query_wallet_xray` - `query_wallet_xray_lite` - `query_wallet_provenance` - `query_similar_wallets` - `query_leaderboard` - `fetch_wallet_labels_batch` - `query_holder_breakdown` - `query_token_holder_pnl` ### Layer 2 composite - `wallet_overview`: X-ray, coordination block, funding provenance, 30-day performance, similar wallets. ### Layer 3 focused tools - `search_tokens` - `query_token_bundles` - `query_token_signal` - `query_token_score` - `query_token_security_status` - `query_pool_security_status` - `query_wallet_ban_status` - `query_wallet_label_evidence` - `query_wallet_coordination` - `query_wallet_follows` - `query_token_coordination` - `query_coordination_evidence` - `query_token_crowd` - `query_entity_detail` - `query_token_funding_abuse` - `query_token_wash_trades` - `query_wallet_entanglement` - `query_bundle_detail` - `query_token_campaigns_history` - `query_entity_token_history` - `query_forming_coordinated_pushes` - `query_follower_cascade` - `query_emerging_entities` - `query_token_minority_buyers` - `query_copy_originator` - `query_token_entity_concentration` - `query_token_late_retail` ### Layer 3 composites - `token_deep_dive`: risk signal, bundle summary, holder-label breakdown, holder PnL, buyer quality, direct security row. - `token_coordination_report`: campaigns, crowd state, entity concentration, early clustered buyers, late-retail flow, wash patterns. - `wallet_network_report`: follow edges in both directions, entity membership/roster, bundle-entanglement clusters. There are no Layer 1-only MCP tools. Layer 1 market data is available through REST and WebSocket. ## REST response and error rules - Success is JSON unless the operation is `/metrics`. - Error envelope: `{"error":"description","code":400}`. - Common statuses: 400 invalid input, 401 invalid key, 403 tier insufficient, 404 no resource, 429 rate limited, 500 internal error, 503 dependency unavailable. - `null`, an empty result, and an HTTP error are distinct states. - Resource roots are singular: `/v1/wallet/...` and `/v1/token/...`. ## Free REST operations ### GET /v1/token/{mint}/buyer-quality Recent buyer composition by `elite_smart_money`, `consistent_organic`, `developing_organic`, `bot_operated`, `farm_funded`, and `unrated_new`, plus volume decomposition and `smart_money_signal`. Optional `window_hours`, default 1. Cache 30 seconds. ### GET /v1/token/{mint}/bundles/summary Returns token mint, total/open bundle count, bundled supply percentage, bundled value, bundled realized PnL, and nullable dominant bundle type. Cache 15 seconds. ## Layer 1 REST operations ### GET /v1/token/{mint}/info Token validation, suspicious, and high-risk state plus nullable validation reason. Cache 300 seconds. ### GET /v1/token/{mint}/ohlcv Parameters: `timeframe=1s|1m|5m|15m|1h` (default 1m), `view=full|filtered` (default full), optional unix-ms `from`/`to`, `limit` default 500 max 2000. Returns candles with OHLC, token/base/USD volume, trade count, buy/sell volume, and nullable VWAP. Cache 5 seconds. ### GET /v1/token/{mint}/trades Parameter `limit`, default 50 max 200. Returns recent swaps with signature, slot, timestamp, wallet, token amount, direction, DEX, base amount, base price USD, and total fees USD. ### GET /v1/token/{mint}/liquidity Returns: ```json { "token_mint": "MINT", "depth": { "venue": "amm_actual", "token_reserve_ui": 8200000.0, "quote_reserve_sol": 412.5, "liquidity_usd": null, "reserve_slot": 245678901, "updated_at_ms": 1775574600000 }, "lock": { "status": "burned", "burn_pct": 1.0, "lock_pct": null, "verified_at": "2026-04-07 14:30:00+00" }, "dump_impact_pct": 0.31, "exit_capacity": { "usd_at_10": null, "usd_at_25": null, "usd_at_50": null, "sol_at_10": 21.72, "sol_at_25": 55.26, "sol_at_50": 120.82 } } ``` `depth` is null when missing, stale, or unsupported. `dump_impact_pct` is a 0..1 fraction. Exit-capacity SOL values are only computed for vetted constant-product shapes. USD values are currently null because this route does not invent a SOL/USD quote. Cache 5 seconds. ### GET /v1/token/{mint}/holders/summary Returns camelCase holder state: distinct count, raw non-zero balance, nullable mint supply, nullable top-10/50/100 percentage, hydration status, slots, and response timestamp. Hydration is `hydrating|hydrated|born_forward|partial_forward`. Treat `partial_forward` concentration as a lower bound. Cache 15 seconds. ### GET /v1/token/{mint}/holders/top Parameter `n`, default 10 max 500. Returns ranked holders with raw balances, fractional/percentage ownership as documented in OpenAPI, and holder-state freshness. ### GET /v1/token/{mint}/holders Parameters `limit` default 100 max 1000 and `offset` default 0. Returns the paginated holder list and next offset. ## Layer 2 REST operations ### GET /v1/wallet/{address}/performance Parameter `window=1d|7d|30d`, default 7d. Returns trade/win/loss counts, per-exit win rate, total PnL/volume/fees USD, average hold seconds, and cash PnL USD. `sharpe_ratio`, `profit_factor`, and `disposition_index` are present but always 0.0 here; use `/quality` for populated position-correct metrics. Cache 30 seconds. ### GET /v1/wallet/{address}/trades Parameters `limit` default 50 max 200, `offset` default 0, optional token mint filter. Each row contains wallet, token, entry/exit signatures, timestamps, hold seconds, entry/exit price USD, realized PnL USD/SOL, percentage gain, position type, exit type, and entry/exit DEX. This REST response does not include the richer live event's fee/tool fields. ### GET /v1/wallet/{address}/positions Parameter `status=open|closed|all`, default all. Returns at most 100 rows with wallet, mint, entry signature/timestamp/price, original/remaining amount, per-token price, status, exit count, and entry DEX. It does not include mark-to-market value. ### GET /v1/wallet/{address}/labels Returns a wallet label object or literal JSON `null`. Fields: wallet, trader type, performance level, size class, exit style, automation label, primary terminal/tool and tool share, 6h/24h freshness flags, farm-funding flag, generic labels, trade badges, identity badges, special labels, nullable description, nullable label hash. Current performance values are `BANNED|UNRATED|DORMANT|EARNER|UNPROFITABLE|BREAK_EVEN`. A null label is unknown/unobserved, not clean. Cache 60 seconds. ### GET /v1/wallet/{address}/quality Returns literal null when no snapshot exists. Otherwise returns rated flag, 0–100 explainable skill score, classification, closed positions, position win rate, raw per-exit win rate, `win_rate_inflation_pts`, disposition, conviction sizing, profit factor, Sharpe, runner score, loss/ROI distribution, big wins/losses, realized PnL, and badges. `rated=true` at 10+ closed positions. Cache 60 seconds. ### GET /v1/wallet/{address}/profile Returns the 30-dimensional behavior vector and raw/normalized features across timing, exit discipline, performance, velocity/sizing, infrastructure, and provenance. Wallets below activity gates can return no vector. Cache 60 seconds. ### GET /v1/wallet/{address}/similar Parameters: `limit` default 20 max 100, optional `min_trades`, optional `performance_level`. Returns cosine-ranked behaviorally similar wallets with shared traits and key differences. This is behavioral similarity, not evidence of coordination. ### GET /v1/wallet/{address}/provenance Returns wallet, nullable known root entity/source, hop count, direct funder, and last-funded timestamp where resolved. An unresolved root is not a clean verdict. Cache 300 seconds. ### GET /v1/leaderboard Parameters: `window=1d|7d|30d`, `sort=pnl_usd|roi|win_rate`, `limit` default 100 max 500, offset, and `include_hft` default false. Requires at least five trades. Malicious wallets are excluded. HFT/MEV wallets with median hold under 60 seconds are excluded unless requested. Cache 60 seconds. ## Layer 3 REST operations ### GET /v1/token/{mint}/bundles Returns bundle list with IDs, types, leaders, lifecycle, member counts, chain inventory, money in/out, realized PnL, tokens bought/sold, sold share, risk, evidence, and timestamps. The 10 types are `JitoMev`, `JitoSequential`, `SameSlotBuyCohort`, `SameSlotSellCohort`, `LaunchSlotBurst`, `MultiSlotBuyCohort`, `SybilPoisoning`, `Hybrid`, `CexCoordinated`, and `SyntheticSwarm`. Cache 15 seconds. ### GET /v1/token/{mint}/bundles/{bundle_id} Returns bundle detail plus member roster. Can include a linked coordination entity when at least 60% of bundle members share it. ### GET /v1/token/{mint}/liquidity/events Returns the newest 100 LP add/remove events. Each event includes signature, ms timestamp, slot, pool, DEX, wallet, side, token/quote vault deltas, nullable fractional share of pool moved, full-close state, bundle membership, and flagged-wallet state. A zero vault delta can mean unresolved parser data, not no movement. Cache 5 seconds. ### GET /v1/token/{mint}/wash-trades Parameter `limit`, default 50 max 200. Returns wallets with rapid direction-flip patterns, volume, net exposure, detection time, and modeled atomic flag. Cache 15 seconds. ### GET /v1/token/{mint}/funding-abuse Parameters: `early_window_minutes`, default 60 clamped 10..240; `limit`, default 50 max 200. Returns summary plus per-wallet breakdown. Stable reason codes include seed waves, farm-funded fresh wallets, CEX root dispersion/convergence, fast/same-day funding, and shared terminal patterns. ### GET /v1/token/{mint}/suspicious-activity Returns `clean|suspicious|rugged`, persisted reasons/timestamps, live funding-abuse reason codes, and nullable embedded funding summary. A clean persisted status can coexist with live activity flags. ### GET /v1/wallet/{address}/entanglement Returns bundle-graph clusters the wallet participates in. ### GET /v1/wallet/{address}/follows Returns camelCase `followsOut` and `followsIn` plus degraded state. `followsOut` means wallets that copy this leader; `followsIn` means leaders this wallet copies. Edges include confidence, support, token breadth, and recency. Cache 30 seconds. ### GET /v1/wallet/{address}/entity Returns nullable shared-funder/shared-execution membership, sibling sample, and degraded state. Cache 60 seconds. ### GET /v1/token/{mint}/campaigns Returns active and recent coordination campaigns plus degraded state. Cache 15 seconds. ### GET /v1/token/{mint}/crowd Returns current and per-minute crowd state over the recent window. Cache 15 seconds. ### GET /v1/entity/{entity_id} Returns entity kind, root wallet, member count, confidence, first/last seen, degraded state, and member sample. Cache 60 seconds. ### GET /v1/entity/{entity_id}/members Parameters `page` default 0 and `page_size` default 100 max 500. Returns the entity member roster. ### GET /v1/coordination/health Returns healthy state, degraded window, dropped messages in the last minute, and observation time. Cache 30 seconds. ### Intel composites - GET `/v1/intel/coordinated-pushes/forming`: forming coordinated regimes across tokens. - GET `/v1/intel/wallet/{leader}/cascade?mint=MINT&window_s=300`: followers buying behind a leader; window clamped 1..3600. - GET `/v1/intel/entities/emerging?hours=24`: recently formed entities; hours clamped 1..168. - GET `/v1/intel/token/{mint}/early-buyers?window_s=300`: entities present in the early-buy window. - GET `/v1/intel/token/{mint}/copy-originator?start_ts_ms=...&end_ts_ms=...`: likely originators in a required window up to 60 minutes. - GET `/v1/intel/token/{mint}/entity-concentration?hours=24`: entity-weighted actor and volume concentration. - GET `/v1/intel/token/{mint}/late-retail?hours=24`: late buyers behind elite exits; hours clamped 1..72. These endpoints report detection structure, not intent or trading advice. ## WebSocket protocol Connect to `wss://api.conyr.ai/ws` with the Bearer header. Client messages: ```json {"op":"subscribe","channels":["token:MINT:trades"]} {"op":"unsubscribe","channels":["token:MINT:trades"]} {"op":"ping"} ``` Server messages: ```json {"op":"subscribed","channels":["token:MINT:trades"]} {"op":"unsubscribed","channels":["token:MINT:trades"]} {"op":"pong"} {"op":"error","message":"..."} {"channel":"token:MINT:trades","data":{}} ``` ### Layer 1 channel families - `token:{mint}:trades` - `token:{mint}:ticks` - `token:{mint}:ohlcv:{view}:{tf}`; view `full|filtered`, timeframe `1s|1m|5m|15m|1h` ### Layer 2 channel families - `wallet:{address}:pnl` - `wallet:{address}:positions` - `wallet:{address}:labels` ### Layer 3 channel families - `token:{mint}:security` - `token:{mint}:campaign` - `token:{mint}:bundles`: raw BundleV2 token updates. - `token:{mint}:dump_alert`: compact qualifying dump-start event with bundle ID/type, fractional sold share, member count, remaining inventory, risk, slot, and time. - `wallet:{address}:security` - `wallet:{address}:follow` - `wallet:{address}:entity` The server sends protocol-level pings every 30 seconds. Invalid/tier-insufficient channel requests return non-fatal `op:error`. Slow consumers can lose events due to the 256-message client buffer. Reconcile state from REST. ## Rate and connection limits | Tier | Requests/min | WS connections/key | Subscriptions/connection | |---|---:|---:|---:| | Free | 10 | 0 | 0 | | Layer 1 | 100 | 5 | 50 | | Layer 2 | 300 | 20 | 50 | | Layer 3 | 600 | 50 | 50 | | Enterprise | 3000 default | unlimited | unlimited | MCP and REST use separate limiter instances; their request budgets are tracked independently. ## Coverage and inference rules 1. Never interpret a null label or unresolved provenance root as clean. 2. Never interpret missing liquidity depth as zero liquidity; it means missing, stale, or unsupported. 3. Preserve holder hydration state; `partial_forward` is not a full historical holder set. 4. Preserve composite `partial`, per-section errors, and coordination `degraded` flags. 5. Behavioral similarity does not prove common control. Use entity/bundle/follow evidence for coordination. 6. A high raw per-exit win rate can be DCA-inflated. Use `/quality` or `query_wallet_quality` for actual position-level skill. 7. Coordination, minority-buyer, and forming-push detections describe observable structure; do not invent motive. 8. The public REST contract has no separate current-price or unrealized-PnL operation. Derive those only when the agent has an observed tick/OHLCV price and open-position cost basis. ## Data provenance and protocol coverage Conyr consumes a self-hosted Yellowstone stream and computes its intelligence from raw Solana transactions. The nine explicitly documented DEX protocols are Raydium V4, Raydium CPMM, PumpFun, PumpSwap, BonkFun, Meteora DLMM, Meteora CPMM, Meteora DBC, and Boop.