How to create an exchange via API

Overview

Exchange API allows you to convert one asset to another inside a merchant account.

Use this guide to check available exchange options, create an exchange, and track its processing status until the exchange reaches a final status.

Integration flow

1. Check account balance and ensure enough funds for the exchange are available by using the method - [POST] account
2. Optionally get available currency pairs by using the method - [POST] exchange/pairs
3. Optionally check minimum and maximum exchange limits for the selected currency pair by using the method - [POST] exchange/limit
4. Optionally pre-calculate the expected exchange amount by using the method - [POST] exchange/pre-calculate
5. Create the exchange by using the method - [POST] exchange/create
6. Get exchange details and current status by using the method - [POST] exchange/get

Sequence

Names of requests on the scheme indicate certain exchange API methods.

API methods

Create exchange - [POST] exchange/create

Request fields

Field	Type	Required	Description
account	string	Yes	Merchant account ID. The request will be sent for this account.
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.
payload	object	Yes	Object with exchange creation data.

Payload fields

Field	Type	Required	Description
sourceCurrency	string	Yes	Currency that will be exchanged from.
destinationCurrency	string	Yes	Currency that will be exchanged to.
amount	number	Yes	Exchange amount. The meaning of the amount depends on the selected direction.
direction	string	Yes	Exchange direction: SOURCE means the amount is set in source currency; DESTINATION means the amount is set in destination currency. Default value: SOURCE.
idempotencyKey	string	Yes	External ID in UUID format. Can be generated by the merchant while creating the exchange to prevent duplicate requests.

Request example

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "sourceCurrency": "USDT",
    "destinationCurrency": "BTC",
    "amount": 100,
    "direction": "SOURCE",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response fields

Field	Type	Description
id	number	Calypso exchange ID.
account	string	Merchant account ID.
sourceCurrency	string	Currency exchanged from.
sourceAmount	number	Amount debited from the source currency balance.
destinationCurrency	string	Currency exchanged to.
destinationAmount	number	Amount credited to the destination currency balance.
state	string	Current exchange status.
createdDate	string	Date and time when the exchange was created.

Response example 200 OK

{
  "id": 123456,
  "account": "0x0000000000000000000000000000000000000000",
  "sourceCurrency": "USDT",
  "sourceAmount": 100,
  "destinationCurrency": "BTC",
  "destinationAmount": 0.0015,
  "state": "IN_PROGRESS",
  "createdDate": "2026-06-29T09:00:00.000Z"
}

Optional methods

Method	Purpose	Main response
[POST] exchange/pairs	Returns available currency pairs for the merchant account.	currencyPairs map.
[POST] exchange/limit	Returns minimum and maximum limits for a selected currency pair.	sourceCurrency, destinationCurrency, minLimit, maxLimit.
[POST] exchange/pre-calculate	Calculates the expected exchange amount before creating an exchange.	sourceCurrency, destinationCurrency, amount, direction.
[POST] exchange/average-rate	Returns the average rate for a selected currency pair.	rate.
[POST] exchange/filter	Returns a paginated list of exchanges by filter.	result, page, size, total, totalElements.

Pre-calculate payload fields

Field	Type	Required	Description
sourceCurrency	string	Yes	Currency that will be exchanged from.
destinationCurrency	string	Yes	Currency that will be exchanged to.
amount	number	Yes	Exchange amount. The meaning of the amount depends on the selected direction.
direction	string	Yes	Exchange direction: SOURCE means the amount is set in source currency; DESTINATION means the amount is set in destination currency. Default value: SOURCE.

Limit and average rate payload fields

Field	Type	Required	Description
sourceCurrency	string	Yes	Currency that will be exchanged from.
destinationCurrency	string	Yes	Currency that will be exchanged to.

Get exchange payload fields

Field	Type	Required	Description
id	number	Yes	Calypso exchange ID.

Status lifecycle

Diagram nodes indicate exchange statuses, arrows indicate processes a successful completion of which transfers an exchange from one status to another.

Status	Description
IN_PROGRESS	The exchange has been created and is awaiting execution.
COMPLETED	Funds have been successfully exchanged on the merchant account.
FAILED	An error occurred during the exchange. There can be many reasons for the error. You may follow these remediation steps: 1. Wait a while and create a new exchange. 2. Contact our technical support.

Errors and edge cases

Case	Description
Not enough funds	Check the account balance before creating an exchange.
Currency pair is not available	Check available pairs by using [POST] exchange/pairs before creating an exchange.
Amount is outside limits	Check minimum and maximum limits by using [POST] exchange/limit.
Duplicate request	Use a unique idempotencyKey for each exchange creation request.
Processing failed	The exchange was not completed. You can create a new exchange with corrected data or contact technical support.

Related docs

Document	Link
Account API	[POST] account
Exchange API reference	Exchange API
Exchange transactions report	Exchange transactions
Limits	Limits