Wallets API

Everything about the tracked wallets: who they are, how they perform, and what they hold right now. Wallets are always identified by their opaque alias (W12), never a real address.

All endpoints require your API key (Authorization: Bearer <API_KEY>) and cost light credits.

---

GET /wallets

List the tracked wallets with their full metrics, 25 per page, ordered W1 … Wn.

Query parameters

Name	Type	Default	Description
page	int	1	Page number (≥1).

Response

{
  "page": 1,
  "page_size": 25,
  "total": 247,
  "has_more": true,
  "items": [
    {
      "identity": { "wallet": "W1", "tracked": true, "score": 82.4, "status": "scored" },
      "pnl": {
        "sol_balance": 12.5, "pnl_sol": 40.2, "sol_bought": 120.0,
        "sol_sold": 160.2, "sol_invested_open": 8.1, "unrealized_token_count": 3
      },
      "activity": {
        "total_trades": 318, "buys": 170, "sells": 148, "transfers_in": 5,
        "transfers_out": 2, "sol_received": 0.0, "sol_sent": 0.0,
        "unique_tokens_traded": 96
      },
      "behavior": {
        "winrate": 61.0, "loserate": 39.0, "avg_holding_time": 5400,
        "avg_time_to_almost_full_exit": 7200, "avg_buy_amount": 0.7,
        "avg_sell_amount": 1.1, "quick_sells": 12, "sold_more_than_bought": 8,
        "active_times": [{ "hour_utc": 14, "tx_count": 40 }]
      },
      "computed_at": 1781450000
    }
  ]
}

---

GET /wallets/{alias}/metrics

The same per-wallet object as above, for a single alias. Returns 404 if the alias doesn't resolve.

How the metrics are computed

Metrics are derived from the wallet's own swaps and transfers. PnL and holding times use FIFO accounting (oldest buy is matched first). All SOL figures are in SOL; trades quoted in USDC/USDT are converted to a SOL-equivalent using the SOL/USD price.

identity

Field	Meaning
wallet	Opaque alias.
score	0–100 quality score (see below). null when the wallet is in review.
status	scored, review, or disqualified.

The score is a three-level model:

1. Disqualified → 0 if the wallet holds less than 10 SOL, or its winrate is below 35% while PnL is negative.

2. Review → null if the trade count is outside 50 … 1000 (sample too small or too noisy to judge).

3. Scored → 0–100, summed from:

   • PnL ratio: pnl_sol / sol_bought, scaled so a +20% ratio earns the full 40 points (clamped to ±40).
   • +20 if winrate > 40%.
   • +10 if average holding time > 300s.
   • +10 if average buy size ≥ 1 SOL.
   • +10 if trade count ≥ 100.
   • up to +10 ramped on balance between 20 and 40 SOL.

   The total is clamped to 0 … 100.

pnl

Field	Formula
pnl_sol	Sum of realized FIFO profit across all tokens. A sell realizes (sell_price − lot_price) × qty.
sol_bought	Total SOL spent on buys.
sol_sold	Total SOL received on sells.
sol_invested_open	Cost basis still sitting in open positions (sum of lot_price × qty over un-sold FIFO lots).
unrealized_token_count	Number of tokens with a non-zero remaining balance.
sol_balance	Wallet SOL balance (null if not fetched).

Note on transfers: a token received by transfer enters FIFO as a zero-cost lot; a token sent out drains FIFO without realizing PnL.

activity

Field	Formula
total_trades	buys + sells.
buys / sells	Count of buy / sell swaps.
transfers_in / out	Count of token transfers received / sent.
sol_received / sent	SOL moved in / out via plain SOL transfers.
unique_tokens_traded	Distinct tokens the wallet has traded.

behavior

Field	Formula
winrate / loserate	Of tokens that were sold, the % that closed in profit / loss. Tokens never sold are not counted.
avg_holding_time	Average seconds between a FIFO-matched buy and its sell.
avg_time_to_almost_full_exit	Average seconds from first buy until cumulative sells reach 90% of the amount bought.
avg_buy_amount	sol_bought / buys.
avg_sell_amount	sol_sold / sells.
quick_sells	Count of buys where ≥50% of the bought amount was sold within 15s (flip behavior).
sold_more_than_bought	Count of tokens where tokens sold exceeded tokens bought.
active_times	Top 3 UTC hours by transaction count: [{ "hour_utc", "tx_count" }].

computed_at is the unix time these metrics were last recomputed.

---

GET /wallets/{alias}/holdings

What the wallet currently holds, derived from its swaps (net of buys and sells). Only positions with a positive balance are returned. Returns 404 for an unknown alias.

Response

{
  "wallet": "W37",
  "tokens": [
    {
      "token": { "address": "FSA7iqBeeENna2LUmZyqCYce7op2jBc9ztXLKdM6bonk", "decimals": 6 },
      "position": {
        "balance": 18452310.42,
        "tokens_acquired": 41200000.0,
        "tokens_held": 18452310.42,
        "sol_invested": 21.7
      },
      "timing": {
        "first_activity_at": 1781380000,
        "last_activity_at": 1781450000,
        "holding_time": 70000
      }
    }
  ]
}

Field	Meaning
balance	Tokens still held (decimal-adjusted). Same as tokens_held.
tokens_acquired	Total tokens bought.
sol_invested	SOL spent buying this token.
first_activity_at	Unix time of the first trade on this token.
last_activity_at	Unix time of the most recent trade.
holding_time	Seconds since first_activity_at.

Amounts are display-salted (one factor per token, so the figures stay consistent with each other). Transfers are not netted into the held amount.