Calculate exchange

curl --request POST \
  --url https://api.example.com/api/v1/user/exchange/calculate

const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/user/exchange/calculate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

POST

api

user

exchange

calculate

Calculate exchange

curl --request POST \
  --url https://api.example.com/api/v1/user/exchange/calculate

const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/user/exchange/calculate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Requires Authorization: Bearer <user-access-token> — the token from Verify login code. See Authentication for details.

Calculates how much the user would receive when converting one currency to another, applying the Qash spread and fees to the market rate. This endpoint is read-only — it does not execute any transaction or reserve funds. The returned quote is valid until expiresAt (typically 30–60 seconds). Pass the quoted rate to your UI before asking the user to confirm the exchange.

Request

POST /api/v1/user/exchange/calculate
Authorization: Bearer <user-access-token>

Body

Field	Type	Required	Description
`fromAsset`	string	Yes	Source currency: `"USD"`, `"COP"`, or `"USDC"`
`toAsset`	string	Yes	Target currency: `"USD"`, `"COP"`, or `"USDC"`
`fromAmount`	number	Yes	Amount to convert, as a decimal value in `fromAsset`’s major unit — e.g. `100` for USD 100.00

{
  "fromAsset": "USD",
  "toAsset": "COP",
  "fromAmount": 100
}

Response

200 OK

{
  "success": true,
  "data": {
    "fromAsset": "USD",
    "toAsset": "COP",
    "fromAmount": 100,
    "toAmount": 415823,
    "rate": 4158.23,
    "expiresAt": "2026-06-05T14:05:00.000Z",
    "signature": "eyJhbGciOiJIUzI1NiJ9.eyJmcm9tQXNzZXQiOiJVU0QiLCJ0b0Fzc2V0IjoiQ09QIn0.abc123",
    "signatureVersion": "v1"
  }
}

`data`

Field	Type	Description
`fromAsset`	string	Source currency
`toAsset`	string	Target currency
`fromAmount`	number	Input amount, decimal value in `fromAsset`’s major unit
`toAmount`	number	Output amount, decimal value in `toAsset`’s major unit, after applying the quoted rate
`rate`	number	Exchange rate including the Qash spread
`expiresAt`	string	ISO 8601 timestamp — quote is invalid after this time
`signature`	string	Cryptographic signature of the quote — pass this to the execute endpoint to lock in the rate
`signatureVersion`	string	Signature algorithm version — currently `"v1"`

Both fromAmount and toAmount are decimal values in their respective asset’s major unit — toAmount: 415823 above means COP 415,823.00, not COP 4,158.23. Never use floating point arithmetic to compute these values before sending them.

Store the signature and expiresAt values — they are required to execute the exchange. A quote cannot be executed after expiresAt.

Exchange rates / TRM

Cards

Users

Login

User profile

KYC

Account Management

Financials

Calculate exchange

Request

Body

Response

`data`

​Request

​Body

​Response

​data

Request

Body

Response

`data`