Request
Async proposals and polling
Abacus Labs waits up to 20 seconds before it answers
202. Set the wait with ?wait=N or the header Prefer: wait=N (0 to 60 seconds). Most proposals take 5 to 20 seconds at standard effort; deep often takes one to two minutes.
To poll, call GET /v1/proposals/{id}?wait=30. It returns as soon as the proposal finishes, or after 30 seconds with status: "running" and Retry-After: 3. When status is succeeded, the body is the full proposal and credits_charged is its settled price. failed carries an error object and costs nothing. Polls are free, but each one counts toward the key’s daily calls.
A 202 body (real, from staging):
id (here saved from the 202 body in running.json):
200 with the full proposal and credits_charged: 25. Its Abacus-Credits-Charged header is 0: the credits were taken from the hold, not charged again.
Over MCP, abacus_propose waits up to 20 seconds; if status is running, call abacus_get_proposal with the id.
Outcome
understood.policy is the policy Abacus Labs solved. understood.resolved adds what Abacus Labs filled in: the benchmark label, the tracking-error number for a level word, the whole-share rule, the cash band, the tax rates and the current volatility.
The trade-off ladder
Options come as a short ladder: the recommended one first, then alternatives that trade one thing for another. Each option’stradeoff key and label say which rung it is.
With a stated target (
positions: {NVDA: {max: 0.25}}) and no tax or gain cap, a concentration cut uses the “other goals” ladder. When none of 10/15/20% is below the current weight, the single rung is half the current weight (cap_N). A rung is left out when it has no feasible answer or makes no change, so you may get one option.
Where the buys come from
policy.buy_only wins when you send it. Without it, an account that is not direct-indexed (fewer than 40 names) stays in what it holds when it raises cash, lowers risk, invests cash or cuts a position; a concentration cut may also buy the account’s index fund (SPY unless the account has its own benchmark). If no valid list stays within those names, the buys widen to the benchmark’s stocks, and a warning says so. Harvesting and sector cuts use the wider universe from the start: they need replacements. On lowest_tax and fewest_trades, a tracking error you state as a number stays a hard cap; a level word (tight, “closely”) is relaxed, so those rungs show what lower tax or fewer trades cost in tracking.
The guarantee
The layered solver proves a lower bound on the best possible score for the rules.guarantee.gap_bp is the most this option can be from that best, in basis points of the account; gap_dollars is the same in dollars. The true gap is often far smaller, and text says so when the bound is loose.
proven is false when the trades are no longer the solver’s own list: the rule checker changed them (live prices, cash or wash sales), or a sale was extended to the whole position so a recent purchase does not wash the loss. text says which.
engine: "templates") have no guarantee, tradeoff or tracking: they meet every rule, but their distance from the best is not proven.
The option block
Trade
Changing one thing
Takeunderstood.policy, change one field, and send it back as policy (with no goal). Only what you changed moves.