FX conversion

Converting between two currencies you hold is a two-call flow. You preview to get a rate and a previewId, then you execute against that id. The rate you were shown is the rate you get. This exists because a quote you cannot act on is not useful. Splitting the call lets you show a number to a customer, let them think about it, and settle on that number rather than on whatever the market has moved to by the time they answer.

Preview

Specify either fromAmount or toAmount, not both. fromAmount sells a fixed amount; toAmount buys a fixed amount and tells you what it will cost.

curl -X POST https://api.stablemint.net/v1/fx/preview \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{ "fromCurrency": "USD", "toCurrency": "EUR", "fromAmount": 100000 }'

{
  "previewId": "3f1b9c44-7e2a-4c81-9f0d-2b6a5e8d1c33",
  "fxRate": 0.9132,
  "fromCurrency": "USD",
  "fromAmount": 100000,
  "toCurrency": "EUR",
  "toAmount": 91320,
  "fromCurrencyPreviousBalance": 284500.12,
  "expiryTime": "2026-09-14T15:32:10Z"
}

Field	Meaning
`previewId`	The handle you execute against.
`fxRate`	All-in rate. Any spread is already in this number — there is no separate fee to add.
`toAmount`	What you receive. This is the figure to show a customer.
`fromCurrencyPreviousBalance`	Your balance in the sell currency before the conversion, so you can show the effect without a second call.
`expiryTime`	After this instant the `previewId` is dead.

Previewing moves no money and has no side effects. Quote as often as you need.

When a preview is refused

A preview StableMint will not book comes back as 400 — including when the only thing wrong is that you cannot afford it. The body is not a problem document: it is the quote you asked for, plus a failureReason saying why it will not be booked, and no previewId.

{
  "fromCurrency": "USD",
  "fromAmount": 500000,
  "toCurrency": "EUR",
  "toAmount": 456600,
  "fxRate": 0.9132,
  "fromCurrencyPreviousBalance": 284500.12,
  "expiryTime": "2026-09-14T15:32:10Z",
  "notes": "Insufficient balance: 500000 USD -> 456600 EUR",
  "failureReason": "NoBalance",
  "minFromAmount": 1.00,
  "maxFromAmount": 1000000.00,
  "minToAmount": 1.00,
  "maxToAmount": 1000000.00
}

`failureReason`	Meaning
`NoBalance`	Your balance in `fromCurrency` is below `fromAmount`. Compare it against `fromCurrencyPreviousBalance`, which is returned on the same body.
`AmountOutOfRange`	The amount falls outside the limits, which come back on the response so you can correct it in one step. Read them rather than hard-coding them.
`InvalidCurrency`	The pair is not convertible.
`InsufficientMasterLiquidity`	StableMint cannot fund a conversion of that size right now.

A 400 here does not mean your request was malformed. NoBalance and InsufficientMasterLiquidity are both worth retrying — the first once the account is funded, the second after a wait — even though Errors treats 400 as “retrying unchanged will not help” everywhere else. Read failureReason before deciding.

Check failureReason before reaching for previewId: a refused preview has no id to execute against.

Execute

curl -X POST https://api.stablemint.net/v1/fx/execute \
  -H "ApiKey: $STABLEMINT_API_KEY" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Nonce: $NONCE" \
  -H "Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{ "previewId": "3f1b9c44-7e2a-4c81-9f0d-2b6a5e8d1c33" }'

A previewId is single-use. It is consumed on the first successful execute. Replaying the same id does not book a second conversion — but it is not an idempotent read either, so treat a non-success response as an unknown outcome and check Transactions for a Conversion before retrying with a fresh preview.

The response restates the rate and amounts that were booked. It may also carry scaOperationId and maxAttemptCount, which indicate the conversion requires a strong customer authentication step before it settles; handle those fields if your flow can produce them rather than assuming every execute completes inline.

Handling expiry

Preview, and record expiryTime

Treat it as a hard deadline, not a guideline.

Show the rate for less time than you have

Leave yourself enough margin to make the execute call and handle a retry.

Re-preview rather than chase

If the quote lapses, get a new one and show the new number. There is no extension mechanism, and executing an expired id fails.

A conversion is two transactions, not one. It appears in Transactions as a pair sharing category: "Conversion" — an Outward leg debiting the sell currency and an Inward leg crediting the buy currency. Nothing leaves StableMint, but do not expect a single row, and do not filter on a transactionDirection of Internal: conversions never carry it.

Currencies

EUR and USD today, in either direction, between accounts you already hold. You cannot convert into a currency you have no account in.

Get started

Authentication

Core resources

Accept payments

Send money

Webhooks

Feed

Cross-chain bridge

Preview

When a preview is refused

Execute

Handling expiry

Currencies

​Preview

​When a preview is refused

​Execute

​Handling expiry

​Currencies

Preview

When a preview is refused

Execute

Handling expiry

Currencies