Skip to main content

Magicweave: Player Currency

This guide is for game developers integrating player currency and wallet-style tracking from the Magicweave.

The client_currency module lets your game:

  • retrieve all active currency balances for the authenticated player
  • fetch the balance of a specific currency
  • view the transaction history for a specific currency

For the legacy single gem wallet (one balance and ledger), see Player Wallet. Use Player Currency when your project defines multiple currencies (each with its own key, display metadata, and ledger).

Base URL and route prefix​

Production-style base URL (same host pattern as other client modules):

  • https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/

Currency routes are typically mounted under:

  • /currencies (some deployments may expose /currency instead)

Combined app path prefix: prepend /client to the route prefix when using the combined deployment (for example /client/currencies).

Examples (production host):

  • GET https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/currencies
  • GET https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/currencies/gems
  • GET https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/currencies/history?currency_key=gems

Required authentication and headers​

All currency endpoints require:

  • x-client-id: <your_project_client_id>
  • x-client-secret: <your_project_client_secret>
  • Authorization: Bearer <magicweave_access_token>
  • Content-Type: application/json

The authenticated user must have the client.currency permission.

Endpoint 1: Get all currency balances​

GET /currencies

Returns a list of all active currencies configured for the project and the player's current balance for each. If a player has not interacted with a currency yet, their balance reflects the currency's default initial_balance.

Response:

{
  "balances": [
    {
      "currency_id": 1,
      "currency_key": "gems",
      "currency_name": "Gems",
      "currency_symbol": "💎",
      "balance": 150
    },
    {
      "currency_id": 2,
      "currency_key": "coins",
      "currency_name": "Gold Coins",
      "currency_symbol": "🟡",
      "balance": 5000
    }
  ]
}

Reference: Get all currency balances

Endpoint 2: Get balance for a specific currency​

GET /currencies/{currency_key}

Returns the player's current balance for a single currency identified by its key.

Path parameters:

  • currency_key: unique string identifier (e.g. gems).

Response:

{
  "currency_id": 1,
  "currency_key": "gems",
  "currency_name": "Gems",
  "currency_symbol": "💎",
  "balance": 150
}

Reference: Get balance for a specific currency

Endpoint 3: Get currency transaction history​

GET /currencies/history?currency_key={currency_key}

Returns transactions for that currency, newest first (paginated or full list, depending on server configuration).

Query parameters:

  • currency_key (required): unique string identifier (e.g. gems).

Response:

{
  "currency_id": 1,
  "currency_key": "gems",
  "transactions": [
    {
      "transaction_type": "credit",
      "amount": 50,
      "balance_after": 150,
      "source": "daily_reward",
      "note": "Claimed daily login reward",
      "created_at": "2023-10-27T14:32:00Z"
    },
    {
      "transaction_type": "debit",
      "amount": -20,
      "balance_after": 100,
      "source": "store_purchase",
      "note": "Purchased a health potion",
      "created_at": "2023-10-26T09:15:00Z"
    }
  ]
}

Reference: Get currency transaction history

Error codes​

Common cases:

  • 404 Not Found
    • Currency definition not found: the requested currency_key does not exist or is not active for the current project.
  • 401: missing or invalid client headers or bearer token.
  • 403: authenticated user lacks client.currency permission.

Client integration notes​

  • Initial balances: players implicitly have a wallet for every currency defined in your project. With no transactions yet, the API returns the configured initial_balance for that currency.
  • UI rendering: use currency_name and currency_symbol with balance so you do not hardcode currency metadata in the client.
  • Transaction history: list is ordered by creation time descending (newest first). source and note explain the transaction (e.g. spin reward, store purchase, gameplay event).
  • Routing: the server should expose /currencies/history as a static path so it is not mistaken for /currencies/{currency_key} with currency_key = "history".

cURL examples​

Get all balances​

curl -X GET "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/currencies" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json"

Get one currency​

curl -X GET "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/currencies/gems" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json"

Get history​

curl -X GET "https://mw-client-api.wonderfulcoast-218d579d.centralindia.azurecontainerapps.io/currencies/history?currency_key=gems" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json"