Convert between currencies

​

Headers

  • X-Api-Key
    Type: string
    required

    API Key

  • X-Idempotency-Key
    Type: string
    required

    Unique key to prevent duplicate requests

Body·

required
application/json
  • sourceCurrency
    Type: stringenum
    required

    Source currency

    values
    NGNUSDEURGBPBTCUSDTUSDC
  • targetCurrency
    Type: stringenum
    required

    Target currency

    values
    NGNUSDEURGBPBTCUSDTUSDC
  • accountId
    Type: number

    ID of the virtual account to use for NGN conversions. If omitted, the first available NGN account is used.

  • amount
    Type: number

    Amount in source currency to convert. Required unless a quoteId is supplied, in which case the quote's locked source amount is used and this field is ignored.

  • quoteId
    Type: string

    UUID of an existing quote to execute with its locked-in rate

Responses

  • application/json
  • application/json
  • application/json
  • 409

    Duplicate request (idempotency conflict)

  • 429

    Rate limit exceeded

Request Example for post/v1/conversions
curl https://api.esca.finance/v1/conversions \
  --request POST \
  --header 'X-Api-Key: ' \
  --header 'X-Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 500000,
  "sourceCurrency": "NGN",
  "targetCurrency": "USD",
  "quoteId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accountId": 1
}'

{
  "status": true,
  "message": "Conversion Successful",
  "data": {
    "conversionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sourceCurrency": "NGN",
    "targetCurrency": "USD",
    "sourceAmount": 500000,
    "targetAmount": 312.5,
    "appliedRate": 1600,
    "status": "COMPLETED",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:31:00.000Z",
    "quoteId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Conversion executed successfully

Previous
Conversion
Next
Get the status of a conversion