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