# Free rounds API

## Free rounds you issue

`POST /v2/aggregator/issue_grant`

| Field | Required | Meaning |
|---|---|---|
| `player_ref`, `game_ids[]` | yes | Who and on which games. |
| `rounds_total` | yes | Number of free rounds. |
| `round_value` | yes | Stake value of one round (Money). |
| `bet_level`, `lines` | no | Provider bet level and lines, from `get_bet_ranges` (§6.1) where the game has levels. |
| `settlement_mode` | no | GA supports only `SETTLEMENT_MODE_ON_COMPLETION`. Leave it out. |
| `idempotency_key` | recommended | The same key returns the same grant. GA refuses a different body under the same key with `IDEMPOTENCY_CONFLICT`. Without a key every call creates a new grant. |
| `valid_until` | yes | Hard end date. GA refuses rounds after it. |
| `external_ref` | no | Your campaign or bonus id. |

Response: `Grant` with `grant_id`, `status` (`active`, `exhausted`, `expired`, `cancelled`, `settled`), `rounds_remaining`, `rounds_played`, `accumulated_win`.

How the money flows for a grant you issued: **no bet and no win reaches your wallet while the player plays the rounds.** The win accumulates on the grant. When the grant is exhausted, expired, or cancelled with a win, GA sends **one `settle_grant`** to your wallet with `total_win`, and that's when you credit the player (§5.9). GA also settles a zero-win grant, with `total_win: 0`.

`list_grants` (by `player_ref` and `status`) and `cancel_grant` (`grant_id`, `reason`) complete the set. You can cancel only an active grant, and GA still settles the win already earned.

## Reference

- **POST** `/v2/wallet/settle_grant` — [Settle free-round grant: parameters, errors, code samples, try it](/docs/aggregation/reference/wallet/#tag/wallet/POST/v2/wallet/settle_grant)
- **POST** `/v2/aggregator/issue_grant` — [issueGrant: parameters, errors, code samples, try it](/docs/aggregation/reference/aggregator/#tag/aggregator/POST/v2/aggregator/issue_grant)
- **POST** `/v2/aggregator/grants` — [listGrants: parameters, errors, code samples, try it](/docs/aggregation/reference/aggregator/#tag/aggregator/POST/v2/aggregator/grants)
- **POST** `/v2/aggregator/cancel_grant` — [cancelGrant: parameters, errors, code samples, try it](/docs/aggregation/reference/aggregator/#tag/aggregator/POST/v2/aggregator/cancel_grant)