Read a trader's PnL across whole wallets

curl --request GET \
  --url https://api.fomoscan.sh/v3/traders/{traderId}/pnl \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fomoscan.sh/v3/traders/{traderId}/pnl', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "trader": "tdr_01jbst8pvcfp79y0938nkrkayd",
  "status": "ready",
  "retryAfterSeconds": null,
  "wallets": [
    "wal_svm_9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "wal_evm_0x52908400098527886e0f7030069857d2e4169ee7"
  ],
  "windows": {
    "24h": {
      "origin": "provider",
      "status": "ready",
      "realized": {
        "value": "1250500000",
        "decimals": 6,
        "currency": "USD"
      },
      "unrealized": {
        "value": "412150000",
        "decimals": 6,
        "currency": "USD"
      },
      "total": {
        "value": "1662650000",
        "decimals": 6,
        "currency": "USD"
      },
      "unpricedProceeds": null,
      "netFlow": null,
      "volume": {
        "value": "18050500000",
        "decimals": 6,
        "currency": "USD"
      },
      "buyVolume": {
        "value": "8400000000",
        "decimals": 6,
        "currency": "USD"
      },
      "sellVolume": {
        "value": "9650500000",
        "decimals": 6,
        "currency": "USD"
      },
      "returnPct": 14.88690476,
      "tradeCount": 21,
      "buys": 12,
      "sells": 9,
      "tokensTraded": 6,
      "winningTokens": 4,
      "rank": null,
      "asOf": "2026-11-01T08:55:00.000Z",
      "approximate": false
    },
    "7d": {
      "origin": "provider",
      "status": "ready",
      "realized": {
        "value": "-312750000",
        "decimals": 6,
        "currency": "USD"
      },
      "unrealized": {
        "value": "1506900000",
        "decimals": 6,
        "currency": "USD"
      },
      "total": {
        "value": "1194150000",
        "decimals": 6,
        "currency": "USD"
      },
      "unpricedProceeds": null,
      "netFlow": null,
      "volume": {
        "value": "80160000000",
        "decimals": 6,
        "currency": "USD"
      },
      "buyVolume": {
        "value": "41200000000",
        "decimals": 6,
        "currency": "USD"
      },
      "sellVolume": {
        "value": "38960000000",
        "decimals": 6,
        "currency": "USD"
      },
      "returnPct": -0.79635371,
      "tradeCount": 105,
      "buys": 58,
      "sells": 47,
      "tokensTraded": 19,
      "winningTokens": 8,
      "rank": null,
      "asOf": "2026-11-01T08:55:00.000Z",
      "approximate": false
    },
    "30d": {
      "origin": "provider",
      "status": "ready",
      "realized": {
        "value": "9884200000",
        "decimals": 6,
        "currency": "USD"
      },
      "unrealized": {
        "value": "2101300000",
        "decimals": 6,
        "currency": "USD"
      },
      "total": {
        "value": "11985500000",
        "decimals": 6,
        "currency": "USD"
      },
      "unpricedProceeds": null,
      "netFlow": null,
      "volume": {
        "value": "312410000000",
        "decimals": 6,
        "currency": "USD"
      },
      "buyVolume": {
        "value": "152300000000",
        "decimals": 6,
        "currency": "USD"
      },
      "sellVolume": {
        "value": "160110000000",
        "decimals": 6,
        "currency": "USD"
      },
      "returnPct": 6.57956223,
      "tradeCount": 412,
      "buys": 214,
      "sells": 198,
      "tokensTraded": 61,
      "winningTokens": 27,
      "rank": null,
      "asOf": "2026-11-01T08:55:00.000Z",
      "approximate": false
    },
    "all": {
      "origin": "computed",
      "status": "ready",
      "realized": null,
      "unrealized": null,
      "total": null,
      "unpricedProceeds": null,
      "netFlow": {
        "value": "48210330000",
        "decimals": 6,
        "currency": "USD"
      },
      "volume": {
        "value": "1290446800000",
        "decimals": 6,
        "currency": "USD"
      },
      "buyVolume": null,
      "sellVolume": null,
      "returnPct": 7.76186035,
      "tradeCount": 3105,
      "buys": null,
      "sells": null,
      "tokensTraded": null,
      "winningTokens": null,
      "rank": {
        "position": 37,
        "of": 18204,
        "ranking": "traders_net_flow_all"
      },
      "asOf": "2026-11-01T08:40:00.000Z",
      "approximate": false
    }
  },
  "unrealized": {
    "origin": "provider",
    "value": {
      "value": "2318400000",
      "decimals": 6,
      "currency": "USD"
    },
    "holdingsValue": {
      "value": "11904650000",
      "decimals": 6,
      "currency": "USD"
    },
    "positions": 9,
    "excludedPositions": 2,
    "asOf": "2026-11-01T08:55:00.000Z"
  },
  "asOf": "2026-11-01T08:55:00.000Z",
  "nextUpdateAt": "2026-11-01T11:55:00.000Z",
  "stale": false
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

Traders

Read a trader's PnL across whole wallets

A trader’s profit and loss over the wallets we verified for them. 24h, 7d, 30d and unrealized come from our data provider and cover the whole wallets on every venue; all is ours, computed from the ranking of net flow.

Read status first:

`status`	Meaning	What to do
`ready`	The figures are present, and `wallets` lists the wallets they cover.	Use them. When `stale` is `true`, a call after `nextUpdateAt` can carry newer figures.
`pending`	No reading exists yet, and a read is running. Every provider value is `null`.	Call again after `retryAfterSeconds` (30).
`failed`	The last read of our data provider failed.	Call again after `retryAfterSeconds`.
`no_wallet`	The trader holds no wallet that passes the wallet rule below.	Nothing to wait for.
`unavailable`	Provider reads are switched off, or this month’s provider budget is spent and we hold no reading of the last 7 days.	Call again next month or ask us; `all` can still hold figures.

Wallet rule: verified links only (tiers proven, account, partial), one wallet per address family, and none that another trader also holds. Per family the strongest tier wins, then the newest lastVerifiedAt.
wallets is empty for every status but ready.
When no fresh reading exists, the call asks our data provider for one and waits for it. A read that misses the wait finishes and serves your next call.
A call that cannot read a figure again serves the stored one, at most 7 days old, with stale true. nextUpdateAt is when the first provider figure falls due to be read again.
window keeps one key in windows. status stays the same.
Every window carries realized, unrealized and total (realized plus unrealized). On 24h, 7d and 30d, unrealized covers the open positions last traded inside the window, on UTC calendar days.
When our data provider fails to read a window, the call counts it from per-token totals of the positions and marks it approximate; the next reading replaces it. When that fails too, the window waits an hour before it is read again.
all takes netFlow, volume, tradeCount, returnPct and rank from the ranking traders_net_flow_all; its realized, unrealized and total are null. It is null when that ranking does not list the trader.

Price

The price depends on the answer. The Reveals column says when a reveal is taken.

Answer	Credits	Reveals
`status` is `ready`.	30,000	1
Any other `status`, or 404.	200	0

Reveals count against a key with a monthly reveal cap. When the answer needs more reveals than the key has left, the call is refused before any credit is taken: 402 REVEAL_LIMIT_REACHED, or 403 PERMISSION_DENIED for a key on a free plan without reveals.

Limits

2,000 requests per minute from one address on this operation, beside the per-minute limit of the key.
A key with less than 200 credits left gets 402 QUOTA_EXCEEDED before any work.
A read of our data provider runs up to 8 seconds inside the call. Past that the call answers with what we hold, and the read finishes for your next call.

GET

traders

{traderId}

pnl

Read a trader's PnL across whole wallets

curl --request GET \
  --url https://api.fomoscan.sh/v3/traders/{traderId}/pnl \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fomoscan.sh/v3/traders/{traderId}/pnl', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "trader": "tdr_01jbst8pvcfp79y0938nkrkayd",
  "status": "ready",
  "retryAfterSeconds": null,
  "wallets": [
    "wal_svm_9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "wal_evm_0x52908400098527886e0f7030069857d2e4169ee7"
  ],
  "windows": {
    "24h": {
      "origin": "provider",
      "status": "ready",
      "realized": {
        "value": "1250500000",
        "decimals": 6,
        "currency": "USD"
      },
      "unrealized": {
        "value": "412150000",
        "decimals": 6,
        "currency": "USD"
      },
      "total": {
        "value": "1662650000",
        "decimals": 6,
        "currency": "USD"
      },
      "unpricedProceeds": null,
      "netFlow": null,
      "volume": {
        "value": "18050500000",
        "decimals": 6,
        "currency": "USD"
      },
      "buyVolume": {
        "value": "8400000000",
        "decimals": 6,
        "currency": "USD"
      },
      "sellVolume": {
        "value": "9650500000",
        "decimals": 6,
        "currency": "USD"
      },
      "returnPct": 14.88690476,
      "tradeCount": 21,
      "buys": 12,
      "sells": 9,
      "tokensTraded": 6,
      "winningTokens": 4,
      "rank": null,
      "asOf": "2026-11-01T08:55:00.000Z",
      "approximate": false
    },
    "7d": {
      "origin": "provider",
      "status": "ready",
      "realized": {
        "value": "-312750000",
        "decimals": 6,
        "currency": "USD"
      },
      "unrealized": {
        "value": "1506900000",
        "decimals": 6,
        "currency": "USD"
      },
      "total": {
        "value": "1194150000",
        "decimals": 6,
        "currency": "USD"
      },
      "unpricedProceeds": null,
      "netFlow": null,
      "volume": {
        "value": "80160000000",
        "decimals": 6,
        "currency": "USD"
      },
      "buyVolume": {
        "value": "41200000000",
        "decimals": 6,
        "currency": "USD"
      },
      "sellVolume": {
        "value": "38960000000",
        "decimals": 6,
        "currency": "USD"
      },
      "returnPct": -0.79635371,
      "tradeCount": 105,
      "buys": 58,
      "sells": 47,
      "tokensTraded": 19,
      "winningTokens": 8,
      "rank": null,
      "asOf": "2026-11-01T08:55:00.000Z",
      "approximate": false
    },
    "30d": {
      "origin": "provider",
      "status": "ready",
      "realized": {
        "value": "9884200000",
        "decimals": 6,
        "currency": "USD"
      },
      "unrealized": {
        "value": "2101300000",
        "decimals": 6,
        "currency": "USD"
      },
      "total": {
        "value": "11985500000",
        "decimals": 6,
        "currency": "USD"
      },
      "unpricedProceeds": null,
      "netFlow": null,
      "volume": {
        "value": "312410000000",
        "decimals": 6,
        "currency": "USD"
      },
      "buyVolume": {
        "value": "152300000000",
        "decimals": 6,
        "currency": "USD"
      },
      "sellVolume": {
        "value": "160110000000",
        "decimals": 6,
        "currency": "USD"
      },
      "returnPct": 6.57956223,
      "tradeCount": 412,
      "buys": 214,
      "sells": 198,
      "tokensTraded": 61,
      "winningTokens": 27,
      "rank": null,
      "asOf": "2026-11-01T08:55:00.000Z",
      "approximate": false
    },
    "all": {
      "origin": "computed",
      "status": "ready",
      "realized": null,
      "unrealized": null,
      "total": null,
      "unpricedProceeds": null,
      "netFlow": {
        "value": "48210330000",
        "decimals": 6,
        "currency": "USD"
      },
      "volume": {
        "value": "1290446800000",
        "decimals": 6,
        "currency": "USD"
      },
      "buyVolume": null,
      "sellVolume": null,
      "returnPct": 7.76186035,
      "tradeCount": 3105,
      "buys": null,
      "sells": null,
      "tokensTraded": null,
      "winningTokens": null,
      "rank": {
        "position": 37,
        "of": 18204,
        "ranking": "traders_net_flow_all"
      },
      "asOf": "2026-11-01T08:40:00.000Z",
      "approximate": false
    }
  },
  "unrealized": {
    "origin": "provider",
    "value": {
      "value": "2318400000",
      "decimals": 6,
      "currency": "USD"
    },
    "holdingsValue": {
      "value": "11904650000",
      "decimals": 6,
      "currency": "USD"
    },
    "positions": 9,
    "excludedPositions": 2,
    "asOf": "2026-11-01T08:55:00.000Z"
  },
  "asOf": "2026-11-01T08:55:00.000Z",
  "nextUpdateAt": "2026-11-01T11:55:00.000Z",
  "stale": false
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_ARGUMENT",
    "message": "<string>",
    "requestId": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

traderId

string

required

A trader id: tdr_ and 26 characters. GET /v3/traders/lookup finds it by handle.

Pattern: ^tdr_[0-7][0-9a-hjkmnp-tv-z]{25}$

Query Parameters

window

enum<string>

One window: 24h, 7d, 30d or all. Leave it out for all four. status stays the same either way.

Available options:

24h,

7d,

30d,

all

Response

A trader's profit and loss over the wallets we verified for them, per window.

trader

string

required

The tdr_ id of the trader, after merges.

status

enum<string>

required

ready: figures present. Only this status takes a reveal. pending: no reading yet; call again after retryAfterSeconds. failed: the last read failed; call again after retryAfterSeconds. no_wallet: the trader holds no verified wallet (tier proven, account or partial) that no other trader also holds. unavailable: provider reads are off or this month's provider budget is spent.

Available options:

ready,

pending,

failed,

no_wallet,

unavailable

retryAfterSeconds

integer | null

required

Seconds to wait before you ask again while status is pending or failed; else null.

Required range: -9007199254740991 <= x <= 9007199254740991

wallets

string[]

required

The wal_ ids the figures cover, at most one per address family. Empty unless status is ready.

windows

object

required

One entry per window. With window set, only that key is present.

Show child attributes

unrealized

object | null

required

Unrealized profit or loss over the wallets, from our data provider. null without a reading.

Show child attributes

asOf

string<date-time> | null

required

The oldest asOf among the ready windows, else the ranking time of all, else null.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3}(?:Z))$

nextUpdateAt

string<date-time> | null

required

When the first figure from our data provider falls due to be read again: its asOf plus its refresh interval. The first call after that time reads it again. Earlier than now when stale is true. null unless status is ready.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3}(?:Z))$

stale

boolean

required

true when at least one figure from our data provider is past its refresh interval and this call could not read it again: the read failed, did not finish within the 8 second wait, or this month's provider budget is spent. A later call can carry newer figures. The computed all window does not count. false unless status is ready.

Overview

Endpoints

Read a trader's PnL across whole wallets

Price

Limits

Authorizations

Path Parameters

Query Parameters

Response