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 or list it through financialOperations.list.
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. 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.