# Conversions And Pricing

> Three-layer conversion model: discovery (conversion pairs), pricing surfaces (indicative, fee preview, full preview), and execution as a tracked operation.

Source: https://business-api-docs.youhodler.com/docs/concepts/conversions-and-pricing

Conversions are how the platform moves value between two assets. The
public API splits the model into three distinct layers — discovery,
pricing, and execution — so integrators can browse, preview, and
execute independently.

A pricing artifact is not an operation, and an operation is not a
market reference. Keeping them as distinct objects keeps integration
code aligned with the platform's internal model.

> **Practical rule:** Use the preview surfaces to show the customer what a conversion will look like. Treat a `Conversion` as the only artifact that actually moves value.

## Mental Model

Three layers, each with its own surface:

- **Discovery** — which corridors are supported (`ConversionPair`)
- **Pricing** — what the rate and fees look like before committing
(`prices/indicative`, `fee-previews`, `conversions/preview`)
- **Execution** — the canonical operation that moves value
(`Conversion`)

Discovery is configuration. Pricing is read-only and time-bounded.
Execution is a write that produces a lifecycle-tracked operation.

## Conversion Pairs

> **Coming soon:** Public discovery for supported conversion corridors is being prepared.

A `ConversionPair` represents a supported conversion corridor —
`(source_asset, target_asset)` plus product-level constraints such as
min/max size and enabled status. Discovery is reference data: a pair
existing means the corridor is allowed, not that any specific size will
fill at any specific rate. Pricing for a real request still goes
through the preview surfaces.

## Pricing Surfaces

Three pricing surfaces serve three different questions, in order of
detail:

- **`prices/indicative`** — *what is the rate right now?* A non-binding
rate for a `(base, quote)` pair. Useful for UI tickers, dashboards,
and rough sizing. No commitment, no expiry.
- **`fee-previews`** — *what fees would apply to a conversion of this
size?* Returns the fee components and an indicative rate at the
moment of issue. Read-only; reserves nothing.
- **`conversions/preview`** — *what would the whole conversion look
like?* A full simulation: principal-after-fees, indicative rate, and
an `expiry`. The closest thing to a non-binding quote — use it when
you need a single read that tells the end customer what they would
get.

None of these surfaces reserve liquidity or commit the platform to a
specific outcome. They reflect pricing rules and commercial agreements
at the moment they were issued.

## Executable Quotes

> **Coming soon:** An explicit `Quote` resource for binding, time-bounded pricing commitments is being prepared.

A `Quote` will be a first-class pricing artifact with its own
lifecycle: a bounded executable offer the platform commits to honor if
the matching conversion is submitted in time and within the stated
conditions. Quotes will expire if unused, will not move balances on
their own, and will not create ledger effect by themselves.

Until quotes land, treat the preview surfaces above as informational —
they describe pricing at issuance, not a commitment.

## Conversion Operations

A `Conversion` is the canonical execution surface. The create request
names the source/target asset, the amount, and the account scope; once
accepted it becomes a lifecycle-tracked `OperationView` with status,
executed amounts, and attribution.

Cancellation is available while the operation has not reached a
terminal status. Terminal status reflects the realized outcome — the
exact rate, fees, and amounts that ledger recognized.

## How This Appears In The API

**Request URL — POST**
```http
POST /conversions/preview
```
**Request Body — application/json**
```json
{
  "subject_ref": "clients/44444444-4444-4444-8444-444444444444",
  "account_ref": "client-accounts/55555555-5555-4555-8555-555555555555",
  "from_amount": { "currency": "USDC", "value": "1000.00" },
  "to_currency": "USD"
}
```
**Response — application/json**
```json
{
  "principal_after_fees": { "currency": "USD", "value": "997.40" },
  "indicative_rate": "1.0001",
  "expiry": "2026-05-07T10:23:34Z"
}
```