Read the PnL of up to 100 traders
curl --request POST \
--url https://api.fomoscan.sh/v3/traders/pnl \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"traderIds": [
"<string>"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({traderIds: ['<string>']})
};
fetch('https://api.fomoscan.sh/v3/traders/pnl', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.fomoscan.sh/v3/traders/pnl"
payload = { "traderIds": ["<string>"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"items": [
{
"trader": "tdr_01jbst8pvcfp79y0938nkrkayd",
"found": true,
"pnl": {
"trader": "tdr_01jbst8pvcfp79y0938nkrkayd",
"status": "ready",
"retryAfterSeconds": null,
"wallets": [
"wal_svm_9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
"wal_evm_0x52908400098527886e0f7030069857d2e4169ee7"
],
"windows": {
"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
}
},
"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
}
},
{
"trader": "tdr_01jbst8v3xft7t04hmasw9nf6y",
"found": true,
"pnl": {
"trader": "tdr_01jbst8v3xft7t04hmasw9nf6y",
"status": "pending",
"retryAfterSeconds": 30,
"wallets": [],
"windows": {
"7d": {
"origin": "provider",
"status": "pending",
"realized": null,
"unrealized": null,
"total": null,
"unpricedProceeds": null,
"netFlow": null,
"volume": null,
"buyVolume": null,
"sellVolume": null,
"returnPct": null,
"tradeCount": null,
"buys": null,
"sells": null,
"tokensTraded": null,
"winningTokens": null,
"rank": null,
"asOf": null,
"approximate": false
}
},
"unrealized": null,
"asOf": null,
"nextUpdateAt": null,
"stale": false
}
},
{
"trader": "tdr_01jbsta48he8h86ct48hanask6",
"found": false,
"pnl": null
}
]
}{
"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 the PnL of up to 100 traders
The PnL of up to 100 traders in one call. items follows the order of traderIds, one item per distinct id.
- Each item holds the id as you sent it,
found, and the documentGET /v3/traders/{traderId}/pnlreturns, ornullwhen no trader has the id. - Two ids that resolve to one trader after merges are two items.
- Every rule of
GET /v3/traders/{traderId}/pnlapplies per item:status,retryAfterSeconds,wallets,window. - An unknown id is an item with
found: false. This operation never answers 404.
Price
Per item: 30,000 credits and one reveal for each item whose status is ready, 200 credits for every other item. Before any work the whole batch is refused when the balance holds less than 200 credits per item (402 QUOTA_EXCEEDED), or the key has fewer reveals left this month than items, whatever their status turns out to be.
| Answer | Credits | Reveals |
|---|---|---|
Each item whose status is ready. | 30,000 | 1 |
Each item with another status, or not found. | 200 | 0 |
100 ids, 60 of them ready. | 1,808,000 | 60 |
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
- 120 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_EXCEEDEDbefore 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.
POST
/
v3
/
traders
/
pnl
Read the PnL of up to 100 traders
curl --request POST \
--url https://api.fomoscan.sh/v3/traders/pnl \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"traderIds": [
"<string>"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({traderIds: ['<string>']})
};
fetch('https://api.fomoscan.sh/v3/traders/pnl', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.fomoscan.sh/v3/traders/pnl"
payload = { "traderIds": ["<string>"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"items": [
{
"trader": "tdr_01jbst8pvcfp79y0938nkrkayd",
"found": true,
"pnl": {
"trader": "tdr_01jbst8pvcfp79y0938nkrkayd",
"status": "ready",
"retryAfterSeconds": null,
"wallets": [
"wal_svm_9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
"wal_evm_0x52908400098527886e0f7030069857d2e4169ee7"
],
"windows": {
"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
}
},
"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
}
},
{
"trader": "tdr_01jbst8v3xft7t04hmasw9nf6y",
"found": true,
"pnl": {
"trader": "tdr_01jbst8v3xft7t04hmasw9nf6y",
"status": "pending",
"retryAfterSeconds": 30,
"wallets": [],
"windows": {
"7d": {
"origin": "provider",
"status": "pending",
"realized": null,
"unrealized": null,
"total": null,
"unpricedProceeds": null,
"netFlow": null,
"volume": null,
"buyVolume": null,
"sellVolume": null,
"returnPct": null,
"tradeCount": null,
"buys": null,
"sells": null,
"tokensTraded": null,
"winningTokens": null,
"rank": null,
"asOf": null,
"approximate": false
}
},
"unrealized": null,
"asOf": null,
"nextUpdateAt": null,
"stale": false
}
},
{
"trader": "tdr_01jbsta48he8h86ct48hanask6",
"found": false,
"pnl": null
}
]
}{
"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
bearerAuthapiKeyHeader
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
1 to 100 trader ids. A repeated id counts once.
Required array length:
1 - 100 elementsPattern:
^tdr_[0-7][0-9a-hjkmnp-tv-z]{25}$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
OK
The PnL of several traders, one item per id.
One item per distinct id you sent, in your order.
Show child attributes
Show child attributes