> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacuslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proposals

> Trade options for a goal and/or a policy: a trade-off ladder, each option with a proven bound.

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.

```bash theme={null}
curl -s https://api.abacuslabs.ai/v1/proposals \
  -H "Authorization: Bearer $ABACUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"account_id": "acct_demo_concentrated",
       "goal": "Get NVDA below 40%",
       "policy": {"tax": {"max_tax": 1190, "rates": {"short_term": 0.408, "long_term": 0.238}}}}'
```

The [Quickstart](https://docs.abacuslabs.ai/quickstart.md#ask-for-options) shows the response.

## Request

| Field | Required | Meaning |
| - | - | - |
| `goal` | `goal` or `policy` | What the person wants, in plain English. |
| `policy` | `goal` or `policy` | The rules. Fields here win over what Abacus Labs reads from `goal`. See [The policy](https://docs.abacuslabs.ai/concepts/policy.md). |
| `account_id` | one of `account_id`, `account`, `accounts`, `snapshot_id` | A saved account. |
| `account` | | An inline account, or `{"id": "..."}` of a saved one. |
| `accounts` + `account_id` | | All of the person's accounts. Trades go to `account_id` (required with more than one); every account counts for wash sales. |
| `save` | no | Save the account with the policy Abacus Labs used. Returns `ids.saved_account_id`: your account `id`, or a new `acct_...` id when you sent none. |
| `options` | no | 1 to 5, default 3. The most options to return. |
| `effort` | no | `quick`, `standard` (default) or `deep`: the solver's search time per option, about 2 s, 6 s or 20 s, for each variant it tries. More time can tighten the guarantee. A `deep` proposal can take two minutes or more: expect `202` and poll. |
| `max_credits` | no | Refuse the call (`402 max_credits_exceeded`, nothing charged) if it would cost more credits than this. See [Credits](https://docs.abacuslabs.ai/credits.md). |
| `wash_sale_policy` | no | `same_index` (default): funds that track the same index count as identical. `exact`: only the same security. |
| `detail` | no | `compact` (default) or `full`: every option with complete before and after analytics. |

## Async proposals and polling

| HTTP | `status` | Meaning |
| - | - | - |
| `201` | `succeeded` | Done. The body is the proposal (`outcome` says what came out). |
| `202` | `running` | Still solving. The body has `id`, `poll` and `credits_held`. Headers: `Location: /v1/proposals/{id}`, `Retry-After: 2`. |
| `4xx` | | The request was wrong. Nothing ran. See [Errors](https://docs.abacuslabs.ai/errors.md). |

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):

```json theme={null}
{ "id": "prop_d433e9e9ae", "object": "proposal", "status": "running", "goal": "Get NVDA below 40% without more than $5,000 of realized gains",
  "created": "2026-11-15T20:52:35Z", "ids": { "proposal_id": "prop_d433e9e9ae", "account_id": "acct_demo_concentrated", "snapshot_id": "snap_3ae3..." },
  "poll": "GET /v1/proposals/prop_d433e9e9ae", "credits_charged": 0, "credits_held": 25 }
```

Poll with its `id` (here saved from the `202` body in `running.json`):

```bash theme={null}
PROPOSAL_ID=$(jq -r .id running.json)
curl -s "https://api.abacuslabs.ai/v1/proposals/$PROPOSAL_ID?wait=30" -H "Authorization: Bearer $ABACUS_API_KEY"
```

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

| `outcome` | What to do |
| - | - |
| `options` | Show the person the options. |
| `clarify` | Ask the person `understood.question`, then send again. |
| `infeasible` | No trade list meets every rule. The `infeasible` result lists, for each option tried, the rules that likely blocked it; when the solver cannot single one out it says "the rules together leave no valid trade list". Tell the person, or relax a field (the tightest first: tracking error, max\_names, a tax or gain cap). |
| `no_change` | Nothing to do (for example, no holding is below its cost, so there is no loss to harvest). `answer` says why. |

`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.

| Goal | Rungs |
| - | - |
| `harvest_losses` | `balanced` (the tracking-error cap, 1% if none is set), `closest` (half the cap), `most_saved` (twice the cap) |
| `lower_risk` without a target | `balanced` (volatility down 15%), `gentle` (7%), `strong` (25%) |
| `reduce_concentration` naming no holding ("I'm too concentrated") | the "other goals" ladder below; name the holding (or send `positions`) to get the cut rungs |
| `reduce_concentration` without a target | `cap_10`, `cap_15`, `cap_20`: the position down to 10%, 15% or 20% (those below the current weight) |
| `reduce_concentration` with `max_tax` or `max_gain` | adds `tax_capped`: the position as far down as the cap allows ("NVDA as low as the gain cap allows"). With a target, the ladder is `balanced` (the target) and `tax_capped`. |
| `reduce_sector` without a target | the sector down 5 points, 10 points, or to the benchmark's weight |
| `tilt_theme` (templates engine) | No `tradeoff` key; read `label`. Through one fund, through a few stocks, or half the tilt: "A smaller tilt: AI semiconductors from 8% to about 12% through SMH (counting what your funds hold)", "Take AI semiconductors from 8% to about 15% through 6 stocks (curated AI chip makers): NVDA, AVGO, AMD, TSM, MRVL, MU". Without a number, the target is 5 points more than now, and at least 15%. Exposure counts what the account's funds hold. |
| other goals | `balanced`, `lowest_tax` (no net gains realized), `fewest_trades` (at most 12) |

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.

```json theme={null}
"guarantee": { "proven": true, "objective_bp": -53.634, "bound_bp": -75.507, "gap_bp": 21.873, "gap_dollars": 666.5,
               "text": "within 21.87 bp of the account ($667) of the best possible score for these rules" }
```

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

| Field | Meaning |
| - | - |
| `id` | The option id. Commit it with [`POST /v1/commits`](https://docs.abacuslabs.ai/concepts/commits). |
| `recommended` | `true` for the first option. |
| `label`, `tradeoff` | The rung. |
| `engine` | `layered` or `templates`. |
| `trades` | Broker-ready trades. See below. |
| `trade_summary` | Counts and dollars bought and sold. Every trade is in `trades`. |
| `impact` | `tracking_error`, `volatility`, `beta`, `cash` as before / after / change; `tax` (realized gain and loss by term, and `estimated_tax` in dollars at `policy.tax.rates`, or top federal rates without them); `turnover`; `largest_holding`; `sector_changes`. |
| `impact.tax` | `realized_gain` and `realized_loss` here are the **net** result split by sign: one of them is 0. Their sum is the net realized gain. (A commit's `tax` reports gross gains and losses and a separate `net`.) |
| `tracking` | Tracking error against the solver's benchmark, before and after, and `names_after`. |
| `guarantee` | See above. |
| `summary` | A short title for the option (often the same as `label`). |
| `commentary` | A few sentences built from the numbers. |
| `notes` | How the option was built: the engine and benchmark, limits on the buys, tax-rate assumptions. |
| `checks` | `pass` when every rule holds. |
| `certificate` | `{id, alg, kid, signature}`: an Ed25519 signature over the option id, the holdings, the market data and the trades. |
| `expires_at` | 15 minutes after the proposal. |

### Trade

```json theme={null}
{ "id": "T9D10C9A2CD0DB41C4AB", "account_id": "acct_demo_concentrated", "symbol": "XLE", "side": "sell", "quantity": 136.0,
  "est_price": 64.96, "order": { "type": "market", "time_in_force": "day" },
  "lots": [ { "id": "lot_13", "acquired_date": "2025-03-03", "cost_basis": 10538.4, "quantity": 120.0, "term": "long" },
            { "id": "lot_14", "acquired_date": "2026-07-15", "cost_basis": 1102.88, "quantity": 16.0, "term": "short" } ],
  "lot_instructions": { "how": "manual", "fallback_method": "tax_loss", "choose_by": "2026-11-17" },
  "realized_gain": { "short_term": -63.52, "long_term": -2743.2 }, "wash_sale": null,
  "notes": [ "Set the order's lot method to tax_loss, or ask the broker to apply these specific lots before 2026-11-17 and keep its confirmation." ] }
```

| Field | Meaning |
| - | - |
| `id` | 20 characters. Use it as the client order id. |
| `account_id` | The account to trade in. |
| `symbol`, `side`, `quantity` | The ticker (upper case, share classes with `-`: `BRK-B`); `buy` or `sell`; shares. |
| `est_price` | The price Abacus Labs used. Not a limit price. |
| `order` | Suggested order type and time in force. |
| `lots` | Sells in taxable accounts: the lots to sell, in order. Quantities add up to the trade. At most 8 lots; at most one partial lot, last. `cost_basis` is for the shares sold. |
| `lot_instructions` | `how` to apply the lots at this broker, the closest broker `fallback_method`, and `choose_by` (the settlement date). See [Executing at a broker](https://docs.abacuslabs.ai/concepts/brokers.md). |
| `realized_gain` | Short and long term gain from this sell. |
| `wash_sale` | Always `null`: Abacus Labs does not propose a sale that causes a wash sale. |
| `notes` | Manual steps for the broker, and warnings about unknown cost or dates. |

## Changing one thing

Take `understood.policy`, change one field, and send it back as `policy` (with no `goal`). Only what you changed moves.

```json theme={null}
{ "account_id": "acct_demo_concentrated",
  "policy": { "goal": "reduce_concentration", "positions": { "NVDA": { "max": 0.45 } },
              "tax": { "mode": "minimize", "max_tax": 1190, "rates": { "short_term": 0.408, "long_term": 0.238 } } } }
```

Reference: [Create a proposal](https://docs.abacuslabs.ai/api-reference/proposals/create-a-proposal.md), [Get a proposal](https://docs.abacuslabs.ai/api-reference/proposals/get-a-proposal.md).


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