# Create Tour

Grants a user a bundle of free rounds (a "free tour") on one slot game. The whole tour is laid out in advance when it is created, so the response already tells you what it will pay.

Only one tour can run per user and game at a time — the previous one has to finish, expire or be canceled first.

> **`PRAGMATIC` only for now.** Free tours are supported on Pragmatic games and nowhere else yet. Sending `tour_create` for any other `provider_code` fails, since that provider's game server has no tour to create. More providers are planned.

### Endpoint

```
POST https://api.nexusggr.com
```

**Content-Type:** `application/json`

### Request

**Method:** `tour_create`

```json
{
    "method": "tour_create",
    "agent_code": "your_agent_code",
    "agent_token": "your_agent_token",
    "user_code": "test",
    "provider_code": "PRAGMATIC",
    "game_code": "vs20doghouse",
    "bet_level": 1,
    "spin_count": 10,
    "amount": 70000,
    "expiration_time": "2026-02-26T06:46:04.000Z",
    "tour_id": "free_tour_777"
}
```

| Field             | Type     | Required | Description                                                                                         |
| ----------------- | -------- | -------- | --------------------------------------------------------------------------------------------------- |
| `method`          | string   | Yes      | Must be `tour_create`                                                                               |
| `agent_code`      | string   | Yes      | Your agent code                                                                                     |
| `agent_token`     | string   | Yes      | Your agent API token                                                                                |
| `user_code`       | string   | Yes      | Target user                                                                                         |
| `provider_code`   | string   | Yes      | Game provider code                                                                                  |
| `game_code`       | string   | Yes      | Game identifier                                                                                     |
| `bet_level`       | integer  | Yes      | Index into the game's bet range: `1` = minimum bet, `2` = the next one, and so on                   |
| `spin_count`      | integer  | Yes      | Number of free rounds. `1` – `1000`                                                                 |
| `amount`          | number   | Yes      | Target payout of the whole tour, in your currency: more than `0`, with at most 2 decimals. The tour never pays more; what it really pays comes back as `real_win` |
| `expiration_time` | datetime | Yes      | When the tour stops being playable. Must be in the future                                           |
| `tour_id`         | string   | Yes      | Your own identifier for the tour, 1 – 36 characters. It comes back in the later callbacks           |

> **The tour pays close to `amount`, never more.** Its paying rounds are drawn at random so that together they come close to `amount` without going over it, usually within 1%, and what they pay comes back as `real_win`. Two tours created with the same values can pay slightly different amounts.
>
> - How many of the rounds pay is drawn at random for each tour, between the fewest of the game's biggest wins that reach `amount` and the most of its smallest wins that fit in it, so the same request can pay in one big round or spread over every round.
> - Tour rounds are drawn from the game's ordinary base-game spins and never trigger its free-spins bonus feature, so a tour can pay at most what the game's `spin_count` biggest base-game wins at that bet add up to. With a low `bet_level`, few rounds, or an `amount` close to that limit, `real_win` can stay well below `amount`.
> - An `amount` below the smallest win the game pays at that bet is still accepted: the tour is created with `real_win` `0`, nothing is charged, and every round is a blank.
> - On games that offer a gamble after a win, a tour round's win cannot be gambled.

### Response

#### Success

```json
{
    "status": 1,
    "code": 7777777,
    "msg": "SUCCESS",
    "tour_id": "free_tour_777",
    "user_code": "test",
    "provider_code": "PRAGMATIC",
    "game_code": "vs20doghouse",
    "bet_level": 1,
    "bet": 100,
    "total_bet": 2000,
    "spin_count": 10,
    "amount": 70000,
    "real_win": 69960,
    "expiration_time": "2026-02-26T06:46:04.000Z"
}
```

| Field       | Type   | Description                                                                         |
| ----------- | ------ | ----------------------------------------------------------------------------------- |
| `bet`       | number | Coin bet of one line at `bet_level`                                                 |
| `total_bet` | number | Bet of one free round (`bet` × the game's pay lines)                                |
| `real_win`  | number | What the prepared rounds pay, and what your agent balance is charged: close to `amount`, never more. Lower when the game's rounds cannot reach `amount`, `0` when `amount` is below the game's smallest win at that bet |

**Balance:** `real_win` is deducted from your agent balance the moment the tour is created, and the unplayed part comes back if you cancel it or it expires. If the played rounds end up paying less than `real_win`, the difference comes back the same way as for an expired tour. A tour never pays more than `real_win`. Your balance still has to cover the full `amount` at creation time, before `real_win` is known.

**Expiry:** once `expiration_time` has passed, what the tour has not paid out comes back to your agent balance on its own, worked out as for **Cancel Tour**. No callback is sent for it. The game server reports expired tours in an hourly check, so this happens up to about 70 minutes after `expiration_time` — later if the user is still in a free round then. A tour is refunded only once: by a cancel or by its expiry, whichever comes first.

**Early end:** if the game stops supporting free tours while a tour is running (the operator switches it to another mode), the tour ends at the user's next request in that game, and what it has not paid out comes back as on expiry. A round already under way is played to its end first.

**Callbacks:** in Seamless mode the `transaction` callbacks of the tour's free rounds also carry `tour_id`, `tour_rest_count`, `tour_total_win` and `tour_end` inside `slot`. See [Transaction (Site Endpoint)](https://my.nexusggr.com/app/docs/integration/seamless-api/transaction-site-endpoint).

#### Failure

```json
{
    "status": 0,
    "code": 7770024,
    "msg": "Duplicated Tour Id."
}
```

```json
{
    "status": 0,
    "code": 7770502,
    "msg": "External Error : INVALID_BET_LEVEL"
}
```

`External Error` means the game server refused the tour. The text after `External Error : ` says why:

| Reason                    | Description                                              |
| ------------------------- | -------------------------------------------------------- |
| `INVALID_GAME`            | The game does not exist, has no pay lines, or does not support free tours |
| `PO_GAME`                 | The game is switched off                                 |
| `INVALID_BET_LEVEL`       | `bet_level` is above the game's highest bet              |
| `INVALID_EXPIRATION_TIME` | `expiration_time` is already past                        |
| `DUPLICATED_TOUR_ID`      | The game server already knows this `tour_id`             |
| `TOUR_IN_PROGRESS`        | This user still has a playable tour on this game         |
| `NO_PATTERN_DATA`         | The game has no round data to build a tour from          |

An `amount` of `0` or less, or with more than 2 decimals, is refused before the game server is asked: code `7770006`, with the reason in `msg` (see [Response Codes](https://my.nexusggr.com/app/docs/integration/response-codes)).

A refused tour is not recorded, so the same `tour_id` can be used again once the cause is fixed.