# Score Multipliers

Score multipliers allow players to boost their effective points on the daily leaderboard by purchasing a multiplier with playcoins (or SOL). This creates an additional monetization layer and drives demand for the game's playcoin.

## How Multipliers Work

* Players can purchase multipliers (2x, 3x, 5x, etc.) for a specific game
* The multiplier applies to **today's points only** - it resets daily
* Higher multipliers cost more, following a bonding curve
* Purchases are made using the game's playcoin (or SOL, which is swapped automatically)
* **All multiplier purchases go into the player reward pool** - they're redistributed to players daily

## For Game Developers

**No integration work required!** Multipliers work automatically with SDK integration. Players purchase multipliers through the Play Fun interface, and their points are automatically boosted.

The SDK handles:

* Displaying multiplier purchase options
* Processing payments (playcoin or SOL)
* Applying multipliers to point calculations
* Showing boosted leaderboard positions

## For Players

Players can:

1. View their current multiplier status
2. See the cost to upgrade to higher multipliers
3. Calculate cost to reach a specific leaderboard position
4. Purchase multipliers using playcoins or SOL

## Pricing Model

Multipliers use a **quadratic bonding curve** that considers:

1. **Per-level cost**: Each multiplier level costs `baseCost * level²`
2. **Global demand**: As more players buy multipliers, prices increase
3. **Daily spend cap**: A soft cap that triggers exponential pricing when exceeded

This creates fair pricing where:

* Early multipliers are affordable
* High multipliers require significant investment
* Prices adjust based on game activity

## API Reference

### Get Multiplier Cost

Calculate the cost to purchase a specific multiplier level.

```
GET /multiplier/cost
```

**Query Parameters:**

| Param        | Type   | Description                              |
| ------------ | ------ | ---------------------------------------- |
| `gameId`     | string | Game UUID                                |
| `multiplier` | number | Desired multiplier level (e.g., 2, 3, 5) |

**Response:**

```json
{
  "atomicAmountRequired": "1000000000",
  "solAmountRequired": "50000000",
  "gameCoin": {
    "mint": "...",
    "symbol": "GAME",
    "decimals": 9
  },
  "currentMultiplier": 1,
  "currentAtomicSpent": "0"
}
```

### Get Current Multiplier

Check a user's current multiplier status for today.

```
GET /multiplier/current
```

**Query Parameters:**

| Param    | Type   | Description |
| -------- | ------ | ----------- |
| `gameId` | string | Game UUID   |

**Response:**

```json
{
  "currentMultiplier": 2.0,
  "totalSpent": "500000000"
}
```

### Calculate Cost for Leaderboard Position

Find out what multiplier (and cost) is needed to reach a specific position.

```
GET /multiplier/cost-for-placement
```

**Query Parameters:**

| Param       | Type   | Description                                    |
| ----------- | ------ | ---------------------------------------------- |
| `gameId`    | string | Game UUID                                      |
| `placement` | number | Desired leaderboard position (1 = first place) |

**Response:**

```json
{
  "atomicAmountRequired": "2500000000",
  "solAmountRequired": "125000000",
  "multiplierNeeded": 3.5,
  "gameCoin": { ... }
}
```

### Purchase Multiplier

Execute a multiplier purchase.

```
POST /multiplier/purchase
```

**Body:**

```json
{
  "gameId": "uuid",
  "multiplier": 3,
  "useSol": true,
  "approvedAmount": "150000000"
}
```

**Notes:**

* Requires user authentication
* `useSol: true` will swap SOL to the game's playcoin automatically
* `approvedAmount` must cover the cost (with buffer for SOL swaps)

## How It Affects Leaderboards

Leaderboards show **effective points** = `base points * multiplier`

Example:

* Player A: 1000 points, 1x multiplier = 1000 effective points
* Player B: 800 points, 2x multiplier = 1600 effective points
* Player B ranks higher despite fewer base points

## Where Multiplier Revenue Goes

All playcoins spent on multipliers go into the **player reward pool**:

* 100% of purchases are added to the daily distribution pool
* This increases rewards for all players in that game
* Creates a positive feedback loop: multipliers → more rewards → more players

## Key Behavior

* Multipliers reset daily at UTC midnight
* Purchases are recorded on-chain
* Use `GET /multiplier/current` to check a player's active multiplier for today