Skip to main content
Four tools read, save and delete portfolios. Start with list_portfolios, then read one portfolio with get_portfolio_snapshot.
​
read
Your portfolios, each with its holdings (symbol and shares, up to 100 per portfolio, with holdings_more past that), active scenario, playbooks, monitors and charts, plus every scenario (rule set). Start here. No prices or dollar totals; use get_portfolio_snapshot for a valued total.
​
read
One portfolio’s holdings, rules, monitors, playbooks and charts. The result opens with a summary line (counts and names; compliance.status carries the status).Prices:
  • Pass prices from you or a source you trust, never remembered or estimated.
  • With none, it lists holdings_to_price (the held symbols a status needs) and symbols_to_price (which adds symbols only monitors use) to ask for.
  • Call it again with them to also get the compliance status (compliance.status, with each class and size breach’s outside_by: which edge and how far outside, in percentage points and dollars at your prices) and the monitor readings.
Optional parts:
  • Add include_rebalance for the pro rata rebalance amounts too (a short or an option gets none, and not_rebalanced lists them; a class’s move lands on its long holdings outside Options).
  • With a price for every non-cash holding (an option with a mark counts as priced) it also returns exposure, how much of the portfolio gains if prices rise (long, short, net and gross as percents of its value). That is a reading, not a rule, and it is null while any holding is unpriced. Options count at their premium.
  • expired_options counts held options past their expiry. Each position carries moves, mark, mark_on and expired_on.
  • With no active scenario, compliance and rebalance say to ask the user which scenario to check against, then pass scenario_id.
Key arguments: portfolio_id, optional scenario_id (defaults to the portfolio’s active scenario), optional prices, optional include_rebalance.

​
Standing in the snapshot

Signed in over OAuth, the snapshot also carries standing with no prices passed: each holding’s and class’s size as a percent of the book, your range or band, inside, below or above, and the room to the nearer edge in percentage points, read from Allocait’s last stored quote at as_of. A note says so whenever a stored quote was used.
  • Once you price every holding and the status is present, standing leaves out the sizes, which would repeat it, and keeps the monitors’ states.
  • When a holding can’t be read, such as an option with no mark, the sizes are null, not empty, and why_not_read says why.
  • key explains close_state, consecutive_closes and edge_distance_pct_points.
  • standing holds no price or dollar figure. Checking or sizing a change still needs prices you give.
See Standing for what each field means.

​
Save and delete

​
write, destructive
Creates a portfolio with starting cash, or renames it, changes its description, switches its active scenario (the rule set it is judged against) or turns Allow shorts on or off. Turning Allow shorts off is refused with IN_USE while a short is held. Allow shorts is the account owner’s setting, so turn it on only when the user asks. Key arguments: portfolio_id (to change one), name, description, active_scenario_id, allow_shorts, initial_cash (create only), base_currency (USD, the only currency Allocait supports).
​
write, destructive
Deletes a portfolio and everything in it: holdings, actions, monitors, playbooks and charts. This can’t be undone. Key arguments: portfolio_id, confirm_name (the portfolio’s name, exactly as you confirmed it).

​
Next steps

Standing

Where you stand against your own ranges.

All tools

Every tool at a glance.