# CONYR API — Full Reference

> The deepest Solana intelligence API. Sub-second realized + unrealized PnL, FIFO position tracking, AI wallet taxonomy (22 badges), coordinated bundle detection, 5-axis token health scores, wallet provenance, 30-dim behavioral vectors, and organic OHLCV candles across 12+ DEXes. REST + WebSocket for every data type.

## Key Capability: Sub-Second Real-Time Streaming

Every major REST endpoint has a live WebSocket counterpart. CONYR streams realized PnL the instant a trade closes and unrealized PnL as prices move — sub-second from chain to your WebSocket. No polling required.

| REST Endpoint | WebSocket Channel | Event Trigger |
|---|---|---|
| GET /v1/wallets/{addr}/trades | wallet:{addr}:pnl | Trade closes (partial or full exit) |
| GET /v1/wallets/{addr}/unrealized-pnl | wallet:{addr}:unrealized-pnl | Mark-to-market price changes on open positions |
| GET /v1/wallets/{addr}/positions | wallet:{addr}:positions | Position opened/updated/closed |
| GET /v1/wallets/{addr}/bundles | wallet:{addr}:bundles | Bundle detected or lifecycle state change |
| GET /v1/wallets/{addr}/security | wallet:{addr}:security | Threat detected |
| GET /v1/wallets/{addr}/taxonomy | wallet:{addr}:taxonomy | Badge or classification changed |
| GET /v1/tokens/{mint}/trades | token:{mint}:trades | Every swap on-chain |
| GET /v1/tokens/{mint}/ohlcv | token:{mint}:ohlcv:{view}:{tf} | Candle computed |
| — | token:{mint}:ticks | Price tick update (stream-only) |

Pattern: Use REST to backfill state, then subscribe via WebSocket for live updates.

## Base URL

https://api.conyr.ai

## Authentication

All /v1/* endpoints require a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

Unauthenticated endpoints: /health, /ready, /metrics, /ws

Error response (401):
```json
{"error": "Missing or invalid Authorization header", "code": 401}
```

## Error Format

All errors return JSON:
```json
{"error": "description", "code": 400}
```

Possible codes: 400 (bad request), 401 (unauthorized), 500 (internal error), 503 (service unavailable)

## Caching

Responses are cached in-memory. Cache TTLs:
- Wallet performance: 30s
- Leaderboard: 60s
- Token info: 300s
- OHLCV: 5s
- Wallet labels: 60s

---

## GET /v1/wallets/{address}/performance

Trading performance summary for a wallet.

### Parameters

| Name | In | Type | Required | Default | Values |
|------|-----|------|----------|---------|--------|
| address | path | string | yes | — | Solana wallet address (base58) |
| window | query | string | no | 7d | 1d, 7d, 30d |

### Response 200

```json
{
  "wallet_address": "7xKXtg...",
  "total_trades": 142,
  "wins": 89,
  "losses": 53,
  "win_rate": 0.6267,
  "total_pnl_usd": 12450.32,
  "total_volume_usd": 98230.50,
  "total_fees_usd": 142.80,
  "avg_hold_time_seconds": 3420.5,
  "cash_pnl_usd": 11200.00
}
```

### Fields

- wallet_address: Solana wallet address
- total_trades: Number of completed round-trip trades
- wins: Trades with positive realized PnL
- losses: Trades with zero or negative realized PnL
- win_rate: wins / total_trades (0.0 to 1.0)
- total_pnl_usd: Sum of realized PnL in USD
- total_volume_usd: Total entry + exit volume in USD
- total_fees_usd: Total network fees paid in USD
- avg_hold_time_seconds: Average time between entry and exit
- cash_pnl_usd: Net cash flow (SOL in/out) in USD terms

---

## GET /v1/wallets/{address}/trades

Paginated trade history with entry/exit details and realized PnL. FIFO cost-basis accounting.

### Parameters

| Name | In | Type | Required | Default | Constraints |
|------|-----|------|----------|---------|-------------|
| address | path | string | yes | — | base58 |
| limit | query | integer | no | 50 | max 200 |
| offset | query | integer | no | 0 | — |
| token | query | string | no | — | Filter by token mint address |

### Response 200

```json
{
  "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,
      "exit_number": 1,
      "entry_price_usd": 234.50,
      "exit_price_usd": 312.00,
      "price_per_token_entry": 0.00023450,
      "price_per_token_exit": 0.00031200,
      "token_amount": 500000.0,
      "remaining_token_amount": 500000.0,
      "realized_pnl_usd": 78.50,
      "realized_pnl_sol": 0.52,
      "percentage_gain": 33.33,
      "total_position_realized_pnl_usd": 78.50,
      "position_type": "FULL_POSITION",
      "exit_type": "PARTIAL",
      "percentage_sold": 50.0,
      "exit_dex": "Raydium",
      "entry_dex": "PumpFun",
      "entry_network_fees_usd": 0.005,
      "exit_network_fees_usd": 0.004,
      "trade_flag": "photon"
    }
  ],
  "limit": 50,
  "offset": 0
}
```

### Key fields

- exit_number: Sequence number of this exit (1st, 2nd, etc.)
- remaining_token_amount: Tokens left after this exit
- total_position_realized_pnl_usd: Running total of realized PnL for this position
- position_type: FULL_POSITION, DCA_EXIT, or ARBITRAGE
- exit_type: FULL or PARTIAL
- percentage_sold: Percentage of position sold in this exit
- trade_flag: Trading tool used (photon, bullx, axiom, bloom, bot)

---

## GET /v1/wallets/{address}/unrealized-pnl

Unrealized PnL on open positions using vetted live prices.

### Parameters

| Name | In | Type | Required | Default | Constraints |
|------|-----|------|----------|---------|-------------|
| address | path | string | yes | — | base58 |
| token | query | string | no | — | Filter by token mint address |

### Response 200

```json
{
  "wallet_address": "7xKXtg...",
  "total_unrealized_pnl_usd": 2450.80,
  "positions": [
    {
      "token_mint": "EPjFWd...",
      "entry_price_usd": 0.00234,
      "current_price_usd": 0.00312,
      "token_amount": 500000.0,
      "cost_basis_usd": 1170.00,
      "current_value_usd": 1560.00,
      "unrealized_pnl_usd": 390.00,
      "unrealized_pnl_sol": 2.58,
      "percentage_gain": 33.33,
      "entry_timestamp": 1709654400,
      "entry_dex": "PumpFun"
    }
  ]
}
```

### Fields

- wallet_address: Solana wallet address
- total_unrealized_pnl_usd: Sum of unrealized PnL across all open positions
- positions[].entry_price_usd: FIFO cost-basis entry price
- positions[].current_price_usd: Current market price from vetted live feeds
- positions[].cost_basis_usd: Total cost of the position (entry_price_usd * token_amount)
- positions[].current_value_usd: Current market value (current_price_usd * token_amount)
- positions[].unrealized_pnl_usd: current_value_usd - cost_basis_usd
- positions[].unrealized_pnl_sol: Unrealized PnL in SOL terms
- positions[].percentage_gain: Percentage change from entry to current price

Live stream: `wallet:{address}:unrealized-pnl` — fires as prices change for open positions.

---

## GET /v1/wallets/{address}/positions

Wallet token positions tracked with lot-level FIFO accounting.

### Parameters

| Name | In | Type | Required | Default | Values |
|------|-----|------|----------|---------|--------|
| address | path | string | yes | — | base58 |
| status | query | string | no | all | open, closed, all |

### Response 200

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

### Status values

- OPEN: Full position, no exits yet
- PARTIAL: Some tokens sold
- CLOSED: Entire position exited

---

## GET /v1/wallets/{address}/labels

Behavioral classification labels computed in real time from closed-position outcomes.

### Parameters

| Name | In | Type | Required |
|------|-----|------|----------|
| address | path | string | yes |

### Response 200

Returns the label object, or `null` if the wallet has not been classified yet.

```json
{
  "wallet": "7xKXtg...",
  "trader_type": "DAY_TRADER",
  "performance_level": "PROFITABLE",
  "size_class": "SHARK",
  "exit_style": "DCA_OUT",
  "automation_label": "ORGANIC",
  "primary_terminal": "photon",
  "primary_terminal_pct": 85.0,
  "primary_dex": "Raydium",
  "primary_dex_pct": 72.5,
  "funded_by_farm": 0,
  "funder_farm_active_now": 0,
  "is_root_cex": 1,
  "trade_badges": ["RUNNER_KEEPER", "CONFIDENCE_SIZER"],
  "identity_badges": ["TOOL_PHOTON", "ROOT_CEX"],
  "total_trades": 142,
  "win_rate_pct": 62.67,
  "total_pnl": 12450.32,
  "total_cash_pnl_usd": 11200.00,
  "sharpe_ratio": 1.85,
  "profit_factor": 2.34,
  "disposition_index": 1.45,
  "cash_roi_percent": 22.5,
  "runner_score": 0.12,
  "confidence_score": 1.65,
  "avg_loss_roi_pct": -12.5,
  "pos_p10_roi_pct": -45.0,
  "pos_p50_roi_pct": 15.0,
  "pos_p90_roi_pct": 180.0,
  "description": "SHARK PROFITABLE DAY_TRADER (RUNNER_KEEPER, TOOL_PHOTON, ROOT_CEX)"
}
```

### Taxonomy values

trader_type: SCALPER, DAY_TRADER, SWING_TRADER, POSITION_TRADER, MALICIOUS
performance_level: PROFITABLE, BREAK_EVEN, UNPROFITABLE, UNRATED, BANNED
size_class: SHRIMP, FISH, SHARK, WHALE
exit_style: FULL_EXITER, DCA_OUT, PARTIAL_TAKER, MIXED

### Trade badges

RUNNER_KEEPER, CONFIDENCE_SIZER, STOP_LOSS_USER, CONSISTENT_WINNER, BAG_HOLDER, LOSS_CUTTER, LOTTO_PLAYER, DIAMOND_HANDS, PAPER_HANDS, ELITE_TRADER, VETERAN_WINNER

### Identity badges

HFT_BOT, FLASH_BOT, ARB_BOT, WASH_TRADER, TOOL_PHOTON, TOOL_BULLX, TOOL_AXIOM, MULTI_TOOL, FRESH_FUNDED_6H, FRESH_FUNDED_24H, FUNDED_BY_FARM, FUNDER_FARM_ACTIVE, DEX_SPECIALIST_{dex}, TOKEN_CONCENTRATED, ROOT_CEX, ROOT_DEX_AUTH, ROOT_KNOWN

---

## GET /v1/wallets/{address}/taxonomy

4-axis wallet classification with up to 22 behavioral and identity badges.

### Parameters

| Name | In | Type | Required |
|------|-----|------|----------|
| address | path | string | yes |

### Response 200

```json
{
  "wallet": "7xKXtg...",
  "trader_type": "DAY_TRADER",
  "performance_level": "PROFITABLE",
  "size_class": "SHARK",
  "exit_style": "DCA_OUT",
  "trade_badges": ["RUNNER_KEEPER", "CONFIDENCE_SIZER", "ELITE_TRADER"],
  "identity_badges": ["TOOL_PHOTON", "ROOT_CEX"],
  "description": "SHARK PROFITABLE DAY_TRADER (RUNNER_KEEPER, CONFIDENCE_SIZER, ELITE_TRADER, TOOL_PHOTON, ROOT_CEX)"
}
```

Live stream: `wallet:{address}:taxonomy` — fires when badges or classification change.

---

## GET /v1/wallets/{address}/bundles

Coordinated wallet bundles associated with this wallet.

### Parameters

| Name | In | Type | Required | Default | Constraints |
|------|-----|------|----------|---------|-------------|
| address | path | string | yes | — | base58 |
| limit | query | integer | no | 25 | max 100 |

### Response 200

```json
{
  "bundles": [
    {
      "bundle_id": "bndl_abc123",
      "token_mint": "EPjFWd...",
      "bundle_type": "SybilPoisoning",
      "status": "active",
      "leader_wallet": "3mPq...",
      "member_count_total": 8,
      "member_count_active": 6,
      "chain_balance_ui": 5000000.0,
      "total_usd_invested": 1250.00,
      "total_usd_returned": 450.00,
      "realized_pnl_usd": -800.00,
      "risk_score": 0.85,
      "evidence": ["8 wallets bought within 3 slots", "Single funder detected", "72% supply controlled"],
      "sold_pct": 0.15,
      "created_ts_ms": 1709654400000,
      "last_trade_ts_ms": 1709658000000
    }
  ]
}
```

### Bundle types

SybilPoisoning, CexCoordinated, JitoSequential, MultiSell, Synthetic, Sleeper, SyntheticSwarm

### Bundle lifecycle states

active, dormant, dumping, derisked, exited, rugged, merged

Live stream: `wallet:{address}:bundles` — fires on bundle detection and lifecycle state changes.

---

## GET /v1/wallets/{address}/security

Malicious activity assessment for a wallet.

### Parameters

| Name | In | Type | Required |
|------|-----|------|----------|
| address | path | string | yes |

### Response 200

```json
{
  "wallet_address": "7xKXtg...",
  "is_malicious": true,
  "detection_reason": "Extracted >$50k from 3 rugged tokens within 48h",
  "total_pnl_usd": 52340.00,
  "suspicious_tokens": ["EPjFWd...", "3mPqAb..."],
  "first_seen": 1709654400,
  "last_seen": 1709741800
}
```

Live stream: `wallet:{address}:security` — fires on threat detection.

---

## GET /v1/leaderboard

Ranked wallet leaderboard. Minimum 5 trades required for inclusion.

### Parameters

| Name | In | Type | Required | Default | Values |
|------|-----|------|----------|---------|--------|
| window | query | string | no | 7d | 1d, 7d, 30d |
| sort | query | string | no | pnl_usd | pnl_usd, roi, win_rate |
| limit | query | integer | no | 100 | max 500 |
| offset | query | integer | no | 0 | — |

### Response 200

```json
{
  "leaderboard": [
    {
      "rank": 1,
      "wallet_address": "7xKXtg...",
      "total_trades": 342,
      "wins": 245,
      "losses": 97,
      "win_rate": 0.7163,
      "total_pnl_usd": 89420.50,
      "total_volume_usd": 456000.00,
      "roi": 19.6,
      "cash_pnl_usd": 78200.00
    }
  ],
  "window": "7d",
  "sort": "total_pnl_usd",
  "limit": 100,
  "offset": 0
}
```

---

## GET /v1/tokens/{mint}/info

Token metadata, validation status, and 5-axis health score.

### Parameters

| Name | In | Type | Required |
|------|-----|------|----------|
| mint | path | string | yes |

### Response 200

```json
{
  "token_mint": "EPjFWd...",
  "name": "ExampleToken",
  "symbol": "EXT",
  "decimals": 9,
  "supply": 1000000000,
  "deployer": "3mPq...",
  "primary_dex": "Raydium",
  "is_mintable": false,
  "is_freezable": false,
  "status": "validated",
  "flagged_reasons": [],
  "score": 78,
  "score_label": "good",
  "contract_score": 95,
  "bundle_score": 60,
  "deployer_score": 85,
  "holder_score": 72,
  "market_score": 80,
  "contract_evidence": ["Not mintable", "Not freezable"],
  "bundle_evidence": ["2 active bundles", "12% supply at risk"],
  "deployer_evidence": ["No rug history"],
  "holder_evidence": ["68% organic wallets", "5% bot activity"],
  "market_evidence": ["Healthy buy/sell ratio", "142 unique wallets"]
}
```

### Score axes (0-100 each, weighted composite)

- Contract (25%): mintable, freezable, flagged reasons, validation status
- Bundle Threat (30%): supply at risk, bundle types, realized profit extracted, dumping/rugged counts
- Deployer Risk (15%): deployer cross-referenced against malicious wallet registry, historical rug count
- Holder Quality (20%): organic %, bot %, farm-funded %, fresh-funded %, profitable wallet %, malicious wallet count
- Market Integrity (10%): buy/sell ratio, unique wallets, volume concentration

Score labels: good, moderate, risky, dangerous

---

## GET /v1/tokens/{mint}/ohlcv

OHLCV candlestick data. Two views: full (all trades) and filtered (bot/wash trades removed for organic price discovery).

### Parameters

| Name | In | Type | Required | Default | Values |
|------|-----|------|----------|---------|--------|
| mint | path | string | yes | — | base58 |
| timeframe | query | string | no | 1m | 1s, 1m, 5m, 15m, 1h |
| view | query | string | no | full | full, filtered |
| from | query | integer | no | — | Unix milliseconds |
| to | query | integer | no | — | Unix milliseconds |
| limit | query | integer | no | 500 | max 2000 |

### Retention

- 1s: 14 days
- 1m: 90 days
- 5m: 90 days
- 15m: 180 days
- 1h: 365 days

### Response 200

```json
{
  "candles": [
    {
      "bucket": "2026-03-05 14:30:00+00",
      "bucket_ms": 1709650200000,
      "open": 0.00234,
      "high": 0.00256,
      "low": 0.00228,
      "close": 0.00245,
      "volume_token": 5000000.0,
      "volume_base": 11.725,
      "volume_usd": 11725.0,
      "num_trades": 42,
      "buy_volume": 3200000.0,
      "sell_volume": 1800000.0,
      "vwap": 0.002345
    }
  ],
  "token_mint": "EPjFWd...",
  "timeframe": "1m",
  "view": "full"
}
```

---

## GET /v1/tokens/{mint}/trades

Recent swap history for a specific token.

### Parameters

| Name | In | Type | Required | Default | Constraints |
|------|-----|------|----------|---------|-------------|
| mint | path | string | yes | — | base58 |
| limit | query | integer | no | 50 | max 200 |

### Response 200

```json
{
  "trades": [
    {
      "signature": "5vGk...",
      "slot": 245678901,
      "timestamp": "2026-03-05 14:30:00",
      "wallet_address": "7xKXtg...",
      "token_amount": 500000.0,
      "direction": "buy",
      "dex_name": "Raydium",
      "base_amount": 0.85,
      "base_price_usd": 150.25,
      "total_fees_usd": 0.012,
      "is_arbitrage": false,
      "labels": [],
      "bundle_id": null
    }
  ],
  "token_mint": "EPjFWd...",
  "limit": 50
}
```

---

## WebSocket /ws

Real-time data via WebSocket. No authentication required. Max 50 subscriptions per connection. Sub-second latency.

### Connect

```
wss://api.conyr.ai/ws
```

### Client -> Server Messages

Subscribe:
```json
{"op": "subscribe", "channels": ["token:EPjFWd...:trades", "wallet:7xKXtg...:pnl"]}
```

Unsubscribe:
```json
{"op": "unsubscribe", "channels": ["token:EPjFWd...:trades"]}
```

Ping:
```json
{"op": "ping"}
```

### Server -> Client Messages

Subscription confirmed:
```json
{"op": "subscribed", "channels": ["token:EPjFWd...:trades"]}
```

Data event:
```json
{"channel": "token:EPjFWd...:trades", "data": { ... }}
```

Pong:
```json
{"op": "pong"}
```

Error:
```json
{"op": "error", "message": "Subscription limit reached (max 50)"}
```

### Channel Format

- token:<mint>:trades — live trade tape
- token:<mint>:ticks — chart tick events
- token:<mint>:ohlcv:<view>:<tf> — OHLCV candle updates (view: full|filtered, tf: 1s|1m|5m|15m|1h)
- wallet:<address>:pnl — realized PnL events (sub-second)
- wallet:<address>:unrealized-pnl — unrealized PnL updates on open positions
- wallet:<address>:positions — position change events
- wallet:<address>:bundles — bundle detection and lifecycle changes
- wallet:<address>:security — threat detection events
- wallet:<address>:taxonomy — badge and classification changes

### Behavior

- Server sends WebSocket ping every 30s
- Slow clients have messages dropped (256-message buffer per client)

---

## Operations Endpoints

### GET /health
No auth. Returns `{"status": "ok"}`.

### GET /ready
No auth. Returns service readiness status.
```json
{"status": "ready"}
```
Returns 503 if service is not ready.

### GET /metrics
No auth. Returns Prometheus text format metrics.

## Supported DEXes

Raydium (AMM, CPMM, CLMM, Launchpad) | PumpFun | PumpSwap | Meteora (DLMM, DAMM v2, Dynamic Pool) | BonkBot (Boop) | Whirlpool (Orca) | Jupiter

All parsed directly from raw transactions, not aggregator APIs.