# Wallet PnL API

> What a wallet made and lost, overall and per token, computed from its swaps. A position's unknown PnL is null, never 0.

## A wallet's results over a window

[`GET /wallets/:chain/:address/analysis`](https://app.aurelia.build/docs/wallet-analysis) takes `window`: `1d`, `7d`, `30d` or `90d`. A request costs 3 credits.

The last 30 days:

```bash
curl -s -H 'Authorization: Bearer <key>' 'https://app.aurelia.build/api/wallets/solana/Fm1Nzv3EcgGMW2MFHHGKjdVDbvHsMMtoRdoBDmUmsFFE/analysis?window=30d'
```

| Field | What it is |
|---|---|
| `realizedPnlUsd`, `unrealizedPnlUsd`, `totalPnlUsd` | Profit and loss, closed, open and together |
| `boughtUsd`, `soldUsd`, `trades`, `buys`, `sells`, `tokens` | How much it traded |
| `wins`, `losses`, `winRate` | How often it came out ahead |
| `distribution`, `timeline[]` | Tokens sold in the window by realized return, and PnL over time |
| `best[]`, `worst[]` | Up to 3 positions with the largest realized gain and loss |
| `labels` | Its [wallet labels](https://app.aurelia.build/docs/labels) |

## Every position

[`GET /wallets/:chain/:address/positions`](https://app.aurelia.build/docs/wallet-positions) lists each token the wallet traded since indexing began. Filter with `status`, sort with `sort`, or pass `token=` for one.

Open positions, largest PnL first:

```bash
curl -s -H 'Authorization: Bearer <key>' 'https://app.aurelia.build/api/wallets/solana/Fm1Nzv3EcgGMW2MFHHGKjdVDbvHsMMtoRdoBDmUmsFFE/positions?status=open&sort=pnl'
```

A position holds amounts bought, sold and open, average buy and sell prices in USD, and realized and unrealized PnL. `unpricedTrades` counts the trades that had no USD price, so you can see when a figure rests on less than everything.

## What a wallet holds now

[`GET /wallets/:chain/:address`](https://app.aurelia.build/docs/wallet-portfolio) gives its holdings, valued in USD. Follow them live on the [balances and positions channels](https://app.aurelia.build/docs/live-wallets).

## Find wallets

[`GET /wallets`](https://app.aurelia.build/docs/wallet-list) gives several wallets' portfolios with totals in one request, or discovery: the top wallets by PnL, volume or win rate.

## How far back it goes

Every answer states `indexedSince`, and PnL covers swaps from then on, so read it next to that date. A position whose PnL cannot be known says `null`. `analysis` sums what is known: an unknown position counts as 0 in `unrealizedPnlUsd`, and a wallet never seen answers with zeros.

## Related

- [Wallet analysis reference](https://app.aurelia.build/docs/wallet-analysis).
- [Wallet labels](https://app.aurelia.build/docs/labels): how a wallet becomes a sniper or an insider.
- [DEX trades API](https://app.aurelia.build/guides/dex-trades-api): a wallet's swaps themselves.