> 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/balance.md).

# Balance

Check account balance

## Retrieve balances

> Returns all balances

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Balance","description":"Check account balance"}],"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":{"BalanceListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"The merchant balances, one entry per currency.","type":"array","items":{"$ref":"#/components/schemas/BalanceDto"}}},"required":["success","message","data"]},"BalanceDto":{"type":"object","properties":{"currency":{"type":"string","description":"Balance currency","enum":["NGN","USDT","USDC"]},"available":{"type":"string","description":"Available balance that can be used for transactions"},"pending":{"type":"string","description":"Pending balance from transactions awaiting confirmation"},"total":{"type":"string","description":"Total balance (available + pending)"}},"required":["currency","available","pending","total"]}}},"paths":{"/api/v1/balance":{"get":{"description":"Returns all balances","operationId":"BalanceController_getBalances","parameters":[],"responses":{"200":{"description":"Balances retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceListResponseDto"}}}}},"summary":"Retrieve balances","tags":["Balance"]}}}}
```

## List balance transactions

> Returns your balance transactions.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Balance","description":"Check account balance"}],"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":{"BalanceTransactionListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful."},"message":{"type":"string","description":"Response message."},"data":{"description":"The balance transactions for this page.","type":"array","items":{"$ref":"#/components/schemas/BalanceTransactionDto"}},"meta":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","data","meta"]},"BalanceTransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the balance transaction."},"source":{"type":"string","nullable":true,"enum":["deposit","payment_session","invoice","payout","swap","refund","fee"],"description":"What this transaction originated from."},"sourceId":{"type":"string","nullable":true,"description":"Id of the object this transaction came from (session, invoice, payout, or swap). Null for deposits and fees."},"sourceReference":{"type":"string","nullable":true,"description":"Reference of the object this transaction came from. Set for sessions, invoices, and payouts; null for swaps, deposits, and fees."},"description":{"type":"string","nullable":true,"description":"What this transaction was for. Set for compliance screening fees and their refunds; null otherwise."},"direction":{"type":"string","enum":["credit","debit"],"description":"Whether funds were added to or removed from the balance."},"status":{"type":"string","enum":["pending","completed","failed","cancelled"],"description":"Current status of the transaction."},"amount":{"type":"string","description":"Amount added to or removed from the balance, in `currency`."},"currency":{"type":"string","enum":["USDT","NGN"],"description":"Currency of the balance this transaction affected."},"reference":{"type":"string","nullable":true,"description":"Reference for the transaction."},"balanceBefore":{"description":"The balance immediately before this transaction was applied.","allOf":[{"$ref":"#/components/schemas/BalanceSnapshotDto"}]},"balanceAfter":{"description":"The resulting balance after this transaction was applied.","allOf":[{"$ref":"#/components/schemas/BalanceSnapshotDto"}]},"createdAt":{"type":"string","description":"When the transaction was created (ISO 8601)."}},"required":["id","source","sourceId","sourceReference","description","direction","status","amount","currency","reference","balanceBefore","balanceAfter","createdAt"]},"BalanceSnapshotDto":{"type":"object","properties":{"available":{"type":"string","nullable":true,"description":"Available balance after this transaction."},"pending":{"type":"string","nullable":true,"description":"Pending balance after this transaction."},"total":{"type":"string","nullable":true,"description":"Total balance after this transaction."}},"required":["available","pending","total"]},"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"]}}},"paths":{"/api/v1/balance/transactions":{"get":{"description":"Returns your balance transactions.","operationId":"BalanceController_getBalanceTransactions","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":"source","required":false,"in":"query","description":"Filter by source type","schema":{"type":"string","enum":["payment_session","invoice","deposit","payout","swap","refund","fee"]}},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{"type":"string","enum":["pending","completed","failed","cancelled"]}},{"name":"direction","required":false,"in":"query","description":"Filter by direction (money in or out)","schema":{"type":"string","enum":["credit","debit"]}},{"name":"currency","required":false,"in":"query","description":"Filter by balance currency","schema":{"type":"string","enum":["NGN","USDT","USDC"]}},{"name":"txHash","required":false,"in":"query","description":"Filter by crypto deposit transaction hash (exact)","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date (ISO string)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO string)","schema":{"type":"string"}}],"responses":{"200":{"description":"Balance transactions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceTransactionListResponseDto"}}}}},"summary":"List balance transactions","tags":["Balance"]}}}}
```

## GET /api/v1/balance/transactions/{id}

> Get a balance transaction by id

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Balance","description":"Check account balance"}],"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":{"BalanceTransactionResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful."},"message":{"type":"string","description":"Response message."},"data":{"description":"The balance transaction.","allOf":[{"$ref":"#/components/schemas/BalanceTransactionDto"}]}},"required":["success","message","data"]},"BalanceTransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the balance transaction."},"source":{"type":"string","nullable":true,"enum":["deposit","payment_session","invoice","payout","swap","refund","fee"],"description":"What this transaction originated from."},"sourceId":{"type":"string","nullable":true,"description":"Id of the object this transaction came from (session, invoice, payout, or swap). Null for deposits and fees."},"sourceReference":{"type":"string","nullable":true,"description":"Reference of the object this transaction came from. Set for sessions, invoices, and payouts; null for swaps, deposits, and fees."},"description":{"type":"string","nullable":true,"description":"What this transaction was for. Set for compliance screening fees and their refunds; null otherwise."},"direction":{"type":"string","enum":["credit","debit"],"description":"Whether funds were added to or removed from the balance."},"status":{"type":"string","enum":["pending","completed","failed","cancelled"],"description":"Current status of the transaction."},"amount":{"type":"string","description":"Amount added to or removed from the balance, in `currency`."},"currency":{"type":"string","enum":["USDT","NGN"],"description":"Currency of the balance this transaction affected."},"reference":{"type":"string","nullable":true,"description":"Reference for the transaction."},"balanceBefore":{"description":"The balance immediately before this transaction was applied.","allOf":[{"$ref":"#/components/schemas/BalanceSnapshotDto"}]},"balanceAfter":{"description":"The resulting balance after this transaction was applied.","allOf":[{"$ref":"#/components/schemas/BalanceSnapshotDto"}]},"createdAt":{"type":"string","description":"When the transaction was created (ISO 8601)."}},"required":["id","source","sourceId","sourceReference","description","direction","status","amount","currency","reference","balanceBefore","balanceAfter","createdAt"]},"BalanceSnapshotDto":{"type":"object","properties":{"available":{"type":"string","nullable":true,"description":"Available balance after this transaction."},"pending":{"type":"string","nullable":true,"description":"Pending balance after this transaction."},"total":{"type":"string","nullable":true,"description":"Total balance after this transaction."}},"required":["available","pending","total"]}}},"paths":{"/api/v1/balance/transactions/{id}":{"get":{"operationId":"BalanceController_getBalanceTransactionById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Balance transaction retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceTransactionResponseDto"}}}},"404":{"description":"Balance transaction not found"}},"summary":"Get a balance transaction by id","tags":["Balance"]}}}}
```


---

# 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/balance.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.