> ## 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. # Check a change > Ask which of your rules a change would put outside range, with prices you supply. A check tests a change against the rules you wrote and returns facts. It does not approve, block or place an order. A result inside every range does not say a change is advisable. Allocait cannot approve, stop or place an order. Your code, or you, decide what to do with the facts. ## Who can call it An app, a script or an agent can call the same check: * **REST:** `POST /trades/check` on `https://allocait.app/api/v1`. * **MCP:** the `check_trades` tool at `https://api.allocait.app/functions/v1/mcp`, and the `check_a_change` prompt. * **Claude Code:** the `allocait-check` skill in the [plugin](https://docs.allocait.app/claude/install-plugin.md). It's a read. A key with read access can call it, including a **Read only** key. It changes no holding, cash or rule. To connect, see [Connect Claude](https://docs.allocait.app/claude/connect.md) or [Connect ChatGPT](https://docs.allocait.app/chatgpt/connect.md). ## What to send | Field | Meaning | | - | - | | `portfolio_id` | The portfolio to check. | | `scenario_id` | Optional. The scenario to check against. Left out, the portfolio's active scenario is used. A portfolio with no active scenario is refused with a `400`; pass `scenario_id` then. In MCP the tool asks for a `scenario_id` instead of judging. | | `trades` | 1 to 50 changes. They are one basket, applied together. Several changes on one symbol are netted. | | `prices` | `{ "SYMBOL": number }`. A price for every non-cash symbol the portfolio holds and every symbol in `trades`. A held option with a mark needs none; an expired option counts 0. | Each item in `trades` is `{ "symbol": "ALFA", "side": "BUY", "shares": 41 }`, or `{ ..., "notional": 7441.5 }` for dollars. Send exactly one of `shares` or `notional`, greater than 0. Shares may be fractional. `side` is the direction of the change you are asking about. `BUY` adds shares and `SELL` removes them. It doesn't say anything about what to do. ### Prices Allocait supplies no price. Without a price for a symbol, the call fails with `PRICES_INCOMPLETE`. REST lists the symbols still needed in `missing_symbols`; MCP lists them in `missing`, and in the error message. A held option with a mark is priced at that mark, which is its owner's own number. A price you send for it replaces the mark for this call only. See [Prices](https://docs.allocait.app/concepts/prices.md) for why you supply them. ### Refused changes * A symbol the portfolio doesn't hold needs `asset_class`: a class name, an alias or an id. * `CASH` can't be changed with this call. * A research label can't be traded. The check refuses it with `INVALID_INPUT`. * Two trades in one symbol can't name different classes in `asset_class`. * A portfolio with no cash row is refused with `INVALID_INPUT`. Add one; it can hold 0. * A `SELL` larger than the shares held is refused with `INVALID_INPUT`. It is never trimmed. On a portfolio with Allow shorts on, a `SELL` can take a holding below zero and a `BUY` can take a short above it; `shares_after` is then signed, and negative is a short. A holding in the Options class never goes below zero. * A trade in an option that has expired is refused with `INVALID_INPUT`. The option counts 0, so a trade can't change the book. The message names the trade and says that a holdings write with `shares` 0 and `price` 0 closes it. ## Example Illustrative example. The figures are hypothetical, not a recommendation. ```bash theme={null} curl -X POST "https://allocait.app/api/v1/trades/check" \ -H "x-api-key: $ALLOCAIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "portfolio_id": "YOUR_PORTFOLIO_ID", "trades": [ { "symbol": "ALFA", "side": "BUY", "shares": 41 } ], "prices": { "ALFA": 181.5, "BRAV": 93.7, "GOLF": 61.3 } }' ``` The [check result](https://docs.allocait.app/concepts/check-result.md) explains every field that comes back. ## Treat a failed call as no result A failed call returns one of these. In MCP the same errors come back as `Error [CODE]` lines, with the symbols in `missing`. | Status | `error_code` | Meaning | | - | - | - | | `400` | `INVALID_INPUT` | The request is malformed. | | `400` | `PRICES_INCOMPLETE` | Prices are short. REST lists `missing_symbols`; MCP lists `missing`. | | `400` | `PRICES_INVALID` | The `prices` map is malformed, or a price is bad: a traded symbol priced 0 or less, or any price below 0, not a number or above 1000000000. | | `404` | `NOT_FOUND` | A portfolio or scenario that isn't yours. | | `403`, `429`, `500` | | See the links below. | A failed call is no result. It isn't a pass and it isn't a finding about the change. You can retry a `500` (`INTERNAL_ERROR`) once. For a per-minute `429`, wait the `Retry-After` interval; a `DAILY_LIMIT_EXCEEDED` `429` carries none, and a retry on a timer won't clear it. See [API errors](https://docs.allocait.app/api/errors.md) and [Rate limits](https://docs.allocait.app/api/rate-limits.md). ## A loop, in prose Your code builds the change it is about to place elsewhere, sends it with its own prices and reads `newly_or_further_outside_count`. A count of 0 means that, for the rules judged, the recorded book and the prices you sent, the change adds no breach and deepens none. Allocait doesn't hold or release the order, and a failed call is no result. ## Next steps > [card] [Check result](https://docs.allocait.app/concepts/check-result.md) > > Every field a check returns. > [card] [Check from a script](https://docs.allocait.app/recipes/run-a-check-from-a-script.md) > > Call the check from your own code. > [card] [Other MCP clients](https://docs.allocait.app/recipes/use-with-any-mcp-client.md) > > Connect any MCP client with an API key. > [card] [Prices](https://docs.allocait.app/concepts/prices.md) > > Why an agent supplies every price. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.