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

# PositionsService

> Margin positions, close flows, risk, margin adjustments, history, and TP/SL

Package: `monaco.api.positions`

Source: `protos/api/positions.proto`

Use `PositionsService` for isolated-margin position management.

```protobuf theme={null}
service PositionsService {
  rpc ListPositions(ListPositionsRequest) returns (ListPositionsResponse);
  rpc GetPosition(GetPositionRequest) returns (GetPositionResponse);
  rpc ClosePosition(ClosePositionRequest) returns (ClosePositionResponse);
  rpc GetPositionRisk(GetPositionRiskRequest) returns (GetPositionRiskResponse);
  rpc ListPositionHistory(ListPositionHistoryRequest) returns (ListPositionHistoryResponse);
  rpc AttachPositionTpSl(AttachPositionTpSlRequest) returns (AttachPositionTpSlResponse);
}
```

## Notes

* Position RPCs are authenticated.
* TP/SL can be attached to existing positions through `AttachPositionTpSl`.
* `ListPositions`, `GetPosition` and `GetPositionRisk` read each market's index price from the matching engine and return `UNAVAILABLE` when that read fails transiently (retry); any other failure of that read is `INTERNAL`.
* `ClosePosition` draws one item from the per-account risk-reduction order budget it shares with cancels; `BatchCloseAll` draws one item per open position it closes (an empty call draws one): the first 100 are charged before anything is sent and over budget the whole call is refused, while positions past 100 that the budget does not cover are not sent and come back in `results` with `RATE_LIMIT_EXCEEDED`. Both return `RESOURCE_EXHAUSTED` with a `google.rpc.RetryInfo` detail when the budget is enforced and spent, before anything reaches the matching engine. See [Rate Limits](/developers/rate-limits).
* `Position.cum_fees`, when present, is the whole-life fee total on open and terminal rows; it is absent while fee history is unavailable or incomplete — before the position's first PnL sample, after retention, or on a terminal row until the final close is recorded. On a terminal row, `exit_price`, `funding_paid`, `fees_paid` (closing-side only), `net_realized_pnl` and `realized_roe` come from the reducing executions when they reconcile with `realized_pnl`, and `size` / `isolated_margin` carry the lifetime closed quantity and allocated initial margin.
* `Position.funding_paid` is the lifetime funding since the position opened (signed; negative means received). On an open row it is the funding accrued on the open size plus the funding its partial closes settled, so the last open value equals the terminal value; it is absent whenever `lifetime_totals_status` is not COMPLETE, rather than understated.
* `ListPositions` and `ListPositionHistory` are cursor-paginated: send an empty `page_token` to start, then each response's `next_page_token` until it comes back empty; `page_size` is 1 to 1000. There is no `page` field: a stub generated from an older proto that still sets it is not rejected (protobuf discards the unknown field) and reads the first page on every call, so regenerate stubs and walk the token.
* `Position.opened_at` (RFC 3339) is the fill that took the position's exposure from zero to non-zero; it never changes for the position id and is absent when unknown.


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