Stablecoin Conversion

The Conversion API prices and executes asset conversions for a customer. The flow is:

Create Quote — price the conversion and get a short-lived quote_id.
Show rate, amounts, and valid_until_timestamp to your customer.
Execute Quote — execute the conversion with the quote_id. The response returns a transaction_id.
Get Conversion — poll the order by transaction_id, or wait for the conversion.completed / conversion.failed webhook.

All conversion endpoints are scoped to a customer: /v1/customers/{customer_id}/conversions/....

Create Quote

Endpoint

POST /v1/customers/{customer_id}/conversions/quote → 201 Created

Purpose

Generate a short-lived quote for converting between two assets. Use it to display pricing to your customer before execution.

Request Parameters

Field	Type	Required	Description
`from_asset.asset`	string	Yes	Asset the customer pays with (for example `USD`, `USDC`).
`from_asset.amount`	string	No	Amount to convert from. Omit if you set `to_asset.amount`.
`to_asset.asset`	string	Yes	Asset the customer receives.
`to_asset.amount`	string	No	Amount to convert to. Omit if you set `from_asset.amount`.

Amount rules:

Set the amount on exactly one side. Setting both, or neither, returns 400.
from_asset.amount set → sell-side quote: the customer pays exactly that amount, and user_obtain_amount is priced from it.
to_asset.amount set → buy-side quote: the customer receives exactly that amount, and user_pay_amount is priced from it.
Amounts are decimal strings. Per-pair minimums and maximums apply and are rejected with error code 00020004.

The request does not take a network field. Conversions move balances inside the 1Money platform; the network is chosen when you deposit or withdraw, not when you convert.

Example Request

{
  "from_asset": {
    "asset": "USD",
    "amount": "1000.00"
  },
  "to_asset": {
    "asset": "USDC"
  }
}

Example Response

{
  "quote_id": "1f581bfe-25de-42aa-9429-6802412850b3",
  "user_pay_amount": "1000.00",
  "user_pay_asset": "USD",
  "user_obtain_amount": "999.50",
  "user_obtain_asset": "USDC",
  "symbol": "USDC/USD",
  "rate": "1.0005",
  "expire_time": 30,
  "valid_until_timestamp": "2025-08-21T07:57:27.981Z"
}

Response Fields

Field	Type	Description
`quote_id`	string	Quote identifier, passed to Execute Quote.
`user_pay_amount`	string	Amount the customer pays.
`user_pay_asset`	string	Asset the customer pays.
`user_obtain_amount`	string	Amount the customer receives.
`user_obtain_asset`	string	Asset the customer receives.
`symbol`	string	Trading pair, `base/quote`. Gives the rate direction: 1 base ≈ `rate` quote.
`rate`	string	Quoted rate for `symbol`.
`expire_time`	integer	Quote lifetime in seconds (currently 30).
`valid_until_timestamp`	string	ISO 8601 timestamp when the quote expires.

Executing an expired quote returns 400 with error code 00020001. If you have not submitted it for execution, you can request a new quote. If an earlier Execute Quote request has an unresolved outcome, expiry does not establish whether it created an order. Follow Resolving an Execute Quote timeout and reconcile that operation before submitting a replacement conversion.

Execute Quote

Endpoint

POST /v1/customers/{customer_id}/conversions/hedge → 201 Created

Purpose

Execute the quoted conversion. This debits the pay asset, credits the obtain asset, and creates a conversion transaction.

Request Parameters

Field	Type	Required	Description
`quote_id`	string	Yes	UUID returned by Create Quote (36 chars).

This endpoint does not accept an Idempotency-Key header. See Error for retry and timeout handling.

Example Request

{
  "quote_id": "1f581bfe-25de-42aa-9429-6802412850b3"
}

Example Response

{
  "transaction_id": "aac5201f-7f1c-11f0-b018-de09fc637374",
  "order_status": "PENDING",
  "quote_id": "1f581bfe-25de-42aa-9429-6802412850b3",
  "user_pay_amount": "1000.00",
  "user_pay_asset": "USD",
  "user_obtain_amount": "999.50",
  "user_obtain_asset": "USDC",
  "symbol": "USDC/USD",
  "rate": "1.0005",
  "fee": "0.50",
  "fee_currency": "USD",
  "platform_fee": {
    "value": "0.50",
    "asset": "USD"
  },
  "partner_fee": {
    "value": "0",
    "asset": "USD"
  }
}

Get Conversion

Endpoint

GET /v1/customers/{customer_id}/conversions/order?transaction_id={transaction_id} → 200 OK

Purpose

Retrieve a conversion order by the transaction_id returned from Execute Quote. Returns 404 if no conversion with that transaction_id exists for the customer.

Response Fields

Get Conversion and Execute Quote return the same object:

Field	Type	Description
`transaction_id`	string	Conversion transaction identifier. Also usable with the transaction APIs.
`order_status`	string	`PENDING`, `SUCCESS`, or `FAIL`.
`quote_id`	string	Quote that was executed.
`user_pay_amount`	string	Amount debited from the customer.
`user_pay_asset`	string	Asset debited.
`user_obtain_amount`	string	Amount credited to the customer.
`user_obtain_asset`	string	Asset credited.
`symbol`	string	Trading pair, `base/quote`.
`rate`	string	Executed rate.
`fee`	string	Total trading fee.
`fee_currency`	string	Asset the fee is charged in.
`platform_fee`	object	`{ "value": string, "asset": string }` — 1Money platform fee.
`partner_fee`	object	`{ "value": string, "asset": string }` — your partner fee, `0` if none.

Order Status

`order_status`	Meaning
`PENDING`	Conversion accepted and in flight. Keep polling or wait for webhook.
`SUCCESS`	Conversion settled. Balances are final.
`FAIL`	Conversion failed or expired. No balance change.

Webhooks

Terminal states are also delivered as conversion.completed and conversion.failed webhooks, keyed by the same transaction_id. See Conversion Webhooks. Webhooks are the recommended way to track completion; poll Get Conversion only for reconciliation.

Fields no longer used

Earlier drafts of this guide described a hedge model. Those fields are not part of the API and are not returned:

hedge_id, conversion_id, status, fills, executed_at, created_at, modified_at, updated_at, valid_until, fee_asset, and any network field on from_asset / to_asset.

Use transaction_id (not hedge_id or conversion_id), order_status (not status), and valid_until_timestamp (not valid_until). Conversions settle in full or fail — there are no partial fills.