> ## 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 from a script

> Call the check from your own code with prices you supply.

This script asks which of your rules a change would put outside range, and prints the facts. A result inside every range does not say a change is advisable. Allocait cannot approve, stop or place an order. Your own code decides what happens next.

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

Save the script as `check.mjs` and run it with Node 18 or later. Set `ALLOCAIT_API_KEY` and `ALLOCAIT_PORTFOLIO_ID` first. Create a **Read only** key under **Settings > API keys**, and get the portfolio id from `GET /portfolios`.

```js theme={null}
const BASE = 'https://allocait.app/api/v1'
const headers = { 'x-api-key': process.env.ALLOCAIT_API_KEY, 'Content-Type': 'application/json' }
const prices = { ALFA: 181.5, BRAV: 94.2, GOLF: 62.3 } // from your own source: every held and every changed symbol
const trades = [{ symbol: 'ALFA', side: 'BUY', shares: 40 }]

const res = await fetch(`${BASE}/trades/check`, { method: 'POST', headers,
  body: JSON.stringify({ portfolio_id: process.env.ALLOCAIT_PORTFOLIO_ID, trades, prices }) })
const result = await res.json()
if (!res.ok) throw new Error(result.missing_symbols ? `Add prices for: ${result.missing_symbols.join(', ')}` : `No result: ${result.error_code ?? res.status}`) // a failed call is no result

console.log('rules this change adds or deepens:', result.newly_or_further_outside_count)
for (const r of result.rules) {
  console.log(r.change, r.kind, r.asset_class, r.symbol ?? '(class)', `${r.before_pct} -> ${r.after_pct}`)
}
console.log('whole book inside every rule afterward:', result.within_rules)
console.log('positions last updated:', result.positions_updated_at)
```

A **Read only** key is enough, because the check only reads.

`result.rules` lists each rule outside its range before or after the change. `change` is `newly_outside`, `further_outside`, `still_outside` or `back_inside`. A class band has a null `symbol`.

Send several planned orders as one `trades` list (up to 50) to check them together; trades in one symbol net. Separate calls each start from the holdings Allocait has recorded, so they don't see each other. Each trade takes `shares` or `notional`, and a symbol you don't hold needs `asset_class`. The check uses the portfolio's active scenario; if the portfolio has none, pass `scenario_id`. Each call needs a price for every held symbol and every changed symbol (a held option with a mark needs none), or it fails with `PRICES_INCOMPLETE` and `missing_symbols`.

`newly_or_further_outside_count` is the number of rules the change puts outside range or leaves further outside. 0 means neither. `within_rules` answers a different question: whether the whole book is inside every rule afterward. See [Check result](https://docs.allocait.app/concepts/check-result.md) for every field and [Check a change](https://docs.allocait.app/guides/check-before-you-trade.md) for the job.

## Next steps

* [API quickstart](https://docs.allocait.app/api/quickstart.md): a key, a first read and a first check.
* [Other MCP clients](https://docs.allocait.app/recipes/use-with-any-mcp-client.md): the same check as an MCP tool call.


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