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

# Accounts and lots

> The data your agent sends: accounts, positions and tax lots from any broker.

Every call takes the person's account in one of these ways:

| Field | Send |
| - | - |
| `account` | One account inline, or `{"id": "..."}` of a [saved account](https://docs.abacuslabs.ai/concepts/saved-accounts.md). |
| `account_id` | Proposals and trade checks: a saved account. With `accounts`, the account to trade in. |
| `accounts` | All of the person's accounts, at any brokers. With more than one, proposals and checks need `account_id`. |
| `snapshot_id` | The `ids.snapshot_id` of an earlier answer: the same holdings, without sending them again. |

An inline account is kept for 24 hours (`account_expires_at`), so its `id` and `snapshot_id` work in follow-up calls; then it is forgotten. A [saved account](https://docs.abacuslabs.ai/concepts/saved-accounts.md) stays until you delete it. Either way the account counts as one [portfolio](https://docs.abacuslabs.ai/credits.md#portfolios) for the month: send the same `id` each time.

Send what the broker gives you and leave out what it does not. Abacus Labs never treats a missing cost as 0.

```json theme={null}
{
  "accounts": [
    {
      "id": "acct_7f3a",
      "broker": "public",
      "tax_type": "taxable",
      "cash": 3000.00,
      "positions": [
        { "symbol": "NVDA", "quantity": 300,
          "lots": [
            { "id": "NVDA;2023-02-10;45.00;200", "quantity": 200, "cost_basis": 9000.00, "acquired_date": "2023-02-10" },
            { "id": "NVDA;2026-09-01;170.00;100", "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": "ira_22", "broker": "schwab", "tax_type": "tax_deferred", "cash": 900.00,
      "positions": [ { "symbol": "BND", "quantity": 100 } ] }
  ]
}
```

Numbers are JSON numbers (strings holding numbers are accepted). Money is in dollars, quantities in shares, rates and weights are fractions. Dates are `YYYY-MM-DD`. Account ids and lot ids come back exactly as you sent them. Trades and lot instructions use each symbol as you sent it (`BRK.B` stays `BRK.B`). Analysis results and saved accounts use an upper-cased form with `.` and `/` turned into `-` (`BRK-B`). A lot sent without an `id` gets one (`lot_3`). An account saved without an `id` gets an Abacus Labs id (`acct_...`).

## Account

| Field | Type | Required | Meaning |
| - | - | - | - |
| `id` | string | yes | Your id for the account. Returned on every trade. Unique in the request. |
| `tax_type` | `taxable`, `tax_deferred`, `tax_free` | no, default `taxable` | How sales are taxed. `tax_deferred`: traditional IRA, 401(k), 403(b). `tax_free`: Roth IRA, Roth 401(k), HSA, 529. Common broker labels (`ira`, `roth_ira`, `401k`, `brokerage`, ...) are accepted. |
| `broker` | string | no | Used to fill `lot_selection`. Accepted: `public`, `etrade` (also `e*trade`, `e-trade`), `apex`, `drivewealth`, `ibkr` (also `interactive brokers`), `schwab`, `fidelity`, `vanguard`, `tradier`, `webull`, `robinhood`, `alpaca`. Anything else means `manual`. |
| `lot_selection` | `on_order`, `after_trade`, `manual`, `fifo_only` | no | How specific lots can be chosen at this broker. See [Executing at a broker](https://docs.abacuslabs.ai/concepts/brokers.md). Filled from `broker`, else `manual`. |
| `cash` | number | no, default 0 | Cash available to trade. Send money-market funds as positions. |
| `positions` | array | no | Holdings. |
| `recent_trades` | array | no | Trades from the last 31 days: `{symbol, side, quantity, date, realized_gain?}`. Needed for wash sales. A sell without `realized_gain` is assumed to be at a loss. |
| `rules` | object | no | `whole_shares` (default true), `max_position`, `max_sector`, `min_cash`. |
| `policy` | object | no | Saved accounts: the standing [policy](https://docs.abacuslabs.ai/concepts/policy.md). |
| `source` | object | no | `format`: `abacus` (default), `plaid` or `snaptrade`. See below. |

## Position

| Field | Type | Required | Meaning |
| - | - | - | - |
| `symbol` | string | yes | The ticker. Share classes as `BRK.B`, `BRK-B` or `BRK/B`. |
| `quantity` | number | yes | Shares held. Short positions are not supported yet. |
| `lots` | array | no | Tax lots. Leave out if you do not have them. |
| `figi`, `cusip`, `isin` | string | no | Other identifiers. |
| `price` | number | no | Your price; used only when Abacus Labs has none for the security. |

## Lot

| Field | Type | Required | Meaning |
| - | - | - | - |
| `quantity` | number | yes | Shares in the lot. |
| `cost_basis` | number or null | yes | Total cost of the lot in dollars (the broker's adjusted basis if it has one). `null` means unknown. |
| `acquired_date` | date | no | Decides short or long term. Missing means unknown. |
| `id` | string | no | The broker's lot id. Needed to name the lot on a sell order at Public, E\*TRADE, Apex and DriveWealth. Without it the lot gets an Abacus Labs id (`lot_3`) that the broker will not know, and responses warn you. |

**Only an average or total cost for the position?** Send one lot: `{ "quantity": 15, "cost_basis": 2400 }`. **No cost?** Leave out `lots`. **Lots cover part of the position?** The rest has unknown cost.

## What Abacus Labs does with missing data

| You send | Analysis | Tax-aware proposals |
| - | - | - |
| Lots with cost and date | Full | Full. Specific lots named on sells. |
| Cost, no date | Full | Gain known. Term unknown: counted as short term and flagged. |
| No cost | Full | Goals about tax (harvest losses, `max_tax`) do not sell it. If only this holding could meet the goal, the outcome is `infeasible` with "send the cost basis for MSFT". Other goals may sell it; its tax shows as unknown. |
| Any lots in a `tax_deferred` or `tax_free` account | Full | Not needed: sales there are not taxed. |

Proposals and trade checks list the gaps in `provenance.data_quality` (`unknown_cost`, `unknown_term`, `unresolved_symbols`) and say what each one means in `warnings`. Symbols Abacus Labs could not price are left out of value, weights and risk.

## Several accounts

Send all of the person's accounts. Analysis treats them as one household (tax stays per account). A proposal or trade check trades in one account, named by `account_id` (required when you send more than one). All accounts count for wash sales: a loss sale in one account is blocked if the same security, or a fund that tracks the same index, was bought in any account within 30 days, including IRAs. `wash_sale_policy: "exact"` counts only the same security. Saved accounts also remember the loss sales you [committed](https://docs.abacuslabs.ai/concepts/commits.md).

## Aggregator payloads

Set `source.format` to send an aggregator's data as it comes:

| `format` | Send | Notes |
| - | - | - |
| `plaid` | `{account, holdings, securities}` from `/investments/holdings/get` | Holding `cost_basis` is a total; `tax_lots` become lots; cash-equivalent holdings count as cash; the account subtype sets `tax_type`. |
| `snaptrade` | `{account, positions, balances}` from `positions/all` | Position `cost_basis` is per share; `tax_lots` become lots when the add-on is on. |

An empty `tax_lots` list from either means "not supplied", not "no lots". Send each account once, by one route: the same `id` twice is `422 duplicate_account`.


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