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

# Positions & Balances

> Your USDC balance and option positions, and how fills change them.

## Balances

`GET /mm/v1/balances`

```bash theme={null}
curl "$D1_API_URL/mm/v1/balances" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

```json theme={null}
{
  "balances": [
    {
      "asset": "USDC",
      "available": { "units": "250000000000", "decimals": 6 },
      "reserved": { "units": "15000000000", "decimals": 6 },
      "total": { "units": "265000000000", "decimals": 6 }
    }
  ],
  "serverTimeMs": "1800000000456"
}
```

That is 250,000 USDC available, 15,000 reserved and 265,000 in total.

| Field | Description |
| - | - |
| `asset` | Always `USDC` today. There is always exactly one entry, even when the balance is zero. |
| `available` | Funds you can use for new `BUY` orders. |
| `reserved` | Funds D1 holds against your open activity, such as the premium set aside for resting `BUY` orders. This is a single total and is not broken down. |
| `total` | `available + reserved`. |

All amounts are USDC atoms (`decimals: 6`). The endpoint takes no parameters.

`available` is what D1 lets you trade with. It can differ from what you would see in a wallet or on-chain, because D1 tracks your obligations, such as funds set aside for resting orders, as part of your account. Use this endpoint, not an outside balance, to size orders.

## Positions

`GET /mm/v1/positions`

**open** `boolean` (default: true)

`true` returns only non-zero positions. `false` also returns flat positions in instruments you have held.

**limit** `integer` (default: 50)

1–200.

**cursor** `string`

`nextCursor` from the previous page. See [Pagination](https://docs.d1.exchange/market-makers/market-data.md#pagination).

```bash theme={null}
curl "$D1_API_URL/mm/v1/positions" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

```json theme={null}
{
  "positions": [
    {
      "instrumentId": "<instrument-id>",
      "quantity": { "units": "4", "decimals": 0 },
      "positionState": "LONG",
      "instrumentStatus": "ACTIVE"
    }
  ],
  "nextCursor": null,
  "limit": 50,
  "serverTimeMs": "1800000000456"
}
```

| Field | Description |
| - | - |
| `instrumentId` | The market. |
| `quantity` | Net position in contracts. Signed. |
| `positionState` | `LONG`, `SHORT` or `FLAT`. Always matches the sign of `quantity`. |
| `instrumentStatus` | The market's current `status`. |

Results are sorted by `instrumentId`.

### How fills change positions

While a market is trading, every fill on [`/executions`](https://docs.d1.exchange/market-makers/executions) changes your position in that market by its `quantity`: up for `BUY`, down for `SELL`. If you apply executions in sequence, your own position for a trading market should match `GET /mm/v1/positions`.

Because `SELL` is [sell-to-close](https://docs.d1.exchange/market-makers/trading-rules.md#sell-to-close), the API never takes you below zero in a market. You can hold long positions and reduce them to flat. You cannot create a short position through this API. `SHORT` is part of the general position format; you should not see it from trading through this API.

`quantity` is your full position, including any contracts set aside for resting `SELL` orders. To work out how much you can still sell, subtract the `remainingQuantity` of your resting `SELL` orders in that market.

> [!NOTE]
>
> The API does not return cost basis, P\&L, Greeks, margin or risk figures. Calculate these in your own system from positions, fills and market data.

## Reconciling account state

Your execution feed is the record of what happened. Positions and balances are a snapshot of where that left you. Check them against each other regularly:

* after startup, once you have caught up on `/executions`;
* after any period where you were not sure what happened, such as timeouts or a lost connection;
* on a fixed schedule, for example every few minutes.

If they disagree, trust D1's values, find the executions you are missing, and alert.


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