A wallet system is the financial backbone of any monetized Ludo game. Whether you're running a virtual currency economy, real-money tournaments, or a hybrid model, the wallet API handles balance management, transaction logging, deposit processing, and withdrawal workflows. This guide covers the complete wallet integration using the Ludo King API, from initial setup to production-scale transaction processing.

Wallet Architecture Overview

The Ludo King Wallet API implements a multi-currency ledger system where every financial movement is recorded as an immutable transaction entry. The wallet supports three operation modes: virtual currency only (coins/gems for standard IAP), real-money mode (INR/USD balance for real-money gaming), and hybrid mode (both currencies with automatic conversion).

All wallet operations are atomic — a debit and credit pair together or both fail. This prevents double-spending, phantom balances, and reconciliation nightmares. Every transaction is idempotent via a client-generated transaction ID, ensuring safe retries without duplicate processing.

Initializing a Player Wallet

Before any financial operations, the wallet must be initialized for each player. This creates the player's wallet record with default configurations.

POST /api/v1/wallet/initialize 
{
  "player_id": "player_7x4k9m2p",
  "mode": "virtual",  // virtual | real_money | hybrid
  "currencies": ["coins", "gems"],
  "welcome_bonus": {
    "currency": "coins",
    "amount": 500
  },
  "player_metadata": {
    "country": "IN",
    "platform": "android",
    "app_version": "2.4.1"
  }
}

// Response
{
  "wallet_id": "wallet_a8b3c9d2",
  "player_id": "player_7x4k9m2p",
  "currencies": ["coins", "gems"],
  "balances": {
    "coins": 500,
    "gems": 0
  },
  "created_at": "2025-01-20T10:30:00Z",
  "kyc_required": false,
  "daily_limits": {
    "deposit_max": null,
    "withdrawal_max": null
  }
}

Credit and Debit Operations

Core wallet operations — crediting winnings, debiting entry fees, granting bonuses — all follow the same transaction API. Each transaction requires a unique client reference ID for idempotency.

POST /api/v1/wallet/transaction 
{
  "player_id": "player_7x4k9m2p",
  "type": "credit",  // credit | debit | lock | unlock | transfer
  "currency": "coins",
  "amount": 250,
  "client_txn_id": "txn_wallet_1705768200",
  "reason": "tournament_prize",
  "metadata": {
    "tournament_id": "tour_abc123",
    "position": 1,
    "source": "LUDO_TOURNAMENT_ENGINE"
  },
  "idempotency_key": "tour_abc123_prize_player_7x4k9m2p"
}

// Response
{
  "txn_id": "txn_9f3k2m8p",
  "client_txn_id": "txn_wallet_1705768200",
  "status": "completed",
  "player_id": "player_7x4k9m2p",
  "currency": "coins",
  "amount": 250,
  "balance_before": 250,
  "balance_after": 500,
  "processed_at": "2025-01-20T10:35:42Z",
  "fee": 0
}

Balance Inquiry

Retrieve the current wallet balance for a player across all currencies, including locked amounts (reserved for ongoing games or pending withdrawals).

GET /api/v1/wallet/balance?player_id={player_id} 
{
  "player_id": "player_7x4k9m2p",
  "wallets": {
    "coins": {
      "available": 4750,
      "locked": 250,
      "total": 5000
    },
    "gems": {
      "available": 42,
      "locked": 0,
      "total": 42
    }
  },
  "last_updated": "2025-01-20T10:35:42Z"
}

Transaction History

Fetch paginated transaction history for player audits, reconciliation, or displaying in-game transaction logs.

GET /api/v1/wallet/transactions?player_id={id}&limit=20&offset=0 
{
  "player_id": "player_7x4k9m2p",
  "transactions": [
    {
      "txn_id": "txn_9f3k2m8p",
      "type": "credit",
      "currency": "coins",
      "amount": 250,
      "reason": "tournament_prize",
      "balance_after": 500,
      "created_at": "2025-01-20T10:35:42Z"
    },
    {
      "txn_id": "txn_8e2j1l7q",
      "type": "debit",
      "currency": "coins",
      "amount": 100,
      "reason": "game_room_entry",
      "balance_after": 250,
      "created_at": "2025-01-19T22:14:08Z"
    },
    {
      "txn_id": "txn_7d1i0k6p",
      "type": "credit",
      "currency": "coins",
      "amount": 50,
      "reason": "daily_bonus",
      "balance_after": 350,
      "created_at": "2025-01-19T09:00:00Z"
    }
  ],
  "pagination": {
    "total": 147,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Withdrawal Processing

Real-money withdrawals require KYC verification, compliance checks, and manual or automated approval workflows. The API supports UPI, bank transfer, and wallet-to-wallet withdrawals with configurable daily and monthly limits.

POST /api/v1/wallet/withdraw 
{
  "player_id": "player_7x4k9m2p",
  "amount": 1000,
  "currency": "INR",
  "withdrawal_method": "upi",
  "destination": "player@upi",
  "client_txn_id": "wd_1705768800",
  "idempotency_key": "wd_upi_player_7x4k9m2p_1705768800"
}

// Response
{
  "withdrawal_id": "wd_abc123xyz",
  "client_txn_id": "wd_1705768800",
  "status": "pending_approval",
  "amount": 1000,
  "currency": "INR",
  "estimated_arrival": "2025-01-21T10:30:00Z",
  "kyc_verified": true,
  "compliance_check": "passed",
  "daily_limit_remaining": 24000,
  "processing_fee": 10
}

Wallet Security Best Practices

Frequently Asked Questions

The Ludo King Wallet API uses optimistic locking with version numbers to handle concurrent operations. When a game session starts, lock the entry fee amount using a lock transaction. If the player wins, credit the winnings and unlock the remaining amount atomically. If the player disconnects, the locked amount is automatically released after the match timeout. This prevents double-spending across multiple devices or sessions for the same player.

Yes, the hybrid wallet mode supports both currencies simultaneously. Virtual currency (coins, gems) operates with instant, automated transactions. Real money (INR, USD) operates with KYC requirements, compliance checks, and manual or automated withdrawal approval. Both currencies are tracked independently in separate ledgers within the same wallet object. Automatic conversion rates can be configured for converting virtual currency winnings to real money.

The Ludo King Wallet API implements a two-phase withdrawal process. In phase one, the amount is debited from available balance and moved to a pending withdrawal hold. If the payment processor subsequently fails, the API automatically initiates a rollback: the pending amount is credited back to the player's available balance and the withdrawal record is marked as "failed" with the reason. The player's wallet is never left in an inconsistent state.

Use a server-side bonus scheduler that triggers credit transactions at player login. The API supports bonus templates that define award amounts, currencies, and eligibility rules. Track bonus claim history per player to implement streak bonuses (Day 1: 50 coins, Day 7: 500 coins) and ensure each bonus is claimed only once per day. The scheduler can run via cron jobs, webhook triggers, or the built-in bonus automation module.

Withdrawal processing times depend on the withdrawal method and verification level. UPI withdrawals typically process within 30 minutes to 24 hours. Bank transfers take 1–3 business days. The platform can configure auto-approval for amounts below a threshold (e.g., under ₹1,000) and require manual review for larger amounts. Real-money gaming withdrawals may have mandatory cooling-off periods as required by applicable regulations.

The wallet API provides a reconciliation endpoint that returns a cryptographically signed daily summary: total credits, total debits, net change, transaction count, and opening/closing balances per currency. Download these reports daily and store them off-platform. For audit purposes, export full transaction history with all metadata as JSON or CSV. The API also supports webhook-based real-time reconciliation where every transaction pushes a signed event to your accounting endpoint.