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_currency, target_currency) plus static source-amount bounds and
active status. Discover corridors with
GET /conversion-pairs
and read one by catalog ID with
GET /conversion-pairs/:id.
Discovery is global 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. Account and tenant scope filters are not accepted
by discovery; use conversion preflight for account eligibility.
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? Returnseconomicswith source gross amount, fee summary, source principal amount, indicative rate, and target amount.bindingis alwaysfalse;expires_atmay benull.
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
An executable quote would commit to economics for a bounded time. The current conversion preview does not reserve funds or lock a rate; creating a conversion may recompute fees and pricing before ledger posting.
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 /conversions/previewRequest Body
{
"account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"from_amount": {
"currency": "USD",
"value": "250.00"
},
"to_currency": "BTC"
}Response
{
"binding": false,
"calculated_at": "2026-05-01T10:00:00Z",
"economics": {
"binding": false,
"fee_summary": {
"components": [
{
"amount": {
"currency": "USD",
"value": "1.00"
},
"kind": "platform_fee"
}
],
"total": {
"currency": "USD",
"value": "1.00"
}
},
"indicative_rate": "0.00002",
"source_gross_amount": {
"currency": "USD",
"value": "250.00"
},
"source_principal_amount": {
"currency": "USD",
"value": "249.00"
},
"target_amount": {
"currency": "BTC",
"value": "0.00498000"
}
},
"execution_min_source_amount": {
"currency": "USD",
"value": "25.00"
},
"expires_at": null,
"fee_summary": {
"components": [
{
"type": "platform_fee",
"amount": {
"currency": "USD",
"value": "1.00"
},
"payee_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
],
"total": {
"currency": "USD",
"value": "1.00"
}
},
"from_amount": {
"currency": "USD",
"value": "250.00"
},
"indicative_price": {
"computed_at": "2026-05-01T10:00:00Z",
"expires_at": null,
"price": "0.00002",
"price_type": "indicative",
"provider_hint": null
},
"min_source_amount": {
"currency": "USD",
"value": "25.00"
},
"principal_amount": {
"currency": "USD",
"value": "249.00"
},
"to_amount": {
"currency": "BTC",
"value": "0.00498000"
}
}