Size a position

Sizing turns a size range into a share count. It is arithmetic on numbers you pass in: it reads no rule, writes nothing and says nothing about whether to add the holding.

In the app

Adding a holding can fill the share count from your size range at its minimum, midpoint or maximum.

With an agent

An agent calls POST /positions/size (MCP: calculate_position_size, see Check tools). The call needs read access and your own price.

Field	What it does
`current_shares`, `price`, `portfolio_value`	Required.
`cash`	Optional. With it, the answer says whether you can afford the target.
`sizing_mode`	`MANUAL` (the default), `MINIMUM`, `BALANCED` or `MAXIMUM`. The last three size to the bottom, midpoint or top of the range you pass as `size_min_pct` and `size_max_pct`, and each needs its bound (`BALANCED` needs both).
`manual_shares`	With `MANUAL`, sizes to that count. With none, `MANUAL` starts from the size held now.
`basis_points`	Added to the target in every mode, either sign (100 is 1%). With `MANUAL` and no `manual_shares`, it moves the holding up or down by that share of `portfolio_value`.
`direction`	`long` (the default) or `short`.

Take both bounds from the class’s rule (get_rules or GET /position-rules): its size range, or its short size range for a short. For a short, pass the class’s short size range as the bounds, a positive manual_shares and a negative current_shares for a short you hold. The share count, value and percent come back negative. See Shorts.

What the target means

The target is held between 0 and 100 percent of portfolio_value, not inside your range. When it lands outside the range, compliance_status is BELOW_MIN or ABOVE_MAX and the share count is still the one asked for. With no bounds, compliance_status is UNEVALUATED, which is not a pass.

Example

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

curl -X POST "https://allocait.app/api/v1/positions/size" \
  -H "x-api-key: $ALLOCAIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current_shares": 41,
    "price": 181.5,
    "portfolio_value": 98765,
    "sizing_mode": "BALANCED",
    "size_min_pct": 3,
    "size_max_pct": 9,
    "cash": 4321
  }'

The response has target_shares, target_value, target_pct, shares_delta and value_delta, with compliance_status and, when you sent cash, can_afford and cash_after_trade. The result is a calculation. Nothing is recorded; to change what you hold, update your holdings.

Rules and checks

Holdings

Webhooks

Agents

Recipes

In the app

With an agent

What the target means

Example

Next steps

​In the app

​With an agent

​What the target means

​Example

​Next steps

In the app

With an agent

What the target means

Example

Next steps