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? Returns economics with source gross amount, fee summary, source principal amount, indicative rate, and target amount. binding is always false; expires_at may be null.

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
POST /conversions/preview

Request Body

application/json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "from_amount": {
    "currency": "USD",
    "value": "250.00"
  },
  "to_currency": "BTC"
}

Response

application/json
{
  "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"
  }
}