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

# Holding tools

> Record holdings and cash that already moved.

Three tools record holdings and cash that already changed somewhere else.

**save\_position** `write, destructive`

Records a holding you bought, sold, opened or closed, as it stands now: its new total shares (the total, not the change: 7 more is the held count plus 7, and `list_portfolios` shows the held count; 0 closes it, negative is a short), the price you paid or received elsewhere, and an optional comment. A negative total needs Allow shorts on and is never an option holding.

Cash and new holdings:

* Other holdings stay as they are.
* Cash falls or rises by the change in shares times price, and a buy the cash can't cover is refused until any unrecorded deposit is recorded.
* Send `asset_class` for a new holding, or no rule judges it.
* The `symbol` argument takes a ticker, a slash pair or an OCC option symbol with no spaces.

Options:

* Record contracts times 100 filed under Options, with the premium per share as `price`; a trade price becomes its `mark`, and `mark` sets it directly.
* Changing only `mark` is not a trade: no price is needed and no cash moves.
* Close an expired option with `shares` 0 and `price` 0, only once the user says what happened.

Moves:

* `moves` (1, 2, 3, -1, -2 or -3) is how many times its index a fund moves. Leave it out to keep the stored value.
* Allocait never sets it from a symbol or fund type. Set it only when the user says a fund is inverse or leveraged.
* Cash and options accept only 1.
* Changing only `moves` is not a trade: no price is needed and no cash moves.

This records the change in Allocait only. It moves no money and places no order.

Key arguments: `portfolio_id`, `symbol` (up to 21 characters), `shares`, `price` (needed when shares change), optional `asset_class`, `moves`, `mark`, `sizing`, `comment`.

**replace\_positions** `write, destructive`

Syncs every holding at once; for one buy or sale use `save_position`. Send every non-cash holding you hold now. A holding you leave out is refused, not closed: close it with a `{symbol, shares: 0, price}` row (`price` 0 for an expired option). This records the change in Allocait only. It moves no money and places no order. Key arguments: `portfolio_id`, `positions` (each with `symbol`, `shares`, and optional `price`, `asset_class`, `moves`, `mark`, `sizing`, `comment`).

**record\_cash\_movement** `write`

Records a deposit or withdrawal you made elsewhere. It adds one entry to the cash record. Pass an `idempotency_key` and reuse it on a retry of the same movement; the same key with the same movement doesn't record a second entry. For holdings you already owned, deposit their value plus any cash not yet recorded, then record each holding at the same prices. This records the change in Allocait only. It moves no money and places no order. Key arguments: `portfolio_id`, `direction` (`DEPOSIT` or `WITHDRAW`), `amount`, optional `comment`, `idempotency_key`.

## Next steps

> [card] [Update with an agent](https://docs.allocait.app/guides/update-with-an-agent.md)
>
> Sync holdings and cash through MCP tools or the REST API.

> [card] [Action log](https://docs.allocait.app/concepts/action-log.md)
>
> The record of changes made to your holdings and cash.


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