> ## Documentation Index
> Fetch the complete documentation index at: https://hedgeem-api.qeetoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# F007 — RTP Margin Application

> Operator-configured house margin subtracted from fair odds to achieve target RTP

# F007 — RTP Margin Application

| Field  | Value                |
| ------ | -------------------- |
| ID     | F007                 |
| Phase  | 1 — Core Game Engine |
| Jira   | HEDGE-133            |
| Status | TS ⬜ · JS ⬜ · UMA ⬜  |

## Business Rule

The operator configures a target RTP at installation time. The game engine converts this into a **house margin** that is subtracted from the fair European odds before presenting them to the player.

**Relationship:**

```
houseMargin = 1 - targetRTP
payoutOdds  = fairOdds × (1 - houseMargin)
            = fairOdds × targetRTP
```

**Example (97% RTP, 3% margin):**

```
fairOdds   = 1 / 0.25 = 4.00   (25% win probability)
margin     = 1 - 0.97 = 0.03
payoutOdds = 4.00 × 0.97 = 3.88
```

**RTP proof:**

Over many plays, the expected value of the payout relative to the stake equals the target RTP:

```
RTP = payoutOdds × winProbability
    = 3.88 × 0.25
    = 0.97 = 97%
```

The RTP figure is the **target** — actual achieved RTP is influenced by:

1. The Rounding Algorithm applied to `oddsActual` (see F033)
2. Player betting strategy (skilled players backing favourites achieve closer to target RTP)

## Source: Game Concept Document

> "At install-time the operator sets the target RTP they desire Hedge'Em to run at."

> "The target RTP is set by the operator at installation time but the actual RTP can be influenced by other configuration parameters such as 'Rounding Algorithms' and player gameplay strategy."

> "As with other table games such as Blackjack, how a player plays Hedge'Em will affect the RTP."

## Operator Configuration

RTP is a per-installation configuration parameter, not a per-session or per-player setting:

| Config      | Type     | Default | Range                                      |
| ----------- | -------- | ------- | ------------------------------------------ |
| `targetRTP` | `number` | TBD     | Operator-defined (regulatory limits apply) |

The RTP parameter drives `houseMargin` during server-side game record generation. Once generated, game records encode the margin implicitly in `oddsActual` values.

## JavaScript Reference

**JS Source:** Margin applied server-side during game generation. Client reads `odds_actual` and `odds_rounded` from pre-generated game records. RTP margin is **not recalculated** in the client — it is baked into the data at generation time.

Relevant field: `gameName` in `coredata.ts` (e.g. `"Max RTP"`) reflects the RTP configuration used to generate the record.

## TypeScript Implementation

**Current status:** TS client consumes pre-computed odds from `coredata.ts`. RTP margin configuration is not yet wired in the TS standalone client — the coredata was generated with a specific margin applied at source.

Full RTP configuration support is tracked in F032.

## Acceptance Criteria

| #   | Criterion                                                  | JS  | TS | UMA |
| --- | ---------------------------------------------------------- | --- | -- | --- |
| AC1 | `payoutOdds = fairOdds × targetRTP` for all hands          | ⬜   | ⬜  | ⬜   |
| AC2 | Changing `targetRTP` updates all computed odds             | ⬜   | ⬜  | ⬜   |
| AC3 | `gameName` in coredata reflects the RTP configuration used | N/A | ✅  | N/A |

## Version Parity

| Version        | Status        | Notes                                           |
| -------------- | ------------- | ----------------------------------------------- |
| JS (reference) | ⬜ Not audited | Margin baked into server-generated game records |
| TS             | ⬜ Not audited | Reads margin-adjusted odds from coredata        |
| UMA            | ⬜ Not audited | Phase 5                                         |

## Related Features

* F006 — Odds Calculation (full formula)
* F032 — RTP Config (operator installation config)
* F033 — Rounding Algorithms (post-margin rounding affects actual RTP)