> For the complete documentation index, see [llms.txt](https://docs.calypso.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.calypso.money/api-reference/exchange-api.md).

# Exchange API

API for exchanges

## Pre-calculate the exchange

> Permission annotations:

```json
{"openapi":"3.0.1","info":{"title":"Public API","version":"dev"},"tags":[{"name":"Exchange API","description":"API for exchanges"}],"servers":[{"url":"https://api.calypso.money","description":"Generated server url"}],"paths":{"/api/v1/exchange/pre-calculate":{"post":{"tags":["Exchange API"],"summary":"Pre-calculate the exchange","description":"Permission annotations:","operationId":"preCalculateExchange","parameters":[{"name":"Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Sign","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithAccountContainerPreCalculateRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PreCalculateExchangeResponseDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}}}}}},"components":{"schemas":{"WithAccountContainerPreCalculateRequestDTO":{"required":["account","payload","timestamp"],"type":"object","properties":{"account":{"pattern":"^0x[0-9a-fA-F]{40}$","type":"string","description":"Merchant account ID. Request will be sent for this account"},"timestamp":{"type":"integer","description":"Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future","format":"int64"},"payload":{"$ref":"#/components/schemas/PreCalculateRequestDTO"}},"description":"Object with request data"},"PreCalculateRequestDTO":{"required":["amount","destinationCurrency","direction","sourceCurrency"],"type":"object","properties":{"sourceCurrency":{"type":"string","description":"Source currency"},"destinationCurrency":{"type":"string","description":"Destination currency"},"amount":{"type":"number","description":"Exchange amount"},"direction":{"type":"string","description":"Exchange direction","default":"SOURCE","enum":["SOURCE","DESTINATION"]}},"description":"Object with request parameters"},"PreCalculateExchangeResponseDTO":{"required":["amount","destinationCurrency","direction","sourceCurrency"],"type":"object","properties":{"sourceCurrency":{"type":"string","description":"Source currency"},"destinationCurrency":{"type":"string","description":"Destination currency"},"amount":{"type":"number","description":"Destination amount"},"direction":{"type":"string","description":"Exchange direction","enum":["SOURCE","DESTINATION"]}},"description":"Response to pre-calculate exchange"},"PublicGatewayErrorResponse":{"required":["errorCode","message","traceId"],"type":"object","properties":{"traceId":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Get currency pairs

> Permission annotations:

```json
{"openapi":"3.0.1","info":{"title":"Public API","version":"dev"},"tags":[{"name":"Exchange API","description":"API for exchanges"}],"servers":[{"url":"https://api.calypso.money","description":"Generated server url"}],"paths":{"/api/v1/exchange/pairs":{"post":{"tags":["Exchange API"],"summary":"Get currency pairs","description":"Permission annotations:","operationId":"getCurrencyPair","parameters":[{"name":"Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Sign","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyWithAccountContainer"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CurrencyPairDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}}}}}},"components":{"schemas":{"EmptyWithAccountContainer":{"required":["account","timestamp"],"type":"object","properties":{"account":{"pattern":"^0x[0-9a-fA-F]{40}$","type":"string","description":"Merchant account ID. Request will be sent for this account"},"timestamp":{"type":"integer","description":"Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future","format":"int64"}},"description":"Object with request data"},"CurrencyPairDTO":{"required":["currencyPairs"],"type":"object","properties":{"currencyPairs":{"type":"object","additionalProperties":{"type":"array","description":"currency pairs map","items":{"$ref":"#/components/schemas/Currency"}},"description":"currency pairs map"}},"description":"Currency pairs"},"Currency":{"type":"string"},"PublicGatewayErrorResponse":{"required":["errorCode","message","traceId"],"type":"object","properties":{"traceId":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Get upper exchange limit by currency

> Permission annotations:

```json
{"openapi":"3.0.1","info":{"title":"Public API","version":"dev"},"tags":[{"name":"Exchange API","description":"API for exchanges"}],"servers":[{"url":"https://api.calypso.money","description":"Generated server url"}],"paths":{"/api/v1/exchange/limit":{"post":{"tags":["Exchange API"],"summary":"Get upper exchange limit by currency","description":"Permission annotations:","operationId":"getLimit","parameters":[{"name":"Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Sign","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithAccountContainerSourceDestinationCurrencyDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ExchangeLimitResponseDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}}}}}},"components":{"schemas":{"WithAccountContainerSourceDestinationCurrencyDTO":{"required":["account","payload","timestamp"],"type":"object","properties":{"account":{"pattern":"^0x[0-9a-fA-F]{40}$","type":"string","description":"Merchant account ID. Request will be sent for this account"},"timestamp":{"type":"integer","description":"Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future","format":"int64"},"payload":{"$ref":"#/components/schemas/SourceDestinationCurrencyDTO"}},"description":"Object with request data"},"SourceDestinationCurrencyDTO":{"required":["destinationCurrency","sourceCurrency"],"type":"object","properties":{"sourceCurrency":{"type":"string","description":"Source currency"},"destinationCurrency":{"type":"string","description":"Destination currency"}},"description":"Source and destination currency"},"ExchangeLimitResponseDTO":{"required":["destinationCurrency","maxLimit","minLimit","sourceCurrency"],"type":"object","properties":{"sourceCurrency":{"type":"string","description":"Exchange currency"},"destinationCurrency":{"$ref":"#/components/schemas/Currency"},"minLimit":{"type":"number","description":"Minimum amount"},"maxLimit":{"type":"number","description":"Maximum amount"}},"description":"Exchange limit by currency"},"Currency":{"type":"string"},"PublicGatewayErrorResponse":{"required":["errorCode","message","traceId"],"type":"object","properties":{"traceId":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Get exchange

> Permission annotations:

```json
{"openapi":"3.0.1","info":{"title":"Public API","version":"dev"},"tags":[{"name":"Exchange API","description":"API for exchanges"}],"servers":[{"url":"https://api.calypso.money","description":"Generated server url"}],"paths":{"/api/v1/exchange/get":{"post":{"tags":["Exchange API"],"summary":"Get exchange","description":"Permission annotations:","operationId":"getExchange","parameters":[{"name":"Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Sign","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithAccountContainerIdDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ExchangeDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}}}}}},"components":{"schemas":{"WithAccountContainerIdDTO":{"required":["account","payload","timestamp"],"type":"object","properties":{"account":{"pattern":"^0x[0-9a-fA-F]{40}$","type":"string","description":"Merchant account ID. Request will be sent for this account"},"timestamp":{"type":"integer","description":"Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future","format":"int64"},"payload":{"$ref":"#/components/schemas/IdDTO"}},"description":"Object with request data"},"IdDTO":{"required":["id"],"type":"object","properties":{"id":{"type":"integer","format":"int64"}},"description":"Object with request parameters"},"ExchangeDTO":{"required":["account","createdDate","destinationCurrency","id","sourceAmount","sourceCurrency","state"],"type":"object","properties":{"id":{"type":"integer","description":"Exchange id","format":"int64"},"account":{"type":"string","description":"Account"},"sourceCurrency":{"type":"string","description":"Source currency"},"sourceAmount":{"type":"number","description":"Source amount"},"destinationCurrency":{"type":"string","description":"Destination currency"},"destinationAmount":{"type":"number","description":"Destination amount"},"state":{"type":"string","description":"Exchange state","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"createdDate":{"type":"string","description":"Exchange creation date","format":"date-time"}},"description":"Exchange"},"PublicGatewayErrorResponse":{"required":["errorCode","message","traceId"],"type":"object","properties":{"traceId":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Find exchange by filter

> Permission annotations:

```json
{"openapi":"3.0.1","info":{"title":"Public API","version":"dev"},"tags":[{"name":"Exchange API","description":"API for exchanges"}],"servers":[{"url":"https://api.calypso.money","description":"Generated server url"}],"paths":{"/api/v1/exchange/filter":{"post":{"tags":["Exchange API"],"summary":"Find exchange by filter","description":"Permission annotations:","operationId":"findExchangeByFilter","parameters":[{"name":"Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Sign","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithAccountContainerExchangeFilterDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PageDTOExchangeDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}}}}}},"components":{"schemas":{"WithAccountContainerExchangeFilterDTO":{"required":["account","payload","timestamp"],"type":"object","properties":{"account":{"pattern":"^0x[0-9a-fA-F]{40}$","type":"string","description":"Merchant account ID. Request will be sent for this account"},"timestamp":{"type":"integer","description":"Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future","format":"int64"},"payload":{"$ref":"#/components/schemas/ExchangeFilterDTO"}},"description":"Object with request data"},"ExchangeFilterDTO":{"required":["pageNumber","pageSize","properties","sort"],"type":"object","properties":{"createdDate":{"$ref":"#/components/schemas/CreatedDTO"},"state":{"type":"array","description":"States","items":{"type":"string","description":"States","enum":["IN_PROGRESS","COMPLETED","FAILED"]}},"pageNumber":{"type":"integer","description":"Numeric value indicating the page number","format":"int32","default":1},"pageSize":{"type":"integer","description":"Numeric value indicating the page size","format":"int32","default":10},"sort":{"type":"string","description":"Direction of result values which can be asc or desc","default":"ASC","enum":["ASC","DESC"]},"properties":{"type":"string","description":"Attribute by which sorting is performed. Accept the parameter name by which sorting is needed"}},"description":"Find exchanges by filter"},"CreatedDTO":{"required":["period"],"type":"object","properties":{"period":{"$ref":"#/components/schemas/PeriodDTO"},"date":{"type":"string","description":"Дата","format":"date-time"}},"description":"Фильтр даты создания"},"PeriodDTO":{"required":["firstDate","secondDate"],"type":"object","properties":{"firstDate":{"type":"string","description":"С даты","format":"date-time"},"secondDate":{"type":"string","description":"По дату","format":"date-time"}},"description":"Фильтр даты"},"PageDTOExchangeDTO":{"required":["page","result","size","total","totalElements"],"type":"object","properties":{"result":{"type":"array","description":"Array of requested objects","items":{"$ref":"#/components/schemas/ExchangeDTO"}},"page":{"type":"integer","description":"Numeric value indicating the page number","format":"int32"},"size":{"type":"integer","description":"Numeric value indicating the page size","format":"int32"},"total":{"type":"integer","description":"Total number of pages matching the query","format":"int32"},"totalElements":{"type":"integer","description":"Total number of objects matching the query","format":"int64"}},"description":"Object with page details"},"ExchangeDTO":{"required":["account","createdDate","destinationCurrency","id","sourceAmount","sourceCurrency","state"],"type":"object","properties":{"id":{"type":"integer","description":"Exchange id","format":"int64"},"account":{"type":"string","description":"Account"},"sourceCurrency":{"type":"string","description":"Source currency"},"sourceAmount":{"type":"number","description":"Source amount"},"destinationCurrency":{"type":"string","description":"Destination currency"},"destinationAmount":{"type":"number","description":"Destination amount"},"state":{"type":"string","description":"Exchange state","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"createdDate":{"type":"string","description":"Exchange creation date","format":"date-time"}},"description":"Exchange"},"PublicGatewayErrorResponse":{"required":["errorCode","message","traceId"],"type":"object","properties":{"traceId":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Create exchange

> Permission annotations:

```json
{"openapi":"3.0.1","info":{"title":"Public API","version":"dev"},"tags":[{"name":"Exchange API","description":"API for exchanges"}],"servers":[{"url":"https://api.calypso.money","description":"Generated server url"}],"paths":{"/api/v1/exchange/create":{"post":{"tags":["Exchange API"],"summary":"Create exchange","description":"Permission annotations:","operationId":"createExchange","parameters":[{"name":"Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Sign","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithAccountContainerExchangeRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ExchangeDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}}}}}},"components":{"schemas":{"WithAccountContainerExchangeRequestDTO":{"required":["account","payload","timestamp"],"type":"object","properties":{"account":{"pattern":"^0x[0-9a-fA-F]{40}$","type":"string","description":"Merchant account ID. Request will be sent for this account"},"timestamp":{"type":"integer","description":"Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future","format":"int64"},"payload":{"$ref":"#/components/schemas/ExchangeRequestDTO"}},"description":"Object with request data"},"ExchangeRequestDTO":{"required":["amount","destinationCurrency","direction","idempotencyKey","sourceCurrency"],"type":"object","properties":{"sourceCurrency":{"type":"string","description":"Source currency"},"destinationCurrency":{"type":"string","description":"Destination currency"},"amount":{"type":"number","description":"Exchange amount"},"direction":{"type":"string","description":"Exchange direction","default":"SOURCE","enum":["SOURCE","DESTINATION"]},"idempotencyKey":{"type":"string","description":"Idempotency key","format":"uuid"}},"description":"Request for exchange"},"ExchangeDTO":{"required":["account","createdDate","destinationCurrency","id","sourceAmount","sourceCurrency","state"],"type":"object","properties":{"id":{"type":"integer","description":"Exchange id","format":"int64"},"account":{"type":"string","description":"Account"},"sourceCurrency":{"type":"string","description":"Source currency"},"sourceAmount":{"type":"number","description":"Source amount"},"destinationCurrency":{"type":"string","description":"Destination currency"},"destinationAmount":{"type":"number","description":"Destination amount"},"state":{"type":"string","description":"Exchange state","enum":["IN_PROGRESS","COMPLETED","FAILED"]},"createdDate":{"type":"string","description":"Exchange creation date","format":"date-time"}},"description":"Exchange"},"PublicGatewayErrorResponse":{"required":["errorCode","message","traceId"],"type":"object","properties":{"traceId":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Get average rate for currency pair

> Permission annotations:

```json
{"openapi":"3.0.1","info":{"title":"Public API","version":"dev"},"tags":[{"name":"Exchange API","description":"API for exchanges"}],"servers":[{"url":"https://api.calypso.money","description":"Generated server url"}],"paths":{"/api/v1/exchange/average-rate":{"post":{"tags":["Exchange API"],"summary":"Get average rate for currency pair","description":"Permission annotations:","operationId":"getAverageRate","parameters":[{"name":"Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Sign","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithAccountContainerSourceDestinationCurrencyDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AverageRateDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicGatewayErrorResponse"}}}}}}}},"components":{"schemas":{"WithAccountContainerSourceDestinationCurrencyDTO":{"required":["account","payload","timestamp"],"type":"object","properties":{"account":{"pattern":"^0x[0-9a-fA-F]{40}$","type":"string","description":"Merchant account ID. Request will be sent for this account"},"timestamp":{"type":"integer","description":"Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future","format":"int64"},"payload":{"$ref":"#/components/schemas/SourceDestinationCurrencyDTO"}},"description":"Object with request data"},"SourceDestinationCurrencyDTO":{"required":["destinationCurrency","sourceCurrency"],"type":"object","properties":{"sourceCurrency":{"type":"string","description":"Source currency"},"destinationCurrency":{"type":"string","description":"Destination currency"}},"description":"Source and destination currency"},"AverageRateDTO":{"required":["rate"],"type":"object","properties":{"rate":{"type":"number","description":"Rate"}},"description":"Average rate"},"PublicGatewayErrorResponse":{"required":["errorCode","message","traceId"],"type":"object","properties":{"traceId":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.calypso.money/api-reference/exchange-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.