# Operations

> API Kickstart for fee previews, indicative prices, withdrawals, and conversions.

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

This group covers real financial execution. Read it from preview into action:
start with fee or price estimation, then move into mutating execution requests
across withdrawal, conversion, and ramp families.

> **Why this group exists:** `fee-previews` and `prices` help callers inspect execution inputs before submission. `withdrawals`, `conversions`, `on-ramp-sessions`, and `off-ramp-sessions` are the mutating execution surfaces that turn intent into runtime operation state.

> **Coming soon:** Of the operations on this page, `fee-previews`, `prices/indicative`, `withdrawals`, and `conversions` are exposed in /openapi.json . `on-ramp-sessions` and `off-ramp-sessions` are being prepared and are not yet callable — see On-Ramp And Off-Ramp for the canonical model.

## Preview And Execute

### Create fee preview

Pre-execution fee check. Create a fee preview when the integration needs visible costs before submitting a real operation.

[API Reference: Create fee preview (POST)](/docs/api/reference/fee-previews/fee-previews-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/fee-previews
```
**Request Body — application/json**
```json
{
  "operation_type": "withdrawal_crypto",
  "principal_amount": {
    "amount": "100.00",
    "currency": "USDC"
  },
  "requested_at": "2026-05-01T10:00:00Z",
  "service_type": "withdrawal_crypto",
  "settlement_amount": null,
  "subject_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```
**200 Fee Preview**

```json
{
  "fee_preview": {
    "binding": "non_binding",
    "computed_at": "2026-05-01T10:00:00Z",
    "enterprise_ca_version": 2,
    "fee_summary": {
      "components": [
        {
          "type": "network_fee",
          "amount": {
            "amount": "1.00",
            "currency": "USDC"
          },
          "payee_ref": null
        }
      ],
      "total": {
        "amount": "1.00",
        "currency": "USDC"
      }
    },
    "operation_type": "withdrawal_crypto",
    "platform_ca_version": 1
  }
}
```

**400 Bad Request**

```json
{
  "code": "invalid_request",
  "message": "Missing required field: principal_amount"
}
```

### Get indicative conversion price

Quoted conversion direction. Read the indicative price surface when the caller needs a directional conversion estimate before creating the real conversion request.

[API Reference: Get indicative conversion price (GET)](/docs/api/reference/prices/prices-indicative)

**Request URL — GET**
```http
GET https://business-api.youhodler.com/prices/indicative?from_asset=USDC&to_asset=BTC&amount_basis=from&from_amount=250.00&account_ref=client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
```
**200 Indicative Price**

```json
{
  "amount_basis": "from",
  "binding": false,
  "calculated_at": "2026-05-01T10:00:00Z",
  "expires_at": "2026-05-01T10:00:00Z",
  "flow_type": "conversion",
  "from_amount": {
    "currency": "USDC",
    "value": "250.00"
  },
  "from_asset": "USDC",
  "indicative_price": {
    "computed_at": "2026-05-01T10:00:00Z",
    "price": "65789.47",
    "price_type": "indicative"
  },
  "pricing_mode": "indicative",
  "to_amount": {
    "currency": "BTC",
    "value": "0.00380000"
  },
  "to_asset": "BTC"
}
```

### Create withdrawal

Outbound account-scoped execution. Create a withdrawal when value should leave the operating account boundary through an explicit rail and destination.

[API Reference: Create withdrawal (POST)](/docs/api/reference/withdrawals/withdrawals-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/withdrawals
```
**Request Body — application/json**
```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "amount": {
    "currency": "EUR",
    "value": "100.00"
  },
  "rail": "fiat",
  "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```
**202 Withdrawal Accepted**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "approval_ref": null,
  "created_at": "2026-05-01T10:00:00Z",
  "failure_reason": null,
  "family": "withdrawal",
  "family_params": {},
  "fee_summary": {
    "components": [
      {
        "amount": {
          "currency": "USDC",
          "value": "1.00"
        },
        "kind": "network_fee"
      }
    ],
    "total": {
      "currency": "USDC",
      "value": "1.00"
    }
  },
  "fill_rate": null,
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "principal_amount": {
    "currency": "USDC",
    "value": "250.00"
  },
  "settled_at": null,
  "status": "executing",
  "subject_attribution": {
    "actor": null,
    "approved_by": null,
    "authenticated_principal": {
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "kind": "user",
      "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "enterprise_binding": {
      "tenant_type": "enterprise",
      "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "federation": null,
    "identity_source": "platform-managed",
    "initiated_by": null,
    "subject": {
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "kind": "user",
      "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  },
  "updated_at": "2026-05-01T10:00:00Z"
}
```

**400 Bad Request**

```json
{
  "code": "invalid_request",
  "details": {
    "reason": "missing_required_field"
  },
  "message": "The withdrawal request payload is invalid."
}
```

### Create conversion

In-account asset change. Create a conversion when the operating account needs to change one asset into another through the canonical conversion family.

[API Reference: Create conversion (POST)](/docs/api/reference/conversions/conversions-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/conversions
```
**Request Body — application/json**
```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "from_amount": {
    "currency": "USDC",
    "value": "250.00"
  },
  "to_currency": "BTC"
}
```
**202 Conversion Accepted**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "approval_ref": null,
  "created_at": "2026-05-01T10:00:00Z",
  "failure_reason": null,
  "family": "withdrawal",
  "family_params": {},
  "fee_summary": {
    "components": [
      {
        "amount": {
          "currency": "USDC",
          "value": "1.00"
        },
        "kind": "network_fee"
      }
    ],
    "total": {
      "currency": "USDC",
      "value": "1.00"
    }
  },
  "fill_rate": null,
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "principal_amount": {
    "currency": "USDC",
    "value": "250.00"
  },
  "settled_at": null,
  "status": "executing",
  "subject_attribution": {
    "actor": null,
    "approved_by": null,
    "authenticated_principal": {
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "kind": "user",
      "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "enterprise_binding": {
      "tenant_type": "enterprise",
      "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "federation": null,
    "identity_source": "platform-managed",
    "initiated_by": null,
    "subject": {
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "kind": "user",
      "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  },
  "updated_at": "2026-05-01T10:00:00Z"
}
```

**400 Bad Request**

```json
{
  "code": "action_token_required",
  "message": "A step-up action token is required for this operation."
}
```

### Create on-ramp session

Inbound purchase surface. Create an on-ramp session when a caller needs a guided fiat-to-asset acquisition flow tied back to an account boundary.

[API Reference: Create on-ramp session (POST)](/docs/api)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/on-ramp-sessions
```
**Request Body — application/json**
```json
{
  "account_ref": "client-accounts/aaa111",
  "fiat_currency": "EUR",
  "asset": "BTC"
}
```
**201 On-Ramp Session**

```json
{
  "id": "ors_123",
  "resource": "on-ramp-session",
  "status": "requested"
}
```

### Create off-ramp session

Outbound liquidation surface. Create an off-ramp session when an asset position needs a guided asset-to-fiat exit path.

[API Reference: Create off-ramp session (POST)](/docs/api)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/off-ramp-sessions
```
**Request Body — application/json**
```json
{
  "account_ref": "client-accounts/aaa111",
  "asset": "BTC",
  "fiat_currency": "EUR"
}
```
**201 Off-Ramp Session**

```json
{
  "id": "ofs_123",
  "resource": "off-ramp-session",
  "status": "requested"
}
```