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

​
What to send

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 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.
The check result 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. 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 and Rate limits.

​
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

Check result

Every field a check returns.

Check from a script

Call the check from your own code.

Other MCP clients

Connect any MCP client with an API key.

Prices

Why an agent supplies every price.