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

# Buy work lifecycle

> Move a buying goal from intent through reviewed terms, reserved funds, delivery, and verified settlement.

Buy uses the canonical goal, deal, transaction, and outcome resources. These are separate records so intent, commercial agreement, money movement, and delivery evidence remain independently reviewable.

## Goals

A goal captures what the buyer wants before a counterparty or price is final. Create it with `mode: BUY`, place the desired result in `intent`, and use `targeting` and `context` for structured constraints.

```bash theme={null}
curl https://api.darwin.so/api/v1/goals \
  --request POST \
  --header "Authorization: Bearer $DARWIN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "BUY",
    "title": "Source three editing laptops",
    "intent": "Compare three lightweight laptops under $1,500 for photo editing, including warranty and return policy.",
    "visibility": "PRIVATE",
    "targeting": { "market": "US", "maximumOptions": 3 },
    "context": { "priority": "battery-life" }
  }'
```

New goals default to active unless you set `lifecycleStatus: DRAFT`. A private goal can become public only through the reviewed publication request and approval flow. Use `GET /goals?mode=BUY` to list the selected AI's buying work.

Goal actions are state-aware: a draft can activate; an active goal can pause or complete; a paused goal can resume or complete. A completed goal can archive. Active deals or recurring agreements block completion and archival.

## Deals

A deal begins when concrete terms exist. It references the goal and records the counterparty context, obligations, delivery criteria, approved maximum cap, fee quote, tax treatment, and cancellation policy. Create deals as private drafts and update them only while they are drafts.

Sending or accepting a deal is a consequential action. The authorized buyer reviews the exact terms before Darwin changes the deal state. Internal matching sessions, routing identifiers, and provider credentials are never fields in the public deal.

## Transactions

After a deal is accepted, reserve funds with `POST /deals/{dealId}/transactions` and a unique `Idempotency-Key`. Repeating the same operation with the same key must not create a second reservation.

Amounts are represented independently in minor currency units:

* `reservedCapMinor` is the most Darwin may consume for the accepted deal;
* `subtotalMinor` is the value before tax and Darwin fees;
* `taxAmountMinor` records calculated tax;
* `darwinFeeMinor` records the immutable fee quote;
* `settledAmountMinor` is the verified final charge; and
* `releasedAmountMinor` is returned to available balance.

For a fixed $40 deal, Darwin reserves $40 and later settles $40. For a performance deal capped at $40 that verifies at $36, Darwin reserves $40, settles $36, and releases $4. Cancellation before settlement releases the unused reservation. Refunds and disputes remain transaction actions rather than edits to historical ledger fields.

<Warning>
  Never calculate spendable balance by subtracting client-side estimates. Read the wallet and transaction projections returned by Darwin; reservations can change after cancellation, verification, settlement, or refund.
</Warning>

## Outcomes

Darwin creates the canonical outcome from goal and deal lifecycle evidence. Authorized participants can submit attributable evidence with a SHA-256 digest and optional signed reference, but cannot directly mark their own delivery complete or overwrite the canonical status.

Evidence remains associated with its source principal, goal, deal, verification state, timestamps, and dispute state. Settlement consumes only the amount supported by the verified outcome and the accepted deal.

## Failure and recovery

| Condition                      | Expected behavior                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| Insufficient available balance | No reservation is created; return an exact funding requirement and direct the owner to the web wallet. |
| Repeated funding request       | The idempotency key returns the existing result instead of double-reserving.                           |
| Deal canceled                  | Release the unconsumed reservation back to available balance.                                          |
| Performance below cap          | Settle the verified amount and release the difference.                                                 |
| Evidence disputed              | Preserve the evidence and transaction history while the canonical outcome remains under review.        |

Continue to the [API reference](/reference/introduction) for exact schemas and response codes.