> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/swap.md).

# Swap

Swap between balance currencies

## GET /api/v1/swap/rates

> List swap rates

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"}},"required":["success","message"]},"SwapRateResponseDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Asset the rate is priced from.","enum":["NGN","USDT","USDC","BTC","ETH","SOL","BNB","TRX","POL","CELO","CNGN"]},"toCurrency":{"type":"string","description":"Settlement currency the rate is priced into.","enum":["NGN","USDT","USDC"]},"rate":{"type":"string","description":"Amount of toCurrency received per 1 fromCurrency."},"timestamp":{"type":"string","description":"When the rate was observed."}},"required":["fromCurrency","toCurrency","rate","timestamp"]}}},"paths":{"/api/v1/swap/rates":{"get":{"operationId":"SwapController_getAllRates","parameters":[],"responses":{"200":{"description":"Swap rates retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SwapRateResponseDto"}}}}]}}}}},"summary":"List swap rates","tags":["Swap"]}}}}
```

## GET /api/v1/swap/estimate

> Estimate swap amount

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"}},"required":["success","message"]},"SwapEstimationResponseDto":{"type":"object","properties":{"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]}}},"paths":{"/api/v1/swap/estimate":{"get":{"operationId":"SwapController_estimateSwap","parameters":[{"name":"fromCurrency","required":true,"in":"query","description":"Currency to swap from","schema":{"type":"string","enum":["NGN","USDT","BTC","ETH","BNB","SOL","TRX","USDC","POL","CELO","CNGN"]}},{"name":"toCurrency","required":true,"in":"query","description":"Currency to swap to","schema":{"type":"string","enum":["NGN","USDT","USDC"]}},{"name":"amount","required":true,"in":"query","description":"Amount to swap","schema":{"type":"string"}}],"responses":{"200":{"description":"Swap estimation retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapEstimationResponseDto"}}}]}}}},"400":{"description":"Invalid currency pair or amount"}},"summary":"Estimate swap amount","tags":["Swap"]}}}}
```

## Create a swap quotation

> Creates a swap quotation that locks the rate for 30 seconds. Execute the quotation before it expires.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"SwapBalanceDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Currency to swap from","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","description":"Currency to swap to","enum":["NGN","USDT","USDC"]},"amount":{"type":"string","description":"Amount to swap"}},"required":["fromCurrency","toCurrency","amount"]},"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"}},"required":["success","message"]},"SwapQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"executed":{"type":"boolean"},"expiresAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","executed","expiresAt","createdAt"]}}},"paths":{"/api/v1/swap/quotation":{"post":{"description":"Creates a swap quotation that locks the rate for 30 seconds. Execute the quotation before it expires.","operationId":"SwapController_createQuotation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapBalanceDto"}}}},"responses":{"201":{"description":"Quotation created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapQuotationResponseDto"}}}]}}}},"400":{"description":"Invalid currency pair or amount"}},"summary":"Create a swap quotation","tags":["Swap"]}}}}
```

## GET /api/v1/swap/quotation/{quotationId}

> Get swap quotation by ID

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"}},"required":["success","message"]},"SwapQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"executed":{"type":"boolean"},"expiresAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","executed","expiresAt","createdAt"]}}},"paths":{"/api/v1/swap/quotation/{quotationId}":{"get":{"operationId":"SwapController_getQuotation","parameters":[{"name":"quotationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Quotation retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapQuotationResponseDto"}}}]}}}},"404":{"description":"Quotation not found"}},"summary":"Get swap quotation by ID","tags":["Swap"]}}}}
```

## POST /api/v1/swap/execute/{quotationId}

> Execute swap quotation

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"ExecuteSwapDto":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Optional URL to receive webhook notifications for this swap (must be HTTPS). Overrides your dashboard webhook URL for this swap only."}}},"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"}},"required":["success","message"]},"SwapResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"status":{"type":"string"},"quotation":{"$ref":"#/components/schemas/SwapQuotationResponseDto"},"createdAt":{"type":"string"},"completedAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","status","createdAt"]},"SwapQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"executed":{"type":"boolean"},"expiresAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","executed","expiresAt","createdAt"]}}},"paths":{"/api/v1/swap/execute/{quotationId}":{"post":{"operationId":"SwapController_executeSwap","parameters":[{"name":"quotationId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteSwapDto"}}}},"responses":{"200":{"description":"Swap completed successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapResponseDto"}}}]}}}},"400":{"description":"Quotation expired or already used"},"404":{"description":"Quotation not found"}},"summary":"Execute swap quotation","tags":["Swap"]}}}}
```

## GET /api/v1/swaps

> List swaps

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"PaginatedApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]},"SwapResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"status":{"type":"string"},"quotation":{"$ref":"#/components/schemas/SwapQuotationResponseDto"},"createdAt":{"type":"string"},"completedAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","status","createdAt"]},"SwapQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"executed":{"type":"boolean"},"expiresAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","executed","expiresAt","createdAt"]}}},"paths":{"/api/v1/swaps":{"get":{"operationId":"SwapController_getSwapHistory","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"fromCurrency","required":false,"in":"query","description":"Filter by source currency","schema":{"type":"string","enum":["NGN","USDT","USDC"]}},{"name":"toCurrency","required":false,"in":"query","description":"Filter by target currency","schema":{"type":"string","enum":["NGN","USDT","USDC"]}},{"name":"startDate","required":false,"in":"query","description":"Start date for filtering (ISO string)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date for filtering (ISO string)","schema":{"type":"string"}}],"responses":{"200":{"description":"Swap history retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedApiResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SwapResponseDto"}}}}]}}}}},"summary":"List swaps","tags":["Swap"]}}}}
```

## GET /api/v1/swaps/{id}

> Get swap details by ID

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"}},"required":["success","message"]},"SwapResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"status":{"type":"string"},"quotation":{"$ref":"#/components/schemas/SwapQuotationResponseDto"},"createdAt":{"type":"string"},"completedAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","status","createdAt"]},"SwapQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"executed":{"type":"boolean"},"expiresAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","executed","expiresAt","createdAt"]}}},"paths":{"/api/v1/swaps/{id}":{"get":{"operationId":"SwapController_getSwapDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Swap details retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapResponseDto"}}}]}}}},"404":{"description":"Swap not found"}},"summary":"Get swap details by ID","tags":["Swap"]}}}}
```
