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

# Balance History

## GET /v1/balance-history

> Retrieves balance history records based on user role and filters

```json
{"openapi":"3.1.1","info":{"title":"Panda Pay API","version":"1.0"},"servers":[{"url":"https://api.paymentgateway24.com"}],"security":[{"ApiKey":[]},{"Signature":[]},{"Timestamp":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Merchant API key"},"Signature":{"type":"apiKey","name":"X-Signature","in":"header","description":"HMAC-SHA256 signature of timestamp + request body (or timestamp only for GET)"},"Timestamp":{"type":"apiKey","name":"X-Timestamp","in":"header","description":"Current Unix timestamp (UTC)"}},"schemas":{"v1.PagedResponse":{"properties":{"balance_history":{"items":{"$ref":"#/components/schemas/internal_controller_balancehistory_v1.Response"},"type":"array"},"pages_total":{"type":"integer"}},"type":"object"},"internal_controller_balancehistory_v1.Response":{"properties":{"amount":{"type":"string"},"balance_after":{"type":"string"},"balance_before":{"type":"string"},"created_at":{"type":"string"},"currency":{"$ref":"#/components/schemas/currency.Currency"},"frozen_balance_after":{"type":"string"},"frozen_balance_before":{"type":"string"},"merchant_id":{"type":"string"},"order_id":{"type":"string"},"type":{"$ref":"#/components/schemas/balancehistory.Type"},"uuid":{"type":"string"}},"type":"object"},"currency.Currency":{"enum":["USDT","RUB","AZN","KGS","KZT","TJS","UZS","ARS","TRY","GEL","XOF","KES","XAF","VND","CNY","MNT","LAK","IDR","PHP","BRL"],"type":"string"},"balancehistory.Type":{"enum":["payout","editPayout","commission","platformFee","topUp","withdrawal","payoutBlock","payoutUnblock","safetyDepositDeduction","safetyDepositTopUp","safetyDepositWithdrawal"],"type":"string"},"models.ErrorResponse":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/v1/balance-history":{"get":{"description":"Retrieves balance history records based on user role and filters","parameters":[{"description":"Page number for pagination","in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1}},{"description":"Number of items per page","in":"query","name":"per_page","schema":{"type":"integer","minimum":10,"maximum":200,"default":10}},{"description":"Type of balance history","in":"query","name":"history_type","schema":{"type":"string","enum":["payout","commission","topUp","withdrawal"]}},{"description":"Start date filter (RFC3339 format)","in":"query","name":"from_date","schema":{"type":"string"}},{"description":"End date filter (RFC3339 format)","in":"query","name":"to_date","schema":{"type":"string"}},{"description":"Filter by payout UUID","in":"query","name":"order_id","schema":{"type":"string"}},{"schema":{"type":"string","default":"application/json"},"name":"Accept","in":"header","description":"Response format"}],"responses":{"200":{"description":"Balance history records with pages_total","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1.PagedResponse"}}}},"400":{"description":"Invalid query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"auth token not found or invalid auth token or invalid role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"403":{"description":"role not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"tags":["Balance History"]}}}}
```