Endpoints

GET /api/traders

Search and filter traders. Returns paginated results sorted by any metric.

Parameters

Parameter	Type	Default	Description
sort_by	string	pnl	Column to sort by (any metric name)
sort_dir	string	desc	Sort direction: asc or desc
page	int	1	Page number (max 5)
page_size	int	25	Results per page (max 100)
trader	string		Filter by wallet address prefix
wallets	string		Comma-separated wallet addresses to look up (max 100)
tokens	string		Comma-separated token addresses (require all)
platform	string		Comma-separated platform names (e.g. Phantom,Axiom,GMGN). Use any for all known platforms
token_search	string		JSON array of token search criteria (advanced)
token_match	string	all	Match mode for token_search: all, any, min:N

Numeric filters

All numeric columns support _min and _max suffixes. For example: pnl_min=1000&pnl_max=50000. All filters are combined with AND logic.

PnL & Value (USD)

Column	Description
pnl	Realized PnL: total_sold - total_bought. Unsold tokens count as 100% loss
pnl_pct	PnL as percentage of total bought
pnl_7d	Realized PnL from the last 7 days
pnl_30d	Realized PnL from the last 30 days
total_sold	Total USD value of all sells
total_bought	Total USD value of all buys
unrealized_value	Estimated value of unsold holdings, capped at 5000x cost or $2M
total_pnl	Realized PnL + unrealized value
total_pnl_pct	Total PnL as percentage of total bought
best_token_pnl	PnL of the trader's single best-performing token (USD)
min_cost	Smallest single buy value (USD). Low values suggest bot or dust buys

Trade Counts

Column	Description
num_buys	Total number of buy transactions
num_sells	Total number of sell transactions
num_tokens	Number of distinct tokens traded

Win Rate & Distribution

Column	Description
win_rate	Percentage of tokens with positive PnL (0-100)
oversold_pct	Percentage of tokens where sell amount exceeds buy amount by >2%. High values suggest wash trading
top_token_pnl_pct	Percentage of total PnL from single best token. High = concentrated/lucky, not consistent
rugged_pct	Percentage of tokens with no trades in the last 48 hours (likely dead tokens)

PnL Distribution Buckets — number of tokens in each PnL range:

Column	PnL Range
pnl_above_500	> +500%
pnl_200_500	+200% to +500%
pnl_0_200	0% to +200%
pnl_neg50_0	-50% to 0%
pnl_below_neg50	< -50%

Holding Time

Column	Description
median_holding_hours	Median time from first buy to last sell across all tokens (hours)
avg_holding_hours	Average time from first buy to last sell (hours)
median_vw_holding_hours	Median volume-weighted holding time. Reduces skew from small early buys
avg_vw_holding_hours	Average volume-weighted holding time

Early Entry

Column	Description
early_entry_rate_60m	Percentage of tokens where first buy was within 60 minutes of token launch
early_entry_rate_15m	Percentage of tokens where first buy was within 15 minutes of launch
median_minutes_from_launch	Median minutes between token launch and trader's first buy
early_win_rate	Win rate on early-entry tokens only (%)
early_pnl_pct	PnL percentage on early-entry tokens only

Bot & Scam Detection

Column	Description
round_trip_pct	Percentage of tokens bought then fully sold. High values suggest bot-like behavior
buy_only_pct	Percentage of tokens that were only bought, never sold
avg_buy_value	Average buy transaction size (USD)
buy_size_cv	Coefficient of variation of buy sizes. Low values = uniform sizing = bot-like
first_buyer_rate	Percentage of tokens where this trader was the first buyer. High = insider/bot

Date filters

Parameter	Type	Description
last_trade_date_min	string	Earliest last trade date (YYYY-MM-DD)
last_trade_date_max	string	Latest last trade date (YYYY-MM-DD)
first_trade_date_min	string	Earliest first trade date (YYYY-MM-DD)
first_trade_date_max	string	Latest first trade date (YYYY-MM-DD)

Example

curl -H "x-api-key: YOUR_API_KEY" \
  "YOUR_API_BASE_URL/api/traders?pnl_min=5000&win_rate_min=50&num_tokens_min=5&sort_by=pnl&page_size=10"

Response

{
  "rows": [
    {
      "trader": "9kJ8tC1AoeSU5Xm...",
      "pnl": 58377487.18,
      "pnl_pct": 494.72,
      "total_sold": 40591069.72,
      "total_bought": 6825234.71,
      "num_sells": 16,
      "num_buys": 8,
      "num_tokens": 1,
      "win_rate": 100.0,
      "last_trade_date": "2026-03-28",
      "pnl_7d": 12500.0,
      "pnl_30d": 45000.0,
      "platform_name": "Phantom",
      "kol_name": null,
      "...": "..."
    }
  ],
  "total": 1000,
  "total_matched": 32632,
  "page": 1,
  "page_size": 10,
  "total_pages": 5
}

Note: total is capped at 5,000 results per query. total_matched shows the true count of matching traders. Use filters to narrow results.

---

GET /api/trader/{address}

Get detailed token-by-token breakdown for a specific wallet.

Parameters

Parameter	Type	Description
address	string (path)	Wallet address

Example

curl -H "x-api-key: YOUR_API_KEY" \
  YOUR_API_BASE_URL/api/trader/9kJ8tC1AoeSU5Xm5z7bxG8oSXSukCPgphBoDTh7P9HT4

Response

{
  "summary": {
    "trader": "9kJ8tC1AoeSU5Xm...",
    "pnl": 58377487.18,
    "pnl_pct": 494.72,
    "total_sold": 40591069.72,
    "total_bought": 6825234.71,
    "num_sells": 16,
    "num_buys": 8,
    "num_tokens": 12,
    "win_rate": 75.0,
    "unrealized_value": 1234.56,
    "avg_buy_value": 853154.34,
    "early_entry_rate_60m": 45.0,
    "...": "..."
  },
  "tokens": [
    {
      "token": "So11111111111111111111111111111111111111112",
      "token_name": "SOL",
      "pnl": 5000.0,
      "pnl_pct": 250.0,
      "total_bought": 2000.0,
      "total_sold": 7000.0,
      "num_buys": 3,
      "num_sells": 2,
      "unrealized_value": 0,
      "holding_hours": 48.5,
      "minutes_from_launch": 120,
      "is_rugged": 0,
      "last_trade_date": "2026-03-25",
      "last_activity_ts": "2026-03-25T14:30:00"
    }
  ]
}

---

GET /api/token-names

Look up human-readable names for token addresses.

Parameters

Parameter	Type	Description
tokens	string (query)	Comma-separated token addresses

Example

curl -H "x-api-key: YOUR_API_KEY" \
  "YOUR_API_BASE_URL/api/token-names?tokens=So11111111111111111111111111111111111111112,EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

Response

{
  "So11111111111111111111111111111111111111112": "Wrapped SOL",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": "USD Coin"
}

---

GET /api/meta

Get metadata about the dataset.

Response

{
  "updated_at": 1711728000.0,
  "last_trade_date": "2026-03-28"
}

---

GET /api/credits

Check your current credit balance. Does not consume a credit.

Response

{
  "credits_remaining": 49950,
  "credits_limit": 50000,
  "credits_reset": "2026-04-01T00:00:00Z",
  "period": "2026-03"
}

---

Advanced: Token Search

The token_search parameter on /api/traders accepts a JSON array of criteria to find wallets by their token-level trades.

Fields per criteria row

Field	Description
token	Token address
pnl_min / pnl_max	PnL range on this token
buy_value_min / buy_value_max	Buy value range (USD)
minutes_max	Max minutes from token launch to first buy
buy_count_max	Max number of buy transactions

Match modes

Mode	Description
all	Wallet must match ALL criteria rows
any	Wallet must match at least one
min:N	Wallet must match at least N rows

Example

Find wallets that bought a specific token within 60 minutes of launch with at least $500:

curl -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'token_search=[{"token":"TOKEN_ADDRESS","buy_value_min":"500","minutes_max":"60"}]' \
  "YOUR_API_BASE_URL/api/traders?token_match=all"