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

# Track balances and portfolio

> Read available funds, locked balances, portfolio performance, and private fills.

Account endpoints use API-key authentication. Balances and portfolio values are decimal strings so clients do not lose precision.

## Understand balances

`GET /balances` requires `ACCOUNT_READ`. Add `?asset=USD` when you need only one asset.

```bash theme={null}
curl https://api.paperdrill.dev/v1/balances \
  --header "x-api-key: $PAPERDRILL_API_KEY"
```

```json theme={null}
{
	"USD": { "available": "9748.50", "locked": "251.50" },
	"SOL": { "available": "2.00", "locked": "0.00" }
}
```

* `available` can be used for a new order.
* `locked` is reserved by open orders.
* Cancelling an order releases its unfilled reservation.
* Fills move value between assets and can change both fields.

Always refresh balances after order activity instead of calculating the authoritative balance only on the client.

## Track portfolio performance

`GET /portfolio` requires `ACCOUNT_READ`. It values positions in the platform quote asset and compares current equity with the account's PnL baseline.

```bash theme={null}
curl https://api.paperdrill.dev/v1/portfolio \
  --header "x-api-key: $PAPERDRILL_API_KEY"
```

| Field | Meaning |
| - | - |
| `equity` | Current portfolio value |
| `baselineEquity` | Value used as the PnL starting point |
| `pnl` / `pnlPercent` | Change from the baseline |
| `baselineAt` | Time at which the baseline was recorded |
| `asOf` | Oldest market-price timestamp used for valuation |
| `partial` | `true` when a position could not be fully priced |
| `positions` | Per-asset balances, mark price, and value |

Treat `partial: true` as an incomplete valuation. Do not present it as the value of the entire portfolio without a warning.

## Reconcile with private trades

Use `GET /trades` with the `ORDER_READ` scope to retrieve your fills newest first. Each record identifies your side, maker status, and related order.

```bash theme={null}
curl "https://api.paperdrill.dev/v1/trades?limit=100" \
  --header "x-api-key: $PAPERDRILL_API_KEY"
```

Use order history for intent and status, private trades for executions, and balances for the current authoritative funds.


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