Find traders by handle
curl --request GET \
--url https://api.fomoscan.sh/v3/traders/lookup \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.fomoscan.sh/v3/traders/lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.fomoscan.sh/v3/traders/lookup"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"items": [
{
"kind": "trader",
"id": "tdr_01jbst8pvcfp79y0938nkrkayd",
"canonical": {
"display": {
"handle": "nightowl",
"name": "Night Owl",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp"
},
"platforms": [
"fomo",
"pump"
],
"mergedFrom": [
"tdr_01jbst8zcefy8b28t5cy4tqkff"
],
"firstSeenAt": "2025-03-14T16:20:05.412Z",
"walletAvailable": true
},
"sources": {
"fomo": {
"profile": {
"handle": "nightowl",
"name": "Night Owl",
"bio": "Solana memecoins, small size, long holds.",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp",
"xHandle": "nightowl_sol",
"verified": null,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"followGraph": {
"followers": 18450,
"following": 312,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"tradingStats": {
"swapCount": 1840,
"tradeCount": 977,
"volume": {
"value": "482113250000",
"decimals": 6,
"currency": "USD"
},
"avgHoldSeconds": 15120.5,
"observedAt": "2026-11-01T08:42:10.250Z"
}
},
"pump": {
"profile": {
"handle": "nightowl",
"name": null,
"bio": "Solana memecoins, small size, long holds.",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp",
"xHandle": "nightowl_sol",
"verified": false,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"followGraph": {
"followers": 2210,
"following": 312,
"observedAt": "2026-11-01T08:42:10.250Z"
}
}
}
}
],
"hasMore": false,
"nextCursor": null,
"match": "closest",
"suggestions": [
{
"trader": {
"kind": "trader",
"id": "tdr_01jbst8pvcfp79y0938nkrkayd",
"canonical": {
"display": {
"handle": "nightowl",
"name": "Night Owl",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp"
},
"platforms": [
"fomo",
"pump"
],
"mergedFrom": [
"tdr_01jbst8zcefy8b28t5cy4tqkff"
],
"firstSeenAt": "2025-03-14T16:20:05.412Z"
},
"sources": {
"fomo": {
"profile": {
"handle": "nightowl",
"name": "Night Owl",
"bio": "Solana memecoins, small size, long holds.",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp",
"xHandle": "nightowl_sol",
"verified": null,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"followGraph": {
"followers": 18450,
"following": 312,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"tradingStats": {
"swapCount": 1840,
"tradeCount": 977,
"volume": {
"value": "482113250000",
"decimals": 6,
"currency": "USD"
},
"avgHoldSeconds": 15120.5,
"observedAt": "2026-11-01T08:42:10.250Z"
}
},
"pump": {
"profile": {
"handle": "nightowl",
"name": null,
"bio": "Solana memecoins, small size, long holds.",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp",
"xHandle": "nightowl_sol",
"verified": false,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"followGraph": {
"followers": 2210,
"following": 312,
"observedAt": "2026-11-01T08:42:10.250Z"
}
}
}
},
"platform": "fomo",
"handle": "nightowl",
"name": "Night Owl"
}
]
}{
"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
Find traders by handle
The traders whose handle on a platform matches handle. Look a trader up once, then store our id and use it from then on.
- The match covers the handle each account holds now and every handle it held in the last 30 days, so a renamed account still answers.
- Order: traders whose current handle matches first, then traders who held it in the last 30 days. Inside each group, the newest profile
observedAtfirst, then trader id. - One handle can match several traders, for example two people with the same handle on two platforms. Check
canonical.platformsandsourcesbefore you pick one. canonical.walletAvailableistruewhenGET /v3/traders/{traderId}/walletslists at least one wallet for the trader andfalsewhen it lists none, so you know before you pay its reveal whether an address will come back. It never carries the address and takes no reveal.- No match answers 200 with an empty page. This operation never answers 404.
- The first page of a miss carries
suggestions: up to 5 traders whose handle or name looks likehandle(a typo, a repeated letter, spaces) or whose handle starts with it, closest first, with a small lift for followed traders. Each names the platform, handle and name of the account that matched. - With
match=closestthat miss answers with the first suggestion as the only item andmatch: "closest". Check it before you store the id: a close handle is a guess, not proof. - Paged with
cursorandlimit(default 50, maximum 200).
Price
The price depends on the answer.
| Answer | Credits | Reveals |
|---|---|---|
| At least one trader holds or held the handle. | 100 | 0 |
None does, and match=closest answers with the first suggestion. | 100 | 0 |
None does, and no trader answers: an empty page with suggestions. | 200 | 0 |
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 100 credits left gets 402
QUOTA_EXCEEDEDbefore any work.
GET
/
v3
/
traders
/
lookup
Find traders by handle
curl --request GET \
--url https://api.fomoscan.sh/v3/traders/lookup \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.fomoscan.sh/v3/traders/lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.fomoscan.sh/v3/traders/lookup"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"items": [
{
"kind": "trader",
"id": "tdr_01jbst8pvcfp79y0938nkrkayd",
"canonical": {
"display": {
"handle": "nightowl",
"name": "Night Owl",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp"
},
"platforms": [
"fomo",
"pump"
],
"mergedFrom": [
"tdr_01jbst8zcefy8b28t5cy4tqkff"
],
"firstSeenAt": "2025-03-14T16:20:05.412Z",
"walletAvailable": true
},
"sources": {
"fomo": {
"profile": {
"handle": "nightowl",
"name": "Night Owl",
"bio": "Solana memecoins, small size, long holds.",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp",
"xHandle": "nightowl_sol",
"verified": null,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"followGraph": {
"followers": 18450,
"following": 312,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"tradingStats": {
"swapCount": 1840,
"tradeCount": 977,
"volume": {
"value": "482113250000",
"decimals": 6,
"currency": "USD"
},
"avgHoldSeconds": 15120.5,
"observedAt": "2026-11-01T08:42:10.250Z"
}
},
"pump": {
"profile": {
"handle": "nightowl",
"name": null,
"bio": "Solana memecoins, small size, long holds.",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp",
"xHandle": "nightowl_sol",
"verified": false,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"followGraph": {
"followers": 2210,
"following": 312,
"observedAt": "2026-11-01T08:42:10.250Z"
}
}
}
}
],
"hasMore": false,
"nextCursor": null,
"match": "closest",
"suggestions": [
{
"trader": {
"kind": "trader",
"id": "tdr_01jbst8pvcfp79y0938nkrkayd",
"canonical": {
"display": {
"handle": "nightowl",
"name": "Night Owl",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp"
},
"platforms": [
"fomo",
"pump"
],
"mergedFrom": [
"tdr_01jbst8zcefy8b28t5cy4tqkff"
],
"firstSeenAt": "2025-03-14T16:20:05.412Z"
},
"sources": {
"fomo": {
"profile": {
"handle": "nightowl",
"name": "Night Owl",
"bio": "Solana memecoins, small size, long holds.",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp",
"xHandle": "nightowl_sol",
"verified": null,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"followGraph": {
"followers": 18450,
"following": 312,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"tradingStats": {
"swapCount": 1840,
"tradeCount": 977,
"volume": {
"value": "482113250000",
"decimals": 6,
"currency": "USD"
},
"avgHoldSeconds": 15120.5,
"observedAt": "2026-11-01T08:42:10.250Z"
}
},
"pump": {
"profile": {
"handle": "nightowl",
"name": null,
"bio": "Solana memecoins, small size, long holds.",
"avatarUrl": "https://img.example.com/a/9b1f0c7e3d2a4b5c8e6f1a2b3c4d5e6f.webp",
"xHandle": "nightowl_sol",
"verified": false,
"observedAt": "2026-11-01T08:42:10.250Z"
},
"followGraph": {
"followers": 2210,
"following": 312,
"observedAt": "2026-11-01T08:42:10.250Z"
}
}
}
},
"platform": "fomo",
"handle": "nightowl",
"name": "Night Owl"
}
]
}{
"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.
Query Parameters
The handle to find, 1 to 64 characters. A leading @ is dropped, and letter case does not count.
Required string length:
1 - 65Only accounts on this platform, for the matches and the suggestions. Leave it out for every platform.
Available options:
fomo, pump, hyperliquid, markets, polymarket, legend, risex exact (the default): only traders that hold the handle or held it in the last 30 days. closest: when none does, answer with the first of suggestions instead of an empty page.
Available options:
exact, closest The nextCursor of the previous page, sent back as it came. Leave it out for the first page. A cursor belongs to the query that produced it: sent with other parameters it answers 400 INVALID_ARGUMENT.
Required string length:
3 - 1024Rows per page, 1 to 200. 50 when left out.
Required range:
1 <= x <= 200Response
OK
The traders that hold or held the handle, one page of them, with suggestions when none does.
The rows of this page, in the order the operation states.
Show child attributes
Show child attributes
true when another page follows this one.
The cursor of the next page (c_…), or null on the last page. Treat it as opaque: send it back as cursor, never parse or build it.
exact: the items hold the handle or held it in the last 30 days, or the page is empty. closest: no trader does, and the only item is the first of suggestions.
Available options:
exact, closest Present on a first page where no trader holds or held the handle: up to 5 traders whose handle or name is close to it, or whose handle starts with it, best first. Empty when the handle has fewer than 3 characters once spaces are dropped, or nothing is close.
Maximum array length:
5Show child attributes
Show child attributes