Skip to content
PredictefyPredictefy Docs
Get an API key

Alert on scored trades

Copy page

The smart-money feed is a scored-trade feed. It ranks trades that have already happened; it is informational and is not a recommendation, and treating a score as a signal to copy is a misreading of what it measures.

Trader Intelligence is the reference. This page builds a watcher.

Poll

Section titled “Poll”
Terminal window
curl -s "$PREDICTEFY_API_URL/v1/traders/smart-money?minScore=80&window=day&limit=100" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Every parameter is optional:

Parameter Values
venue One Trader Intelligence venue
minScore 0–100
market Exact market id
wallet Exact venue-scoped wallet
category bot, whale, smart, fresh, fish
window day, week, month, all (default all)
limit 1–100
cursor Opaque (ts, tradeId) keyset cursor

Rows add tradeScore, tradeFactors, scoreVersion, walletScoreAtTrade and categoryAtTrade to the normal trader-trade fields. Under score version t1 the factors are walletScore, size, entry and timing.

Watch without re-alerting

Section titled “Watch without re-alerting”

The cursor is a keyset over (ts, tradeId), so it is stable for a watcher: hold the newest cursor and page forward from it.

let cursor = null;


async function poll() {
  const url = new URL('/v1/traders/smart-money', BASE);
  url.searchParams.set('minScore', '80');
  url.searchParams.set('window', 'day');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);


  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.PREDICTEFY_API_KEY}` },
  });
  const body = await res.json();


  if (!body.success) {
    // TRADERS_UNSUPPORTED is a 400 and is not retryable — it is an answer.
    if (!body.error.retryable) throw new Error(`${body.error.code}: ${body.error.message}`);
    return;
  }


  for (const trade of body.data) alert(trade);
  cursor = body.page?.hasMore ? body.page.nextCursor : cursor;
}

Keep the cursor across polls rather than re-querying a time window. Two identical window-based polls overlap, and a watcher that alerts on the overlap sends the same trade twice.

Reading the score honestly

Section titled “Reading the score honestly”
  • window=all means all collected feed data. No historical backfill is included — the feed starts when collection started, so an empty early window is a collection boundary, not a quiet market.
  • walletScoreAtTrade and categoryAtTrade are the values as they were at the time of the trade, not the wallet’s current standing. Rendering a current score next to a historical trade attributes information to the trader that they did not have.
  • scoreVersion matters. Factors differ between versions, so scores are not comparable across them. Store the version with anything you persist.
  • A listed capability is not a claim that rows exist. Scored-trade coverage requires activity from that venue; a supported venue can legitimately return nothing.

The errors are answers

Section titled “The errors are answers”
Response Meaning
400 TRADERS_UNSUPPORTED That venue does not support that verb. Not retryable.
404 TRADER_NOT_FOUND Unknown wallet.
404 on any /v1/traders/* Trader Intelligence is unavailable.

TRADERS_UNSUPPORTED names the verb and the venue — for example, market holders being unsupported on a given venue. Do not fall back to another venue’s data to fill the gap; the honest render is that this venue does not expose it. See Capability-honest data.

Through an agent instead

Section titled “Through an agent instead”

The same surface is available as MCP tools — get_smart_money, get_market_traders, get_market_holders, get_leaderboard, get_wallet_profile — each capped at 100 rows, with get_wallet_profile under a 50 KB response budget. See MCP server.

Section titled “Related”