# Balance
Wallet and currency management APIs. These endpoints provide access to player balances, transaction histories, and all currency-related operations within the game economy.
## Get wallet balances
> Get balance of all in-game currencies for a specific user
```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Server SDK)","version":"1.0.0"},"tags":[{"name":"Balance","description":"Wallet and currency management APIs.\nThese endpoints provide access to player balances,\ntransaction histories, and all currency-related operations\nwithin the game economy.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Production Environment"},{"url":"https://sandbox.api.sverse.io","description":"Sandbox / Testing Environment"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"paths":{"/api/private/users/{identity}/wallets/balance":{"get":{"tags":["Balance"],"summary":"Get wallet balances","description":"Get balance of all in-game currencies for a specific user","parameters":[{"name":"identity","in":"path","required":true,"description":"User identity (userId / walletId / external identity)","schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get wallet balance successfully","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CurrencyBalance"}}}}}}},"400":{"description":"Bad request – missing or invalid item","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized – game not found or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}},"components":{"schemas":{"CurrencyBalance":{"type":"object","properties":{"currency_code":{"type":"string","description":"Unique currency code"},"currency_name":{"type":"string","description":"Display name of currency"},"balance":{"type":"number","description":"Current balance of user"}}}}}}
```
## Make a wallet transaction (credit / debit)
> Create a wallet transaction for a user.\
> Supports credit (add balance) and debit (subtract balance).\
> Uses idempotencyKey to prevent duplicate transactions.
```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Server SDK)","version":"1.0.0"},"tags":[{"name":"Balance","description":"Wallet and currency management APIs.\nThese endpoints provide access to player balances,\ntransaction histories, and all currency-related operations\nwithin the game economy.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Production Environment"},{"url":"https://sandbox.api.sverse.io","description":"Sandbox / Testing Environment"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"paths":{"/api/private/users/{identity}/wallet/{walletCode}/transactions":{"post":{"tags":["Balance"],"summary":"Make a wallet transaction (credit / debit)","description":"Create a wallet transaction for a user.\nSupports credit (add balance) and debit (subtract balance).\nUses idempotencyKey to prevent duplicate transactions.\n","parameters":[{"name":"identity","in":"path","required":true,"schema":{"type":"string"}},{"name":"walletCode","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletTransactionRequest"}}}},"responses":{"200":{"description":"Transaction success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"$ref":"#/components/schemas/WalletTransaction"}}}}}},"400":{"description":"Bad request – missing or invalid item","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized – game not found or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}},"components":{"schemas":{"WalletTransactionRequest":{"type":"object","required":["currency","amount","type","idempotencyKey"],"properties":{"amount":{"type":"number","description":"Transaction amount (must be positive)"},"type":{"type":"string","enum":["credit","debit"]},"reason":{"type":"string","description":"Reason for transaction"},"meta":{"type":"object","additionalProperties":true},"idempotencyKey":{"type":"string","description":"Unique key to prevent duplicate transactions"}}},"WalletTransaction":{"type":"object","properties":{"user_identity":{"type":"string"},"game_id":{"type":"string"},"currency_code":{"type":"string"},"type":{"type":"string","enum":["credit","debit"]},"amount":{"type":"number"},"balance_before":{"type":"number"},"balance_after":{"type":"number"},"reason":{"type":"string"},"meta":{"type":"object","additionalProperties":true},"_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}
```
## Get wallet transactions
> Get transaction history of a specific wallet (currency) of a user
```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Server SDK)","version":"1.0.0"},"tags":[{"name":"Balance","description":"Wallet and currency management APIs.\nThese endpoints provide access to player balances,\ntransaction histories, and all currency-related operations\nwithin the game economy.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Production Environment"},{"url":"https://sandbox.api.sverse.io","description":"Sandbox / Testing Environment"}],"paths":{"/api/private/users/{identity}/wallets/{currencyCode}/transactions":{"get":{"tags":["Balance"],"summary":"Get wallet transactions","description":"Get transaction history of a specific wallet (currency) of a user","parameters":[{"name":"identity","in":"path","required":true,"schema":{"type":"string"}},{"name":"currencyCode","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"type","in":"query","schema":{"type":"string","enum":["credit","debit"]}}],"responses":{"200":{"description":"Get transactions success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"$ref":"#/components/schemas/WalletTransactionList"}}}}}},"400":{"description":"Bad request – missing or invalid item","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized – game not found or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}},"components":{"schemas":{"WalletTransactionList":{"type":"object","properties":{"wallet":{"type":"object","properties":{"currency_code":{"type":"string"},"balance":{"type":"number"}}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/WalletTransaction"}}}},"WalletTransaction":{"type":"object","properties":{"user_identity":{"type":"string"},"game_id":{"type":"string"},"currency_code":{"type":"string"},"type":{"type":"string","enum":["credit","debit"]},"amount":{"type":"number"},"balance_before":{"type":"number"},"balance_after":{"type":"number"},"reason":{"type":"string"},"meta":{"type":"object","additionalProperties":true},"_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}
```
---
# Agent Instructions: 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:
```
GET https://sverse-1.gitbook.io/sverse-docs/api-reference/server/balance.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.