Skip to main content
Send a goal in plain English, a policy, or both. Abacus Labs returns up to three options. Each is a list of broker-ready trades with its tax, risk before and after, rule checks and a proven bound on how far it is from the best answer.
The Quickstart shows the response.

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):
Poll with its id (here saved from the 202 body in running.json):
The finished poll answers 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’s tradeoff 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.
Options from the templates engine (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

Take understood.policy, change one field, and send it back as policy (with no goal). Only what you changed moves.
Reference: Create a proposal, Get a proposal.