# Financial operations

A financial operation records one exact request to move funds. It has its own id, consent and
execution lifecycle, whether an agent proposed the request or a user prepared a withdrawal
directly. Read it through [`financialOperations.get`](/api-reference/financial-operations/financial-operations-get)
or list it through [`financialOperations.list`](/api-reference/financial-operations/financial-operations-list).

```bash
export FIN_OPERATION_ID='<operationId from the response>'
curl --fail-with-body -sS \
  "$FIN_BASE_URL/v1/users/$FIN_USER_ID/financial-operations/$FIN_OPERATION_ID" "${FIN_AUTH[@]}"
curl --fail-with-body -sS \
  "$FIN_BASE_URL/v1/users/$FIN_USER_ID/financial-operations?runId=$FIN_RUN_ID" "${FIN_AUTH[@]}"
```

Use the credentials and variables from the [quickstart](/quickstart). Lists can
filter by `runId`, `conversationId` or `origin`, and return ordinary cursor pages.

## Request identity and consent

For `origin: "agent"`, the operation links to the actual conversation, stable agent run and
recorded model tool call. An automation occurrence id is present only when an actual occurrence
exists. For `origin: "direct"`, there is no conversation or model call; those links are null.

`request` contains the ordered actions and bounds that were reviewed. `requestApproval` exposes
the exact request's decision and contract, while `grantApprovalId` identifies the approval that
created the execution grant. An authorized automation may use a standing grant without opening
another request approval. These links distinguish the proposed action from the consent that
allows it to execute.

For a direct withdrawal, `wallets.prepareWithdrawal` returns `operationId`, `approvalId`,
`fingerprint`, expiry and contract. Show those terms and have `wallets.confirmWithdrawal` echo
the approval id and fingerprint. Keep the operation id: `wallets.getWithdrawal` provides its
withdrawal view, and `financialOperations.get` provides the full financial evidence.

## Execution and settlement are different facts

| Field | How to interpret it |
| --- | --- |
| `state` | The command's lifecycle: prepared, denied, expired, executing, reported or uncertain. |
| `plan` | Frozen execution terms and every planned leg. Null before a plan exists. |
| `legs` | Only actual execution claims, with their current state and complete receipt when resolved. |
| `result` | The safe executor outcome, updated from verified receipts when reconciliation resolves it. |
| `terminal` | Whether this request is finished with no unresolved actual execution leg. It does not mean success. |

An execution claim means the operation reserved authority to act. A returned executor result
does not prove settlement. `reported` can still have `terminal: false` while the provider's
outcome remains unresolved. Likewise, an agent run's `completed` status says the agent finished
its work, not that a financial operation settled.

Inspect the outcome and each receipt. `settled`, `refunded` and `status: "not_executed"` describe different
resolutions. `partial` may mean mixed final results or unfinished work; `terminal` distinguishes
those cases. A denied or expired preparation is terminal with a null result because execution
never started. An approved preparation can also expire before its consent is consumed.

The planned legs and actual legs need not have the same length. Execution can stop after an
earlier leg is refused or refunded. Later unattempted actions have no invented claims or
receipts; a finished request can therefore have fewer actual legs than planned legs.

## After a timeout or uncertain result

Retain the operation id and read it again. A lost response, `pending` result or `uncertain`
state is not permission to start a replacement transfer. Fin reconciles the existing execution
against provider evidence. The operation remains readable while that evidence is incomplete;
it does not manufacture a settlement result from a successful HTTP response or model reply.

These reads expose frozen public terms and receipts. Signing keys, signatures, provider session
credentials, raw provider payloads and internal execution fences are never part of the resource.