Skip to main content
POST
/
api
/
v1
/
user
/
exchange
/
calculate
Calculate exchange
curl --request POST \
  --url https://api.example.com/api/v1/user/exchange/calculate
Requires X-Api-Key, X-Api-Secret, and Authorization: Bearer <user-jwt> headers. 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

​
Body

FieldTypeRequiredDescription
fromAssetstringYesSource currency: "USD", "COP", or "USDC"
toAssetstringYesTarget currency: "USD", "COP", or "USDC"
fromAmountnumberYesAmount to convert in base unit (not smallest 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

FieldTypeDescription
fromAssetstringSource currency
toAssetstringTarget currency
fromAmountnumberInput amount in base unit
toAmountnumberOutput amount in smallest unit after applying the quoted rate
ratenumberExchange rate including the Qash spread
expiresAtstringISO 8601 timestamp — quote is invalid after this time
signaturestringCryptographic signature of the quote — pass this to the execute endpoint to lock in the rate
signatureVersionstringSignature algorithm version — currently "v1"
fromAmount is in base units (e.g. 100 = USD 100.00), but toAmount is in smallest units (e.g. 415823 = COP 4,158.23). Keep this in mind when displaying amounts to users.
Store the signature and expiresAt values — they are required to execute the exchange. A quote cannot be executed after expiresAt.