> 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","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"]}}}}
```


---

# 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, and the optional `goal` query parameter:

```
GET https://developers.coincircuit.io/swap.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.