Jump to Content

Exchange

This guide explains how to exchange one currency for another within a user account using the Vault API.

Endpoint

POST /direct-exchange

Query Parameters

Name	Type	Required	Description
`dryRun`	`boolean`	➖	This parameter allows to check resulting rate and fee amount without executing any operation. If `true`, the API simulates the operation without executing it. This allows you to preview all the details before committing. The actual operation will only proceed if dryRun is omitted or explicitly set to `false`.

Body Parameters

Name	Type	Required	Description
`fromAccount`	`string`	✅	Identifies the `CHECKING` type of account initiating the transfer. All accounts can be retrieved using List all accounts endpoint.
`toAccount`	`string`	✅	Identifies the `CHECKING` type of account initiating the transfer. All accounts can be retrieved using List all accounts endpoint.
`fromCurrency`	`string`	✅	The original currency of the amount before conversion.
`toCurrency`	`string`	✅	The destination currency after conversion.
`fromAmount`	`string`	✅	The amount in the source currency.
`toAmount`	`string`	➖	The amount in the target currency.
`signedRate`	`object`	➖	Provides the signed exchange rate details required to execute the conversion.

`signedRate` Object

Name	Type	Required	Description
`rateRequest`	`object`	➖	Request details for the currency conversion rate.
`rate`	`string`	➖	The exchange rate for currency conversion.
`validUntil`	`string`	➖	The timestamp until which the rate remains valid.
`signature`	`string`	➖	The digital signature of the rate.

Example Request / Response

`dryRun` = `true`

Request example:

curl 'https://platform-api.dev.testessential.net/wallet/direct-exchange?dryRun=true' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-type: application/json' \
  -d '{
        "fromAccount":"64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
        "fromCurrency":"BTC",
        "toCurrency":"ETH",
        "fromAmount":"0.0001"
      }'

Response example:

{
  "id": "84d09ca6-1518-4e77-a6c4-1d0958a26c7d",
  "fromAccount": "64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
  "toAccount": "64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
  "fromCurrency": "BTC",
  "toCurrency": "ETH",
  "fromAmount": "0.00010000",
  "toAmount": "0.003379848343632860",
  "signedRate": {
    "rateRequest": {
      "fromCurrency": "BTC",
      "toCurrency": "ETH",
      "amount": 0.0001,
      "account": "64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
      "partner": "Wafee"
    },
    "rate": 33.79848343632860229074,
    "feeConfig": { "feePercent": 0.025 },
    "minFromAmount": 0.0000603534,
    "maxFromAmount": 0.05813725,
    "minToAmount": 0.0019998562649275633975430858,
    "maxToAmount": 2.004250067774286115840882,
    "exchangeRoute": {
      "routeElements": [
        { "fromCurrency": "BTC", "toCurrency": "USD", "exchange": "kraken", "rate": 68086.7 },
        { "fromCurrency": "USD", "toCurrency": "ETH", "exchange": "kraken", "rate": 0.000506534292371593 }
      ]
    },
    "validUntil": "2026-02-17T10:06:56.535Z",
    "signature": "<SIGNATURE>"
  },
  "feeAmount": "0.000084496208590822",
  "feeCurrency": "ETH",
  "status": "PENDING"
}

`dryRun` = `false`

Example Request:

curl 'https://platform-api.dev.testessential.net/wallet/direct-exchange?dryRun=false' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-type: application/json' \
  -d '{
        "fromAccount":"64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
        "toAccount":"64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
        "fromCurrency":"BTC",
        "toCurrency":"ETH",
        "fromAmount":"0.0001",
        "id":"84d09ca6-1518-4e77-a6c4-1d0958a26c7d",
        "feeAmount":"0.000084496208590822",
        "feeCurrency":"ETH"
      }'
}

Example Response:

{
  "id": "d81c1b8a-e09a-4a15-b9ea-ddc47195b52c",
  "fromAccount": "64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
  "toAccount": "64b25f29-a2c9-42ba-8fc0-f490ec0a1eda",
  "fromCurrency": "BTC",
  "toCurrency": "ETH",
  "fromAmount": "0.00010000",
  "toAmount": "0.003379848343632860",
  "signedRate": { /* structure as dryRun = true */ },
  "feeAmount": "0.000084496208590822",
  "feeCurrency": "ETH",
  "status": "SUCCESS",
  "note": "Reserve funds success;Hedging Success;Release funds success",
  "createdAt": "2026-02-17T10:06:17.256439532Z",
  "updatedAt": "2026-02-17T10:06:17.002166546Z"
}

Best Practices

Use dryRun= true to preview rate and fees before executing a live exchange.
Ensure the validUntil timestamp has not expired before confirming the operation.
ReviewfeeAmount to understand the total cost of the exchange.

Updated 6 days ago