Skip to main content

MagicWeave SDK: Player Wallet (apps/client/client_wallet)

This guide is for game developers integrating wallet and gem history features from the MagicWeave SDK.

The client_wallet module gives you:

  • current player gem balance
  • wallet identity for the authenticated player
  • wallet transaction history

Base URL and Route Prefix​

Use one of these deployment styles:

  • Split client API deployment: http://localhost:8001
  • Combined deployment: http://localhost:8000/client

Wallet routes are under:

  • /wallet

Examples:

  • GET http://localhost:8001/wallet
  • GET http://localhost:8001/wallet/history

Required Authentication and Headers​

All wallet endpoints require:

  • x-client-id: <your_project_client_id>
  • x-client-secret: <your_project_client_secret>
  • Authorization: Bearer <magicweave_access_token>

The authenticated user must have client.wallet permission.

Endpoint 1: Get Wallet​

GET /wallet

Returns the authenticated player's wallet.

Behavior:

  • If wallet exists, it is returned.
  • If wallet does not exist yet, backend auto-creates an empty wallet (gems = 0) and returns it.

Response shape:

{
  "id": 10,
  "user_id": 42,
  "gems": 1250,
  "created_at": "2026-04-15T10:30:00Z",
  "updated_at": "2026-04-15T12:45:00Z"
}

Reference: Get wallet

Endpoint 2: Get Wallet History​

GET /wallet/history

Returns wallet transactions for the authenticated player.

Behavior:

  • If wallet exists, returns transaction list ordered newest first.
  • If wallet does not exist, returns 404 Wallet not found.

Response shape:

{
  "transactions": [
    {
      "id": 301,
      "wallet_id": 10,
      "amount": -150,
      "balance_after": 1250,
      "description": "Store redemption: Amazon INR 100",
      "created_at": "2026-04-15T12:45:00Z",
      "updated_at": "2026-04-15T12:45:00Z"
    },
    {
      "id": 300,
      "wallet_id": 10,
      "amount": 200,
      "balance_after": 1400,
      "description": "Daily streak reward",
      "created_at": "2026-04-15T09:00:00Z",
      "updated_at": "2026-04-15T09:00:00Z"
    }
  ]
}

Amount semantics:

  • positive amount = gems credited
  • negative amount = gems debited
  • balance_after = resulting wallet balance after that transaction

Reference: Get wallet history

Common Error Codes​

  • 401: missing/invalid project headers or bearer token
  • 403: authenticated user lacks client.wallet permission
  • 404: wallet not found (history endpoint only)

cURL Examples​

Get Wallet​

curl -X GET "http://localhost:8001/wallet" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>"

Get Wallet History​

curl -X GET "http://localhost:8001/wallet/history" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>"

Integration Notes for Game Teams​

  • Call GET /wallet on app bootstrap after login to hydrate gem balance.
  • Refresh wallet after every gem-impacting action (redeem, reward claim, event payout).
  • Use GET /wallet/history for ledger screens and to explain balance changes to users.
  • Treat backend wallet as source of truth; avoid optimistic client-only gem mutation.