# Balance

Wallet and balance APIs. Provide access to the player's in-game currencies and current balances.

## Get user wallet balance

> Retrieves the wallet balances of a specific user, including all\
> in-game currencies and their current amounts.\
> \
> Each entry represents a currency defined by the game and the\
> corresponding balance owned by the user.\
> \
> The request \*\*requires authentication\*\*.\
> The Bearer token \*\*must be the \`sessionId\`\*\* returned from the Login API.\
> \
> This API is intended for \*\*game developers without their own backend\*\*,\
> using the Sverse backend and authentication services.<br>

```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Client SDK)","version":"1.0.0"},"tags":[{"name":"Balance","description":"Wallet and balance APIs.\nProvide access to the player's in-game currencies\nand current balances.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Sverse Managed Backend (Production)"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"http","scheme":"bearer","bearerFormat":"sessionId","description":"Use the `sessionId` returned from the Login API.\nExample:\nAuthorization: Bearer 9d7b6121-30d3-44cf-8b4f-c00e2f4f016e\n"}}},"paths":{"/api/public/users/balance":{"get":{"tags":["Balance"],"summary":"Get user wallet balance","description":"Retrieves the wallet balances of a specific user, including all\nin-game currencies and their current amounts.\n\nEach entry represents a currency defined by the game and the\ncorresponding balance owned by the user.\n\nThe request **requires authentication**.\nThe Bearer token **must be the `sessionId`** returned from the Login API.\n\nThis API is intended for **game developers without their own backend**,\nusing the Sverse backend and authentication services.\n","operationId":"getUserBalance","parameters":null,"responses":{"200":{"description":"Wallet balance retrieved successfully","content":{"application/json":{"schema":{"type":"object","required":["error","data"],"properties":{"error":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"currency_code":{"type":"string","description":"Unique currency identifier"},"currency_name":{"type":"string","description":"Display name of the currency"},"balance":{"type":"number","description":"Current balance of the currency"}}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{}}},"401":{"description":"Unauthorized or invalid session","content":{"application/json":{}}},"429":{"description":"Too many requests","content":{"application/json":{}}},"500":{"description":"Internal server error","content":{"application/json":{}}}}}}}}
```

## Get wallet transactions

> Retrieve a paginated list of transactions for a specific wallet currency of the authenticated user. This endpoint is used to view transaction history such as rewards, purchases, or other balance changes.<br>

```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Client SDK)","version":"1.0.0"},"tags":[{"name":"Balance","description":"Wallet and balance APIs.\nProvide access to the player's in-game currencies\nand current balances.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Sverse Managed Backend (Production)"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"http","scheme":"bearer","bearerFormat":"sessionId","description":"Use the `sessionId` returned from the Login API.\nExample:\nAuthorization: Bearer 9d7b6121-30d3-44cf-8b4f-c00e2f4f016e\n"}}},"paths":{"/api/public/wallets/{currencyCode}/transactions":{"get":{"tags":["Balance"],"summary":"Get wallet transactions","description":"Retrieve a paginated list of transactions for a specific wallet currency of the authenticated user. This endpoint is used to view transaction history such as rewards, purchases, or other balance changes.\n","parameters":[{"name":"currencyCode","in":"path","required":true,"description":"Unique code of the wallet currency.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number for pagination.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Number of transactions per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Get transactions successfully","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"currency":{"type":"string"},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"transactions":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"type":{"type":"string","enum":["credit","debit"]},"amount":{"type":"number"},"balance_before":{"type":"number"},"balance_after":{"type":"number"},"reason":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}}}
```

## Make a wallet transaction

> Create a credit or debit transaction for a specific wallet currency\
> of a user.\
> \
> This API is designed for \*\*developers without their own backend\*\*.\
> Authentication is performed using:\
> \- \`x-api-key\` (game API key)\
> \- \`sessionId\` (returned from Login API)\
> \
> Supported transaction types:\
> \- \`credit\`: Add balance to wallet\
> \- \`debit\`: Subtract balance from wallet<br>

```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Client SDK)","version":"1.0.0"},"tags":[{"name":"Balance","description":"Wallet and balance APIs.\nProvide access to the player's in-game currencies\nand current balances.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Sverse Managed Backend (Production)"}],"paths":{"/api/public/wallets/{currencyCode}/transactions":{"post":{"tags":["Balance"],"summary":"Make a wallet transaction","description":"Create a credit or debit transaction for a specific wallet currency\nof a user.\n\nThis API is designed for **developers without their own backend**.\nAuthentication is performed using:\n- `x-api-key` (game API key)\n- `sessionId` (returned from Login API)\n\nSupported transaction types:\n- `credit`: Add balance to wallet\n- `debit`: Subtract balance from wallet\n","parameters":[{"name":"currencyCode","in":"path","required":true,"description":"Unique currency code of the wallet.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","amount","type","reason"],"properties":{"sessionId":{"type":"string","description":"Session ID returned from the Login API."},"amount":{"type":"number","minimum":1,"description":"Transaction amount (must be positive)."},"type":{"type":"string","enum":["credit","debit"],"description":"Transaction type."},"reason":{"type":"string","description":"Reason for the transaction."},"meta":{"type":"object","description":"Optional metadata related to the transaction.","additionalProperties":true}}}}}},"responses":{"200":{"description":"Transaction created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"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"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"404":{"description":"Resource not found","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"}}}}}}}}}}}
```


---

# 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/client/balance.md?ask=<question>
```

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.