Convert API

The Convert API lets you swap between the currencies held in your merchant balance at the current market price — the same engine that powers the Swap tab in the merchant dashboard, now callable from your backend.

Get conversion price

Returns an indicative quote for a conversion at the current market price — the effective rate and the resulting amounts. Nothing is debited or reserved; call it as often as you need before executing.

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Request parameters

🟢 200 OK · application/json

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

Response fields

• The quote is indicative only — the market price can move between the quote and the execute call.
• No balance is debited or reserved by this call.

Execute convert

Executes a conversion at the current market price and updates your merchant balance. There is no separate "commit a quote" step — call this directly with the amount you want to convert.

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Request parameters

🟢 200 OK · application/json

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

Response fields

Convert statuses

Errors

On failure the response has state: 1 and an error_code — shared by both /v1/convert/price and /v1/convert:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

Automatic conversion of incoming payments

Auto-convert is a project setting for incoming invoice and static-wallet credits. It is configured in the merchant dashboard, not by adding fields to /v1/payment. Each rule selects one or more source currencies and a target currency.

When conversion completes, payment info and merchant webhooks can include:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

The amount domains are intentionally separate:

• payment_amount — what was detected on-chain in the source payment currency;
• merchant_amount — the net source amount attributable to the merchant before conversion;
• convert.amount — the amount credited in convert.to_currency;
• convert.rate and convert.commission — the executed conversion result, not a price you should recompute locally.

Auto-convert failure and fallback

Conversion is downstream of receiving the blockchain payment. Market availability, minimum order sizes, precision limits, exchange timeouts, and insufficient executable liquidity can delay or prevent conversion.

• Deposits below the global/project minimum bypass the conversion pipeline and credit the source currency.
• Transient failures can be retried asynchronously.
• Large or untradeable deposits can fall back to a source-currency credit after the retry policy is exhausted.
• A payment can therefore be valid even when the desired target-currency conversion did not occur.

Your integration should persist the verified payment first, then reconcile the actual credited currency from payment info, the optional convert block, and merchant balances. Do not block acknowledgement of the payment webhook while waiting on your own analytics or notification systems.

Auto-convert acceptance tests

Test at least: successful direct conversion, bridge/multi-hop conversion, dust below minimum, transient retry, fallback to source currency, underpayment, overpayment, duplicate webhook, missing convert, and reconciliation after an ambiguous timeout.

Manual conversion edge cases

• /v1/convert/price is an indicative preview; market movement can change the execution result.
• amount_type: from fixes the source-side request, while amount_type: to requests a target-side amount. Do not swap the meaning when presenting confirmation UI.
• A pair without a direct market can be routed through an intermediate currency. If only one leg completes, partially_completed reports the intermediate credit.
• If an execute call times out, reconcile before retrying. A market order can execute even when its HTTP response is lost.
• Treat failed as a state to reconcile, not as permission to apply a local compensating balance entry; the platform owns debit/refund accounting.