Skip to main content
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.

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

​
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.
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).
  • 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 for why you supply the price, and the API overview for the full request and response shape.

​
Next steps

Action log

Each change is listed and can carry a comment.

Idempotency

Make a cash movement retry safe.

Holding tools

The MCP tools that record holdings and cash.

Update holdings

The same job in the app.