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

# Size a position

> Work out a share count that fits a holding's size range.

Sizing turns a [size range](https://docs.allocait.app/concepts/position-sizes.md) 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](https://docs.allocait.app/claude/tools/checks.md)). 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](https://docs.allocait.app/concepts/shorts.md).

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

```bash theme={null}
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](https://docs.allocait.app/guides/update-holdings.md).

## Next steps

* [Size ranges](https://docs.allocait.app/concepts/position-sizes.md)
* [Check tools](https://docs.allocait.app/claude/tools/checks.md)
* [Update holdings](https://docs.allocait.app/guides/update-holdings.md)


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