Alpha FAQ

Two options:

• Poll the API — call GET /notifications?since=... every 10–30 seconds to pull new signals. Each signal includes a headline, trader details, token info, and a CTA for deep-linking to your swap UI.
• Webhook — set a webhook URL in your config panel and receive signals as POST requests in real time. Ideal for server-side processing or Slack/Discord integrations.

See the Integration Guide in the docs for step-by-step instructions.

Alpha supports Base, Ethereum, Solana, and Polymarket (prediction markets). DEX chains each have their own wallet pool; Polymarket uses a separate ranked bettor pool and outcome-convergence signals. Enable or disable chains per account in the config panel.

Alpha is currently in private beta. Reach out to our team for pricing details. Plans are based on signal volume and the number of chains you want coverage on.

By default, traders are ranked by Realized PnL — actual profit from closed positions. This surfaces wallets with a proven track record rather than paper gains from unrealized holdings.

You can also sort by Trader Score (a composite blending profitability, win rate, consistency, and activity), Win Rate, Volume, or Trade Count using the Rank By dropdown or rank_by API param.

Rankings are refreshed every 15 minutes. The leaderboard UI auto-refreshes every 30 seconds, so you'll always see near-real-time data. The "Last Updated" timestamp in the stats bar shows when the most recent ranking cycle completed.

Realized PnL (realized_pnl_usd) is profit from positions that have been closed (bought and sold). It's computed from our own position rollup and is the most reliable measure of actual trading skill because it only counts completed trades.

Net PnL (net_pnl_usd) includes both realized and unrealized gains/losses. It can be higher if a trader is sitting on unrealized profit, but it's also more volatile since open positions can reverse.

Total PnL (total_pnl) in signal payloads currently uses realized PnL. This is the most conservative measure and avoids showing inflated numbers from unrealized gains.

The Trader Score uses realized PnL as the primary profitability signal. Notification payloads include all PnL fields (realized_pnl_usd, net_pnl_usd, total_pnl) so you can choose which to display.

Win Rate shows the percentage of closed positions that were profitable. A wallet showing 65% (13/20) means 13 out of 20 closed positions made money.

Wallets with fewer than 3 closed positions show a dimmed win rate with sample size (e.g., "100% (1/1)") to indicate the number is not yet statistically meaningful. Wallets with zero closed positions show "N/A".

Realized PnL only counts positions that were opened and closed within the data window. A trader who bought a token last month and is still holding it won't show that profit as realized yet.

As the system matures and accumulates more historical data, realized PnL values will grow to reflect each trader's full track record.

MEV/arb bots are filtered by default. These bots close every position perfectly, resulting in exactly zero net PnL. The hide_bots parameter (default: true) removes these wallets from the leaderboard.

You can set hide_bots=false to see the full unfiltered wallet pool. On Base, this typically reveals ~90 additional bot wallets that would otherwise dominate the rankings.

Each wallet has a data_confidence badge reflecting how much evidence backs their stats:

• High (green) — 20+ closed positions. Strong statistical confidence in win rate and PnL.
• Medium (yellow) — 10–19 closed positions. Reasonable sample size but could shift.
• Low (gray) — Fewer than 10 closed positions. Stats are directionally useful but may change significantly.

This helps you decide how much weight to put on a wallet's metrics. A 90% win rate on 3 trades is less meaningful than a 65% win rate on 50 trades.

Each notification card shows a quality badge (High/Medium/Low) next to the signal type. This is computed from the traders in the signal:

• Trader count — more traders = stronger signal
• Realized PnL — traders with >$100 realized profit add credibility
• Closed positions — traders with 5+ closed positions have a real track record
• Win rate — traders with >40% win rate on 3+ positions demonstrate skill

A signal with 5 proven traders scoring High is more actionable than a 2-trader Low signal. Use these badges to prioritize which signals to surface prominently.

Each blockchain ecosystem has different trading patterns. Solana has lower minimum thresholds because it has a higher volume of smaller trades (meme tokens, pump.fun activity) and fewer closed positions per wallet on average. Base and Ethereum traders tend to have larger positions and more traditional DeFi patterns.

Polymarket uses a separate ranked wallet pool and leaderboard defaults tuned for prediction markets (e.g., lower min_tokens and min_closed on the public leaderboard API than on DEX chains).

These defaults are tuned per chain to surface the best traders in each ecosystem.

Alpha generates DEX and Polymarket signal types:

• Convergence P0 (Critical, DEX) — Multiple top-ranked traders buying the same token within the convergence window. Classified as P0 when five or more distinct qualifying wallets (top 200, after per-trade size and quality filters) have bought that token. You must also meet your convergence_min_wallets setting (default 3).
• Convergence P1 (Notable, DEX) — Same pattern with fewer than five wallets but at least convergence_min_wallets (default 3). Set convergence_min_wallets to 2 if you want the earliest possible P1 alerts.
• Whale Move (DEX only) — A single high-ranked trader (defaults: top 50, large buy threshold configurable) on Base, Ethereum, or Solana. Not emitted for Polymarket in the current pipeline.
• Sell Signal (DEX only) — Multiple top traders selling the same token. Polymarket v1 focuses on buy-side outcome convergence only.
• Polymarket convergence P0 — Same convergence idea on prediction markets: five or more ranked bettors on the same outcome (clob_token_id) within the window. Payloads include a market object (question, outcome, slug) and a cta for Polymarket when enrichment data is available.
• Polymarket convergence P1 — Same as P0 but below five wallets while still meeting convergence_min_wallets (default 3), or 2 if you lower that setting.

Priority levels indicate signal strength and recommended treatment:

• P0 (pink) — Highest conviction. Rare signals worth surfacing prominently, e.g., push notifications or banner alerts. Typically 1–3 per day.
• P1 (purple) — Strong signal. Good for in-app feeds, notification center items, or email digests.
• P2 (yellow) — Informational. Sell signals and lower-confidence alerts. Useful for portfolio monitoring or risk dashboards.

Use the Priority Filter in the config panel to only receive signals at or above your desired level.

Signals are generated in near real-time as activity is indexed — DEX swaps on Base, Ethereum, and Solana, and Polymarket fills on Polygon. From the time a qualifying trade is ingested to the signal being available via the API is typically on the order of tens of seconds, depending on stream batching and load.

If you use webhooks, signals are delivered as they're generated. If you poll the API, you'll see new signals on your next poll cycle.

A few things to check:

• Daily budget exhausted — if your daily notification budget is reached, no more signals are delivered until the next UTC day. Check or raise your daily budget in the config panel.
• Filters too strict — high quality gates (e.g., min trader score > 0.3) or token filters can suppress signals. Try relaxing these to see if signals appear.
• Cooldown active — the same DEX token or Polymarket outcome (token/CLOB key) won't trigger a duplicate signal within the cooldown window. This is by design to reduce noise.
• Low market activity — during quiet trading periods (weekends, holidays), fewer signals are naturally generated.

DEX: Stablecoins (USDC, USDT, DAI) and wrapped native tokens (WETH, Wrapped SOL) are excluded from signal logic. Every trader interacts with these routinely, so they'd generate constant noise without actionable signal.

Polymarket: Additional outcome/CLOB ids can be excluded via operator configuration when needed.

We also filter out trades above a size cap to exclude protocol-level or bot-driven activity that doesn't represent genuine trading conviction.

The Min Trade Size (min_trade_size_usd) filter sets the minimum USD value of an individual trade for it to count toward a signal. The default is $50.

For example, if three wallets buy a token but two of them only spent $5 each, those $5 trades are excluded. Only trades above your threshold count toward the convergence wallet count. This prevents dust trades and test transactions from inflating signal quality.

There is also a global floor of $10 applied system-wide — trades below $10 are never counted regardless of your setting.

DEX signals include a traders[] array (merged rows: wallet stats plus nested trade). Polymarket signals use user_trades[] instead — each element is { trader, trade } with the same fields split across those two objects:

• Ranking — leaderboard_rank, trader_score
• PnL — realized_pnl_usd (closed positions only), net_pnl_usd (including unrealized), total_pnl (best available)
• Win rate — win_rate, true_win_rate (from position rollup), winning_positions / closed_positions
• Activity — trade_count, avg_trade_size_usd, total_buy_volume_usd
• Trade details — nested trade object with size_usd, transaction_hash, traded_at, and on DEX signals typically token_bought / token_sold (and amounts) for the swap pair
• Polymarket — top-level token.address is the outcome CLOB id; market carries question, outcome_label, slug, item_id when Dynamo enrichment succeeds; cta.action is polymarket for deep links

On DEX signals, the trade receipt links to the on-chain swap (e.g., WETH → TOSHI). On Polymarket, use market plus Polygon (transaction_hash) for context and the cta for “open on Polymarket” flows.

Each signal includes a why.reasons[] array that explains what makes the signal notable. These are auto-generated context amplifiers:

• Trader credibility — combined PnL and win rate of the triggering traders.
• Early momentum — price or outcome pricing has moved since the first smart-money entry (DEX token or Polymarket leg).
• Conviction — large total dollar inflow from top traders.
• Freshness — how recently the last trade happened.

Surface these reasons in your UI to help users understand why a signal matters.

Pass wallet_id as a query parameter to GET /notifications or GET /signals to get personalized results. The API cross-references each signal against the wallet's on-chain positions and adds a personal block to every signal.

How it works:

• DEX signals (Base, Ethereum, Solana) — checks the wallet's token holdings in our position tracker. If the wallet holds the signal's token, the personal block shows position size, average entry price, unrealized PnL %, trade count, and a relevance label (validates_your_position or confirms_your_exit).
• Polymarket signals — checks the wallet's open outcome bets. If the wallet has a position on the signal's outcome, the personal block shows your bet direction (YES/NO), cost basis, remaining shares, realized PnL, unrealized PnL, and relevance (validates_your_bet).
• No position — signals where the wallet has no position simply show {"holds_token": false}.

Ordering: Signals where the wallet holds a position are automatically boosted to the top of results, sorted by position size descending. This means the most relevant signals appear first.

Chain routing: When you combine wallet_id with a chain filter, only the relevant backend is queried. For example, chain=base&wallet_id=0x... only checks DEX holdings (skips Polymarket), and chain=polymarket&wallet_id=0x... only checks Polymarket bets (skips DEX). Without a chain filter, both are checked.

Without wallet_id: The API returns the standard broadcast feed with no personalization overhead. The parameter is entirely optional and backward-compatible.

The personal block is added to each signal when wallet_id is provided. Its shape depends on the chain:

DEX (Base/Ethereum/Solana):

• holds_token — whether the wallet holds this token
• position_size_usd — total amount bought
• net_position_usd — bought minus sold
• avg_entry_price_usd — average cost basis (populated as new trades flow through the system)
• unrealized_pnl_pct — current price vs entry price
• direction — last trade direction (BUY/SELL)
• relevance — validates_your_position (you hold it, smart money agrees) or confirms_your_exit (you sold, smart money agrees)

Polymarket:

• holds_token — whether the wallet has a bet on this outcome
• your_bet — the outcome label (e.g., "YES", "Up")
• avg_cost_basis_usd — average price paid per share
• remaining_shares — shares still held
• realized_pnl_usd / unrealized_pnl_usd / unrealized_pnl_pct
• relevance — validates_your_bet or closed_position

The why.personal field also gets a human-readable summary string, e.g., "You hold $1,950 of $TOSHI — top traders just validated your position" or "You hold 142 shares of YES at $0.35 avg — top traders just validated your bet".

Use the Polymarket chain tab to load the prediction-market leaderboard (chain=polymarket). Open the gear icon to enable or disable the Polymarket chain and the PM convergence P0 / P1 signal types; convergence min wallets, window, min trade size, quality gates, and cooldown apply to PM as well as DEX (liquidity/holder filters are DEX-only in the detector).

PM notifications show a market line and View on Polymarket when the payload includes slug or item id. Click a wallet on the PM tab to see positions under Outcome (CLOB).

Step-by-step copy lives in the Polymarket controls section of the integration docs.

Click the gear icon in the leaderboard header. This opens your per-account config panel where you can adjust signal sensitivity, quality gates, token filters, priority routing, and delivery settings.

You can also manage configuration programmatically via the GET /config and PUT /config API endpoints.

Config changes are saved immediately and take effect within 5 minutes. The signal engine periodically reloads your configuration, so there's a short propagation delay.

Daily budget is a global cap on total notifications per day across all signal types. Per-type limits cap individual signal types independently (e.g., max 5 convergence P0 signals per day).

Both limits apply — whichever is reached first will stop that signal type for the day. Limits reset at midnight UTC.

It depends on your noise tolerance:

• Default — min trade size $50, min trigger win rate 20%, min trigger closed 3, min trader score 0.1. Provides base-level quality filtering while maintaining signal volume.
• Moderate — min trade size $100, min trader score 0.15, min trigger win rate 35%, min closed positions 5, min holding period 1h. Filters out small trades, weak track records, and pure scalpers.
• Strict — min trade size $500, min trader score 0.25, min trigger win rate 50%, min closed positions 10, min holding period 4h. Only substantial trades from well-established swing traders trigger signals.

Start with defaults and tighten gradually based on the signal quality you observe. The min trigger win rate and min trade size filters are the most impactful controls for improving signal quality. The holding period filter is useful if you specifically want swing trade signals rather than scalp alerts.

This filter lets you exclude signals from scalpers — wallets that buy and sell within minutes. It works by computing each wallet's average holding period across their closed positions (time between first trade and last trade on each token).

When set to e.g. 2 hours, only wallets whose average holding period is at least 2 hours can contribute to a signal. If filtering removes enough wallets, the signal may not fire at all (convergence needs at least your convergence_min_wallets, default 3).

Default: 0 (disabled). Good starting values:

• 0.5–1h — filters out pure scalpers (hold <5 min) while keeping day traders
• 2–4h — swing trade signals only
• 24h+ — position trader signals (may be too restrictive initially)

Note: This metric self-improves over time as the pipeline accumulates more closed position data.

Cooldown prevents the same DEX token or Polymarket outcome (shared key per token/CLOB) from generating another signal too soon. After any signal type is delivered for that key, all further signals for it are suppressed until the cooldown window elapses (default 2 hours). This stops high-activity assets from firing on every batch. Duplicate signal_ids are also blocked at write time. Lower cooldown (e.g. 0.5h) yields more frequent updates; higher (6h+) reduces notification fatigue.

Data comes from verifiable on-chain activity: DEX swaps on Base, Ethereum, and Solana, and Polymarket trades (Polygon) ingested into the same notification pipeline. No centralized exchange books and no self-reported portfolios for ranking — signals are derived from indexed chain activity.

The ranking system is designed to be resistant to gaming. It uses multiple signals — not just PnL — and applies smoothing to prevent single-trade flukes from dominating. Wallets need a sustained track record of profitable, closed positions to rank highly.

For DEX leaderboards we apply hard volume floors ($5K on Base/ETH, $1K on Solana), closed-position minimums (typically 5 for Base/Ethereum/Solana in API defaults), token-diversity thresholds, and bot filtering (e.g., MEV/arb wallets with zero net PnL excluded by default). Polymarket uses its own pool and default filters (e.g., lower closed-position bar on the demo leaderboard) so ranking stays meaningful for prediction markets.

No. Each customer has their own isolated configuration. Your signal thresholds, quality gates, chain preferences, and webhook URLs are private to your account.

A 404 response means the wallet address was not found in our index for the specified chain. This can happen if:

• The wallet has no indexed activity for that chain (no qualifying DEX swaps, or no Polymarket activity for chain=polymarket) within the current data window
• You're querying the wrong chain (e.g., a Solana address on chain=base)
• The wallet was filtered out by minimum thresholds (volume, trade count, etc.)

Double-check the wallet address and chain parameter. Use the leaderboard to find valid wallet addresses.

The API validates inputs and returns 400 with a descriptive error message. Common causes:

• Invalid chain — must be one of: base, ethereum, solana, polymarket
• Invalid rank_by — the error message lists all valid sort metrics
• Invalid limit — must be a positive integer (1–200)

This is usually a temporary network issue. Try refreshing the page. If it persists, check that your browser console doesn't show CORS or network errors. The leaderboard API requires an active internet connection.

Check that:

• Your webhook URL is correct and publicly accessible (not behind a VPN or firewall).
• Your endpoint returns a 2xx status code within 5 seconds. Timeouts or error responses will cause retries and eventual skipping.
• Your daily budget hasn't been exhausted — webhooks are subject to the same rate limits as the polling API.

Signal freshness depends on trading activity. During low-volume periods, there may simply be fewer top-wallet trades happening. Check the "Most recent trade was X min ago" context in the signal's why-reasons for freshness info.

If you recently changed config, allow up to 5 minutes for the new settings to propagate.

GET /trader?wallet={address}&chain={chain} returns a full trader profile including:

• Stats: realized PnL, win rate, trade count, volume, tokens traded, avg trade size
• Rank: leaderboard rank and trader_score (if in top 200)
• Positions: top 20 positions by volume — DEX tokens or Polymarket outcome legs (CLOB id), with buy/sell amounts, realized PnL, open/closed status, and timestamps

Use this to build trader profile cards. Click any wallet in the leaderboard to see a live demo.

GET /signals returns a paginated, filterable history of all signals sent to your account.

• Filters: chain, type (convergence_p0, convergence_p1, whale_move, sell_signal, pm_convergence_bet_p0, pm_convergence_bet_p1)
• Pagination: cursor-based — use next_cursor from the response as cursor in the next request
• Full payloads: each signal includes traders, trade details, why-reasons, token data, and CTA

Use this for signal history pages, analytics dashboards, or backtesting signal quality.

GET /signals/performance tracks how your signals performed over time. For each signal it uses DexScreener-style pricing where applicable to compute return since signal time.

• Per-signal: signal_price_usd, current_price_usd, return_pct
• Summary: total signals, avg return, median return, hit rate (% of signals with positive return), best and worst signal
• Controls: filter by chain, lookback window (1–30 days)

This path is DEX-oriented. Polymarket outcome (CLOB) signals may not map cleanly to DexScreener token pricing; treat performance stats for chain=polymarket as best-effort or exclude that chain in your analytics until you have a dedicated PM price source.

Use this to build a “signal track record” page for token signals; complement with separate logic for prediction-market outcomes if needed.