Pre-trade check
A pre-trade check compares a trade you are considering with the rules you set for your own portfolio, before the order is placed. It reports which asset-class bands and position size ranges the trade would leave outside range, using your recorded holdings and prices you supply.
What does a pre-trade check tell me?
Send the proposed trades yourself or through an agent. Allocait compares them with your recorded holdings and reports:
- Which asset-class bands and position size ranges the change would put outside range, or push further outside.
- Whether every rule it judged is in range afterward and cash covers the change.
- Cash before and after, and each holding's shares before and after.
- Which holdings the check could not cover.
Can an AI agent run the check before it places an order?
Yes. Over MCP, the agent calls the check_trades tool. Over REST, it sends POST /trades/check. Either way it passes the proposed trades and its own prices, then reads the result before it places an order.
The check runs only when the agent calls it. Put the call first in the agent's instructions, and have it skip the order when the result is not what you want.
What does a check look like?
This request asks about buying one holding and selling part of another. The result is trimmed: ids, exposure and timestamps are left out.
Request
POST /trades/check
{
"portfolio_id": "YOUR_PORTFOLIO_ID",
"trades": [
{ "symbol": "ALFA", "side": "BUY", "shares": 41 },
{ "symbol": "GOLF", "side": "SELL", "shares": 11 }
],
"prices": { "ALFA": 181.5, "BRAV": 93.7, "GOLF": 61.3 }
}Result
{
"within_rules": false,
"newly_or_further_outside_count": 2,
"rules_judged_count": 4,
"rules": [
{ "kind": "class_band", "asset_class": "Equities",
"min_pct": 29, "max_pct": 39,
"before_pct": 37.2981, "after_pct": 41.0188,
"before_status": "COMPLIANT", "after_status": "ABOVE_MAX",
"gap_after_pts": 2.0188, "change": "newly_outside" },
{ "kind": "position_size", "symbol": "ALFA", "asset_class": "Equities",
"min_pct": 15, "max_pct": 39.5,
"before_pct": 37.2981, "after_pct": 41.0188,
"before_status": "COMPLIANT", "after_status": "ABOVE_MAX",
"gap_after_pts": 1.5188, "change": "newly_outside" }
],
"not_covered": [
{ "symbol": "GOLF", "asset_class": "Commodities", "reason": "NO_SIZE_RANGE", "traded": true }
],
"trades": [
{ "symbol": "ALFA", "side": "BUY", "shares": 41, "shares_before": 411, "shares_after": 452 },
{ "symbol": "GOLF", "side": "SELL", "shares": 11, "shares_before": 301, "shares_after": 290 }
],
"cash": { "before": 54200.1, "after": 47432.9, "sufficient": true },
"total_value": 200001
}Illustrative example. The figures are hypothetical, not a recommendation.
What happens when a trade would leave my range?
The result lists each rule the trade leaves outside its range, with the share before, the share after and the gap in percentage points. A rule that was inside and is now outside reads newly_outside. A rule that was already outside and moved further out reads further_outside.
The count newly_or_further_outside_count adds them up, and within_rules is true only when every rule holds after the change, at least one rule was checked and cash covers it. Allocait reports this and does nothing else. What to do next is yours or your agent's to decide.
Where do the prices come from?
From you or your agent. The request carries a price for every symbol you hold, except cash, and every symbol you trade. Allocait supplies none, uses them for that one call and stores none.
A request with a price missing fails with PRICES_INCOMPLETE and names the symbols still needed. A failed call is no result, not a pass.
Does Allocait place or stop the order?
No. A result inside every range is not an approval. It reports where the change leaves each rule.
- It places no order and connects to no brokerage.
- It cannot stop an order. An agent skips the check unless its instructions say to call it first.
- It supplies no prices. You or your agent pass a price for each traded symbol and each holding.
How is it different from a prompt or a broker's limits?
Three ways to hold a trade to your rules, and what each one knows and does.
| Approach | What it knows | What it does with a trade |
|---|---|---|
| Rules typed into a prompt | What you wrote in the conversation. It has no record of your holdings unless you paste them. | The model reads the rules and does the arithmetic itself. The answer can change between runs, and it can skip the check. |
| A broker's own limits | Whatever the broker offers. Allocait does not read it. | Set by the broker. It is separate from the rules you save in Allocait. |
| Your own rules, checked by Allocait | Your saved bands and size ranges, your recorded holdings and the prices passed with the call. | Reports which rules the trade leaves outside range, the same way each time. It places no order and cannot stop one. |
Where do I go next?
- Rebalancing calculator: type your ranges and read each class against them, with nothing sent.
- Check before you trade: the request, the result and how to read it.
- Check from a script: call the check from your own code.
- Add a check to a trading bot: put the call before the order.
- Use with any MCP client: connect a client with an API key.
- For agents: connect Claude, ChatGPT or your own agent.