> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# Trader Intelligence API

> Live wallet-attributed public activity, venue-scoped profiles, versioned scores, and the scored-trade feed.

:::note[Live, capability-qualified]
Trader Intelligence is publicly available. Scored-trade coverage includes Polymarket,
Limitless, Myriad, Hyperliquid, SX Bet, Predict.fun, Pascal, XO, PRED, and Rain.
Opinion is lookup-only. The capability table below is the contract: unsupported venue
concepts return `TRADERS_UNSUPPORTED` instead of synthetic data.
:::

Trader Intelligence organizes public venue-published/on-chain activity by wallet
and venue. Scores are versioned informational signals, not financial advice, and
nothing on this page is a recommendation. Wallets remain venue-scoped; Predictefy
does not claim that addresses on different venues belong to the same person.

All endpoints are authenticated, metered `GET` requests. List endpoints default
to `limit=20` and cap it at 100.

## Endpoints

### Market trader trades

`GET /v1/traders/{venue}/markets/{marketId}/trades`

| Parameter  | Required | Meaning                                       |
| ---------- | :------: | --------------------------------------------- |
| `venue`    |   yes    | One supported Trader Intelligence venue id.   |
| `marketId` |   yes    | Venue-native market id.                       |
| `limit`    |    no    | 1–100 rows.                                   |
| `cursor`   |    no    | Opaque venue/keyset cursor from `nextCursor`. |

Rows contain `venue`, `marketId`, `outcomeId`, `tradeId`, `ts`, `wallet`, optional
`displayName`, `side`, `price`, `amount`, and `usdSize`. Nullable fields stay
`null` when the venue payload cannot prove them.

### Market holders

`GET /v1/traders/{venue}/markets/{marketId}/holders`

Parameters: `venue`, `marketId`, and optional `limit`. Rows contain `wallet`,
optional `displayName`, `outcomeId`, `shares`, and nullable `usdValue`. Venues
without a public holder/outcome concept return `TRADERS_UNSUPPORTED`.

### Venue leaderboard

`GET /v1/traders/{venue}/leaderboard`

| Parameter | Required | Values                                            |
| --------- | :------: | ------------------------------------------------- |
| `by`      |    no    | `profit`, `volume`, or `score`; default `profit`. |
| `window`  |    no    | `day`, `week`, `month`, or `all`; default `all`.  |
| `limit`   |    no    | 1–100 rows.                                       |

Native profit/volume rows contain `venue`, `wallet`, optional `displayName`,
`rank`, `window`, nullable `profitUsd`, and nullable `volumeUsd`. `by=score`
uses Predictefy scores and instead includes `score`, `scoreVersion`, `factors`,
`category`, `stats`, `refreshedAt`, `refreshState`, `asOf`, and `provenance`.
Wallet `factors` contain the versioned `trackRecord`, `experience`, `scale`, and
`discipline` components when a `w1` score is available.

The exact score note is:

> Score ranking uses the current stored score; window is retained for API consistency.

### Cross-venue score leaderboard

`GET /v1/traders/leaderboard`

This endpoint supports `by=score` only, plus optional `window` and `limit`.
Profit and volume are venue-native and are never merged into a synthetic ranking.
Rows use the score-leaderboard shape above and remain venue-tagged.

The response carries these exact honesty notes:

> Wallets are venue-scoped; the cross-venue leaderboard interleaves venue-tagged entries without claiming same-person identity.

> Score ranking uses current stored scores; window is retained for API consistency.

### Wallet profile

`GET /v1/traders/{venue}/wallets/{addr}`

Profiles contain `venue`, `wallet`, optional `displayName`, `score`,
`scoreVersion`, `factors`, `category`, `stats`, `refreshedAt`, `refreshState`,
`asOf`, and `provenance`. `stats` contains `walletAgeDays`, `marketsTraded`,
`totalVolumeUsd`, `winRate`, `realizedPnlUsd`, `firstSeen`, `lastSeen`, and
`depositFirstAt`.

A live fill-in can return `score`, `scoreVersion`, `factors`, and `category` as
`null` until Predictefy scores that wallet. It says so in `note`; the API does
not invent a score from incomplete venue data.

### Wallet trades

`GET /v1/traders/{venue}/wallets/{addr}/trades`

Parameters: `venue`, `addr`, optional `limit`, and optional `cursor`. The list
uses the same wallet-attributed trade fields as the market tape. A venue without
keyless wallet history returns `TRADERS_UNSUPPORTED`.

### Smart-money feed

`GET /v1/traders/smart-money`

The route name is part of the API; the response is an informational scored-trade
feed, not a recommendation.

| Parameter  | Required | Meaning                                          |
| ---------- | :------: | ------------------------------------------------ |
| `venue`    |    no    | One Trader Intelligence venue.                   |
| `minScore` |    no    | Minimum trade score, 0–100.                      |
| `market`   |    no    | Exact market id.                                 |
| `wallet`   |    no    | Exact venue-scoped wallet.                       |
| `category` |    no    | `bot`, `whale`, `smart`, `fresh`, or `fish`.     |
| `window`   |    no    | `day`, `week`, `month`, or `all`; default `all`. |
| `limit`    |    no    | 1–100 rows.                                      |
| `cursor`   |    no    | Opaque `(ts, tradeId)` keyset cursor.            |

Rows add `tradeScore`, `tradeFactors`, `scoreVersion`, `walletScoreAtTrade`, and
`categoryAtTrade` to the normal trader-trade fields. Version `t1` trade factors
are `walletScore`, `size`, `entry`, and `timing`. The response carries these exact
honesty notes:

> window=all means all collected feed data; no historical backfill is included.

## Error honesty

An unknown venue or unsupported venue/verb returns HTTP 400:

```json
{
  "success": false,
  "error": {
    "code": "TRADERS_UNSUPPORTED",
    "message": "market holders are unsupported for hyperliquid",
    "retryable": false
  }
}
```

An unknown wallet returns `404 TRADER_NOT_FOUND`. If Trader Intelligence is
unavailable, `/v1/traders/*` returns 404.

## Venue capabilities

Hyperliquid market selection follows the active catalog and refreshes periodically as
that catalog changes. A listed capability is not a claim that every venue currently has
collected rows: scored-trade and smart-money coverage requires activity from that venue.

| Venue           | Trader trades | Holders | Leaderboard | Wallet profile | Scored-trade feed |
| --------------- | :-----------: | :-----: | :---------: | :------------: | :---------------: |
| `polymarket`    |      yes      |   yes   |     yes     |      yes       |        yes        |
| `limitless`     |      yes      |   yes   |     yes     |      yes       |        yes        |
| `myriad`        |      yes      |   yes   |     no      |      yes       |        yes        |
| `hyperliquid`   |      yes      |   no    |     yes     |      yes       |        yes        |
| `sxbet`         |      yes      |   no    |     no      |       no       |        yes        |
| `predictfun`    |      yes      |   no    |     yes     |      yes       |        yes        |
| `opinion`       |      no       |   no    |     no      |      yes       |        no         |
| `kalshi`        |      no       |   no    |     no      |       no       |        no         |
| `gemini`        |      no       |   no    |     no      |       no       |        no         |
| `smarkets`      |      no       |   no    |     no      |       no       |        no         |
| `polymarket_us` |      no       |   no    |     no      |       no       |        no         |

Opinion is a lookup-only venue (no public per-market tape,
so no scored-trade or smart-money coverage). The final four rows are a
venue property, not a gap.

Venue-specific limits matter:

- PredictFun ranks venue points only. `by`/sort has no venue effect, only `all`
  exists, and the board contains no profit or volume figures. Position pages do
  not prove lifetime totals, and match collateral is unknown, so `usdSize` is null.
- Limitless's board is all-time volume only, with no keyless wallet history.
- Myriad has no board. Sizes are token-denominated, so USD fields are null.
- Hyperliquid has no holders. Its tape is push-based, and profile totals cover
  only the recent fills window returned by the venue.
- SXBET is trades-only: `side` is null, and `usdSize` exists only for SX USDC.
- Opinion wallet lookups require a venue API key held server-side; the venue
  hides order ids for privacy. Wallet trades paginate with an opaque cursor.

## SDK examples

TypeScript uses venue subclients for venue lookups and root methods for merged
score/feed reads:

```ts
const tape = await client.polymarket.fetchTraderTrades(conditionId, { limit: 25 });
const holders = await client.limitless.fetchHolders(marketSlug, { limit: 10 });
const board = await client.hyperliquid.fetchLeaderboard({
  by: 'profit',
  window: 'week',
  limit: 20,
});
const profile = await client.polymarket.fetchWalletProfile(wallet);
const history = await client.sxbet.fetchWalletTrades(wallet, { limit: 25 });
const feed = await client.fetchSmartMoney({ venue: 'polymarket', minScore: 70, window: 'week' });
const top = await client.fetchTopTraders({ by: 'score', window: 'all', limit: 20 });
```

Python exposes the same surface in snake case:

```python
tape = client.polymarket.fetch_trader_trades(condition_id, {"limit": 25})
holders = client.limitless.fetch_holders(market_slug, {"limit": 10})
board = client.hyperliquid.fetch_leaderboard(
    {"by": "profit", "window": "week", "limit": 20}
)
profile = client.polymarket.fetch_wallet_profile(wallet)
history = client.sxbet.fetch_wallet_trades(wallet, {"limit": 25})
feed = client.fetch_smart_money(
    {"venue": "polymarket", "minScore": 70, "window": "week"}
)
top = client.fetch_top_traders({"by": "score", "window": "all", "limit": 20})
```