> For the complete documentation index, see [llms.txt](https://docs.kiiglobal.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiiglobal.io/docs/kiichain-pay/api-reference/ledger.md).

# Ledger

## GetAvailableBalances returns the user's available balance for each product

> Splits available vs locked amounts derived from the ledger entries,\
> rather than returning the entries themselves

```json
{"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"LedgerQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["ledger.entries.read"]},{"BearerAuth":["ledger.entries.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey <api-key>' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetAvailableBalancesResponse":{"properties":{"balances":{"items":{"$ref":"#/components/schemas/ledgerV1Balance"},"title":"balances contains the available balance for each product","type":"array"}},"required":["balances"],"title":"GetAvailableBalancesResponse is the response for retrieving a user's available balance per product","type":"object"},"ledgerV1Balance":{"properties":{"available":{"title":"available represents the current available balance for the asset","type":"string"},"locked":{"title":"locked represents the locked amount for the asset","type":"string"},"productId":{"title":"product_id represents the product identifier","type":"string"}},"required":["productId","available","locked"],"title":"Balance represents the balance for a specific asset","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/ledger/v1/balances/{accountId}":{"get":{"description":"Splits available vs locked amounts derived from the ledger entries,\nrather than returning the entries themselves","operationId":"LedgerQueryService_GetAvailableBalances","parameters":[{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetAvailableBalancesResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetAvailableBalances returns the user's available balance for each product","tags":["LedgerQueryService"]}}}}
```

## GetUserTradeHistory returns historical ticket trade data for a user (paginated)

> Each entry is a single ticket-linked trade (deposit, withdraw, swap)\
> Use GetUserTradeHistoryGrouped for aggregated totals per time bucket\
> instead

```json
{"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"LedgerQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["ledger.entries.read"]},{"BearerAuth":["ledger.entries.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey <api-key>' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetUserTradeHistoryResponse":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/v1TradeHistoryEntry"},"title":"entries contains the paginated list of trade entries","type":"array"},"total":{"format":"int64","title":"total is the total number of entries (for pagination)","type":"string"}},"required":["entries","total"],"title":"GetUserTradeHistoryResponse is the response for retrieving a user's trade history","type":"object"},"v1TradeHistoryEntry":{"properties":{"amount":{"title":"amount is the net token-unit volume for this trade","type":"string"},"amountUsd":{"title":"amount_usd is the USD value of the trade","type":"string"},"createdAt":{"format":"date-time","title":"created_at is when the trade was recorded","type":"string"},"journalId":{"title":"journal_id is the ledger journal identifier","type":"string"},"subType":{"title":"sub_type is the trade subtype (deposit, withdraw, swap)","type":"string"},"symbol":{"title":"symbol is the ticker symbol of the traded asset (e.g. \"USDC\")","type":"string"},"ticketId":{"title":"ticket_id is the ticket identifier (ref_id from the journal)","type":"string"}},"required":["journalId","ticketId","symbol","subType","amount","amountUsd","createdAt"],"title":"TradeHistoryEntry represents a single ticket-linked trade in the user's ledger","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/ledger/v1/trades/{accountId}":{"get":{"description":"Each entry is a single ticket-linked trade (deposit, withdraw, swap)\nUse GetUserTradeHistoryGrouped for aggregated totals per time bucket\ninstead","operationId":"LedgerQueryService_GetUserTradeHistory","parameters":[{"description":"account_id is the user's account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"description":"limit is the maximum number of entries to return (defaults to 50)","in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"page is the 1-indexed page number (defaults to 1)","in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetUserTradeHistoryResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetUserTradeHistory returns historical ticket trade data for a user (paginated)","tags":["LedgerQueryService"]}}}}
```

## GetUserTradeHistoryGrouped returns historical ticket trade data grouped by time frame for a user

> Buckets trades by day, week or month, aggregating amount and ticket\
> count per bucket instead of returning individual trades

```json
{"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"LedgerQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["ledger.entries.read"]},{"BearerAuth":["ledger.entries.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey <api-key>' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetUserTradeHistoryGroupedResponse":{"properties":{"groups":{"items":{"$ref":"#/components/schemas/v1TradeHistoryGroup"},"title":"groups contains the aggregated trade data per time bucket","type":"array"}},"required":["groups"],"title":"GetUserTradeHistoryGroupedResponse is the response for grouped trade history","type":"object"},"v1TradeHistoryGroup":{"properties":{"period":{"format":"date-time","title":"period is the start of the time bucket","type":"string"},"subType":{"title":"sub_type is the trade subtype (deposit, withdraw, swap)","type":"string"},"symbol":{"title":"symbol is the ticker symbol of the traded asset (e.g. \"USDC\")","type":"string"},"ticketCount":{"format":"int64","title":"ticket_count is the number of distinct tickets in this period","type":"string"},"totalAmount":{"title":"total_amount is the net token-unit volume for this period","type":"string"},"totalAmountUsd":{"title":"total_amount_usd is the total USD volume for this period","type":"string"}},"required":["period","subType","symbol","totalAmount","totalAmountUsd","ticketCount"],"title":"TradeHistoryGroup represents aggregated trade data for a single time period","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/ledger/v1/trades/{accountId}/grouped":{"get":{"description":"Buckets trades by day, week or month, aggregating amount and ticket\ncount per bucket instead of returning individual trades","operationId":"LedgerQueryService_GetUserTradeHistoryGrouped","parameters":[{"description":"account_id is the user's account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"description":"time_frame specifies the grouping period: \"day\", \"week\", or \"month\"","in":"query","name":"timeFrame","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetUserTradeHistoryGroupedResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetUserTradeHistoryGrouped returns historical ticket trade data grouped by time frame for a user","tags":["LedgerQueryService"]}}}}
```

## GetLedgerEntries returns all ledger entries for an account

> Unfiltered and unpaginated. Use GetLedgerEntriesFiltered for large\
> accounts or when scoping to a product/time range

```json
{"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"LedgerQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["ledger.entries.read"]},{"BearerAuth":["ledger.entries.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey <api-key>' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetLedgerEntriesResponse":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/v1LedgerEntry"},"title":"entries contains the list of ledger entries","type":"array"}},"required":["entries"],"title":"GetLedgerEntriesResponse is the body response structure from the Get ledger entries endpoint","type":"object"},"v1LedgerEntry":{"properties":{"accountId":{"title":"account_id represents the account identifier","type":"string"},"amount":{"title":"amount represents the amount of the ledger entry (positive for credit, negative for debit)","type":"string"},"amountUsd":{"title":"amount_usd represents the USD value of the ledger entry","type":"string"},"createdAt":{"format":"date-time","title":"created_at represents the time when the ledger entry was created","type":"string"},"description":{"title":"description provides additional information about the ledger entry","type":"string"},"direction":{"title":"direction represents whether the entry is a credit or debit","type":"string"},"id":{"format":"int64","title":"id represents the unique identifier for the ledger entry","type":"string"},"journalId":{"title":"journal_id represents the journal identifier","type":"string"},"productId":{"title":"product_id represents the product identifier","type":"string"},"subType":{"title":"sub_type represents the type of the ledger entry (locked, available, etc.)","type":"string"},"type":{"title":"type represents the primary account type of the ledger entry (available, locked, limit, etc.)","type":"string"}},"required":["id","accountId","journalId","productId","amount","amountUsd","direction","type","subType","createdAt"],"title":"LedgerEntry represents a single ledger entry","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/ledger/v1/{accountId}":{"get":{"description":"Unfiltered and unpaginated. Use GetLedgerEntriesFiltered for large\naccounts or when scoping to a product/time range","operationId":"LedgerQueryService_GetLedgerEntries","parameters":[{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetLedgerEntriesResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetLedgerEntries returns all ledger entries for an account","tags":["LedgerQueryService"]}}}}
```

## GetLedgerEntriesFiltered returns a user's entries filtered by product and time range

> product\_id, start\_date and end\_date are all optional and independently\
> combinable

```json
{"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"LedgerQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["ledger.entries.read"]},{"BearerAuth":["ledger.entries.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey <api-key>' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetLedgerEntriesFilteredResponse":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/v1LedgerEntry"},"title":"entries contains the list of ledger entries","type":"array"}},"required":["entries"],"title":"GetLedgerEntriesFilteredResponse is the response for retrieving a user's entries filtered by product and time range","type":"object"},"v1LedgerEntry":{"properties":{"accountId":{"title":"account_id represents the account identifier","type":"string"},"amount":{"title":"amount represents the amount of the ledger entry (positive for credit, negative for debit)","type":"string"},"amountUsd":{"title":"amount_usd represents the USD value of the ledger entry","type":"string"},"createdAt":{"format":"date-time","title":"created_at represents the time when the ledger entry was created","type":"string"},"description":{"title":"description provides additional information about the ledger entry","type":"string"},"direction":{"title":"direction represents whether the entry is a credit or debit","type":"string"},"id":{"format":"int64","title":"id represents the unique identifier for the ledger entry","type":"string"},"journalId":{"title":"journal_id represents the journal identifier","type":"string"},"productId":{"title":"product_id represents the product identifier","type":"string"},"subType":{"title":"sub_type represents the type of the ledger entry (locked, available, etc.)","type":"string"},"type":{"title":"type represents the primary account type of the ledger entry (available, locked, limit, etc.)","type":"string"}},"required":["id","accountId","journalId","productId","amount","amountUsd","direction","type","subType","createdAt"],"title":"LedgerEntry represents a single ledger entry","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/ledger/v1/{accountId}/entries":{"get":{"description":"product_id, start_date and end_date are all optional and independently\ncombinable","operationId":"LedgerQueryService_GetLedgerEntriesFiltered","parameters":[{"description":"account_id represents the account identifier","in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"description":"product_id optionally filters entries to a single product","in":"query","name":"productId","required":false,"schema":{"type":"string"}},{"description":"start_date optionally filters entries created at or after this time","in":"query","name":"startDate","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"end_date optionally filters entries created at or before this time","in":"query","name":"endDate","required":false,"schema":{"format":"date-time","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetLedgerEntriesFilteredResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetLedgerEntriesFiltered returns a user's entries filtered by product and time range","tags":["LedgerQueryService"]}}}}
```


---

# 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://docs.kiiglobal.io/docs/kiichain-pay/api-reference/ledger.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.