Exchange

This module contains endpoints for exchanging cryptocurrencies and fiat currencies.
Available currencies: btc, doge, eth, eur, eurt, ltc, pol, usdc, usdt.
The standard flow for exchange - create rate lock → create exchange

---

Retrieve exchange rate

Method: GET
Endpoint: /v1/exchange/get-rate

Response

Code: 200
Description: Returns the exchange rate

Example response

{
  "btc": 55647.81453411,
  "doge": 0.09853434,
  "eth": 2188.45355799,
  "eur": 1,
  "eurt": 0.993082,
  "ltc": 59.23864178,
  "pol": 0.35312008,
  "usdc": 0.914372,
  "usdt": 0.914208
}

---

Retrieve exchange rate and create a lock

Method: GET
Endpoint: /v1/exchange/get-lock/:externalUserId

Rate lock is valid for 40 seconds, then it expires.

Request

Parameters - required

Name	Type	Required	Example	Description
externalUserId	string	Yes	f9b430dc-7e1a-42a0-bbb4-9003935ea9f9	External user id (from your system)

Response

Code: 200
Description: Returns the exchange rate and lock details, including rates and validity period

Example response

{
  "id": "f4a33667-0824-4d73-88d3-3698a6f7c534",
  "rates": {
    "btc": 63115.99036294,
    "doge": 0.1405009,
    "eth": 2260.61529615,
    "eur": 1,
    "eurt": 0.992974,
    "ltc": 61.02279304,
    "pol": 0.27442258,
    "usdc": 0.918038,
    "usdt": 0.917832
  },
  "feePercentage": 1.49,
  "createdAt": "2024-11-05T10:54:02.982Z",
  "validUntil": "2024-11-05T22:00:42.981Z"
}

 

Code: 400
Description: User does not exist

Example response

{
  "errorCode": "P412",
  "errorName": "invalid-user"
}

---

Create and finalize an exchange

Method: POST
Endpoint: /v1/exchange

Request

Request body - required

Name	Type	Required	Description
sourceExternalUserId	string	Yes	External user id (from your system)
amount	number	Yes	The amount of exchange
currencyFrom	string	Yes	Source currency for the exchange (e.g., btc, eth)
currencyTo	string	Yes	Target currency for the exchange (e.g., eur, btc)
lockId	string	Yes	Unique identifier for the currency lock associated with the exchange

Example body request

{
  "sourceExternalUserId": "bca65c48-df49-4831-a7b2-de7903321581",
  "amount": 100,
  "currencyFrom": "btc",
  "currencyTo": "eur",
  "lockId": "123e4567-e89b-12d3-a456-426614174000"
}

Response

Code: 201
Description: Exchange created and finalized successfully

Example response

{
  "exchangeId": "7fb02323-969a-4936-94ea-86b8773ff1a2"
}

 

Code: 400
Description: User does not exist

Example response

{
  "errorCode": "P412",
  "errorName": "invalid-user"
}

 

Code: 400
Description: Exchange lock is not valid or not exist

Example response

{
  "errorCode": "P432",
  "errorName": "invalid-exchange-lock"
}

 

Code: 400
Description: Insufficient funds

Example response

{
  "errorCode": "P433",
  "errorName": "insufficient-funds"
}

---

Retrieve detailed exchange information

Method: GET
Endpoint: /v1/exchange/details/:exchangeId

Request

Parameters - required

Name	Type	Required	Example	Description
exchangeId	string	Yes	7fb02323-969a-4936-94ea-86b8773ff1a2	Unique ID of the exchange

Response

Code: 200
Description: Returns details of the exchange

Example response

{
  "id": "7fb02323-969a-4936-94ea-86b8773ff1a2",
  "sourceAmount": 100,
  "destinationAmount": 0.09524305,
  "exchangeRate": "0.0009665568",
  "createdAt": "2024-11-05T11:14:24.933Z",
  "status": "SUCCESSFUL",
  "fee": 90.92,
  "sourceCurrency": "ltc",
  "destinationCurrency": "btc",
  "exchangeLockId": "f4a33667-0824-4d73-88d3-3698a6f7c534",
  "user": {
    "externalUserId": "8bdd8c8a-e9b7-475e-9690-8a34e8b78dab",
    "email": "Giovani34@yahoo.com",
    "firstName": "Will",
    "lastName": "Hahn",
    "address": "0294 Greenholt Burgs",
    "city": "Wilfredchester",
    "country": "BM",
    "documentType": "id",
    "documentNumber": "109314",
    "pesel": null,
    "birthCountry": null,
    "birthDate": null
  }
}

 

Code: 404
Description: Exchange not found error

Example response

{
  "errorCode": "P425",
  "errorName": "exchange-not-found"
}