> ## Documentation Index
> Fetch the complete documentation index at: https://doc.playsmart.api.dolly.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# How players earn and accumulate coins in PlaySmart

> Learn how PlaySmart awards coins to players automatically when they complete levels, and how to track coin balances through the user profile.

PlaySmart awards coins to players automatically whenever a `LevelCompleted` event is received and the game has `coins_enabled` set to `true`. You do not need to calculate or credit coins yourself — the server handles that as soon as it processes the event. The player's `coins_balance` on their profile increases, and a periodic conversion job turns accumulated coins into a USD balance that players can withdraw.

<Steps>
  <Step title="Confirm coins are enabled for your game">
    Call `GET /v1/games` and find your game in the response. Check the `coins_enabled` field. If it is `false`, completing levels will not award coins and you should contact your PlaySmart admin before proceeding.

    ```bash theme={null}
    curl https://playsmart-gateway-1w8ko864.uc.gateway.dev/v1/games \
      -H "Authorization: Bearer <access_token>"
    ```

    Look for your game's entry in the response array:

    ```json theme={null}
    {
      "data": [
        {
          "game_id": 482910374,
          "name": "Stack Blaster",
          "bundle_id": "com.example.stackblaster",
          "coins_enabled": true,
          "ads_enabled": true,
          "game_mode": "level_based",
          "maintenance": false
        }
      ]
    }
    ```

    Proceed only if `coins_enabled` is `true`.
  </Step>

  <Step title="Send a LevelCompleted event">
    When a player completes a level, send a `LevelCompleted` event to `POST /ingest/events`. The `user_id` must match the authenticated player's ID (the `sub` claim from their access token), and `game_id` must be your game's `bundle_id`.

    ```bash theme={null}
    curl -X POST https://playsmart-gateway-1w8ko864.uc.gateway.dev/ingest/events \
      -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
        "user_id": "device-abc-123",
        "game_id": "com.example.stackblaster",
        "events": [
          {
            "type": "LevelCompleted",
            "timestamp": "2024-01-15T12:00:00+00:00",
            "customdata": { "level": 5, "score": 1250 }
          }
        ]
      }'
    ```

    The server returns `202 Accepted` to confirm the event was queued for processing.
  </Step>

  <Step title="Coin transaction is recorded">
    After the event is processed, the server creates a coin transaction record for the player with the following fields:

    | Field            | Value                                         |
    | ---------------- | --------------------------------------------- |
    | `type`           | `earn`                                        |
    | `trigger`        | `level_complete`                              |
    | `amount`         | configured per game in the admin panel        |
    | `balance_before` | the player's `coins_balance` before the award |
    | `balance_after`  | the player's `coins_balance` after the award  |

    The player's `coins_balance` on their profile is updated accordingly.
  </Step>

  <Step title="Coins convert to USD automatically">
    A background conversion job runs on a scheduled cycle and converts each player's accumulated `coins_balance` into `money_balance_usd` using the exchange rate configured for your game. You do not need to trigger this — it happens automatically. After conversion, `coins_balance` is reduced and `money_balance_usd` increases by the converted amount.

    Players can then request a PayPal withdrawal once their `money_balance_usd` meets the minimum threshold. See the [withdrawal guide](/guides/withdraw-earnings) for details.
  </Step>
</Steps>

<Note>
  The number of coins awarded per completed level is configured in the admin panel by your PlaySmart admin. If coin awards are not appearing as expected, verify the reward amount is set and the game's `coins_enabled` flag is `true`.
</Note>