> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fomoscan.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Traders, wallets and PnL

> From a handle to a trader, their verified wallets and their profit.

![GET /v3/traders/\{traderId}/wallets: the fictional trader @tradername, on FOMO, pump.fun and Hyperliquid, owns an SVM wallet and an EVM wallet, both at tier proven, shown as fictional shortened strings 8qNx...vR4m and 0x7aB2...9cF4](https://mintcdn.com/socialscan/IovDmO5aKwtscGfq/images/art/v3-traders.webp?fit=max\&auto=format\&n=IovDmO5aKwtscGfq\&q=85\&s=4252610d9e9c740b245d76f0684a578a)

| Endpoint | Answers |
| - | - |
| [`GET /v3/traders/lookup`](https://docs.fomoscan.sh/v3/api-reference/traders/find-traders-by-handle) | handle to traders, on every platform |
| [`GET /v3/traders/{traderId}`](https://docs.fomoscan.sh/v3/api-reference/traders/read-one-trader) | one trader |
| [`GET /v3/traders/{traderId}/wallets`](https://docs.fomoscan.sh/v3/api-reference/traders/list-the-wallets-of-a-trader) | the trader's wallets, strongest first |
| [`GET /v3/wallets/{family}/{address}`](https://docs.fomoscan.sh/v3/api-reference/wallets/read-one-wallet-and-who-owns-it) | wallet to the traders who own it |
| [`GET /v3/traders/{traderId}/pnl`](https://docs.fomoscan.sh/v3/api-reference/traders/read-a-traders-pnl-across-whole-wallets) | profit over 24h, 7d, 30d and all time |
| [`POST /v3/traders/pnl`](https://docs.fomoscan.sh/v3/api-reference/traders/read-the-pnl-of-up-to-100-traders) | the same for up to 100 traders in one call |

## Find a trader

`GET /v3/traders/lookup?handle=…` matches the handle on every platform, and
every handle an account held in the last 30 days, so a renamed account still
answers. Narrow it with `platform=fomo`, `pump` or another platform.

* One handle can match several traders, for example two people with the same
  handle on two platforms. Check `canonical.platforms` and `sources` before you
  pick one.
* No match answers `200` with an empty page and up to 5 `suggestions`.
  `match=closest` returns the closest suggestion as the only item, with
  `"match": "closest"`. A close handle is a guess: check it before you store it.
* Store the `tdr_` id and use it from then on. A trader merged into another one
  keeps answering, with the old id in `canonical.mergedFrom`.

## Wallets

Each wallet lists its owners, and each owner carries a `tier`: how sure we are
that the trader owns the wallet.

| `tier` | Behind it |
| - | - |
| `proven` | An on-chain proof. |
| `account` | The wallet is the key of the trader's platform account. |
| `partial` | A one-sided proof. |
| `weak` | An ambiguous or imported link. Also the cap when two traders hold the wallet, or it carries a `custodial` or `exchange` label. |
| `unverified` | No proof. |

* `canonical.walletAvailable` on the trader says whether
  `GET /v3/traders/{traderId}/wallets` will list a wallet, without a reveal.
* Listing a trader's wallets takes one reveal when the page lists a wallet.
  Reading one wallet takes one reveal when an owner holds a tier other than
  `account`, and none when every owner is `account` or it has no owner.
* An EVM address matches in any letter case and comes back lowercase.

## PnL

![Illustrative PnL from GET /v3/traders/\{traderId}/pnl: total profit over 24h, 7d and 30d across whole wallets on every venue, beside an all-time figure we compute ourselves](https://mintcdn.com/socialscan/IovDmO5aKwtscGfq/images/art/v3-pnl.webp?fit=max\&auto=format\&n=IovDmO5aKwtscGfq\&q=85\&s=f07e8c75d69db620385310fbd9d60b44)

`GET /v3/traders/{traderId}/pnl` covers the trader's verified wallets, whole, on
every venue, over `24h`, `7d` and `30d`. `all` is our own figure. Each window
carries `realized`, `unrealized` and `total`, as `Amount` objects.

Read `status` first:

| `status` | Meaning | What to do |
| - | - | - |
| `ready` | The figures are present, and `wallets` lists the wallets they cover. | Use them. |
| `pending` | A read is running and no figure exists yet. | Call again after `retryAfterSeconds`, 30. |
| `failed` | The last read failed. | Call again after `retryAfterSeconds`. |
| `no_wallet` | The trader holds no wallet that passes the wallet rule below. | Nothing to wait for. |
| `unavailable` | PnL reads are switched off, or this month's budget for them is spent. | Call again next month; `all` can still hold figures. |

* Wallet rule: tiers `proven`, `account` and `partial` only, one wallet per
  address family, and none that another trader also holds.
* A `ready` answer can carry `stale: true` with a figure up to 7 days old.
  `nextUpdateAt` says when a newer one falls due.
* `window=7d` keeps one window in the answer.
* A `ready` answer takes one reveal and 30,000 credits. Any other `status`
  costs 200 credits and no reveal.

```bash theme={null}
curl -s -H "Authorization: Bearer $KEY" \
  "https://api.fomoscan.sh/v3/traders/tdr_01jbst8pvcfp79y0938nkrkayd/pnl?window=7d"
```

For many traders, send up to 100 ids to `POST /v3/traders/pnl` with
`{ "traderIds": [ … ] }`. Each item carries its own `status`, and only `ready`
items take a reveal. The key needs one reveal left per item before the call
starts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.