# Abacus Labs: portfolio analysis and checked trade proposals for AI agents

You are reading the onboarding note for Abacus Labs, written for agents. Base URL: https://api.abacuslabs.ai/v1.
MCP: https://mcp.abacuslabs.ai/mcp. Full docs: https://docs.abacuslabs.ai. OpenAPI: https://api.abacuslabs.ai/openapi.json

## What it is

Your agent sends a person's account (holdings and tax lots from any broker) and a question or a goal in
plain English. Abacus Labs answers with numbers, and with lists of broker-ready trades checked against the
account's rules, taxes and wash sales.

Abacus Labs does not hold assets, place orders, forecast returns or give investment advice. It returns
options and their consequences. The person decides. You place the orders at the broker.

## 1. Get a key (one call, no sign-up)

    curl -s -X POST https://api.abacuslabs.ai/v1/keys -H "Content-Type: application/json" -d '{"use": "my-agent"}'

    -> 201 { "key": "abacus_sk_test_...", "kind": "sandbox", "plan": "personal", "scopes": ["read", "propose", "commit"],
             "claim_url": "https://app.abacuslabs.ai/claim?token=...",
             "accounts": [ {"id": "acct_demo_concentrated"}, {"id": "acct_demo_etf"}, {"id": "acct_demo_tech"} ] }

- The key is shown once. Send `Authorization: Bearer <key>` on every other call (REST and MCP).
- Each demo account has a `try` hint: a question to analyze and a goal to propose. `next` names a first call.
- Show `claim_url` to your human: signing in there moves the key and its accounts into their account (7 days).
- Live keys (`abacus_sk_live_...`) come from the dashboard: https://app.abacuslabs.ai/signup.
- A new key is on the free Personal plan: 3 portfolios and 300 credits a month, hard stop.
  Demo accounts do not count as portfolios. Limits: 1,000 calls a day per sandbox key; new keys: 20 keys an hour per address.

## 2. The calls

| call                     | what it does                                                      | credits (standard) |
|--------------------------|-------------------------------------------------------------------|--------------------|
| `POST /v1/analyze`       | Answer a question about an account. Read-only.                    | 15 |
| `POST /v1/proposals`     | Trade options for a goal and/or a policy. 202 -> poll the GET.    | 25 |
| `GET /v1/proposals/{id}` | A proposal that was still running.                                | 0 |
| `POST /v1/trades/check`  | Check drafted trades; get the nearest list that passes.           | 5 |
| `POST /v1/commits`       | Record the option the person approved. Needs `Idempotency-Key`.    | 0 |
| `GET /v1/commits/{id}`   | A commit, its certificate and fills.                              | 0 |
| `/v1/accounts`           | Optional: save, get, patch, list, delete accounts.                | 0 |

Primitives: plain reads with no model and no AI step, for when you need one fact and not an answer.

| call                                 | what it does                                                            | credits |
|--------------------------------------|-------------------------------------------------------------------------|---------|
| `GET /v1/accounts`                   | Saved accounts and inline ones still inside their 24 hours (`inline: true`, `expires_at`). `?saved=true`: saved only. | 0 |
| `GET /v1/accounts/{id}/holdings`     | The account priced now: quantity, price, value, weight, sector, cost basis, unrealized gain and lots per position; cash; total value. | 1 |
| `POST /v1/accounts/{id}/save`        | Keep an inline account: same id, no expiry.                             | 0 |
| `GET /v1/benchmarks`                 | The indexes Abacus Labs tracks, with every name, alias and ticker for each, plus saved benchmarks. | 1 |
| `POST /v1/benchmarks/resolve`        | Preview what a benchmark resolves to: label, constituents, top holdings, sources. Body `{"benchmark": ...}`. | 1 |

Questions that need the risk model (risk, tracking error, exposures, tax) go to `POST /v1/analyze`.

No auth: `POST /v1/keys`, `POST /v1/certificates/verify`, `GET /.well-known/jwks.json`.

## 3. One complete example

The task: "How risky is the demo concentrated account? Cut NVDA below 40% without more than $5,000 of
realized gains, check it, and commit it." (Real sandbox numbers, trimmed.)

Ask:

    curl -s https://api.abacuslabs.ai/v1/analyze -H "Authorization: Bearer $ABACUS_API_KEY" -H "Content-Type: application/json" \
      -d '{"account": {"id": "acct_demo_concentrated"}, "question": "How risky is this account?"}'

    -> { "object": "analysis", "answer": "... volatility 27.7% versus 14.2% for SPY ... NVDA is 52% of the account but 78.8% of modeled risk ...",
         "results": [ {"type": "risk", "data": {"vol": 0.2769, "benchmark_vol": 0.1419, "beta": 1.496, ...}}, ... ],
         "credits_charged": 15 }

Propose. Say the goal in plain English; read `understood.policy` back, since it is exactly what was solved. "No more
than $5,000 of gains" becomes `tax.max_gain: 5000` (a cap on net gain); "keep the tax under $5,000" becomes
`tax.max_tax: 5000`. For no net gain, use `tax.mode: neutral`. An option's `impact.tax` is net
(`realized_gain + realized_loss`); a commit's `tax` has gross gains, losses and `net`.

    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% without more than $5,000 of realized gains"}'

    -> 201 { "status": "succeeded", "outcome": "options",
             "results": [ {"type": "option", "data": {"id": "opt_9e053f35", "label": "Balanced",
                             "trades": [ {"symbol": "NVDA", "side": "sell", "quantity": 317, "lots": [{"id": "lot_3", ...}], ...}, ... ],
                             "impact": {"position": {"symbol": "NVDA", "before": 0.52, "after": 0.3999},
                                        "tax": {"realized_gain": 4946.37, "realized_loss": 0.0, "estimated_tax": 1177.24}, ...},
                             "guarantee": {"proven": true, "gap_bp": 96.3}, "expires_at": "..."}}, ... ] }

Check the chosen option's trades right before placing them:

    curl -s https://api.abacuslabs.ai/v1/trades/check -H "Authorization: Bearer $ABACUS_API_KEY" -H "Content-Type: application/json" \
      -d '{"account_id": "acct_demo_concentrated", "trades": [{"symbol": "NVDA", "side": "sell", "quantity": 317, "lots": ["lot_3", "lot_2"]}, ...]}'

    -> 200 { "object": "trade_check", "status": "pass", "answer": "The drafted trades pass every rule check as sent." }

Place the orders at the broker, then commit (retry with the same key returns the same commit):

    curl -s https://api.abacuslabs.ai/v1/commits -H "Authorization: Bearer $ABACUS_API_KEY" -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" -d '{"option_id": "opt_9e053f35"}'

    -> 201 { "commit_id": "cmt_8f5772607fb3", "status": "committed",
             "tax": {"realized_gain": 17053.78, "realized_loss": -12107.41, "net": 4946.37, "estimated_tax": 1177.24},
             "checks": {"cash": "pass", "whole_shares": "pass", "wash_sale": "pass", "limits": "pass", "status": "pass"},
             "signature": {"alg": "EdDSA", "kid": "...", "value": "..."}, "certified": {...} }

## 4. Every answer has the same shape

`analyze`, `proposals` and `trades/check` answer:

    { "object": "analysis | proposal | trade_check",
      "answer": "plain English; every number in it comes from results",
      "understood": { ...what Abacus Labs read from the request... },
      "results": [ { "type": "...", "data": { ... } } ],
      "warnings": [ "..." ],
      "ids": { "account_id": "...", "snapshot_id": "...", "proposal_id": "...", "decision_id": "..." },
      "provenance": { "risk_model": { "version": "...", "data_end": "..." }, "prices": "...", "engine": { ... } },
      "as_of": "2026-11-13 close", "effort": "standard", "credits_charged": 15 }

Show `answer` to the person; read numbers from `results`. Block types: `holdings`, `exposures`, `lookthrough`
(company exposure counting what the funds hold, and fund overlap), `factor_exposures`, `risk`, `tracking_error`, `tax`, `drift` (analyze); `option`, `violations`, `infeasible`,
`benchmark` (proposals and checks). Proposals add `id`, `status` and `outcome`; checks add `status`.

## 5. The accounts you send

Send `account` (one inline account, or `{"id": ...}` of a saved one), `accounts` (all of the person's accounts;
with more than one, proposals and checks need `account_id`), `account_id` (a saved account) or `snapshot_id`.

    { "id": "acct_7f3a", "broker": "public", "tax_type": "taxable", "cash": 3000.00,
      "positions": [
        { "symbol": "NVDA", "quantity": 300,
          "lots": [ { "id": "NVDA-2023-02-10", "quantity": 200, "cost_basis": 9000.00, "acquired_date": "2023-02-10" },
                    { "id": "NVDA-2026-09-01", "quantity": 100, "cost_basis": 17000.00, "acquired_date": "2026-09-01" } ] },
        { "symbol": "BRK.B", "quantity": 10, "lots": [ { "quantity": 10, "cost_basis": 3000.00 } ] },
        { "symbol": "MSFT", "quantity": 20 } ],
      "recent_trades": [ { "symbol": "XLE", "side": "sell", "quantity": 120, "date": "2026-10-22", "realized_gain": -1944.00 } ] }

- `id` (required): your id; it comes back on every trade. `tax_type`: `taxable` (default), `tax_deferred`, `tax_free`.
- Lot `cost_basis` is the total cost in dollars (`null` if unknown). Lot `id` is the broker's lot id: send it.
- Leave out what you do not have. A missing cost is never treated as 0. Gaps are listed in `provenance.data_quality`
  (`unknown_cost`, `unknown_term`, `unresolved_symbols`) and `warnings` says what each one means.
- Symbols come back upper-cased with share classes as `BRK-B`. Account and lot ids come back as sent.
- An inline account is kept 24 hours. `GET /v1/accounts` lists it with `inline: true` and `expires_at`;
  `POST /v1/accounts/{id}/save` keeps it. Every account you use counts as one portfolio a month: send the same `id`.
- Index names that work as `benchmark`: `S&P 500` (`SPY`), `Russell 1000` (`R1000`, `IWB`), `S&P 400` (`S&P MidCap 400`,
  `IJH`, `MDY`), `S&P 600`, `Russell 2000`, `Russell 3000`, `Nasdaq-100`. `GET /v1/benchmarks` has the full list.
- Plaid or SnapTrade payloads: `"source": {"format": "plaid"}` or `{"format": "snaptrade"}`.

## 6. Proposals

Send `goal` (plain English), `policy`, or both; policy fields win. `understood.policy` is what was solved:
edit one field and send it back as `policy` to change one thing.

    { "goal": "harvest_losses | invest_cash | raise_cash | reduce_concentration | reduce_sector | lower_risk |
               track_benchmark | rebalance | tilt_theme",
      "benchmark": "current | SPY | S&P 500 | half S&P 500, half ARKK | {mix} | {manager} | {weights}",
      "tracking_error": 0.01, "max_volatility": 0.15, "max_position": 0.25,
      "tax": { "mode": "harvest | minimize | neutral | ignore", "max_tax": 2000, "max_gain": 5000, "rates": { "short_term": 0.37, "long_term": 0.20 } },
      "cash": { "min": 20000, "max": 30000, "invest": true },
      "keep": ["NVDA"], "exclude": ["MO"], "exclude_themes": ["tobacco"], "buy_only": [],
      "positions": { "NVDA": { "max": 0.15 } }, "sectors": { "Information Technology": { "max": 0.30 } },
      "max_names": 100, "trading": { "whole_shares": true, "min_trade": 500, "max_trades": 40, "max_turnover": 0.10, "no_sells": false,
                   "sell_lots": "any | short_term_only | long_term_only" } }

- Weights are fractions (0.10 = 10%); money is dollars. Unknown fields: `422 invalid_policy`.
- Without `tax.rates`, tax is estimated at 40.8% short term / 23.8% long term (`warnings` says so).
- Without `buy_only`, an account of fewer than 40 names keeps its buys to what it holds when it raises cash, lowers risk,
  invests cash or cuts a position (a cut may also buy the account's index fund); a warning says when the buys had to widen.
  Harvesting and sector cuts buy from the benchmark's stocks.
- `outcome`: `options` (show them all), `clarify` (ask the person `understood.question`), `infeasible`
  (tell them which rule could not be met). Clarify and infeasible cost nothing.
- `202` + `Location`: still running. Poll `GET /v1/proposals/{id}?wait=30` until `status` is `succeeded`
  (or `failed`, free). The `202` holds the credits; the final poll reports the settled `credits_charged`.
- `effort`: `quick` | `standard` | `deep` (10 / 25 / 60 credits). `deep` often takes 1 to 2 minutes (expect 202).
  `max_credits`: refuse a call that costs more.
- Options expire after 15 minutes. Each sell names its `lots` and `lot_instructions`.

## 7. Trade checks

Always HTTP 200. `status` is `pass`, `repaired` (the `option` result is the nearest list that passes) or
`rejected`; `violations` says why. Checks cash, whole shares, position and sector limits, wash sales (across the
accounts sent, saved accounts linked to them, and committed loss sales), no shorts, no overselling, and an
optional `policy`. 5 credits for `pass` or `repaired`; `rejected` is free.

## 8. Commits

Commit only the option the person approved. `Idempotency-Key` header required (MCP: `idempotency_key`).
Same key again: the same commit (200). A stale option is refused (`410 option_expired`, `409 stale_snapshot`,
`409 prices_moved`) with a `replacement_option_id`: show it to the person first. `fills` (optional) records
executions; a saved account is updated. Certificates verify with `POST /v1/certificates/verify` or offline with
`https://api.abacuslabs.ai/.well-known/jwks.json`. A certificate shows what was checked at which prices; it says nothing about suitability, settlement or employer trading windows.

## 9. Executing at the broker

| broker                                   | `lot_instructions.how` | what you do |
|------------------------------------------|------------------------|-------------|
| Public                                   | `on_order`    | `taxLotMatchingInstructions: [{taxLotId: lot.id, quantity}]` on the sell |
| E*TRADE                                  | `on_order`    | `Instrument.lots: [{id: lot.id, size: quantity}]` on preview and place |
| Apex-cleared apps                        | `on_order`    | `lot_matching_instructions: [{open_lot_id: lot.id, quantity}]` |
| DriveWealth-cleared apps                 | `on_order`    | `taxLotDisposition: [{taxLotID: lot.id}]` |
| Interactive Brokers                      | `after_trade` | Choose the lots in Tax Optimizer the same day, by 8:30 PM ET |
| Schwab, Fidelity, Vanguard, Tradier, Webull, Robinhood | `manual` | Set the order's lot method to `fallback_method`, or ask the broker to apply the lots before `choose_by` |
| Alpaca                                   | `fifo_only`   | Nothing: Abacus Labs planned the sale oldest lots first |

## 10. Credits and headers

Prices: analyze 5 / 15 / 40, proposals 10 / 25 / 60, trade checks 5, holdings and benchmark reads 1, everything else free. Errors, unmet
goals and rejected checks are free. Headers on every authenticated `/v1` call: `Abacus-Credits-Charged`,
`Abacus-Credits-Remaining`, `Abacus-Request-Id` (and `Abacus-Credits-Held` on a 202). `Abacus-Version` is the API version
(send `Abacus-Version: 2026-11-15` to pin it); `Abacus-Api-Version` is the commit and certificate schema version.
There is no balance call.

    402  credits_exhausted        out of credits this month, or a spend cap reached (upgrade_url / top_up_url)
    402  portfolio_limit_reached  a new account over the plan's portfolio limit; accounts already used keep working
    402  max_credits_exceeded     the call costs more than max_credits (price is in the error); nothing charged

## 11. Errors

    { "error": { "code": "invalid_policy", "message": "...", "param": "policy.tracking_error", "request_id": "req_...", "http_status": 422 } }

Branch on `code`. `param` names the field; `next`, when present, says what to do.

    400  idempotency_key_required   commit without an Idempotency-Key header
    401  unauthorized               bad or missing key: get one from POST /v1/keys
    403  forbidden                  key lacks the scope
    404  not_found                  unknown account, proposal, option or commit for this key
    404  snapshot_not_found         send the account again
    404  not_available              not part of the public API
    409  option_already_committed   GET /v1/commits/{commit_id} from the error
    409  stale_snapshot / prices_moved, 410 option_expired   see replacement_option_id
    422  invalid_request / invalid_policy / invalid_benchmark / account_id_required / duplicate_account / unsupported
    429  rate_limited               daily calls used, or too many new keys from this address
    503  llm_unavailable            retry later

## 12. MCP

URL https://mcp.abacuslabs.ai/mcp (streamable HTTP), header `Authorization: Bearer <key>`. Tools:
`abacus_analyze`, `abacus_propose`, `abacus_get_proposal`, `abacus_check_trades`, `abacus_commit`
(`idempotency_key` required), `abacus_get_commit`, `abacus_create_account`, `abacus_get_account`,
`abacus_patch_account`, `abacus_list_accounts`, `abacus_delete_account`, `abacus_get_holdings`, `abacus_save_account`,
`abacus_list_benchmarks`, `abacus_resolve_benchmark`. Arguments are the REST body fields, with these
differences: path ids are arguments (`proposal_id`, `commit_id`, `account_id`); `abacus_create_account` takes the account
as `account`; `abacus_patch_account` takes the PATCH body as `changes`. API errors are tool errors (`isError`) whose text
is `Error executing tool <name>: ` followed by the JSON above. There is no OAuth sign-in yet: every client sends the key header.

    Claude Code:  claude mcp add --transport http abacus https://mcp.abacuslabs.ai/mcp --header "Authorization: Bearer $ABACUS_API_KEY"

More clients (Claude API, OpenAI, Cursor, Claude Desktop): https://docs.abacuslabs.ai/mcp-server

## 13. How to behave

- Show the person every option and its trade-offs. Do not pick for them.
- Place orders only after the person approves one option; apply its lot instructions on each sell. Commit it.
- Send every account and the recent trades. Wash-sale checks only see what you send or saved.
- Read `warnings`, and tell the person when a number rests on missing data.
- Check `understood.policy` before you show options: it is what Abacus Labs solved.
- Monitoring webhooks (`policy.monitor`) are stored but not delivered yet. Do not rely on them.

## Data

Prices: Databento, cached up to 15 minutes. Risk: Abacus Labs' factor model (`provenance.risk_model` names the
version and `data_end`). Benchmarks: SEC N-PORT fund holdings and 13F manager books, rolled forward with prices.
Goals are read by a language model with a JSON schema.
