postPreview a conversion
Authentication: Send Authorization: Bearer <access_token>.
Returns a non-binding ledger-native conversion preview for display. economics names source gross amount, fee summary, source principal amount, indicative rate, and target amount explicitly; binding is always false. Preview does not reserve funds, lock a rate, create an executable quote, or resolve external settlement facts. Creating/executing a conversion may recompute fees and rate before ledger posting.
Parameters
| Name | Location | Type | Required | Description and constraints |
|---|---|---|---|---|
Idempotency-Key |
header | string | No | Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying. minLength: 1; maxLength: 128 |
Request
Required request body.
Request body schema
| Field | Type | Required | Description and constraints |
|---|---|---|---|
account_ref |
string | Yes | pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ |
from_amount |
object | Yes | No additional fields |
to_currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
Additional fields are not accepted.
Request body schema.from_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
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"
}Responses
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"
}
}Operation succeeded.
Response 200 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
binding |
false | Yes | |
calculated_at |
string | Yes | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ |
economics |
object | Yes | No additional fields |
execution_min_source_amount |
object or null | Yes | |
expires_at |
string or null | Yes | |
fee_summary |
object | Yes | No additional fields |
from_amount |
object | Yes | No additional fields |
indicative_price |
object | Yes | No additional fields |
min_source_amount |
object | Yes | No additional fields |
principal_amount |
object | Yes | No additional fields |
to_amount |
object | Yes | No additional fields |
Additional fields are not accepted.
application/json body.economics
| Field | Type | Required | Description and constraints |
|---|---|---|---|
binding |
false | Yes | |
fee_summary |
object | Yes | No additional fields |
indicative_rate |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
source_gross_amount |
object | Yes | No additional fields |
source_principal_amount |
object | Yes | No additional fields |
target_amount |
object | Yes | No additional fields |
Additional fields are not accepted.
application/json body.economics.fee_summary
| Field | Type | Required | Description and constraints |
|---|---|---|---|
components |
object[] | Yes | |
total |
object | Yes | No additional fields |
Additional fields are not accepted.
application/json body.economics.fee_summary.components
Type: object[].
application/json body.economics.fee_summary.components item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
amount |
object | Yes | No additional fields |
kind |
"platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |
Additional fields are not accepted.
application/json body.economics.fee_summary.components item.amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.economics.fee_summary.total
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.economics.source_gross_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.economics.source_principal_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.economics.target_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.execution_min_source_amount
At least one alternative must match.
application/json body.execution_min_source_amount: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.execution_min_source_amount: alternative 2
Type: null.
application/json body.expires_at
At least one alternative must match.
application/json body.expires_at: alternative 1
Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
application/json body.expires_at: alternative 2
Type: null.
application/json body.fee_summary
| Field | Type | Required | Description and constraints |
|---|---|---|---|
components |
object[] | Yes | |
total |
object | Yes | No additional fields |
Additional fields are not accepted.
application/json body.fee_summary.components
Type: object[].
application/json body.fee_summary.components item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
type |
"platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes | |
amount |
object | Yes | No additional fields |
payee_ref |
string | Yes | pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ |
Additional fields are not accepted.
application/json body.fee_summary.components item.amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.fee_summary.total
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.from_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.indicative_price
| Field | Type | Required | Description and constraints |
|---|---|---|---|
computed_at |
string | Yes | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ |
expires_at |
string or null | No | |
price |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
price_type |
"indicative" | Yes | |
provider_hint |
string or null | No |
Additional fields are not accepted.
application/json body.indicative_price.expires_at
At least one alternative must match.
application/json body.indicative_price.expires_at: alternative 1
Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
application/json body.indicative_price.expires_at: alternative 2
Type: null.
application/json body.indicative_price.provider_hint
At least one alternative must match.
application/json body.indicative_price.provider_hint: alternative 1
Type: string.
application/json body.indicative_price.provider_hint: alternative 2
Type: null.
application/json body.min_source_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.principal_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
application/json body.to_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
Response 400 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
code |
string | Yes | |
data |
object | No | No additional fields |
details |
object | No | Additional fields allowed |
message |
string | Yes |
Additional fields are not accepted.
application/json body.data
| Field | Type | Required | Description and constraints |
|---|---|---|---|
acr_values |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
blockers |
object[] | No | For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition. |
code |
string | No | For legal refusals: the document code the refusal is about. |
max_age |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
max_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields |
min_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields |
published_version |
string | No | For document_version_superseded: the version currently published. |
reason |
string | No | Typed refinement of code, from the failing service's contract. |
resource |
string | No | Resource kind a resource_not_found refers to. |
retry_after_ms |
integer | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
source |
string | No | For not_admissible: the gate that denied (verification, lifecycle, policy, compliance). |
Additional fields are not accepted.
application/json body.data.blockers
For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
Type: object[].
application/json body.data.blockers item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
description |
string | Yes | |
type |
"non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes | |
assets |
object[] | No | minItems: 1 |
count |
integer | No | minimum: 0; maximum: 9007199254740991 |
Additional fields are not accepted.
application/json body.data.blockers item.assets
Type: object[]. minItems: 1
application/json body.data.blockers item.assets item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
asset |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
kind |
"balance" / "held" / "owed" / "unsettled" | Yes |
Additional fields are not accepted.
application/json body.data.max_source_amount
For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
application/json body.data.min_source_amount
For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
Response 401 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
code |
string | Yes | |
data |
object | No | No additional fields |
details |
object | No | Additional fields allowed |
message |
string | Yes |
Additional fields are not accepted.
application/json body.data
| Field | Type | Required | Description and constraints |
|---|---|---|---|
acr_values |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
blockers |
object[] | No | For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition. |
code |
string | No | For legal refusals: the document code the refusal is about. |
max_age |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
max_source_amount |
object or null | No | For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields |
min_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields |
published_version |
string | No | For document_version_superseded: the version currently published. |
reason |
string | No | Typed refinement of code, from the failing service's contract. |
resource |
string | No | Resource kind a resource_not_found refers to. |
retry_after_ms |
integer or null | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
source |
string | No | For not_admissible: the gate that denied (verification, lifecycle, policy, compliance). |
Additional fields are not accepted.
application/json body.data.blockers
For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
Type: object[].
application/json body.data.blockers item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
description |
string | Yes | |
type |
"non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes | |
assets |
object[] | No | minItems: 1 |
count |
integer | No | minimum: 0; maximum: 9007199254740991 |
Additional fields are not accepted.
application/json body.data.blockers item.assets
Type: object[]. minItems: 1
application/json body.data.blockers item.assets item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
asset |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
kind |
"balance" / "held" / "owed" / "unsettled" | Yes |
Additional fields are not accepted.
application/json body.data.max_source_amount
For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
application/json body.data.min_source_amount
For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
Response 403 schema
Content type: application/json.
See response 401 schema.
Response 409 schema
Content type: application/json.
See response 401 schema.
Response 422 schema
Content type: application/json.
See response 401 schema.
Response 500 schema
Content type: application/json.
See response 401 schema.
Response 502 schema
Content type: application/json.
See response 400 schema.
Response 503 schema
Content type: application/json.
See response 400 schema.