> ## 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.

# Update with an agent

> Sync holdings and cash through MCP tools or the REST API.

An agent or script records the share count you hold now and the price, not the change. Writes need **Read and change** access; see [Access levels](https://docs.allocait.app/concepts/access-levels.md).

## Through Claude or another agent

The `save_position` tool takes a holding's new total shares, not the change, and the price. Your other holdings stay as they are, and cash moves by the change in shares times the price.

Illustrative example. The figures are hypothetical, not a recommendation.

You can tell your assistant "I hold 10 shares of ALFA, priced at \$181.5" and it can pass those values to the tool.

If your recorded cash can't cover the change, the call is refused (`INSUFFICIENT_CASH`) until the deposit is recorded. `record_cash_movement` takes an `idempotency_key`; a retry with the same key does not record the movement twice. If you already owned your holdings, deposit their value plus any cash not yet recorded, then record each holding at the same prices.

* **Close a holding:** set the total to 0.
* **Inverse or leveraged fund:** pass `moves` without changing the share count. Leave `moves` out and the setting stays.
* **Option:** shares are contracts times 100 and `price` is the premium per share, which becomes the mark. To change only the premium, pass `mark`. To close an expired option, send `shares` 0 and `price` 0. Allocait changes no holding when an option expires and does not guess what it became.
* **Short:** a negative total is a short, and works only when Allow shorts is on. It is off by default. Turn on Allow shorts in the portfolio's settings, or set `allow_shorts` on `save_portfolio`.

To sync every holding at once, use `replace_positions`. A holding you leave out of the list is refused (`WOULD_CLOSE_POSITIONS`), not closed. To close one, include it with 0 shares and a price (a price of 0 for an expired option). For the arguments, see [Holding tools](https://docs.allocait.app/claude/tools/holdings.md).

## Through the REST API

Set a holding's new total share count with the price. A key with write access is required.

Illustrative example. The figures are hypothetical, not a recommendation.

```bash theme={null}
curl -X POST "https://allocait.app/api/v1/positions/ALFA?portfolio_id=YOUR_PORTFOLIO_ID" \
  -H "x-api-key: $ALLOCAIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shares": 160, "price": 181.5, "comment": "Set to 160 shares"}'
```

The response includes the cash impact and your new cash balance.

* **New holding:** the same call opens one. Add `asset_class` (a class name, alias or id), or no rule judges the holding.
* **Several holdings:** `POST /portfolios/{id}/positions/apply` replaces them in one request.
* **Cash:** `POST /portfolios/{id}/cash-movements` records a deposit or withdrawal and takes an `idempotency_key` (see [Idempotency](https://docs.allocait.app/api/idempotency.md)).
* **`moves`:** 1, 2, 3, -1, -2 or -3. Left out, the stored value stays. A call that changes only `moves` needs no `price`.
* **`mark`:** an option's premium per share, for the Options class only. Left out, the price becomes the mark. A call that changes only `mark` needs no `price` and moves no cash.
* **Symbol length:** up to 21 characters, so an option symbol fits.
* **Short:** a negative `shares` records a short on a portfolio with `allow_shorts` on, and is refused with `INVALID_INPUT` otherwise.

After a change, call `/compliance/check` with your own prices to see the new status. See [Prices](https://docs.allocait.app/concepts/prices.md) for why you supply the price, and the [API overview](https://docs.allocait.app/api/introduction.md) for the full request and response shape.

## Next steps

> [card] [Action log](https://docs.allocait.app/concepts/action-log.md)
>
> Each change is listed and can carry a comment.

> [card] [Idempotency](https://docs.allocait.app/api/idempotency.md)
>
> Make a cash movement retry safe.

> [card] [Holding tools](https://docs.allocait.app/claude/tools/holdings.md)
>
> The MCP tools that record holdings and cash.

> [card] [Update holdings](https://docs.allocait.app/guides/update-holdings.md)
>
> The same job in the app.


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