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

# Commits

> Record the option the person approved: re-checked at current prices, signed, and remembered for wash sales.

Commit an option only after the person approved that exact option. A commit records a decision. Abacus Labs places no orders. Commits are free.

```bash theme={null}
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\": \"$OPTION_ID\"}"
```

`OPTION_ID` is the `id` of the option the person approved, from `results[].data.id` of the proposal (the [Quickstart](https://docs.abacuslabs.ai/quickstart.md) sets it in its last step).

| Field | Required | Meaning |
| - | - | - |
| `Idempotency-Key` header | yes | Any unique string, such as a UUID. Over MCP: the `idempotency_key` argument. |
| `option_id` | yes | The option the person approved. Options expire 15 minutes after the proposal. |
| `fills` | no | Executions already done at the broker: `[{id, symbol, side, qty, price, date?, lots?}]`. `id` is the broker's execution id. A saved account is updated: lots, cash and history. |
| `reference` | no | Your own id for this decision. Unique per organisation. |
| `current_snapshot_id` | no | The `snapshot_id` of the holdings as they are now. A commit on changed holdings is refused. |
| `on_stale` | no | `reject` (default): refuse a stale option. `resolve`: re-solve and commit the fresh option; the certificate records it. |

## Retries and idempotency

| You send | You get |
| - | - |
| The same `Idempotency-Key` and body again | `200` with the same commit. Nothing new is recorded. |
| The same `Idempotency-Key` with a different body | `409 idempotency_conflict` |
| A new `Idempotency-Key` for an option already committed | `409 option_already_committed`, with `commit_id` |
| No `Idempotency-Key` | `400 idempotency_key_required` |

So on a timeout or a `5xx`, retry with the same key. An option commits once.

## What a commit does

1. Re-checks the option at current prices: cash, whole shares, wash sales, limits.
2. Signs the result: an Ed25519 certificate over the trades, prices, holdings and checks.
3. Remembers it. Loss sales in a commit count in every later wash-sale check on that account, and on accounts linked to it.
4. With `fills`, updates a saved account to a new version.

A commit is permanent: there is no cancel on the public API. If the person changes their mind before trading, ask for a new proposal and commit the option they choose. The earlier commit stays as a record; until it expires from the 30-day window, its loss sales still count in wash-sale checks, which errs on the safe side.

## The answer

`201 Created`, with `Location: /v1/commits/{id}`:

```json theme={null}
{ "commit_id": "cmt_8f5772607fb3", "status": "committed", "option_id": "opt_9e053f35", "account_id": "acct_demo_concentrated",
  "snapshot_id": "snap_1913...", "data_version": "mkt_562b...", "as_of": "2026-11-13 close",
  "trades": [ { "symbol": "XLE", "side": "sell", "qty": 145.0, "lots": ["lot_13", "lot_14"], "est_price": 64.96 },
              { "symbol": "UNH", "side": "sell", "qty": 25.0, "lots": ["lot_9"], "est_price": 407.46 },
              { "symbol": "NVDA", "side": "sell", "qty": 317.0, "lots": ["lot_3", "lot_2"], "est_price": 162.85 }, ... ],
  "tax": { "realized_gain": 17053.78, "realized_loss": -12107.41, "short_term": -5137.71, "long_term": 10084.08, "net": 4946.37,
           "estimated_tax": 1177.24, "tax_rates": { "short_term": 0.408, "long_term": 0.238, "state": 0.0, "niit": 0.0 }, "tax_rates_source": "default" },
  "risk": { "before": 0.2769, "after": 0.2533, "benchmark": 0.1419, "tracking_error": 0.1593, "beta_before": 1.496, "beta_after": 1.463, ... },
  "checks": { "cash": "pass", "whole_shares": "pass", "wash_sale": "pass", "limits": "pass", "status": "pass" },
  "certificate": "cert_af9e97e3...",
  "signature": { "alg": "EdDSA", "kid": "af1390ddf6affb60", "value": "M5klqkbG...", "jwks": "/.well-known/jwks.json" },
  "certified": { "version": "abacus.cert.v2", "commit_id": "cmt_8f5772607fb3", "option_id": "opt_9e053f35", "prices": { ... }, "trades": [ ... ], ... },
  "re_solved": false }
```

On a commit, `tax.realized_gain` is the gross gain and `tax.net` the net. `tax_rates_source` is `default` when no rates were sent (top federal rates), and `request` when the request or the saved account gave them. Commit trades use `qty`; proposal trades use `quantity`.

## Fills

Send what the broker executed. Each fill needs `id`, `symbol`, `side`, `qty` and `price`; sells may name `lots`.

This example uses the saved account `acct_7f3a` from [Saved accounts](https://docs.abacuslabs.ai/concepts/saved-accounts.md#save-an-account) (300 NVDA, and \$5,000 of cash after the `PATCH` there). First a proposal:

```bash theme={null}
curl -s "https://api.abacuslabs.ai/v1/proposals?wait=60" \
  -H "Authorization: Bearer $ABACUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"account_id": "acct_7f3a", "goal": "Raise $10,000 in cash with as little tax as possible"}' > raise.json
jq -c '.results[0].data | {id, trades: [.trades[] | {symbol, side, quantity, lots: [.lots[].id]}]}' raise.json
```

```json theme={null}
{"id":"opt_b01aebc4","trades":[{"symbol":"NVDA","side":"sell","quantity":31.0,"lots":["NVDA-2026-09-01"]}]}
```

The person approves it, and the broker sells 31 NVDA at \$162.85. Commit with the fill:

```json theme={null}
{ "option_id": "opt_b01aebc4",
  "fills": [ { "id": "fill_0", "symbol": "NVDA", "side": "sell", "qty": 31, "price": 162.85, "lots": ["NVDA-2026-09-01"] } ] }
```

The answer then has `status: "filled"` (or `partially_filled` when some trades have no fill yet) and:

```json theme={null}
"fills": { "recorded": ["fill_0"], "skipped_duplicates": [], "status": "filled",
           "account_update": { "account_id": "acct_7f3a", "snapshot_id": "snap_e22e...", "version": 3 } }
```

The saved account now has 69 shares in lot `NVDA-2026-09-01`, \$10,048.35 of cash, and the sale in `history` (see [Saved accounts](https://docs.abacuslabs.ai/concepts/saved-accounts.md#manage-accounts)).

Fills are recorded only with the commit; there is no separate fills call. For later executions, `PATCH` the saved account (see [Saved accounts](https://docs.abacuslabs.ai/concepts/saved-accounts.md)).

`GET /v1/commits/{id}` returns the commit, with `status` `committed`, `partially_filled` or `filled`, and its `fills`.

## Stale options

| HTTP | `code` | Why |
| - | - | - |
| `410` | `option_expired` | More than 15 minutes old. |
| `409` | `stale_snapshot` | The holdings changed since the option was made. |
| `409` | `prices_moved` | A traded symbol's price moved more than 1%. |
| `409` | `rules_failed` | The option no longer passes the rules at today's prices. |

The first three carry `replacement_option_id` when Abacus Labs can build one. Show the replacement to the person before you commit it.

## Verify a certificate

No key needed. Send the commit's `certified` object exactly as returned, and `signature.value`. With the commit answer saved as `commit.json`:

```bash theme={null}
jq '{certified, signature: .signature.value}' commit.json | \
  curl -s https://api.abacuslabs.ai/v1/certificates/verify -H "Content-Type: application/json" -d @-
```

```json theme={null}
{ "valid": true, "certificate_id": "cert_af9e97e3...", "kid": "af1390ddf6affb60" }
```

A changed payload answers `{"valid": false, "reason": "signature does not match the payload"}`. To verify offline, use the Ed25519 public key at `GET /.well-known/jwks.json`. A certificate shows what Abacus Labs checked, at which prices. It is not a statement of suitability.

Reference: [Create a commit](https://docs.abacuslabs.ai/api-reference/commits/create-a-commit.md), [Get a commit](https://docs.abacuslabs.ai/api-reference/commits/get-a-commit.md), [Verify a certificate](https://docs.abacuslabs.ai/api-reference/commits/verify-a-certificate.md).


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