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.

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#

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#

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#

POST /conversions/preview

{
  "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"
}

{
  "principal_after_fees": {
    "currency": "USD",
    "value": "997.40"
  },
  "indicative_rate": "1.0001",
  "expiry": "2026-05-07T10:23:34Z"
}