# Operations

> Canonical operation model that unifies multiple financial families behind one OperationView read shape with a shared lifecycle.

Source: https://business-api-docs.youhodler.com/docs/concepts/operations

The public money-movement model is centered on `OperationView`. Multiple
families use different request bodies, but they converge on one lifecycle
shape, one status model, and one canonical read surface for operators and
integrations.

Conceptually, this is the page that turns many endpoints into one execution
story.

> **Practical rule:** Read family-specific create requests as entry points. Read `OperationView` as the canonical runtime state once the request exists in the system.

## Mental Model

An operation starts as a family-specific request, then becomes a canonical
readable object with lifecycle, fee, attribution, and approval context.

That lets an integrator do two useful things:

- submit different financial families through the correct request surface
- consume one normalized runtime model after submission

## Family Types

The current public families include:

- `deposit`
- `withdrawal`
- `conversion`
- `internal_transfer`
- `on_ramp`
- `off_ramp`

## Lifecycle Status

`OperationStatus` tracks the lifecycle from request to outcome, including:

- `requested`
- `admissible`
- `pending_approval`
- `executing`
- `executed`
- `partially_settled`
- `settled`
- `ledger_visible`
- `failed`
- `cancelled`

## Nested Structure

`OperationView` is not just an amount and a status. It usually combines:

- `account_ref`
- `principal_amount`
- `fee_summary`
- `approval_ref`
- `subject_attribution`
- `failure_reason`
- `family_params`

Read that as a layered object:

1. execution boundary
2. monetary intent
3. governance context
4. attribution
5. family-specific details

## Operation View

The canonical operation read model includes:

- `account_ref`
- `principal_amount`
- `fee_summary`
- `approval_ref`
- `failure_reason`
- `subject_attribution`
- `family_params`

This lets integrators render one lifecycle model across multiple financial
families.

## How This Appears In The API

**Request Body — application/json**
```json
{
  "account_ref": "client-accounts/55555555-5555-4555-8555-555555555555",
  "amount": {
    "value": "250.00",
    "currency": "USD"
  },
  "destination_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "rail": "fiat"
}
```
**Pending approval**

```json
{
  "id": "op_123",
  "family": "withdrawal",
  "status": "pending_approval",
  "account_ref": "client-accounts/55555555-5555-4555-8555-555555555555",
  "principal_amount": {
    "value": "250.00",
    "currency": "USD"
  },
  "approval_ref": "approvals/apr_456",
  "fee_summary": {
    "total": {
      "value": "3.00",
      "currency": "USD"
    }
  }
}
```

**Executed**

```json
{
  "id": "op_123",
  "family": "withdrawal",
  "status": "executed",
  "account_ref": "client-accounts/55555555-5555-4555-8555-555555555555",
  "principal_amount": {
    "value": "250.00",
    "currency": "USD"
  },
  "approval_ref": "approvals/apr_456",
  "fee_summary": {
    "total": {
      "value": "3.00",
      "currency": "USD"
    }
  }
}
```